Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1397,6 +1397,31 @@ next `await`. A process `run()` started keeps running unless `run()` stops it,
so kill it before re-raising. Trajectory events it appended, including any it
appends while cleaning up, are kept, and its log ends `canceled`.

#### The control token

agent-env deploys each agent with a token of its own in `AGENTENV_CONTROL_TOKEN`
(`CONTROL_TOKEN_ENV`), and sends it on every call to the agent's extension routes
in the `AgentEnv-Control-Token` header (`CONTROL_TOKEN_HEADER`;
`client.control_token_headers(token)`), never in `Authorization`, which a front
door may claim. When the application starts serving, under `serve()` or any ASGI
server that runs its lifespan, it takes the token out of the environment, so the
CLIs and tools the agent runs never inherit it, and from then on every extension
operation refuses a call without it with a 401, before its body is read, and logs
the refusal. `/a2a`, the card, `/health`, staging and the peer-agents MCP endpoint
stay open. An agent deployed without a token, or an application that isn't served,
answers anyone, as before.

An agent that serves its `/ext/*` routes by hand adds `ControlTokenMiddleware`
(`Middleware(ControlTokenMiddleware)`), which takes the token the same way and
guards every `/ext/` path but staging and the peer-agents MCP endpoint.

An agent installed into a running container (`install/v1`) gets its token when its
declaration lists it in `optional_params` (`optional_params_host` for a host
install): the installer exports it to every install command as
`AGENTENV_CONTROL_TOKEN`, and the agent's install writes it where the agent's
server reads its environment. An optional param is never a `{placeholder}`, so an
installer that doesn't know it still installs the agent, without a token.

#### Live trajectories

A runtime that sees its native events as they happen appends each complete
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@
extension,
request_fields,
)
from .control_token import ControlTokenMiddleware
from .framework import (
A2AAgentApplication,
AgentEnvAgent,
Expand Down Expand Up @@ -155,6 +156,7 @@
"TRIGGERS_V1",
"CLOCK_V1",
"A2AAgentApplication",
"ControlTokenMiddleware",
"AgentCapabilities",
"AgentConfig",
"AgentEnvAgent",
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
"""The agent's control token: agent-env hands each deployed agent one (``CONTROL_TOKEN_ENV``), and the agent's
extension routes refuse a call that doesn't carry it in ``CONTROL_TOKEN_HEADER``. An agent with no token configured
serves them to anyone, as before."""

from __future__ import annotations

import hmac
import logging
import os
from collections.abc import Mapping

from starlette.datastructures import Headers
from starlette.responses import JSONResponse
from starlette.types import ASGIApp, Receive, Scope, Send

from ..types import CONTROL_TOKEN_ENV, CONTROL_TOKEN_HEADER
from .peer_agents import PEER_MCP_PATH
from .staging import STAGING_ENDPOINT

logger = logging.getLogger(__name__)

REFUSAL = f"this route takes the agent's control token in the {CONTROL_TOKEN_HEADER} header"


def take_control_token() -> str | None:
"""The token agent-env handed the agent, taken out of the environment so the tools and CLIs the agent runs never
inherit it."""
return os.environ.pop(CONTROL_TOKEN_ENV, None) or None


def carries_control_token(headers: Mapping[str, str], token: str | None) -> bool:
"""Whether a call's ``headers`` carry ``token``; with no token, any do."""
if token is None:
return True
return hmac.compare_digest(headers.get(CONTROL_TOKEN_HEADER, "").encode(), token.encode())


def log_guard(token: str | None) -> None:
"""Say, as serving starts, whether the extension routes take a token: an agent deployed without one serves them
open, which is otherwise silent."""
if token is None:
logger.info("no %s: the extension routes are open", CONTROL_TOKEN_ENV)
else:
logger.info("the extension routes take the agent's control token (%s)", CONTROL_TOKEN_HEADER)


def log_refusal(method: str, path: str, client: str | None) -> None:
logger.warning("refused %s %s from %s: no valid %s", method, path, client or "unknown", CONTROL_TOKEN_HEADER)


class ControlTokenMiddleware:
"""The SDK's check for an agent that serves its ``/ext/*`` routes by hand: each one but staging and the peer-agents
MCP endpoint refuses a call without the agent's token with a 401. The token is taken out of the environment when
the application builds its middleware, as it starts serving, unless one is given."""

def __init__(self, app: ASGIApp, *, token: str | None = None) -> None:
self.app = app
self.token = token or take_control_token()
log_guard(self.token)

async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if scope["type"] == "http" and _guarded(_route_path(scope)):
if not carries_control_token(Headers(scope=scope), self.token):
client = scope.get("client")
log_refusal(scope.get("method", ""), scope["path"], client[0] if client else None)
await JSONResponse({"detail": REFUSAL}, status_code=401)(scope, receive, send)
return
await self.app(scope, receive, send)


def _route_path(scope: Scope) -> str:
"""The path the app's routes match, without the prefix it is mounted under, as Starlette's router reads it."""
path, root = scope["path"], scope.get("root_path", "")
return path[len(root):] if root and path.startswith(root) else path


def _guarded(path: str) -> bool:
return path.startswith("/ext/") and not any(
path == open_path or path.startswith(open_path + "/") for open_path in (STAGING_ENDPOINT, PEER_MCP_PATH)
)
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@
)
from ..computer.errors import ComputerError
from . import clock as agent_clock
from .control_token import REFUSAL, carries_control_token, log_guard, log_refusal, take_control_token
from .peer_agents import PEER_MCP_PATH, PEER_MCP_SERVER_NAME, PeerAgents
from .registry import RegisteredOperation, build_registry
from .staging import STAGING_ENDPOINT, StagingStore, staging_routes
Expand Down Expand Up @@ -978,6 +979,26 @@ async def lifespan(app: Starlette) -> AsyncIterator[Any]:
return lifespan


