Your first custom agent

In Quick Start, you used the built-in general agent. In this tutorial, you will create a second agent with its own system prompt and permission mode, store it in the correct runtime path, and launch a session with it.

Before you begin: Run these steps from the repository root where you want the agent to be visible. The current CompozyOS runtime uses <workspace>/.compozy/agents/<name>/AGENT.md for workspace-local agents.

1. Create the workspace-local agent directory

mkdir -p .compozy/agents/code-reviewer

2. Write the AGENT.md file

Create .compozy/agents/code-reviewer/AGENT.md with this minimal example:

---
name: code-reviewer
provider: claude
permissions: approve-reads
---
You are a focused code reviewer.

- Read the relevant files before answering.
- Put bugs, regressions, and missing tests first.
- Cite files and symbols when you can.
- Keep the final response concise and actionable.

This tutorial intentionally keeps the file small. The important pieces are:

Field	Why it matters in this tutorial
`name`	The identifier CompozyOS uses for discovery and selection.
`provider`	Tells CompozyOS which provider configuration to resolve for this agent.
`permissions`	This is the enforced session boundary today. `approve-reads` auto-allows read operations and prompts for the rest.
Markdown body	Becomes the agent's startup prompt.

For the full implemented schema, use AGENT.md.

3. Verify that CompozyOS can see the agent

compozy agent list

Inspect the resolved definition:

compozy agent info code-reviewer

This is the right moment to catch path mistakes. If the agent does not appear here, CompozyOS will not be able to start a session with it.

4. Start a session with the custom agent

compozy session new --cwd "$PWD" --agent code-reviewer

Then send it a focused task:

compozy session prompt sess_1234 "Review the changes in this repository and tell me the highest-risk issue first." \
  --provider claude \
  --model claude-sonnet-5 \
  --reasoning-effort high \
  --speed normal

Creating the session is promptless: it returns state: "active" with runtime.status: "unbound" and no ACP process. The prompt above supplies the first runtime snapshot and binds ACP. Because the agent uses approve-reads, read operations can proceed automatically, while write or terminal operations still require approval.

5. Understand the enforcement boundaries

This minimal definition sets only a provider and permission mode, but the other runtime fields are not descriptive metadata:

permissions sets the runtime approval policy.
provider, model, reasoning_effort, and speed form the runtime snapshot for each prompt. The first prompt binds ACP. A same-provider change can configure that ACP session live; a provider or harness change replaces the process and replays the canonical transcript. An unadvertised model fails that prompt instead of silently falling back.
tools and toolsets narrow the callable tool registry for the agent. deny_tools narrows it further and wins when an allow and deny overlap.

Read the complete AGENT.md contract before adding those fields. A stricter definition changes runtime authority and startup behavior, not only discovery labels.

6. Add more later

When you are ready to go beyond the minimal example:

use Agent Providers for provider resolution behavior
use Agent Spawning for the startup path
use AGENT.md for the full field contract
use mcp.json when you want MCP sidecars

Next step

Open the Web UI and inspect the same runtime state in the browser.