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 AGH runtime uses <workspace>/.agh/agents/<name>/AGENT.md for workspace-local agents. The draft .agents/<name>/ path appears in RFC material, but it is not the runtime path to use today.

1. Create the workspace-local agent directory

mkdir -p .agh/agents/code-reviewer

2. Write the AGENT.md file

Create .agh/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 AGH uses for discovery and selection.
`provider`	Tells AGH 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 AGH can see the agent

agh agent list

Inspect the resolved definition:

agh agent info code-reviewer

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

4. Start a session with the custom agent

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

Then send it a focused task:

agh session prompt sess_1234 "Review the changes in this repository and tell me the highest-risk issue first."

Because the agent uses approve-reads, read operations can proceed automatically, while write or terminal operations still require approval.

5. Know what this tutorial does not claim

Two field families are easy to overread:

permissions is enforced by the runtime and matters immediately.
tools and model are useful metadata, but you should treat the full field behavior according to the current reference docs, not as a separate enforcement layer introduced by this tutorial.

That distinction is important when you start designing stricter agents.

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.