Skip to content

feat(agents): each deployed agent gets a control token, and agent-env sends it on every extension call - #743

Merged
earakely-scale merged 4 commits into
mainfrom
edgararakelyan/agent-control-token
Nov 17, 2026
Merged

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

Conversation

@earakely-scale

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

Copy link
Copy Markdown
Collaborator

Each agent deployment now gets a control token, as env deployments already do, and agent-env sends it on every call it makes to an agent's extension routes. Nothing checks the token yet, and agents ignore the header, so this changes no behaviour. It's the groundwork for the agent SDK to require it.

What changes

  • Minted at deploy. A2AAgent.deploy and install_agent create a token with the same generator computers use. It's kept as control_token on DeployedA2AAgent, in the instance store, and on DeployedAgent, in the run context.
    • Like DeployedEnv.control_token, it isn't redacted. A context rebuilt in another process, such as a resumed run, still has it.
    • Each record's control_headers carries it in its own header, AgentEnv-Control-Token: <token>, named by the protocol package (CONTROL_TOKEN_HEADER, client.control_token_headers). It stays out of Authorization, which front doors such as a private Hugging Face Space, an IAM proxy or a JWT-validating mesh claim for their own login. Env routes keep Authorization: Bearer for now.
    • A plugin env that registers its own agent through metadata["deployed_agent"] can pass control_token there.
  • Sent on every extension call, explicitly, from the agent's record:
    • deploy_agent: MCP registration, skills, agent-config, snapshot load, changelog enable and apply;
    • prompt_agent and always_on: agent-config, trajectory, the live trajectory follower, trigger state and decide;
    • peer_agents, register_agent_triggers, deploy_user_sim_agent, rate_user_satisfaction;
    • the rubric judge, whether from the context or deployed on the fly;
    • agent-state capture (snapshot_agent_state and snapshot series);
    • connect_cdp, the episode proxy and its in-process config;
    • the A2A validator and its checks;
    • a2a-agent add-skill, through register_skill.
  • Helpers. post_agent_config, invoke_transfer, fetch_trajectory, follow_trajectory and ProxyClient take headers, optional so outside callers keep working. The private helpers along the way take them as required arguments, so a new call path has to say what it sends.

Not in this change

  • The agent side. Handing the agent its token (AGENTENV_CONTROL_TOKEN, and install/v1's control_token param) and the SDK check that refuses a call without it come in their own change.
  • Staging calls are unchanged: staging keeps its capability ids.

Tests

  • New:
    • Each deploy gets its own token, and the instance store round-trips it.
    • install_agent records it.
    • deploy_agent sends it on every request to the agent.
    • prompt_agent sends it on agent-config.
    • The trajectory follower and the proxy client send the headers they're given.
  • Updated: the existing tests whose stand-in records and fake clients predate the field.
  • Run: on a Linux box from uv sync --locked --extra dev.
    • tst/unit/a2a_agent, tst/unit/task_step and tst/unit/task: 3,909 passed. The 3 failures fail the same way on main on that box: run_docker_container_test's real local sandbox, and two mcp_cli_builder tests.
    • packages/agentenv-protocol/tests: 1,637 passed.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; no actionable new issues were found.

Summary

The PR creates a token for each agent deployment, saves it with the deployment records, and sends it through AgentEnv-Control-Token on extension calls.

  • Each deployed agent keeps its own control token in its records.
  • Agent-env sends the control-token header on its extension calls.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Deploy["Deploy or install agent"] --> Token["Create control_token"]
  Token --> Store["Save deployment record"]
  Store --> Context["Build run context"]
  Context --> Headers["Read control_headers"]
  Headers --> Calls["Call agent extensions with AgentEnv-Control-Token"]
Loading

Reviews (6) · Last reviewed commit: "refactor(a2a-agent): read the judge's co..." · Reviewed by Greptile

earakely-scale and others added 2 commits November 16, 2026 22:33
… sends it on every extension call

A2AAgent.deploy and install_agent mint a per-deploy token and keep it as control_token on DeployedA2AAgent and DeployedAgent, unredacted like DeployedEnv.control_token, so a context rebuilt in another process still has it. Each record's control_headers carry it as Authorization: Bearer.

Every call agent-env makes to an agent's extension routes now sends those headers: deploy_agent's MCP, skill, agent-config, snapshot and changelog calls; prompt_agent and always_on (agent-config, trajectory, the live follower, trigger state and decide); peer and trigger registration; the rubric judge; agent-state capture; connect_cdp; the episode proxy; the validator checks. post_agent_config, invoke_transfer, fetch_trajectory, follow_trajectory and ProxyClient take headers.

The agent isn't handed the token yet and nothing checks it: agents ignore the header today. The SDK check, the env var and install/v1's control_token param follow in their own change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oken too; test doubles take it

LiveTurn, not LiveTurns, calls follow_trajectory, so the headers travel with each turn through following_live_trajectory. The tests' stand-in records gain control_token and control_headers, and their fake clients take headers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale and others added 2 commits November 17, 2026 10:45
…ken, not Authorization

A front door in front of an agent (a private Hugging Face Space, an IAM proxy, a mesh that validates every bearer as a JWT) claims Authorization for its own login, so the agent's token takes a header of its own. The protocol package names it (CONTROL_TOKEN_HEADER) and builds it (client.control_token_headers), and both agent records' control_headers use it. Env routes keep Authorization: Bearer for now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rs keyword-only

The rubric verifier read the judge's control headers through a getattr fallback, so a
judge record without them would silently send no token. Both record types carry
control_headers, so read it directly. headers is keyword-only on _decide and ProxyClient,
so a positional dict can't land in the wrong slot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit c1fab78 into main Nov 17, 2026
39 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/agent-control-token branch November 17, 2026 21:41
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