def _taking_the_control_token(
application: "A2AAgentApplication",
inner: Callable[[Starlette], AbstractAsyncContextManager] | None,
) -> Callable[[Starlette], AbstractAsyncContextManager]:
"""The application's lifespan, ``inner``'s if it has one: serving starts by taking the agent's control token out of
the environment, and the extension routes take it from then on. An application that isn't served stays open."""

@asynccontextmanager
async def lifespan(app: Starlette) -> AsyncIterator[Any]:
application.control_token = take_control_token() or application.control_token
log_guard(application.control_token)
if inner is None:
yield None
else:
async with inner(app) as state:
yield state

return lifespan


class A2AAgentApplication:
"""Resolved Agent Card, extension routes, and A2A task executor."""

Expand Down Expand Up @@ -1088,10 +1109,12 @@ def __init__(self, agent: Any, definition: _AgentDefinition | None = None) -> No
if self.services.peers is not None:
routes.append(Route(PEER_MCP_PATH, self.services.peers.app))
lifespan = _serving_peer_tools(self.services.peers, lifespan)
kwargs = {"routes": routes, "middleware": [Middleware(_ServingOnItsPort)]}
if lifespan is not None:
kwargs["lifespan"] = lifespan
self.app = Starlette(**kwargs)
self.control_token: str | None = None
self.app = Starlette(
routes=routes,
middleware=[Middleware(_ServingOnItsPort)],
lifespan=_taking_the_control_token(self, lifespan),
)

try:
from a2a.server.apps import A2AStarletteApplication
Expand Down Expand Up @@ -1158,6 +1181,9 @@ def _route_handler(
self, extension_uri: str, operation: RegisteredOperation
) -> Callable:
async def invoke(request: Request) -> JSONResponse:
if not carries_control_token(request.headers, self.control_token):
log_refusal(request.method, request.url.path, request.client.host if request.client else None)
return JSONResponse({"detail": REFUSAL}, status_code=401)
try:
if operation.definition.method == "GET":
payload = dict(request.query_params)
Expand Down
68 changes: 68 additions & 0 deletions packages/agentenv-protocol/tests/test_a2a_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import asyncio
import inspect
import json
import os
import time
from dataclasses import FrozenInstanceError
from functools import wraps
Expand Down Expand Up @@ -44,6 +45,7 @@
AgentEnvAgent,
AgentIdentity,
AttributionProbeResponse,
ControlTokenMiddleware,
BuiltinTools,
BundleSkillRequest,
ContextObjectTrajectoryRequest,
Expand Down Expand Up @@ -99,7 +101,12 @@
_SdkServices,
_StandardExecutor,
)
from agentenv_protocol import CONTROL_TOKEN_ENV, client as protocol_client
from pydantic import BaseModel, Field, ValidationError, field_serializer
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import PlainTextResponse
from starlette.routing import Mount, Route
from starlette.testclient import TestClient


Expand Down Expand Up @@ -3024,3 +3031,64 @@ def state(client: TestClient, task_id: str) -> str:

assert cancelled == ["hang"]
assert ran == ["hang", "next"]


@a2a_agent(identity=AgentIdentity(name="guarded", description="test", version="1"), extensions=(MCP_CONFIG_V1,))
class _GuardedAgent(AgentEnvAgent):
async def run(self, request: TaskRequest) -> TaskResult:
return TaskResult.text("ok")


def test_a_served_agent_takes_its_control_token_out_of_the_environment_and_its_routes_refuse_calls_without_it(
monkeypatch, caplog,
) -> None:
monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")

