Skip to content
Agentic Control Plane

ACP for AI agents

Audience: AI agents. This docs section is plain markdown, dense and copy-pasteable. No images, no marketing prose. Humans are welcome, but the format is built for an agent reading it as context.

A parent agent can mint a child API key in one HTTP call. The child key can do no more than the parent’s key, and every call the child makes is attributed to the human who started the chain.

You have to do the minting. A subagent is only covered if it runs with a key minted from yours. Nothing happens on its own when an agent spawns another agent.

What the gateway does when you mint a child key

Parent agent A is attributed to human H through its API key. A calls POST /api/v1/keys/child to get a key for child agent B. The gateway:

  • Sets B’s originSub to H. It is kept through the whole chain, so audit logs trace back to the human.
  • Sets B’s effectiveScopes to the intersection of A’s scopes, the profile’s scopes and the request’s scopes. A child never gets more than its parent.
  • Strips bench.impersonate. This meta-scope never passes down.
  • Takes the child’s budget out of A’s remaining budget in one transaction, so fan-out can’t exceed the parent’s cap.
  • Sets expiresAt no later than the parent’s expiry.
  • Stores chain metadata, so audit logs follow the chain back to H.
  • Rejects cycles anywhere in the ancestor chain.

What you need for this to work:

  • The parent mints the key. Use the SDK’s spawn_subagent, the acp-spawn skill, or a raw POST /api/v1/keys/child.
  • The subagent must run with that child key.
  • The agent profile must not be marked delegatable: false.
  • The gateway must have KEYS_CHILD_API_ENABLED set to true. The code default is off, and it is a deploy setting, so a 404 from the route means it is off in that environment.

Two pages

  • Agents-building-agents quickstart The delegation call, the SDK helpers and the Claude Code skill. Use it when your agent runs inside an existing tenant. It also covers the sandbox path for agents with no tenant yet.

  • Config-as-code reference Field-level reference for the REST endpoints: agent profiles, child keys, OAuth and custom HTTP connectors, custom PII patterns and effective-policy lookup.

Why this exists

ACP checks a coding agent’s tool calls with a hook that runs inside the agent’s harness. The hook ties each call to the user who started the session and records it. In audit mode, the default, nothing is held except the safety floor. When the workspace is in enforce mode, the hook also applies per-user rules (allow, ask first, never), spend caps and optional PII redaction.

If the gateway is unreachable, the hook fails open by default. Set ACP_FAIL_MODE=closed (or write closed to ~/.acp/failmode) on that machine to block calls instead. The Claude Code plugin works differently: it fails open with a loud UNGOVERNED banner in interactive sessions, and fails closed for subagent, background and API sessions.

The usual setup assumes a human onboards the agent and hands out keys. That breaks when an agent spawns another agent. The subagent either shares the parent’s full-power key, with no scope narrowing and no separate audit trail, or it can’t get a key without a human.

A child key fixes both. The parent narrows the scopes in one call, and the audit trail still points at the human who started the chain.

Going to production

Three ways to mint and use a child key:

  1. SDK wrapper (Python today). from acp_governance import spawn_subagent, child_context. Inside with child_context(child), every @governed tool call is reported under the child key.

  2. Claude Code skill. acp-spawn lives in claude-code-acp-plugin. When a user or agent delegates work, the skill mints the child key and runs the subagent with that token.

  3. Raw HTTP, for anything that is not Python or Claude Code. POST /api/v1/keys/child with the parent’s gsk_ token, then pass the child key to the subagent as its bearer token.

Source and feedback

If you found these docs through llms.txt, you are using them as intended. Welcome.

Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Getting started