Repository navigation
feat(agents)!: an agent's extension routes take its control token - #780
Conversation
Each agent agent-env deploys now gets its control token, and the protocol SDK makes its extension routes require it. - SDK: when an agent application starts serving (its lifespan, under serve() or any ASGI server), it takes AGENTENV_CONTROL_TOKEN out of the environment, so the CLIs and tools it runs never inherit it. From then on every extension operation answers a call without AgentEnv-Control-Token with a 401, before the body is read, and logs the refusal. /a2a, the card, /health, staging and the peer-agents MCP endpoint stay open; without a token, or unserved, everything stays open as before. - ControlTokenMiddleware gives the same check to an agent that serves /ext/* by hand. - A2AAgent.deploy hands the agent the token it records, set last in its environment. - install/v1 gains optional_params (optional_params_host): install_agent exports control_token to every install command as AGENTENV_CONTROL_TOKEN rather than as a placeholder, so an older installer still installs the agent, without a token. The nine bundled install/v1 agents declare it and write it where their server reads its environment. - The validator's new verify_a2a_control_token check calls a read every SDK agent serves, without the token and with it. - An extension call refused with a 401 says the agent refused its control token, and logs it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a prefix ControlTokenMiddleware read the full request path, so in an app mounted at /agent a call to /agent/ext/agent-config didn't look like an extension route. It now reads the path the app's routes match, without the root_path it is mounted under, as Starlette's router does. The validator's control-token check names its request timeout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nt card tests follow
The SDK's route check raised an HTTPException, which a plain agent app answers as text; it now
answers {"detail": ...} as ControlTokenMiddleware does and agent-env reads. The codex and gemini
card tests take the install declaration's new optional_params; the openhands, pi and
pydantic-ai tests find the env-file command by what it writes, now that the token's command
follows it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…on routes take a token An agent deployed without a control token, or served without its lifespan, serves its extension routes open and said nothing. The application, and ControlTokenMiddleware, now log at start whether the routes take the agent's token or are open. BREAKING CHANGE: an agent built on this SDK and deployed by this agent-env refuses a call to its /ext/* routes without AgentEnv-Control-Token. agent-env's own calls carry it; a direct caller sends the deployed agent's control_headers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… under the protocol's variable The nine install/v1 agents each spell AGENTENV_CONTROL_TOKEN in their own install files. One that drifted would install fine and serve its extension routes open, so a test checks that each declares control_token in optional_params (and optional_params_host where it installs on a host) and that its install reads CONTROL_TOKEN_ENV. It also pins which agents install, so a new one meets the check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hrough a heredoc Their install commands each run docker, so the token's command is a docker exec too: the install's shell expands the exported AGENTENV_CONTROL_TOKEN into a heredoc appended to the agent's 0600 env file, off any command line, as its credentials are. Without one it appends an empty value, which the SDK reads as no token. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…control-token-guard
It writes verifications, so it declares step_role = StepRole.GRADER as the other validator checks do since main added step roles. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…utes send its control token The agents these tests deploy now take their control token, so a test's own call to an agent's /ext/* route sends the deployed record's control_headers, as agent-env's do. The triggers e2e also checks a call without it is refused with a 401 on a real deploy, and the proxy's container install, handed a token as install_agent hands it, refuses a claim without it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s control token Its RegisterAgentTriggersStep runs on a DeployedAgent the test builds from the deploy, which now carries the deploy's control_token as agent-env's records do; the state read after it sends the token too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Linux box results (Ubuntu 24.04, c6i.4xlarge, local Docker and a local registry):
The unit tier passes in GitHub CI and in CodeBuild (16,452 passed). |
The 401 warning carried the message raised to the caller, which keeps up to 500 characters of the body for reads made with include_body. It now logs the operation, status and hint only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Agent matrix with the guard actually in the agents, on a Linux box at The shipped agent folders install the newest SDK from PyPI, so a normal bundle run never exercises an unreleased guard. For this run, every agent folder's
What each case checks:
Negative control: hermes rebuilt on the released SDK. The same check reports the route open ( The existing agent suites, rerun with the guard in the images, passed 38 of 38 with no skips: Not from this PR: openhands and pi installed into a task container fail |
What
An agent's extension routes now take its control token. Since 0.9.1556, agent-env records a token for each deployed agent and sends it on every call to the agent's
/ext/*routes. This PR hands that token to the agent and has the protocol SDK require it.SDK (
agentenv-framework-protocol)AGENTENV_CONTROL_TOKEN(CONTROL_TOKEN_ENV) out of the environment, so the CLIs and tools the agent runs never inherit it. This happens in its lifespan, which runs underserve()and under any ASGI server, so it also covers the bundled agents that runuvicorn a2a_server:app._route_handler) answers a call that doesn't carryAgentEnv-Control-Tokenwith a 401, before the body is read, and logs the refusal (hmac.compare_digest)./a2a, the card,/health, staging and the peer-agents MCP endpoint stay open.ControlTokenMiddlewaregives the same check to an agent that serves/ext/*by hand.Framework
A2AAgent.deployhands the agent the token it records, set last in the agent's environment so a caller's env var can't stand in for it.install/v1 gains
optional_params(optional_params_hostfor a host install).install_agentexportscontrol_tokento every install command asAGENTENV_CONTROL_TOKEN, never as a{placeholder}. So an installer that doesn't know the param still installs the agent, just without a token, instead of failing on an unknown placeholder.The nine bundled install/v1 agents declare it, and write the token where their server reads its environment:
install.sh'sagent.env;docker exec -eby name.None of them puts it on a command line.
The validator gains
verify_a2a_control_token. It calls a read every SDK agent serves (mcp-configlist, else agent-configget), first without the token and then with it. It reportsverifications["a2a_control_token"]and gates nothing.An extension call refused with a 401 now says the agent refused its control token, and logs a warning. That makes a missing or stale token visible on the trajectory reads, which otherwise fail quietly.
Compatibility
Breaking: an agent built on this SDK and deployed or installed by this agent-env refuses a call to its
/ext/*routes withoutAgentEnv-Control-Token. agent-env's own calls carry it. A direct caller sends the deployed agent'scontrol_headers.As it starts serving, the agent logs whether its extension routes take its token or are open, so an agent deployed without one is visible.
Tests
Authorization, and answer one with it;/healthand the card stay open;/ext/*but staging and the peer tools.export AGENTENV_CONTROL_TOKEN=<the recorded token>, which isn't logged; an unknown optional param is ignored.The unit tier and the integration suites that deploy and install agents on local Docker are running on a Linux box. The echo agent there is built from this checkout, so they exercise the check end to end. I'll post the results here.
Follow-up, not in this PR: a shared client for agent extension calls, and making
headersrequired on the public helpers.🤖 Generated with Claude Code


Confidence Score: 5/5
The changes reviewed in this follow-up appear safe to merge.Summary
Agents now require their deployment's control token on extension calls, with token delivery through deployment and installation. The latest update keeps response bodies out of refusal warnings while preserving error details for callers.
Reviews (12) · Last reviewed commit: "fix(agents): a refused control token is ..." · Reviewed by Greptile