with caplog.at_level("INFO", logger="agentenv_protocol.a2a_agent.control_token"), \
TestClient(_GuardedAgent().create_app()) as agent:
left_in_environment = CONTROL_TOKEN_ENV in os.environ
refused = [
agent.get("/ext/mcp-config", headers=headers).status_code
for headers in ({}, protocol_client.control_token_headers("guess"), {"Authorization": "Bearer s3cret"})
]
detail = agent.get("/ext/mcp-config").json()["detail"]
answered = agent.get("/ext/mcp-config", headers=protocol_client.control_token_headers("s3cret"))
still_open = [agent.get(path).status_code for path in ("/health", "/.well-known/agent.json")]

assert not left_in_environment and "the extension routes take the agent's control token" in caplog.text
assert "s3cret" not in caplog.text
assert refused == [401, 401, 401] and "AgentEnv-Control-Token" in detail
assert answered.status_code == 200 and answered.json() == {"mcp_servers": {}}
assert still_open == [200, 200]


def test_an_agent_with_no_token_or_not_served_keeps_its_routes_open(monkeypatch, caplog) -> None:
monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")
unserved = TestClient(_GuardedAgent().create_app()).get("/ext/mcp-config").status_code
monkeypatch.delenv(CONTROL_TOKEN_ENV)

with caplog.at_level("INFO", logger="agentenv_protocol.a2a_agent.control_token"), \
TestClient(_GuardedAgent().create_app()) as agent:
tokenless = agent.get("/ext/mcp-config").status_code

assert unserved == tokenless == 200
assert f"no {CONTROL_TOKEN_ENV}: the extension routes are open" in caplog.text


def test_the_middleware_guards_a_hand_served_agents_extension_routes_where_its_app_is_mounted_but_staging_and_the_peer_tools(
monkeypatch,
) -> None:
monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret")

async def ok(request):
return PlainTextResponse("ok")

paths = ("/ext/agent-config", "/ext/staging/abc", "/ext/peer-agents/mcp", "/health")
agent_app = Starlette(routes=[Route(path, ok) for path in paths], middleware=[Middleware(ControlTokenMiddleware)])
with TestClient(Starlette(routes=[Mount("/agent", agent_app)])) as agent:
without = [agent.get(f"/agent{path}").status_code for path in paths]
with_token = agent.get("/agent/ext/agent-config", headers=protocol_client.control_token_headers("s3cret"))
left_in_environment = CONTROL_TOKEN_ENV in os.environ

assert without == [401, 200, 200, 200]
assert with_token.status_code == 200 and not left_in_environment
6 changes: 5 additions & 1 deletion src/agent_env/a2a_agent/a2a_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

from agentenv_protocol import client as protocol_v1
from agentenv_protocol.a2a_agent import STANDARD_EXTENSIONS
from agentenv_protocol.types import CONTROL_TOKEN_ENV

