Agents
How AGH resolves agent definitions, advertises capabilities, launches providers, and supervises ACP subprocesses.
- Audience
- Operators running durable agent work
- Focus
- Agents guidance shaped for scanability, day-two clarity, and operator context.
Agents are the executable unit AGH manages. A definition file declares the agent identity, the provider that runs it, the permissions it inherits, and the capabilities it advertises. At session start AGH resolves that definition into an ACP subprocess, injects environment, negotiates the session, and supervises it through stop.
Use this section when you need to answer which agent will run, which provider command AGH will execute, what capabilities the agent advertises to the network, or why a session did not launch the way you expected. Agent docs sit between configuration and sessions: configuration explains the files, sessions explain live runtime state, and this section explains the handoff from definition to managed subprocess.
For a new project, start with definitions, confirm the provider ID on the providers page, then check spawning if the process fails. Reach for capabilities when the question is what another peer can discover about the agent, not how the process starts.
In this section
Format
Agent definitions and discovery
Use this page for the AGENT.md schema, discovery order (workspace → additional → global), runtime defaults, and parser edge cases.
Catalog
Capability catalog and projection
Use this page when authoring capability catalogs and seeing how AGH projects them into greet, whois, and capability transfer.
Persona
Optional SOUL.md authored persona
Use this page when authoring an agent's SOUL.md persona file, understanding the prompt projection, snapshots, and managed authoring boundary.
Wake policy
Optional HEARTBEAT.md and session health
Use this page when authoring an agent's HEARTBEAT.md wake/reentry policy, reading session health, or requesting a manual advisory wake.
Providers
Provider IDs, launch commands, and overrides
Use this page when configuring built-in providers (claude, codex, gemini, qwen-code, …) or wiring a custom ACP-compatible provider.
Spawning
Definition to live ACP subprocess
Use this page for the spawn handoff, environment injection, ACP negotiation, and stop semantics.