Providers

A provider is the ACP-compatible command AGH launches for an agent. The provider owns the actual LLM integration. AGH owns definition resolution, process lifecycle, workspace boundaries, permissions, MCP server wiring, and event persistence.

Provider IDs appear in AGENT.md:

---
name: implementation
provider: codex
---
You implement scoped changes and verify them before handoff.

Or they can be selected globally:

[defaults]
agent = "general"
provider = "claude"

Built-in providers

The built-in registry lives in internal/config/provider.go.

Provider config fields

Provider overrides and custom providers are configured in config.toml.

AGH overlays provider config on top of a built-in provider when the name matches. Unknown provider names are accepted only when they have a [providers.<name>] entry.

Direct ACP built-ins such as claude, codex, and gemini expose their API-key env name as an optional slot because those CLIs can authenticate through their own login flows. Pi-backed API-key providers mark the built-in API-key slot required so missing credentials fail before the subprocess starts. Custom providers should set required to match the runtime's real authentication contract.

Override a built-in provider

Use this when you need to pin a different adapter command or change the default model used by agents that omit model.

[providers.claude]
default_model = "claude-sonnet-4-6"

[[providers.claude.credential_slots]]
name = "api_key"
target_env = "ANTHROPIC_API_KEY"
secret_ref = "env:ANTHROPIC_API_KEY"
kind = "api_key"
required = false

[[providers.claude.mcp_servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
secret_env = { GITHUB_TOKEN = "env:GITHUB_TOKEN" }

Only non-empty scalar fields replace the built-in values. MCP servers merge by name.

Configure an API-key provider

Most secondary providers use the Pi harness. The provider is still selected as an AGH provider in agents, CLI flags, the web session dialog, and settings APIs.

[providers.openrouter]
display_name = "OpenRouter"
harness = "pi_acp"
runtime_provider = "openrouter"
command = "npx -y pi-acp@latest"
default_model = "openai/gpt-5.4"

[[providers.openrouter.credential_slots]]
name = "api_key"
target_env = "OPENROUTER_API_KEY"
secret_ref = "env:OPENROUTER_API_KEY"
kind = "api_key"
required = true

For AGH-managed encrypted storage, use a vault:providers/<provider>/<slot> ref and save the value through the settings API or web provider editor. The <provider> and <slot> segments are lowercase provider/slot identifiers using letters, numbers, hyphens, underscores, or dots; path traversal, whitespace, and arbitrary vault paths are rejected.

[[providers.openrouter.credential_slots]]
name = "api_key"
target_env = "OPENROUTER_API_KEY"
secret_ref = "vault:providers/openrouter/api-key"
kind = "api_key"
required = true

AGH never exposes provider secret values through settings reads. Status surfaces report only whether the bound credential is present.

Add a custom provider

A custom provider needs an ACP-compatible command. AGH will launch it the same way it launches the built-ins.

[providers.local-agent]
command = "local-agent --acp --stdio"
default_model = "local-default"

[[providers.local-agent.credential_slots]]
name = "api_key"
target_env = "LOCAL_AGENT_API_KEY"
secret_ref = "env:LOCAL_AGENT_API_KEY"
kind = "api_key"
required = false

[[providers.local-agent.mcp_servers]]
name = "filesystem-index"
command = "local-index-mcp"
args = ["serve"]

Then point an agent at the custom provider:

---
name: local-operator
provider: local-agent
permissions: approve-reads
---
You inspect this repository with the local agent runtime.
Report risks and cite exact files.

Command parsing

Provider commands are parsed with shell-style quoting, then launched without a shell. That means:

• quoted arguments are preserved
• shell expansion is not performed
• the executable must be available on the daemon process PATH
• npx-based built-ins can download and run their adapter package through the local Node toolchain

For example, this is valid:

[providers.reviewer]
command = "reviewer-acp --profile \"team default\""

But shell-only behavior is not applied:

[providers.bad-example]
command = "MY_FLAG=1 reviewer-acp"

Set environment variables before starting the daemon instead.

Models and API keys

model and default_model are resolved and exposed as runtime metadata. Direct acp providers receive the normal ACP startup flow; Pi-backed providers also receive a session-local Pi settings.json and models.json with the resolved runtime_provider and model.

The practical rule is:

• use model in AGENT.md when you want AGH metadata and provider-specific wrappers to agree on the intended model
• use credential_slots when AGH should inject a specific API key into the subprocess
• use env: refs for operator-managed process environment and vault:providers/<provider>/<slot> refs for AGH-managed encrypted provider credentials

MCP server merge order

MCP servers can be declared at several levels. Startup uses this order:

1. Top-level mcp_servers from resolved config
2. Provider mcp_servers
3. Agent mcp_servers
4. Active skill MCP servers

Config/provider/agent merges are field overlays by server name. Agent-local mcp.json sidecars replace same-name inline servers as whole objects before that cross-scope merge happens. Configured MCP env values are passed through as literal strings. Pi-backed providers are launched through pi-acp; current Pi ACP support does not wire AGH MCP server declarations into Pi's own MCP configuration.

Choosing a provider

Use the provider that already owns your credentials and preferred workflow:

Then keep provider-specific behavior in the provider command or provider config, and keep the agent's role, permissions, MCP servers, and startup prompt in AGENT.md.

Related pages

• Agent Definitions explains the AGENT.md fields that reference providers.
• Spawning shows exactly how the resolved provider command becomes a running ACP process.
• CLI agent reference lists the current agh agent inspection commands.