from agent_env.config import get_config
from agent_env.config.model import MODEL_HEADERS_ENV
Expand Down Expand Up @@ -541,6 +542,9 @@ async def deploy(
resolved_env["LITELLM_BASE_URL"] = (provider or sandbox).url_from_sandbox(resolved_env["LITELLM_BASE_URL"])

merged_env = await asyncio.to_thread(self._build_merged_env, resolved_env, a2a_port)
# Last, so no caller's env var stands in for it: the agent's extension routes take it from here on.
control_token = new_control_token()
merged_env[CONTROL_TOKEN_ENV] = control_token
image = self.docker_image_artifact
image_name = image.image_name
if provider is None:
Expand Down Expand Up @@ -600,7 +604,7 @@ async def deploy(
a2a_url=a2a_url, sandbox_id=self._sandbox.sandbox_id,
agent_card=agent_card, sandbox_type=self._sandbox.type,
network_policy=self._sandbox.network_policy.to_dict() if self._sandbox.network_policy else None,
control_token=new_control_token(),
control_token=control_token,
)
from agent_env.a2a_agent.store import get_a2a_agent_instance_store
deployed = get_a2a_agent_instance_store().create_instance(deployed, ttl_seconds)
Expand Down
9 changes: 6 additions & 3 deletions src/agent_env/a2a_agent/protocol.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ class AgentUnreachableError(TimeoutError):


_ERROR_CODE = re.compile(r"[a-z][a-z0-9_]{0,63}")
_REFUSED = " (the agent refused its control token: the record it was sent from has none, or another deployment's)"


def raise_for_extension_status(
Expand All @@ -60,9 +61,11 @@ def raise_for_extension_status(
error = body.get("error") if isinstance(body, Mapping) else None
code = error.get("code") if isinstance(error, Mapping) else None
detail = code if isinstance(code, str) and _ERROR_CODE.fullmatch(code) else ""
message = f"{operation} failed with HTTP {response.status_code}"
if detail:
message += f": {detail}"
status = f"{operation} failed with HTTP {response.status_code}"
refused = _REFUSED if response.status_code == 401 else ""
if refused:
logger.warning(status + refused)
message = status + (f": {detail}" if detail else "") + refused
raise httpx.HTTPStatusError(message, request=exc.request, response=response) from exc


Expand Down
2 changes: 2 additions & 0 deletions src/agent_env/a2a_agent/validator.py
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,7 @@ async def _run(
VerifyA2AAgentCardStep,
VerifyA2AAgentConfigIdentityStep,
VerifyA2AAgentMCPStep,
VerifyA2AControlTokenStep,
VerifyA2ABuiltinToolsStep,
VerifyA2AModalitiesStep,
VerifyA2APeerAgentsStep,
Expand Down Expand Up @@ -303,6 +304,7 @@ async def _run(
DeployAgentTaskStep(id=deploy_agent_id, version=None, env_ids=[agent.VALIDATION_ENV_ID], a2a_agent_id=agent.id, a2a_agent_version=agent.version),
VerifyA2AAgentCardStep(id=f"{task_id}-card", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False),
VerifyA2AAgentConfigIdentityStep(id=f"{task_id}-agent-config-identity", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False),
VerifyA2AControlTokenStep(id=f"{task_id}-control-token", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False),
VerifyA2ARoleStep(id=f"{task_id}-role", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False),
VerifyA2ABuiltinToolsStep(id=f"{task_id}-builtin-tools", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False),
VerifyA2ASystemPromptStep(id=f"{task_id}-system-prompt", version=None, a2a_agent_id=agent.id, a2a_agent_version=agent.version, depends_on=deploy_agent_dep, fail_task_on_error=False),
Expand Down
2 changes: 2 additions & 0 deletions src/agent_env/agents/agents/claude-code/a2a_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -417,8 +417,10 @@ async def _turns_stop_with_the_server(app: Starlette) -> AsyncIterator[None]:
description="Commands to install this agent into a running task container, or onto its sandbox's host.",
install_commands=_INSTALL_COMMANDS,
a2a_port=_A2A_PORT,
optional_params=["control_token"],
required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS],
install_commands_host=_INSTALL_COMMANDS_HOST,
optional_params_host=["control_token"],
required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS],
workdir_host=_HOST_WORKDIR,
user_host="root",
Expand Down
1 change: 1 addition & 0 deletions src/agent_env/agents/agents/claude-code/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ chmod 0755 "$stage/claude" "$stage/uv-$uv_cpu-unknown-linux-musl/uv"
printf '%s=%s\n' "$name" "$(quoted "${!name:-}")"
done
[ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV"
[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")"
printf 'A2A_PORT=%s\nCLAUDE_CONFIG_DIR=%s\n' "$(quoted "$port")" "$(quoted "$root/claude")"
printf 'DISABLE_AUTOUPDATER=1\nCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1\n'
} > "$stage/agent.env"
Expand Down
2 changes: 2 additions & 0 deletions src/agent_env/agents/agents/codex/a2a_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -613,8 +613,10 @@ async def _stage_granted_workspace(source: ReadObject | None) -> Path | None:
# Port the agent's A2A server listens on inside the container.
a2a_port=8000,
# Every placeholder referenced in install_commands must be in this list.
optional_params=["control_token"],
required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS],
install_commands_host=_INSTALL_COMMANDS_HOST,
optional_params_host=["control_token"],
required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", *_ENDPOINT_PARAMS],
workdir_host=_HOST_WORKDIR,
user_host="root",
Expand Down
1 change: 1 addition & 0 deletions src/agent_env/agents/agents/codex/install.sh
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ case ${AGENT_TRUST_ENV:-} in *SSL_CERT_FILE=*) needs_cas= ;; esac
printf '%s=%s\n' "$name" "$(quoted "${!name:-}")"
done
[ -z "${AGENT_TRUST_ENV:-}" ] || printf '%s\n' "$AGENT_TRUST_ENV"
[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\n' "$(quoted "$AGENTENV_CONTROL_TOKEN")"
[ -z "$needs_cas" ] || printf 'SSL_CERT_FILE=%s\n' "$(quoted "$certifi")"
printf 'A2A_PORT=%s\nCODEX_HOME=%s\nCODEX_WORKSPACE_DIR=%s\n' \
"$(quoted "$port")" "$(quoted "$root/codex")" "$(quoted "$workspace")"
Expand Down
Loading
Loading