Skip to content

feat(agents)!: an agent's extension routes take its control token - #780

Merged
earakely-scale merged 11 commits into
mainfrom
edgararakelyan/agent-control-token-guard
Nov 18, 2026
Merged

earakely-scale merged 11 commits into
mainfrom
edgararakelyan/agent-control-token-guard

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

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)

  • When an agent application starts serving, it takes 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 under serve() and under any ASGI server, so it also covers the bundled agents that run uvicorn a2a_server:app.
  • From then on, every extension operation (_route_handler) answers a call that doesn't carry AgentEnv-Control-Token with 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.
  • An agent with no token configured, or an application that isn't served (in-process, tests), stays open as before.
  • ControlTokenMiddleware gives the same check to an agent that serves /ext/* by hand.

Framework

  • A2AAgent.deploy hands 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_host for a host install). install_agent exports control_token to every install command as AGENTENV_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:

    • claude-code, codex, gemini, letta-code and opencode write it in install.sh's agent.env;
    • pi, openhands and pydantic-ai append it to their 0600 env file through a pipe;
    • proxy passes it through docker exec -e by 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-config list, else agent-config get), first without the token and then with it. It reports verifications["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 without AgentEnv-Control-Token. agent-env's own calls carry it. A direct caller sends the deployed agent's control_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.

  • Callers: framework callers have sent the token since 0.9.1556. The scaleapi and synthetic-pipelines callers are deployed.
  • When a guard turns on: only for an agent whose image is built on this SDK and that is deployed or installed by this framework. Everything older stays open:
    • an image built on an older SDK ignores the token;
    • an older framework hands the agent none.
  • Rebuilt images: an agent image rebuilt after this release, on a newer SDK, picks the check up.

Tests

  • Protocol:
    • a served agent takes its token out of the environment;
    • its routes refuse a call with no token, a wrong one, or the token as a Bearer in Authorization, and answer one with it;
    • /health and the card stay open;
    • an agent that isn't served, or has no token, stays open;
    • the middleware guards /ext/* but staging and the peer tools.
  • Deploy: the agent's environment carries the recorded token, over a caller-supplied one.
  • Install: the install commands get export AGENTENV_CONTROL_TOKEN=<the recorded token>, which isn't logged; an unknown optional param is ignored.
  • Validator: a guarded agent passes; an open one, an agent with no guarded read, or one with no token on its record fails.

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 headers required on the public helpers.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence 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.

  • Served agents check a control token on extension routes.
  • Each deployment gives the agent and its callers the same token.
  • Installable agents carry the deployment token into their server environment.
  • Agent checks now report whether extension reads require a token.
  • A 401 now explains that an agent refused its token.

Reviews (12) · Last reviewed commit: "fix(agents): a refused control token is ..." · Reviewed by Greptile

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>
earakely-scale and others added 2 commits November 18, 2026 09:50
… 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>
Comment thread tst/unit/agents/pi/test_pi_agent.py Resolved
…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>
@earakely-scale earakely-scale changed the title feat(agents): an agent's extension routes take its control token feat(agents)!: an agent's extension routes take its control token Nov 18, 2026
earakely-scale and others added 4 commits November 18, 2026 10:07
… 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>
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>
Comment thread src/agent_env/a2a_agent/protocol.py Resolved
…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>
@earakely-scale

earakely-scale commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator Author

Linux box results (Ubuntu 24.04, c6i.4xlarge, local Docker and a local registry):

  • 8003fcf5, 29 passed, 0 skipped. Each run goes through deploy, prompt, trajectory reads and agent-config from agent-env's own calls.
    • proxy_container_install_test: the proxy, installed with this checkout's SDK by its install.sh with a token exported as install_agent exports it, refuses a claim without the token and answers one with it.
    • The openhands, pydantic-ai, browser-use and claude-code bundle runs. Correction: these images are built from the shipped folders, which install the newest SDK from PyPI, so the guard isn't in them. The runs show agent-env still works with these agents, not that they enforce the token.
    • run_role_models_test.
  • b3667649, 13 passed, 53 skipped. The skips are capability gaps on the box: no remote sandbox, model endpoint or default agent.
    • proxy_local_container_test: an agent installed into a task container through install_agent.
    • run_bundle_claude_code_install_test.
    • The echo-agent task-step and bundle suites.
  • agent_triggers_e2e_test needs Modal, so it runs only in the CodeBuild "Integration Tests" check. There it now also checks that a call without the token is refused with a 401 on a real deploy.

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>
@earakely-scale

Copy link
Copy Markdown
Collaborator Author

Agent matrix with the guard actually in the agents, on a Linux box at bc65dfad (Ubuntu 24.04, local Docker, local registry).

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 agentenv-framework-protocol[agent] requirement pointed at a wheel built from this checkout and served on the box; image builds and install.sh installs both picked it up. Each case is one agent-env run bundle task against fake model endpoints, with no model key.

Agent Deploy Install
claude-code ✓ ✓
codex ✓ token checks only ✓ token checks only
gemini ✓ token checks only ✓ token checks only
letta-code ✓ ✓
opencode ✓ ✓
openhands ✓ ✓ without add_skills (below)
pi ✓ ✓ without add_skills (below)
pydantic-ai ✓ ✓
hermes ✓ token checks only no install path

What each case checks:

  • verify_a2a_control_token: a guarded read without the token gets 401, and with the record's token it doesn't. This held in all 17 cases.
  • add_skills succeeds: agent-env's own guarded call, sent with the record's token.
  • With a prompt (all but codex, gemini and hermes, whose model APIs have no fake here): the agent's own shell runs env | grep -c '^AGENTENV_CONTROL_TOKEN=' and gets 0, the response verifier passes, and the prompt's trajectory is stored. A trajectory read that gets a 401 fails silently, so the stored trajectory is the check.

Negative control: hermes rebuilt on the released SDK. The same check reports the route open (refuses_without_token: false), and the case fails.

The existing agent suites, rerun with the guard in the images, passed 38 of 38 with no skips: proxy_container_install, proxy_local_container, run_bundle_claude_code, run_bundle_claude_code_install, run_bundle_openhands, run_bundle_pydantic_ai, run_bundle_browser_use, run_bundle_installed_agent, run_role_models.

Not from this PR: openhands and pi installed into a task container fail add_skills with 502 transfer_unavailable (the agent doesn't reach the local grant server). The same task fails the same way on main at 6e1deee5, and pydantic-ai passes in both.

@earakely-scale
earakely-scale merged commit e605606 into main Nov 18, 2026
64 of 66 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/agent-control-token-guard branch November 18, 2026 20:00
williamloo-scale added a commit that referenced this pull request Nov 19, 2026
# Conflicts:
#	src/agent_env/agents/agents/opencode/requirements.txt
#	tst/unit/agents/opencode/test_image_contract.py
williamloo-scale added a commit that referenced this pull request Nov 19, 2026
# Conflicts:
#	src/agent_env/agents/agents/codex/requirements.txt
#	tst/unit/agents/codex/test_image_contract.py
williamloo-scale added a commit that referenced this pull request Nov 19, 2026
# Conflicts:
#	src/agent_env/agents/agents/hermes/requirements.txt
williamloo-scale added a commit that referenced this pull request Nov 19, 2026
# Conflicts:
#	src/agent_env/agents/agents/letta-code/requirements.txt
williamloo-scale added a commit that referenced this pull request Nov 19, 2026
# Conflicts:
#	src/agent_env/agents/agents/gemini/requirements.txt
#	tst/unit/agents/gemini/test_image_contract.py
williamloo-scale added a commit that referenced this pull request Nov 19, 2026
# Conflicts:
#	src/agent_env/agents/agents/pi/requirements.txt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant