From a504153f6c9ef7ade8c98e275275a71b0fd249dd Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 09:25:13 -0800 Subject: [PATCH 01/10] feat(agents): an agent's extension routes take its control token 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 --- packages/agentenv-protocol/README.md | 25 +++++++ .../agentenv_protocol/a2a_agent/__init__.py | 2 + .../a2a_agent/control_token.py | 64 ++++++++++++++++++ .../agentenv_protocol/a2a_agent/framework.py | 33 +++++++-- .../agentenv-protocol/tests/test_a2a_agent.py | 64 ++++++++++++++++++ src/agent_env/a2a_agent/a2a_agent.py | 6 +- src/agent_env/a2a_agent/protocol.py | 3 + src/agent_env/a2a_agent/validator.py | 2 + .../agents/agents/claude-code/a2a_server.py | 2 + .../agents/agents/claude-code/install.sh | 1 + .../agents/agents/codex/a2a_server.py | 2 + src/agent_env/agents/agents/codex/install.sh | 1 + .../agents/agents/gemini/a2a_server.py | 2 + src/agent_env/agents/agents/gemini/install.sh | 1 + .../agents/agents/letta-code/a2a_server.py | 2 + .../agents/agents/letta-code/install.sh | 1 + .../agents/agents/opencode/a2a_server.py | 2 + .../agents/agents/opencode/install.sh | 1 + .../agents/openhands/openhands_agent.py | 4 ++ src/agent_env/agents/agents/pi/pi_agent.py | 4 ++ .../agents/agents/proxy/a2a_server.py | 2 + src/agent_env/agents/agents/proxy/install.sh | 2 +- .../agents/pydantic-ai/pydantic_ai_agent.py | 4 ++ src/agent_env/task/episode/rules.py | 2 +- src/agent_env/task_step/registry.py | 2 + .../a2a_agent_validator/__init__.py | 2 + .../verify_a2a_control_token.py | 60 +++++++++++++++++ .../task_step/task_steps/install_agent.py | 20 +++++- tst/unit/a2a_agent/deploy_cleanup_test.py | 12 +++- tst/unit/task_step/install_agent_test.py | 19 ++++-- .../test_verify_a2a_control_token.py | 67 +++++++++++++++++++ 31 files changed, 395 insertions(+), 19 deletions(-) create mode 100644 packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py create mode 100644 src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py create mode 100644 tst/unit/task_step/test_verify_a2a_control_token.py diff --git a/packages/agentenv-protocol/README.md b/packages/agentenv-protocol/README.md index 75aaead43..2d26fbdca 100644 --- a/packages/agentenv-protocol/README.md +++ b/packages/agentenv-protocol/README.md @@ -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 diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py index 174561232..af2817887 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/__init__.py @@ -88,6 +88,7 @@ extension, request_fields, ) +from .control_token import ControlTokenMiddleware from .framework import ( A2AAgentApplication, AgentEnvAgent, @@ -155,6 +156,7 @@ "TRIGGERS_V1", "CLOCK_V1", "A2AAgentApplication", + "ControlTokenMiddleware", "AgentCapabilities", "AgentConfig", "AgentEnvAgent", diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py new file mode 100644 index 000000000..90383454d --- /dev/null +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py @@ -0,0 +1,64 @@ +"""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_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() + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] == "http" and _guarded(scope["path"]): + 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 _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) + ) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 6851ab3de..2d7058607 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -64,6 +64,7 @@ ) from ..computer.errors import ComputerError from . import clock as agent_clock +from .control_token import REFUSAL, carries_control_token, 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 @@ -978,6 +979,25 @@ 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 + 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.""" @@ -1088,10 +1108,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 @@ -1158,6 +1180,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) + raise HTTPException(status_code=401, detail=REFUSAL) try: if operation.definition.method == "GET": payload = dict(request.query_params) diff --git a/packages/agentenv-protocol/tests/test_a2a_agent.py b/packages/agentenv-protocol/tests/test_a2a_agent.py index 5e82d5501..f109f6138 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -3,6 +3,7 @@ import asyncio import inspect import json +import os import time from dataclasses import FrozenInstanceError from functools import wraps @@ -44,6 +45,7 @@ AgentEnvAgent, AgentIdentity, AttributionProbeResponse, + ControlTokenMiddleware, BuiltinTools, BundleSkillRequest, ContextObjectTrajectoryRequest, @@ -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 Route from starlette.testclient import TestClient @@ -3024,3 +3031,60 @@ 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, +) -> None: + monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret") + + with 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 + 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) -> None: + monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret") + unserved = TestClient(_GuardedAgent().create_app()).get("/ext/mcp-config").status_code + monkeypatch.delenv(CONTROL_TOKEN_ENV) + + with TestClient(_GuardedAgent().create_app()) as agent: + tokenless = agent.get("/ext/mcp-config").status_code + + assert unserved == tokenless == 200 + + +def test_the_middleware_guards_a_hand_served_agents_extension_routes_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") + app = Starlette(routes=[Route(path, ok) for path in paths], middleware=[Middleware(ControlTokenMiddleware)]) + with TestClient(app) as agent: + without = [agent.get(path).status_code for path in paths] + with_token = agent.get("/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 diff --git a/src/agent_env/a2a_agent/a2a_agent.py b/src/agent_env/a2a_agent/a2a_agent.py index 79e4bb0dd..efdcfc4f5 100644 --- a/src/agent_env/a2a_agent/a2a_agent.py +++ b/src/agent_env/a2a_agent/a2a_agent.py @@ -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 @@ -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: @@ -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) diff --git a/src/agent_env/a2a_agent/protocol.py b/src/agent_env/a2a_agent/protocol.py index 04ae02cfc..963e8db55 100644 --- a/src/agent_env/a2a_agent/protocol.py +++ b/src/agent_env/a2a_agent/protocol.py @@ -63,6 +63,9 @@ def raise_for_extension_status( message = f"{operation} failed with HTTP {response.status_code}" if detail: message += f": {detail}" + if response.status_code == 401: + message += " (the agent refused its control token: the record it was sent from has none, or another deployment's)" + logger.warning(message) raise httpx.HTTPStatusError(message, request=exc.request, response=response) from exc diff --git a/src/agent_env/a2a_agent/validator.py b/src/agent_env/a2a_agent/validator.py index b0f8a66f6..09a72117e 100644 --- a/src/agent_env/a2a_agent/validator.py +++ b/src/agent_env/a2a_agent/validator.py @@ -209,6 +209,7 @@ async def _run( VerifyA2AAgentCardStep, VerifyA2AAgentConfigIdentityStep, VerifyA2AAgentMCPStep, + VerifyA2AControlTokenStep, VerifyA2ABuiltinToolsStep, VerifyA2AModalitiesStep, VerifyA2APeerAgentsStep, @@ -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), diff --git a/src/agent_env/agents/agents/claude-code/a2a_server.py b/src/agent_env/agents/agents/claude-code/a2a_server.py index d01b1dce3..77ab702f8 100644 --- a/src/agent_env/agents/agents/claude-code/a2a_server.py +++ b/src/agent_env/agents/agents/claude-code/a2a_server.py @@ -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", diff --git a/src/agent_env/agents/agents/claude-code/install.sh b/src/agent_env/agents/agents/claude-code/install.sh index fe35f29be..a4f030723 100755 --- a/src/agent_env/agents/agents/claude-code/install.sh +++ b/src/agent_env/agents/agents/claude-code/install.sh @@ -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" diff --git a/src/agent_env/agents/agents/codex/a2a_server.py b/src/agent_env/agents/agents/codex/a2a_server.py index 4ad2be072..44cf656d4 100644 --- a/src/agent_env/agents/agents/codex/a2a_server.py +++ b/src/agent_env/agents/agents/codex/a2a_server.py @@ -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", diff --git a/src/agent_env/agents/agents/codex/install.sh b/src/agent_env/agents/agents/codex/install.sh index 247328b84..57fb9d255 100755 --- a/src/agent_env/agents/agents/codex/install.sh +++ b/src/agent_env/agents/agents/codex/install.sh @@ -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")" diff --git a/src/agent_env/agents/agents/gemini/a2a_server.py b/src/agent_env/agents/agents/gemini/a2a_server.py index 1d4bfacbb..a9a8fca05 100644 --- a/src/agent_env/agents/agents/gemini/a2a_server.py +++ b/src/agent_env/agents/agents/gemini/a2a_server.py @@ -433,9 +433,11 @@ async def _vertex_openai_bridge( "or directly onto a task VM (host mode)." ), install_commands=_INSTALL_COMMANDS, + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port", *_ENDPOINT_PARAMS], install_commands_host=_INSTALL_COMMANDS_HOST, a2a_port=8000, + 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", diff --git a/src/agent_env/agents/agents/gemini/install.sh b/src/agent_env/agents/agents/gemini/install.sh index 9f7b00d1a..954472462 100755 --- a/src/agent_env/agents/agents/gemini/install.sh +++ b/src/agent_env/agents/agents/gemini/install.sh @@ -113,6 +113,7 @@ chmod 0755 "$stage/gemini" 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\nGEMINI_CLI_HOME=%s\nGEMINI_CWD=%s\n' \ "$(quoted "$port")" "$(quoted "$root/gemini")" "$(quoted "$workspace")" } > "$stage/agent.env" diff --git a/src/agent_env/agents/agents/letta-code/a2a_server.py b/src/agent_env/agents/agents/letta-code/a2a_server.py index 57519820b..d11349b52 100644 --- a/src/agent_env/agents/agents/letta-code/a2a_server.py +++ b/src/agent_env/agents/agents/letta-code/a2a_server.py @@ -295,8 +295,10 @@ async def lifespan(app: Starlette): # 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", diff --git a/src/agent_env/agents/agents/letta-code/install.sh b/src/agent_env/agents/agents/letta-code/install.sh index ee3fd9fd2..a89987fdf 100644 --- a/src/agent_env/agents/agents/letta-code/install.sh +++ b/src/agent_env/agents/agents/letta-code/install.sh @@ -122,6 +122,7 @@ chmod 0755 "$stage/letta" 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")" # Letta Code's state, its sessions and skills, as the image keeps it under /data. printf 'A2A_PORT=%s\nLETTA_CODE_WORKSPACE_DIR=%s\nHOME=%s\n' \ "$(quoted "$port")" "$(quoted "$workspace")" "$(quoted "$root/data")" diff --git a/src/agent_env/agents/agents/opencode/a2a_server.py b/src/agent_env/agents/agents/opencode/a2a_server.py index 5bea2eb74..456781eb5 100644 --- a/src/agent_env/agents/agents/opencode/a2a_server.py +++ b/src/agent_env/agents/agents/opencode/a2a_server.py @@ -318,8 +318,10 @@ def memory_mb(cgroup_limit: Path = Path("/sys/fs/cgroup/memory.max")) -> int: # 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", diff --git a/src/agent_env/agents/agents/opencode/install.sh b/src/agent_env/agents/agents/opencode/install.sh index 678ff410f..5785d3bfe 100755 --- a/src/agent_env/agents/agents/opencode/install.sh +++ b/src/agent_env/agents/agents/opencode/install.sh @@ -112,6 +112,7 @@ chmod 0755 "$stage/opencode" 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")" # OpenCode's state, its sessions and skills, as the image keeps it under /data. printf 'A2A_PORT=%s\nOPENCODE_WORKSPACE_DIR=%s\nHOME=%s\n' \ "$(quoted "$port")" "$(quoted "$workspace")" "$(quoted "$root/data")" diff --git a/src/agent_env/agents/agents/openhands/openhands_agent.py b/src/agent_env/agents/agents/openhands/openhands_agent.py index 8ef037d3b..c1334ab93 100644 --- a/src/agent_env/agents/agents/openhands/openhands_agent.py +++ b/src/agent_env/agents/agents/openhands/openhands_agent.py @@ -89,6 +89,9 @@ "LITELLM_BASE_URL={litellm_base_url}\n" "LITELLM_EXTRA_HEADERS={litellm_extra_headers}\n" "OPENHANDS_A2A_ENV", + # agent-env's control token for the agent, when the runner hands it one (install/v1 optional_params), the same way. + "[ -z \"${{AGENTENV_CONTROL_TOKEN:-}}\" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\\n' \"$AGENTENV_CONTROL_TOKEN\" | " + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}'", f"{_DOCKER} exec -d -e A2A_PORT={{a2a_port}} {{container}} sh {INSTALL_DIR}/start.sh", ] @@ -334,6 +337,7 @@ def _stage_conversation(archive: Path, conversations_dir: Path, target_id: str, enable( INSTALL_V1, install_commands=INSTALL_COMMANDS, + optional_params=["control_token"], required_params=[ "container", "agent_ctx_tar", "a2a_port", "litellm_api_key", "litellm_base_url", "litellm_extra_headers", diff --git a/src/agent_env/agents/agents/pi/pi_agent.py b/src/agent_env/agents/agents/pi/pi_agent.py index 9c9b70a86..9970cbbab 100644 --- a/src/agent_env/agents/agents/pi/pi_agent.py +++ b/src/agent_env/agents/agents/pi/pi_agent.py @@ -111,6 +111,9 @@ "LITELLM_API_KEY={litellm_api_key}\n" "LITELLM_BASE_URL={litellm_base_url}\n" "PI_A2A_ENV", + # agent-env's control token for the agent, when the runner hands it one (install/v1 optional_params), the same way. + "[ -z \"${{AGENTENV_CONTROL_TOKEN:-}}\" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\\n' \"$AGENTENV_CONTROL_TOKEN\" | " + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}'", f"{_DOCKER} exec -d -e A2A_PORT={{a2a_port}} {{container}} sh {INSTALL_DIR}/start.sh", ] @@ -378,6 +381,7 @@ def _unpack(archive: Path, directory: Path) -> None: enable( INSTALL_V1, install_commands=INSTALL_COMMANDS, + optional_params=["control_token"], required_params=["container", "agent_ctx_tar", "a2a_port", "litellm_api_key", "litellm_base_url"], a2a_port=8000, ), diff --git a/src/agent_env/agents/agents/proxy/a2a_server.py b/src/agent_env/agents/agents/proxy/a2a_server.py index 938885ccc..ede7a589e 100644 --- a/src/agent_env/agents/agents/proxy/a2a_server.py +++ b/src/agent_env/agents/agents/proxy/a2a_server.py @@ -17,8 +17,10 @@ extensions=( *EXTENSIONS, enable(INSTALL_V1, install_commands=_INSTALL_COMMANDS, + optional_params=["control_token"], required_params=["container", "work_dir", "agent_ctx_tar", "a2a_port"], install_commands_host=_INSTALL_COMMANDS_HOST, + optional_params_host=["control_token"], required_params_host=["work_dir", "agent_ctx_tar", "a2a_port", "agent_name", "host_workdir", "host_user"], a2a_port=8000), ), diff --git a/src/agent_env/agents/agents/proxy/install.sh b/src/agent_env/agents/agents/proxy/install.sh index 1bff9b21f..4ee4fc44f 100644 --- a/src/agent_env/agents/agents/proxy/install.sh +++ b/src/agent_env/agents/agents/proxy/install.sh @@ -67,7 +67,7 @@ case $mode in python=$root/venv/bin/python fi docker cp "$here/a2a_server.py" "$target:$root/a2a_server.py" >/dev/null - docker exec -d -u 0 -e A2A_PORT="$port" "$target" \ + docker exec -d -u 0 -e A2A_PORT="$port" ${AGENTENV_CONTROL_TOKEN:+-e AGENTENV_CONTROL_TOKEN} "$target" \ sh -c "echo \$\$ > $root/proxy.pid; exec $python $root/a2a_server.py > $root/proxy.log 2>&1" ;; *) echo "usage: install.sh host NAME PORT WORKDIR USER | install.sh container NAME PORT" >&2; exit 2 ;; diff --git a/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py b/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py index ea706e084..dcba8a573 100644 --- a/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py +++ b/src/agent_env/agents/agents/pydantic-ai/pydantic_ai_agent.py @@ -93,6 +93,9 @@ # The KEY='VALUE' lines pointing TLS clients at the local transfer CA, which start.sh applies. "AGENT_TRUST_ENV={trust_env}\n" "PYDANTIC_AI_A2A_ENV", + # agent-env's control token for the agent, when the runner hands it one (install/v1 optional_params), the same way. + "[ -z \"${{AGENTENV_CONTROL_TOKEN:-}}\" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\\n' \"$AGENTENV_CONTROL_TOKEN\" | " + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}'", f"{_DOCKER} exec -d -e A2A_PORT={{a2a_port}} {{container}} sh {INSTALL_DIR}/start.sh", ] @@ -354,6 +357,7 @@ def _stage_conversation( enable( INSTALL_V1, install_commands=INSTALL_COMMANDS, + optional_params=["control_token"], required_params=[ "container", "agent_ctx_tar", "a2a_port", "litellm_api_key", "litellm_base_url", "litellm_extra_headers", "trust_env", diff --git a/src/agent_env/task/episode/rules.py b/src/agent_env/task/episode/rules.py index f6cd5045a..02653164c 100644 --- a/src/agent_env/task/episode/rules.py +++ b/src/agent_env/task/episode/rules.py @@ -145,7 +145,7 @@ def _rubrics_verifier(step: RubricsVerifierTaskStep, outside: Outside) -> list[s "always_on_agent_verifier": _rubrics_verifier, **dict.fromkeys(( "verify_a2a_agent_card", "verify_a2a_agent_config_identity", "verify_a2a_agent_mcp", "verify_a2a_builtin_tools", - "verify_a2a_core_protocol", "verify_a2a_install", "verify_a2a_modalities", "verify_a2a_peer_agents", + "verify_a2a_control_token", "verify_a2a_core_protocol", "verify_a2a_install", "verify_a2a_modalities", "verify_a2a_peer_agents", "verify_a2a_role", "verify_a2a_skill_config", "verify_a2a_snapshot", "verify_a2a_system_prompt", "verify_a2a_trajectory", ), _validates_an_agent), diff --git a/src/agent_env/task_step/registry.py b/src/agent_env/task_step/registry.py index c4b5c5b9d..7d42cbb2e 100644 --- a/src/agent_env/task_step/registry.py +++ b/src/agent_env/task_step/registry.py @@ -96,6 +96,7 @@ def _builtin_registry() -> dict[str, type["TaskStep"]]: from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_snapshot import VerifyA2ASnapshotStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_trajectory import VerifyA2ATrajectoryStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_builtin_tools import VerifyA2ABuiltinToolsStep + from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_control_token import VerifyA2AControlTokenStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_role import VerifyA2ARoleStep from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_system_prompt import VerifyA2ASystemPromptStep from agent_env.task_step.task_steps.add_skills import AddSkillsTaskStep @@ -183,6 +184,7 @@ def _builtin_registry() -> dict[str, type["TaskStep"]]: _get_type(AggregateVerifiersTaskStep): AggregateVerifiersTaskStep, _get_type(VerifyA2ABuiltinToolsStep): VerifyA2ABuiltinToolsStep, _get_type(VerifyA2ARoleStep): VerifyA2ARoleStep, + _get_type(VerifyA2AControlTokenStep): VerifyA2AControlTokenStep, _get_type(VerifyA2ASystemPromptStep): VerifyA2ASystemPromptStep, } diff --git a/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py b/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py index a386ca654..3cd15b66b 100644 --- a/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py +++ b/src/agent_env/task_step/task_steps/a2a_agent_validator/__init__.py @@ -1,5 +1,6 @@ from .verify_a2a_agent_card import VerifyA2AAgentCardStep from .verify_a2a_agent_config_identity import VerifyA2AAgentConfigIdentityStep +from .verify_a2a_control_token import VerifyA2AControlTokenStep from .verify_a2a_agent_mcp import VerifyA2AAgentMCPStep from .verify_a2a_builtin_tools import VerifyA2ABuiltinToolsStep from .verify_a2a_core_protocol import VerifyCoreA2AProtocolStep @@ -15,6 +16,7 @@ __all__ = [ "VerifyA2AAgentCardStep", "VerifyA2AAgentConfigIdentityStep", + "VerifyA2AControlTokenStep", "VerifyA2AAgentMCPStep", "VerifyA2ABuiltinToolsStep", "VerifyCoreA2AProtocolStep", diff --git a/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py new file mode 100644 index 000000000..c743de64f --- /dev/null +++ b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py @@ -0,0 +1,60 @@ +"""Verify the agent's extension routes take its control token: a call without it is refused with a 401, one with it is +not.""" +from __future__ import annotations + +import logging +from typing import ClassVar, Optional + +import httpx + +from agent_env.a2a_agent import A2AAgent +from agent_env.entity.refs import EntityRef +from agent_env.task_step.context import TaskStepContext +from agent_env.task_step.task_step import TaskStep, TaskStepDependency + +logger = logging.getLogger(__name__) + +# Reads the SDK serves for every agent that enables the extension, so the check changes nothing on the agent. +_READS = ((A2AAgent.EXT_MCP_CONFIG, "list"), (A2AAgent.EXT_AGENT_CONFIG, "get")) + + +class VerifyA2AControlTokenStep(TaskStep): + type: ClassVar[str] = "verify_a2a_control_token" + entity_refs = (EntityRef.agent("a2a_agent_id", version_field="a2a_agent_version"),) + + def __init__(self, id: str, version: Optional[int], a2a_agent_id: str, a2a_agent_version: Optional[int] = None, + depends_on: Optional[list[TaskStepDependency]] = None, fail_task_on_error: bool = True): + super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error) + self.a2a_agent_id = a2a_agent_id + self.a2a_agent_version = a2a_agent_version + + def to_dict(self) -> dict: + return {**super().to_dict(), "a2a_agent_id": self.a2a_agent_id, "a2a_agent_version": self.a2a_agent_version} + + @classmethod + def from_dict(cls, data: dict) -> "VerifyA2AControlTokenStep": + return cls(**cls._base_from_dict(data), a2a_agent_id=data["a2a_agent_id"], + a2a_agent_version=data.get("a2a_agent_version")) + + async def execute(self, context: TaskStepContext) -> TaskStepContext: + deployed = next((a for a in context.deployed_agents if a.agent_name == TaskStep.DEFAULT_AGENT_NAME), None) + if deployed is None: + raise RuntimeError("VerifyA2AControlTokenStep: no deployed default-agent in context") + card = deployed.a2a_card or {} + route = next((path for uri, name in _READS + if (path := A2AAgent.operation(A2AAgent.find_extension(card, uri), name)[1]) is not None), None) + entry: dict = {"route": route, "refuses_without_token": False, "accepts_with_token": False} + if route is not None and deployed.control_token: + url = (deployed.a2a_url or deployed.api_url) + route + try: + async with httpx.AsyncClient() as client: + without = await client.get(url, timeout=30) + with_token = await client.get(url, headers=deployed.control_headers, timeout=30) + entry["refuses_without_token"] = without.status_code == 401 + entry["accepts_with_token"] = with_token.status_code != 401 + except httpx.HTTPError as e: + logger.warning(f"VerifyA2AControlTokenStep: {url} unreachable: {e}") + entry["passed"] = entry["refuses_without_token"] and entry["accepts_with_token"] + context.metadata.setdefault("verifications", {})["a2a_control_token"] = entry + logger.info(f"control token validation: {entry}") + return context diff --git a/src/agent_env/task_step/task_steps/install_agent.py b/src/agent_env/task_step/task_steps/install_agent.py index c72b74d03..4c0a92d85 100644 --- a/src/agent_env/task_step/task_steps/install_agent.py +++ b/src/agent_env/task_step/task_steps/install_agent.py @@ -4,10 +4,15 @@ varies per install — container name, work dir, agent build context, A2A port, and config-sourced creds. The runner resolves each declared `required_params` entry via the registry below, `shlex.quote`s the value, and `cmd.format(**resolved)`s -each command before exec. No host env vars are exported. +each command before exec. To add a new param: register it in `_build_param_resolvers` (and document what it returns); the agent's extension declares it in `required_params` to opt in. + +`optional_params` lists what an install takes only from a runner that has it, as an +environment variable of every install command rather than a placeholder, so a runner +that doesn't know it still installs the agent: `control_token` is exported as +`AGENTENV_CONTROL_TOKEN`, the token the agent's extension routes then take. """ from __future__ import annotations @@ -37,6 +42,7 @@ from agent_env.task_step.context import DeployedAgent, StepContextError, TaskStepContext from agent_env.entity.refs import EntityRef from agent_env.task_step.task_step import TaskStep, TaskStepDependency +from agentenv_protocol.types import CONTROL_TOKEN_ENV logger = logging.getLogger(__name__) @@ -44,6 +50,8 @@ INSTALL_COMMANDS_HOST_KEY = "install_commands_host" REQUIRED_PARAMS_KEY = "required_params" REQUIRED_PARAMS_HOST_KEY = "required_params_host" +OPTIONAL_PARAMS_KEY = "optional_params" +OPTIONAL_PARAMS_HOST_KEY = "optional_params_host" A2A_PORT_KEY = "a2a_port" WORKDIR_HOST_KEY = "workdir_host" USER_HOST_KEY = "user_host" @@ -278,6 +286,7 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: install_commands = params.get(commands_key) a2a_port = self.a2a_port or params.get(A2A_PORT_KEY) required_params = params.get(REQUIRED_PARAMS_HOST_KEY if host_mode else REQUIRED_PARAMS_KEY) or [] + optional_params = params.get(OPTIONAL_PARAMS_HOST_KEY if host_mode else OPTIONAL_PARAMS_KEY) or [] if host_mode and not install_commands: raise RuntimeError( f"Agent {agent.id} v{agent.version} install/v1 params have no '{INSTALL_COMMANDS_HOST_KEY}'; " @@ -289,6 +298,8 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: raise RuntimeError(f"Agent {agent.id} v{agent.version} install/v1 params missing '{A2A_PORT_KEY}' (int) and the step has no a2a_port override") if not isinstance(required_params, list): raise RuntimeError(f"Agent {agent.id} v{agent.version} install/v1 params 'required_params' must be a list") + if not isinstance(optional_params, list): + raise RuntimeError(f"Agent {agent.id} v{agent.version} install/v1 params 'optional_params' must be a list") if not ds.tunnel_urls or str(a2a_port) not in ds.tunnel_urls: raise RuntimeError( @@ -340,6 +351,9 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: raise RuntimeError(f"Failed to resolve required_param {name!r}: {e}") from e resolved[name] = shlex.quote(raw) + control_token = new_control_token() + exported = f"export {CONTROL_TOKEN_ENV}={shlex.quote(control_token)}\n" if "control_token" in optional_params else "" + target = "the VM host" if host_mode else f"container '{self.container_name}'" logger.info( f"Running {len(install_commands)} install command(s) against {target} " @@ -355,14 +369,14 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: ) # The template, not the command: resolved params carry the model key and headers. logger.info(f" [{i}/{len(install_commands)}] {cmd.splitlines()[0][:140]}") - await sandbox.exec_script(formatted) + await sandbox.exec_script(exported + formatted) if not host_mode: # copied into the container; a host install may run from it await sandbox.exec_script(f"rm -rf {shlex.quote(work_dir)}") agent_card = await self._wait_for_agent_card(a2a_url) logger.info(f"Agent '{self.agent_name}' reachable at {a2a_url} (card name={agent_card.get('name')})") - deployed = self._register_instance(agent, a2a_url, ds, agent_card, new_control_token()) + deployed = self._register_instance(agent, a2a_url, ds, agent_card, control_token) context.deployed_agents.append(DeployedAgent( agent_name=self.agent_name, diff --git a/tst/unit/a2a_agent/deploy_cleanup_test.py b/tst/unit/a2a_agent/deploy_cleanup_test.py index 131e6ed91..1a68c24a2 100644 --- a/tst/unit/a2a_agent/deploy_cleanup_test.py +++ b/tst/unit/a2a_agent/deploy_cleanup_test.py @@ -51,9 +51,14 @@ async def wait_for_card(self, url): @pytest.mark.asyncio -async def test_each_deploy_is_recorded_with_a_control_token_of_its_own(monkeypatch, local_stores): +async def test_each_deploy_is_recorded_with_a_control_token_of_its_own_which_the_agent_is_handed( + monkeypatch, local_stores, +): + handed: list[str | None] = [] + class _Provider(SandboxProvider): - async def create_sandbox(self, **_): + async def create_sandbox(self, *, env, **_): + handed.append(env.get("AGENTENV_CONTROL_TOKEN")) return _Sandbox() async def card(self, url): @@ -62,11 +67,12 @@ async def card(self, url): monkeypatch.setattr(sandbox_provider, "build_sandbox_provider", lambda name: _Provider()) monkeypatch.setattr(A2AAgent, "_wait_for_agent_card", card) agent = A2AAgent(id="solver", version=1, docker_image_artifact=DockerImageArtifact(id="img", description="d", image_name="img")) - env_vars = {"LITELLM_API_KEY": "k", "LITELLM_BASE_URL": "http://llm"} + env_vars = {"LITELLM_API_KEY": "k", "LITELLM_BASE_URL": "http://llm", "AGENTENV_CONTROL_TOKEN": "caller-chosen"} first = await agent.deploy(sandbox_type="fake", env_vars=env_vars) second = await agent.deploy(sandbox_type="fake", env_vars=env_vars) assert first.control_token and second.control_token and first.control_token != second.control_token + assert handed == [first.control_token, second.control_token] assert first.control_headers == {"AgentEnv-Control-Token": first.control_token} assert get_a2a_agent_instance_store().get(first.instance_id).control_token == first.control_token diff --git a/tst/unit/task_step/install_agent_test.py b/tst/unit/task_step/install_agent_test.py index 0eef2a44c..e3f22119d 100644 --- a/tst/unit/task_step/install_agent_test.py +++ b/tst/unit/task_step/install_agent_test.py @@ -161,7 +161,9 @@ def _resolved(value): @pytest.mark.asyncio -async def test_install_logs_show_the_command_template_not_the_model_key_or_headers(monkeypatch, caplog, local_stores): +async def test_install_logs_show_the_command_template_not_the_model_key_headers_or_control_token( + monkeypatch, caplog, local_stores, +): monkeypatch.setenv("LITELLM_BASE_URL", "http://localhost:4000/v1") monkeypatch.setenv("LITELLM_API_KEY", "sk-never-logged") monkeypatch.setattr(local_stores, "_model_cfg", ModelConfig(headers={"X-Bill-To": "org-never-logged"})) @@ -174,9 +176,12 @@ async def test_install_logs_show_the_command_template_not_the_model_key_or_heade step = InstallAgentTaskStep(id="i", version=None, sandbox_name="vm", a2a_agent_id="agent-x", agent_name="solver") monkeypatch.setattr(step, "_extract_install_extension", _resolved({"params": { "install_commands_host": ["start --key {litellm_api_key} --headers {litellm_extra_headers}"], - "required_params_host": ["litellm_api_key", "litellm_extra_headers"], "a2a_port": 8000}})) + "required_params_host": ["litellm_api_key", "litellm_extra_headers"], + "optional_params_host": ["control_token", "a-param-this-runner-doesnt-know"], "a2a_port": 8000}})) monkeypatch.setattr(step, "_wait_for_agent_card", _resolved({})) - monkeypatch.setattr(step, "_register_instance", lambda *args: SimpleNamespace(instance_id="solver-1", control_token=None)) + recorded: list[str] = [] + monkeypatch.setattr(step, "_register_instance", lambda agent, url, ds, card, token: recorded.append(token) + or SimpleNamespace(instance_id="solver-1", control_token=token)) context = TaskStepContext(deployed_sandboxes=[DeployedSandbox( sandbox_name="vm", sandbox_id="sb-1", sandbox_mode="vm", sandbox_type="local", tunnel_urls={"8000": "http://127.0.0.1:8000"})]) @@ -184,10 +189,12 @@ async def test_install_logs_show_the_command_template_not_the_model_key_or_heade with caplog.at_level(logging.INFO, logger="agent_env.task_step.task_steps.install_agent"): await step.execute(context) - [command] = [s for s in sandbox.scripts if s.startswith("start ")] - assert "sk-never-logged" in command and "org-never-logged" in command + [token] = recorded + [script] = [s for s in sandbox.scripts if "start " in s] + assert script.startswith(f"export AGENTENV_CONTROL_TOKEN={token}\nstart --key sk-never-logged --headers ") + assert "org-never-logged" in script and context.deployed_agents[0].control_token == token assert "start --key {litellm_api_key} --headers {litellm_extra_headers}" in caplog.text - assert "never-logged" not in caplog.text + assert "never-logged" not in caplog.text and token not in caplog.text @pytest.mark.asyncio diff --git a/tst/unit/task_step/test_verify_a2a_control_token.py b/tst/unit/task_step/test_verify_a2a_control_token.py new file mode 100644 index 000000000..7d365b272 --- /dev/null +++ b/tst/unit/task_step/test_verify_a2a_control_token.py @@ -0,0 +1,67 @@ +"""The validator's control-token check: a read the SDK serves on every agent, mcp-config's list, is called without the +agent's token and with it; the agent passes when the first is refused with a 401 and the second is not.""" + +import httpx +import pytest + +from agent_env.a2a_agent import A2AAgent +from agent_env.task_step.context import DeployedAgent, TaskStepContext +from agent_env.task_step.task_steps.a2a_agent_validator import verify_a2a_control_token as module +from agent_env.task_step.task_steps.a2a_agent_validator.verify_a2a_control_token import VerifyA2AControlTokenStep + +_CARD = {"capabilities": {"extensions": [{"uri": A2AAgent.EXT_MCP_CONFIG, "params": {"endpoint": "/ext/mcp-config"}}]}} + + +def _serve(monkeypatch, *, guarded: bool) -> list[tuple[str, str | None]]: + calls: list[tuple[str, str | None]] = [] + + def handle(request: httpx.Request) -> httpx.Response: + token = request.headers.get("AgentEnv-Control-Token") + calls.append((request.url.path, token)) + if guarded and token != "s3cret": + return httpx.Response(401, json={"detail": "this route takes the agent's control token"}) + return httpx.Response(200, json={"mcp_servers": {}}) + + real_client = httpx.AsyncClient + monkeypatch.setattr(module.httpx, "AsyncClient", + lambda **kw: real_client(transport=httpx.MockTransport(handle), **kw)) + return calls + + +async def _check(card: dict = _CARD, token: str | None = "s3cret") -> dict: + context = TaskStepContext(deployed_agents=[DeployedAgent( + agent_name="default-agent", api_url="http://agent", a2a_url="http://agent", a2a_card=card, control_token=token)]) + step = VerifyA2AControlTokenStep(id="v", version=None, a2a_agent_id="agent-x") + return (await step.execute(context)).metadata["verifications"]["a2a_control_token"] + + +@pytest.mark.asyncio +async def test_an_agent_that_refuses_a_call_without_its_token_and_answers_one_with_it_passes(monkeypatch): + calls = _serve(monkeypatch, guarded=True) + + entry = await _check() + + assert entry == {"route": "/ext/mcp-config", "refuses_without_token": True, "accepts_with_token": True, + "passed": True} + assert calls == [("/ext/mcp-config", None), ("/ext/mcp-config", "s3cret")] + + +@pytest.mark.asyncio +async def test_an_agent_that_answers_without_its_token_fails(monkeypatch): + _serve(monkeypatch, guarded=False) + + entry = await _check() + + assert entry["refuses_without_token"] is False and entry["accepts_with_token"] is True + assert entry["passed"] is False + + +@pytest.mark.asyncio +async def test_an_agent_with_no_guarded_read_or_no_token_on_its_record_fails_without_a_call(monkeypatch): + calls = _serve(monkeypatch, guarded=True) + + no_read = await _check(card={}) + no_token = await _check(token=None) + + assert no_read["route"] is None and no_read["passed"] is False + assert no_token["passed"] is False and calls == [] From af79d6b2366e0dcb001d876981aee026aa617b5f Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 09:50:23 -0800 Subject: [PATCH 02/10] fix(agents): the control-token middleware guards an app mounted under 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 --- .../src/agentenv_protocol/a2a_agent/control_token.py | 8 +++++++- packages/agentenv-protocol/tests/test_a2a_agent.py | 12 ++++++------ .../a2a_agent_validator/verify_a2a_control_token.py | 5 +++-- 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py index 90383454d..19c13a8d1 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py @@ -49,7 +49,7 @@ def __init__(self, app: ASGIApp, *, token: str | None = None) -> None: self.token = token or take_control_token() async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: - if scope["type"] == "http" and _guarded(scope["path"]): + 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) @@ -58,6 +58,12 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: 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) diff --git a/packages/agentenv-protocol/tests/test_a2a_agent.py b/packages/agentenv-protocol/tests/test_a2a_agent.py index f109f6138..5949d9558 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -106,7 +106,7 @@ from starlette.applications import Starlette from starlette.middleware import Middleware from starlette.responses import PlainTextResponse -from starlette.routing import Route +from starlette.routing import Mount, Route from starlette.testclient import TestClient @@ -3071,7 +3071,7 @@ def test_an_agent_with_no_token_or_not_served_keeps_its_routes_open(monkeypatch) assert unserved == tokenless == 200 -def test_the_middleware_guards_a_hand_served_agents_extension_routes_but_staging_and_the_peer_tools( +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") @@ -3080,10 +3080,10 @@ async def ok(request): return PlainTextResponse("ok") paths = ("/ext/agent-config", "/ext/staging/abc", "/ext/peer-agents/mcp", "/health") - app = Starlette(routes=[Route(path, ok) for path in paths], middleware=[Middleware(ControlTokenMiddleware)]) - with TestClient(app) as agent: - without = [agent.get(path).status_code for path in paths] - with_token = agent.get("/ext/agent-config", headers=protocol_client.control_token_headers("s3cret")) + 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] diff --git a/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py index c743de64f..caa4b118b 100644 --- a/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py +++ b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py @@ -16,6 +16,7 @@ # Reads the SDK serves for every agent that enables the extension, so the check changes nothing on the agent. _READS = ((A2AAgent.EXT_MCP_CONFIG, "list"), (A2AAgent.EXT_AGENT_CONFIG, "get")) +_REQUEST_TIMEOUT_SECONDS = 30 class VerifyA2AControlTokenStep(TaskStep): @@ -48,8 +49,8 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext: url = (deployed.a2a_url or deployed.api_url) + route try: async with httpx.AsyncClient() as client: - without = await client.get(url, timeout=30) - with_token = await client.get(url, headers=deployed.control_headers, timeout=30) + without = await client.get(url, timeout=_REQUEST_TIMEOUT_SECONDS) + with_token = await client.get(url, headers=deployed.control_headers, timeout=_REQUEST_TIMEOUT_SECONDS) entry["refuses_without_token"] = without.status_code == 401 entry["accepts_with_token"] = with_token.status_code != 401 except httpx.HTTPError as e: From 7d00ff77d67f92855fa5d899601a8d160bcb99e9 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 09:58:35 -0800 Subject: [PATCH 03/10] fix(agents): a refused extension call answers with a JSON detail; agent 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 --- .../src/agentenv_protocol/a2a_agent/framework.py | 2 +- tst/unit/agents/codex/test_card_contract.py | 5 +++-- tst/unit/agents/gemini/test_card_contract.py | 5 +++-- tst/unit/agents/openhands/test_openhands_agent.py | 5 ++++- tst/unit/agents/pi/test_pi_agent.py | 5 ++++- tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py | 5 ++++- 6 files changed, 19 insertions(+), 8 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 2d7058607..6617aebda 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -1182,7 +1182,7 @@ def _route_handler( 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) - raise HTTPException(status_code=401, detail=REFUSAL) + return JSONResponse({"detail": REFUSAL}, status_code=401) try: if operation.definition.method == "GET": payload = dict(request.query_params) diff --git a/tst/unit/agents/codex/test_card_contract.py b/tst/unit/agents/codex/test_card_contract.py index 4150411d9..a5c20e216 100644 --- a/tst/unit/agents/codex/test_card_contract.py +++ b/tst/unit/agents/codex/test_card_contract.py @@ -169,9 +169,10 @@ def test_request_and_response_contracts(codex): def test_install_params(codex): params = _extensions(codex)["urn:agentenv:install/v1"]["params"] assert list(params) == [ - "install_commands", "a2a_port", "required_params", "install_commands_host", "required_params_host", - "workdir_host", "user_host", + "install_commands", "a2a_port", "optional_params", "required_params", "install_commands_host", + "optional_params_host", "required_params_host", "workdir_host", "user_host", ] + assert params["optional_params"] == params["optional_params_host"] == ["control_token"] assert params["a2a_port"] == 8000 endpoint = ["litellm_api_key", "litellm_base_url", "litellm_extra_headers", "trust_env"] assert params["required_params"] == ["container", "work_dir", "agent_ctx_tar", "a2a_port", *endpoint] diff --git a/tst/unit/agents/gemini/test_card_contract.py b/tst/unit/agents/gemini/test_card_contract.py index eea71acca..0202ac504 100644 --- a/tst/unit/agents/gemini/test_card_contract.py +++ b/tst/unit/agents/gemini/test_card_contract.py @@ -201,9 +201,10 @@ def test_request_and_response_contracts(app): def test_install_params(app): params = _extensions(app)["urn:agentenv:install/v1"]["params"] assert list(params) == [ - "install_commands", "required_params", "install_commands_host", "a2a_port", "required_params_host", - "workdir_host", "user_host", + "install_commands", "optional_params", "required_params", "install_commands_host", "a2a_port", + "optional_params_host", "required_params_host", "workdir_host", "user_host", ] + assert params["optional_params"] == params["optional_params_host"] == ["control_token"] assert params["a2a_port"] == 8000 endpoint = ["litellm_api_key", "litellm_base_url", "litellm_extra_headers", "trust_env"] assert params["required_params"] == ["container", "work_dir", "agent_ctx_tar", "a2a_port", *endpoint] diff --git a/tst/unit/agents/openhands/test_openhands_agent.py b/tst/unit/agents/openhands/test_openhands_agent.py index ac0505bce..da13dad1e 100644 --- a/tst/unit/agents/openhands/test_openhands_agent.py +++ b/tst/unit/agents/openhands/test_openhands_agent.py @@ -656,7 +656,10 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: for command in install["install_commands"]] assert formatted[-1].endswith("c sh /opt/openhands-a2a/start.sh") assert all("sk-secret" not in command.splitlines()[0] for command in formatted) - assert "LITELLM_API_KEY='sk-secret'" in formatted[-2].splitlines() + [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] + assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() + assert install["optional_params"] == ["control_token"] + assert formatted[-2].startswith('[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf') def test_the_card_advertises_the_extensions_agent_env_validates(client: TestClient) -> None: diff --git a/tst/unit/agents/pi/test_pi_agent.py b/tst/unit/agents/pi/test_pi_agent.py index d8ee8027c..417423212 100644 --- a/tst/unit/agents/pi/test_pi_agent.py +++ b/tst/unit/agents/pi/test_pi_agent.py @@ -740,7 +740,10 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: litellm_base_url="u") for command in install["install_commands"]] assert formatted[-1].endswith("c sh /opt/pi-a2a/start.sh") assert all("sk-secret" not in command.splitlines()[0] for command in formatted) - assert "LITELLM_API_KEY='sk-secret'" in formatted[-2].splitlines() + [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] + assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() + assert install["optional_params"] == ["control_token"] + assert formatted[-2].startswith('[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf') assert all(command.startswith("$(sudo -n true 2>/dev/null && echo sudo) docker ") for command in formatted) diff --git a/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py b/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py index 6324cb06a..9b9388d85 100644 --- a/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py +++ b/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py @@ -634,7 +634,10 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: for command in install["install_commands"]] assert formatted[-1].endswith("c sh /opt/pydantic-ai-a2a/start.sh") assert all("sk-secret" not in command.splitlines()[0] for command in formatted) - assert "LITELLM_API_KEY='sk-secret'" in formatted[-2].splitlines() + [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] + assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() + assert install["optional_params"] == ["control_token"] + assert formatted[-2].startswith('[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf') def test_the_installed_agent_starts_with_the_endpoint_and_trust_lines_install_wrote(tmp_path: Path) -> None: From 93e0c9a6b912ee1334d110e732cf266781f46eba Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:01:18 -0800 Subject: [PATCH 04/10] feat(agents)!: an agent says as it starts serving whether its extension 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 --- .../agentenv_protocol/a2a_agent/control_token.py | 10 ++++++++++ .../src/agentenv_protocol/a2a_agent/framework.py | 3 ++- packages/agentenv-protocol/tests/test_a2a_agent.py | 14 +++++++++----- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py index 19c13a8d1..78f3dbe5c 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/control_token.py @@ -35,6 +35,15 @@ def carries_control_token(headers: Mapping[str, str], token: str | None) -> bool 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) @@ -47,6 +56,7 @@ class ControlTokenMiddleware: 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)): diff --git a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py index 6617aebda..ed2faaaa1 100644 --- a/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py +++ b/packages/agentenv-protocol/src/agentenv_protocol/a2a_agent/framework.py @@ -64,7 +64,7 @@ ) from ..computer.errors import ComputerError from . import clock as agent_clock -from .control_token import REFUSAL, carries_control_token, log_refusal, take_control_token +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 @@ -989,6 +989,7 @@ def _taking_the_control_token( @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: diff --git a/packages/agentenv-protocol/tests/test_a2a_agent.py b/packages/agentenv-protocol/tests/test_a2a_agent.py index 5949d9558..8e8bbc709 100644 --- a/packages/agentenv-protocol/tests/test_a2a_agent.py +++ b/packages/agentenv-protocol/tests/test_a2a_agent.py @@ -3040,11 +3040,12 @@ async def run(self, request: TaskRequest) -> TaskResult: def test_a_served_agent_takes_its_control_token_out_of_the_environment_and_its_routes_refuse_calls_without_it( - monkeypatch, + monkeypatch, caplog, ) -> None: monkeypatch.setenv(CONTROL_TOKEN_ENV, "s3cret") - with TestClient(_GuardedAgent().create_app()) as agent: + 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 @@ -3054,21 +3055,24 @@ def test_a_served_agent_takes_its_control_token_out_of_the_environment_and_its_r 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 + 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) -> None: +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 TestClient(_GuardedAgent().create_app()) as agent: + 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( From a62aabb9ed4367490cf71d92deee02a51b786580 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:07:28 -0800 Subject: [PATCH 05/10] test(agents): every installable bundled agent takes its control token 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 --- .../agents/test_installed_control_token.py | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 tst/unit/agents/test_installed_control_token.py diff --git a/tst/unit/agents/test_installed_control_token.py b/tst/unit/agents/test_installed_control_token.py new file mode 100644 index 000000000..90f03abf4 --- /dev/null +++ b/tst/unit/agents/test_installed_control_token.py @@ -0,0 +1,39 @@ +"""Every bundled agent that installs through install/v1 takes its control token from the installer: its declaration +lists ``control_token`` in ``optional_params`` (and ``optional_params_host`` for a host install), and its install reads +the protocol's ``CONTROL_TOKEN_ENV``, which the installer exports. An agent whose install spelled it otherwise would +install fine and serve its extension routes open.""" + +import re +from pathlib import Path + +import pytest +from agentenv_protocol import CONTROL_TOKEN_ENV + +import agent_env + +AGENTS = Path(agent_env.__file__).parent / "agents" / "agents" + + +def _sources(agent: str) -> dict[str, str]: + return {path.name: path.read_text() for path in (AGENTS / agent).iterdir() if path.suffix in (".py", ".sh")} + + +INSTALLABLE = sorted(path.name for path in AGENTS.iterdir() + if path.is_dir() and any("required_params=" in src for src in _sources(path.name).values())) + + +def test_the_bundled_agents_that_install_are_the_ones_this_test_knows(): + assert INSTALLABLE == ["claude-code", "codex", "gemini", "letta-code", "opencode", "openhands", "pi", "proxy", + "pydantic-ai"] + + +@pytest.mark.parametrize("agent", INSTALLABLE) +def test_an_installed_agent_takes_its_control_token_under_the_protocols_variable(agent): + sources = _sources(agent) + (declaration,) = [src for src in sources.values() if "required_params=" in src] + + assert 'optional_params=["control_token"]' in declaration + if "required_params_host=" in declaration: + assert 'optional_params_host=["control_token"]' in declaration + # The installer exports the variable; the install reads it, as ${...} in a shell (${{...}} in a format template). + assert any(re.search(r"\$\{+" + CONTROL_TOKEN_ENV + r"\b", src) for src in sources.values()) From ece0179b0218f7fc8c202c458b2adf61d4191898 Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:14:50 -0800 Subject: [PATCH 06/10] fix(agents): pi, openhands and pydantic-ai take their control token through 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 --- src/agent_env/agents/agents/openhands/openhands_agent.py | 8 +++++--- src/agent_env/agents/agents/pi/pi_agent.py | 8 +++++--- .../agents/agents/pydantic-ai/pydantic_ai_agent.py | 8 +++++--- tst/unit/agents/openhands/test_openhands_agent.py | 2 +- tst/unit/agents/pi/test_pi_agent.py | 2 +- tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py | 2 +- 6 files changed, 18 insertions(+), 12 deletions(-) diff --git a/src/agent_env/agents/agents/openhands/openhands_agent.py b/src/agent_env/agents/agents/openhands/openhands_agent.py index c1334ab93..9c8129f98 100644 --- a/src/agent_env/agents/agents/openhands/openhands_agent.py +++ b/src/agent_env/agents/agents/openhands/openhands_agent.py @@ -89,9 +89,11 @@ "LITELLM_BASE_URL={litellm_base_url}\n" "LITELLM_EXTRA_HEADERS={litellm_extra_headers}\n" "OPENHANDS_A2A_ENV", - # agent-env's control token for the agent, when the runner hands it one (install/v1 optional_params), the same way. - "[ -z \"${{AGENTENV_CONTROL_TOKEN:-}}\" ] || printf 'AGENTENV_CONTROL_TOKEN=%s\\n' \"$AGENTENV_CONTROL_TOKEN\" | " - f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}'", + # agent-env's control token for the agent, which the runner exports when it has one (install/v1 optional_params), + # the same way: expanded by the install's shell into the heredoc, empty without one, which leaves the agent open. + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}' <> {INSTALL_DIR}/{ENV_FILE}'", + # agent-env's control token for the agent, which the runner exports when it has one (install/v1 optional_params), + # the same way: expanded by the install's shell into the heredoc, empty without one, which leaves the agent open. + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}' <> {INSTALL_DIR}/{ENV_FILE}'", + # agent-env's control token for the agent, which the runner exports when it has one (install/v1 optional_params), + # the same way: expanded by the install's shell into the heredoc, empty without one, which leaves the agent open. + f"{_DOCKER} exec -i {{container}} sh -c 'cat >> {INSTALL_DIR}/{ENV_FILE}' < None: [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() assert install["optional_params"] == ["control_token"] - assert formatted[-2].startswith('[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf') + assert formatted[-2].splitlines()[1] == "AGENTENV_CONTROL_TOKEN=${AGENTENV_CONTROL_TOKEN:-}" def test_the_card_advertises_the_extensions_agent_env_validates(client: TestClient) -> None: diff --git a/tst/unit/agents/pi/test_pi_agent.py b/tst/unit/agents/pi/test_pi_agent.py index 417423212..641c5bd3a 100644 --- a/tst/unit/agents/pi/test_pi_agent.py +++ b/tst/unit/agents/pi/test_pi_agent.py @@ -743,7 +743,7 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() assert install["optional_params"] == ["control_token"] - assert formatted[-2].startswith('[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf') + assert formatted[-2].splitlines()[1] == "AGENTENV_CONTROL_TOKEN=${AGENTENV_CONTROL_TOKEN:-}" assert all(command.startswith("$(sudo -n true 2>/dev/null && echo sudo) docker ") for command in formatted) diff --git a/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py b/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py index 9b9388d85..39313b428 100644 --- a/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py +++ b/tst/unit/agents/pydantic_ai/test_pydantic_ai_agent.py @@ -637,7 +637,7 @@ def test_install_extension_is_declared_on_the_card(client: TestClient) -> None: [env_file] = [command for command in formatted if "LITELLM_API_KEY" in command] assert "LITELLM_API_KEY='sk-secret'" in env_file.splitlines() assert install["optional_params"] == ["control_token"] - assert formatted[-2].startswith('[ -z "${AGENTENV_CONTROL_TOKEN:-}" ] || printf') + assert formatted[-2].splitlines()[1] == "AGENTENV_CONTROL_TOKEN=${AGENTENV_CONTROL_TOKEN:-}" def test_the_installed_agent_starts_with_the_endpoint_and_trust_lines_install_wrote(tmp_path: Path) -> None: From b3667649d07b95edd909e5b86cd07b92101f089a Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:22:29 -0800 Subject: [PATCH 07/10] fix(agents): the validator's control-token check is a grader 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 --- .../task_steps/a2a_agent_validator/verify_a2a_control_token.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py index caa4b118b..bab2b48fa 100644 --- a/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py +++ b/src/agent_env/task_step/task_steps/a2a_agent_validator/verify_a2a_control_token.py @@ -10,7 +10,7 @@ from agent_env.a2a_agent import A2AAgent from agent_env.entity.refs import EntityRef from agent_env.task_step.context import TaskStepContext -from agent_env.task_step.task_step import TaskStep, TaskStepDependency +from agent_env.task_step.task_step import StepRole, TaskStep, TaskStepDependency logger = logging.getLogger(__name__) @@ -21,6 +21,7 @@ class VerifyA2AControlTokenStep(TaskStep): type: ClassVar[str] = "verify_a2a_control_token" + step_role = StepRole.GRADER entity_refs = (EntityRef.agent("a2a_agent_id", version_field="a2a_agent_version"),) def __init__(self, id: str, version: Optional[int], a2a_agent_id: str, a2a_agent_version: Optional[int] = None, From 8003fcf5c8ff2d1a1b39af7afd70c3dbe6dffdae Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:34:44 -0800 Subject: [PATCH 08/10] test(agents): the integration tests that call an agent's extension routes 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 --- .../a2a_agent/agent_triggers_e2e_test.py | 24 +++++++++++-------- .../agent/proxy_container_install_test.py | 14 ++++++++--- .../cli/run_bundle_browser_use_test.py | 10 ++++---- .../cli/run_bundle_claude_code_test.py | 3 ++- .../cli/run_bundle_openhands_test.py | 14 +++++------ .../cli/run_bundle_pydantic_ai_test.py | 14 +++++------ tst/integration/cli/run_role_models_test.py | 9 +++---- .../env/task_step/task_steps_test.py | 2 +- 8 files changed, 53 insertions(+), 37 deletions(-) diff --git a/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py b/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py index f8dd27389..bb12e6302 100644 --- a/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py +++ b/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py @@ -84,8 +84,12 @@ async def test_agent_triggers_e2e(agent): triggers_url = deployed.a2a_url + endpoint decide_url = deployed.a2a_url + methods["decide"]["endpoint"] - async with httpx.AsyncClient(timeout=30) as client: - # 2. Register the full script (every condition type + both actions). + # 2. The extension routes take the agent's control token: a call without it is refused before it runs. + async with httpx.AsyncClient(timeout=30) as anonymous: + assert (await anonymous.post(triggers_url, json=_SCRIPT)).status_code == 401 + + async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: + # 3. Register the full script (every condition type + both actions). resp = await client.post(triggers_url, json=_SCRIPT) resp.raise_for_status() body = resp.json() @@ -93,7 +97,7 @@ async def test_agent_triggers_e2e(agent): assert set(body["added"]) == _SCRIPT_IDS assert set(body["all"]) >= _SCRIPT_IDS - # 3. Fail-loud: an unknown when.type rejects the whole batch (HTTP 400). + # 4. Fail-loud: an unknown when.type rejects the whole batch (HTTP 400). bad = await client.post(triggers_url, json={"triggers": [ {"when": {"type": "bogus"}, "actions": [{"type": "say", "text": "x"}]}]}) assert bad.status_code == 400 @@ -108,7 +112,7 @@ async def decide(turn, message="", env=None, ctx="default"): r.raise_for_status() return r.json() - # 4. Deterministic firing sequence on context c1 (step -> conversational -> env_trigger -> all/end). + # 5. Deterministic firing sequence on context c1 (step -> conversational -> env_trigger -> all/end). r = await decide(1, "hello", ctx="c1") assert r["fired"] == ["open"] and r["done"] is False assert r["parts"] == [{"kind": "text", "text": "[PM]: Look into LeapBlock."}] @@ -123,25 +127,25 @@ async def decide(turn, message="", env=None, ctx="default"): assert r["fired"] == ["accept"] and r["done"] is True # all -> say + end assert "sending to Arthur" in r["parts"][0]["text"] - # 5. Turn-regression reset: replaying turn 1 clears c1's fired-set -> `open` re-fires (retry-safe). + # 6. Turn-regression reset: replaying turn 1 clears c1's fired-set -> `open` re-fires (retry-safe). r = await decide(1, "hello", ctx="c1") assert r["fired"] == ["open"] - # 6. once:false recurrence + the step branch of `any` on a fresh context. + # 7. once:false recurrence + the step branch of `any` on a fresh context. r = await decide(6, ctx="c2") assert r["fired"] == ["nudge"] and r["done"] is False # any[step >= 6] r = await decide(7, ctx="c2") assert r["fired"] == ["nudge"] # once:false -> fires again - # 7. The conversational branch of `any` (fires on "stuck"). + # 8. The conversational branch of `any` (fires on "stuck"). r = await decide(2, "I am stuck", ctx="c3") assert "nudge" in r["fired"] - # 8. decide validates its turn (non-positive -> 400). + # 9. decide validates its turn (non-positive -> 400). bad_turn = await client.post(decide_url, json={"turn": 0}) assert bad_turn.status_code == 400 - # 9. State read-back: config + trigger summary + firing log. + # 10. State read-back: config + trigger summary + firing log. state = (await client.get(triggers_url)).json() summary = {t["id"]: t for t in state["triggers"]} assert _SCRIPT_IDS <= set(summary) @@ -155,7 +159,7 @@ async def decide(turn, message="", env=None, ctx="default"): fired_ids = {e["trigger_id"] for e in state["firing_log"] if e["kind"] == "fired"} assert {"open", "answer-format", "re-sweep", "accept", "nudge"} <= fired_ids - # 10. The real RegisterAgentTriggersStep drives registration against the live agent's card. + # 11. The real RegisterAgentTriggersStep drives registration against the live agent's card. da = DeployedAgent( agent_name="stakeholder", api_url=deployed.a2a_url, diff --git a/tst/integration/agent/proxy_container_install_test.py b/tst/integration/agent/proxy_container_install_test.py index 58d90fa61..60649635e 100644 --- a/tst/integration/agent/proxy_container_install_test.py +++ b/tst/integration/agent/proxy_container_install_test.py @@ -1,7 +1,9 @@ """The proxy's folder installed into a running container by its own install.sh, as install_agent installs it there. It brings its own Python and serves; its bash runs commands with bash, or with sh in a container that has only sh (Alpine, -musl), and says which. The container installs this checkout's protocol, so the test covers the code beside it.""" +musl), and says which. The container installs this checkout's protocol, so the test covers the code beside it, and its +extension routes take the control token the install was handed, as install_agent hands it.""" +import os import shutil import subprocess import time @@ -11,6 +13,8 @@ import httpx import pytest +from agentenv_protocol import CONTROL_TOKEN_ENV +from agentenv_protocol.client import control_token_headers import agent_env @@ -20,6 +24,7 @@ PROTOCOL_DIR = Path(agent_env.__file__).parents[2] / "packages" / "agentenv-protocol" PORT = 8000 TOKEN = "t" * 32 +CONTROL_TOKEN = "c" * 32 @pytest.fixture(params=[("alpine:3.20", "sh"), ("debian:12-slim", "bash")], ids=["sh-only", "with-bash"]) @@ -46,10 +51,13 @@ def test_installed_into_a_container_the_proxy_serves_and_its_bash_runs_the_shell (folder / "requirements.txt").write_text("agentenv-framework-protocol[agent] @ file:///tmp/protocol\n") subprocess.run(["docker", "cp", f"{PROTOCOL_DIR}/.", f"{name}:/tmp/protocol"], check=True, capture_output=True) - subprocess.run(["bash", str(folder / "install.sh"), "container", name, str(PORT)], check=True) + subprocess.run(["bash", str(folder / "install.sh"), "container", name, str(PORT)], check=True, + env={**os.environ, CONTROL_TOKEN_ENV: CONTROL_TOKEN}) - with httpx.Client(base_url=f"http://{_published(name)}", timeout=30) as client: + base_url = f"http://{_published(name)}" + with httpx.Client(base_url=base_url, timeout=30, headers=control_token_headers(CONTROL_TOKEN)) as client: _serving(client) + assert httpx.post(f"{base_url}/ext/proxy/claim", json={"token": TOKEN}, timeout=30).status_code == 401 assert client.post("/ext/proxy/claim", json={"token": TOKEN}).status_code == 200 task_id = _send(client, "go") tools = _proxy(client, "tools", task_id=task_id).json()["tools"] diff --git a/tst/integration/cli/run_bundle_browser_use_test.py b/tst/integration/cli/run_bundle_browser_use_test.py index 5f7d3309e..bd6339faf 100644 --- a/tst/integration/cli/run_bundle_browser_use_test.py +++ b/tst/integration/cli/run_bundle_browser_use_test.py @@ -117,12 +117,13 @@ async def steps(context): sandbox_type="local").execute(context) (env,), (agent,) = context.deployed_envs, context.deployed_agents base_url = agent.a2a_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) outcomes["none"] = await _send(base_url, PROMPT) outcomes["none_asked"] = len(endpoint.completions()) await BrowserConnectCdpTaskStep(id="connect", version=None, env_id=BROWSER).execute(context) - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"connect_by": "http"}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"connect_by": "http"}, + headers=agent.control_headers) outcomes["http"] = await _send(base_url, PROMPT, context_id="kept") asked = len(endpoint.completions()) outcomes["again"] = await _send(base_url, AGAIN, context_id="kept") @@ -130,14 +131,15 @@ async def steps(context): forged = reachable_url(env.environment_url.rstrip("/"), from_sandbox_type=env.sandbox_type, to_sandbox_type=agent.sandbox_type).rstrip("/") + f"/svc/chromium/cdp/{uuid.uuid4().hex}" - async with httpx.AsyncClient(timeout=60) as client: + async with httpx.AsyncClient(timeout=60, headers=agent.control_headers) as client: added = await client.post(f"{base_url}/ext/cdp-config", json={ "name": "forged", "http_url": f"{forged}/", "ws_url": "ws" + forged.removeprefix("http") + "/devtools/browser"}) added.raise_for_status() for connect_by in ("ws", "http"): await protocol.post_agent_config(f"{base_url}/ext/agent-config", - {"browser": "forged", "connect_by": connect_by}) + {"browser": "forged", "connect_by": connect_by}, + headers=agent.control_headers) outcomes[f"forged_{connect_by}"] = await _send(base_url, PROMPT) written = CliRunner().invoke(cli, ["run", str(_writes_the_agent_and_browser(state))]) diff --git a/tst/integration/cli/run_bundle_claude_code_test.py b/tst/integration/cli/run_bundle_claude_code_test.py index c4f59b81e..6f9baeddc 100644 --- a/tst/integration/cli/run_bundle_claude_code_test.py +++ b/tst/integration/cli/run_bundle_claude_code_test.py @@ -204,7 +204,8 @@ async def _send_project_id(step, context): return negotiated = A2AAgent.negotiate_agent_config(agent.a2a_card or {}, {"project_id": project_id}) assert negotiated and "project_id" in negotiated.fields, "the card doesn't take project_id over agent-config" - await protocol.post_agent_config((agent.a2a_url or agent.api_url) + negotiated.endpoint, negotiated.fields) + await protocol.post_agent_config((agent.a2a_url or agent.api_url) + negotiated.endpoint, negotiated.fields, + headers=agent.control_headers) def test_a_project_id_posted_over_agent_config_attributes_every_model_call_to_the_project(state, endpoint): diff --git a/tst/integration/cli/run_bundle_openhands_test.py b/tst/integration/cli/run_bundle_openhands_test.py index 1ecd21167..e1e260e49 100644 --- a/tst/integration/cli/run_bundle_openhands_test.py +++ b/tst/integration/cli/run_bundle_openhands_test.py @@ -186,8 +186,8 @@ async def steps(context): await DeployAgentTaskStep(id="agent", version=None, sandbox_type="local", a2a_agent_id=AGENT).execute(context) (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) - async with httpx.AsyncClient() as client: + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) + async with httpx.AsyncClient(headers=agent.control_headers) as client: registered = await client.post(f"{base_url}/ext/mcp-config", json={ "name": "probe", "url": f"{endpoint.url}/mcp-probe", "headers": {"X-Probe": "${LITELLM_API_KEY}"}}) registered.raise_for_status() @@ -208,7 +208,7 @@ async def steps(context): await DeployAgentTaskStep(id="agent", version=None, sandbox_type="local", a2a_agent_id=AGENT).execute(context) (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) outcomes["first"] = await _send(base_url, "ctx", "Say pong.") subprocess.run(["docker", "exec", f"agent-{agent.sandbox_id}", "sh", "-c", "for f in ~/.openhands-a2a/conversations/*/base_state.json; do printf '{' > \"$f\"; done"], @@ -253,7 +253,7 @@ async def steps(context): (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url endpoint.respond = respond - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}, headers=agent.control_headers) endpoint.fail_next(Fault("stall", seconds=15)) started = time.monotonic() outcomes["timed_out"] = await _send(base_url, "ctx", "Say pong.") @@ -261,7 +261,7 @@ async def steps(context): calls = len(endpoint.completions()) await asyncio.sleep(25) # past the stall, so a run left going would have called the endpoint again outcomes["calls_after_the_timeout"] = len(endpoint.completions()) - calls - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}, headers=agent.control_headers) outcomes["after"] = await _send(base_url, "ctx", "Say pong again.") _with_agent(state, steps) @@ -295,11 +295,11 @@ async def steps(context): (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url endpoint.respond = respond - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL, "timeout_seconds": 5}, headers=agent.control_headers) started = time.monotonic() outcomes["timed_out"] = await _send(base_url, "ctx", "Sleep.") outcomes["seconds"] = time.monotonic() - started - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}, headers=agent.control_headers) outcomes["after"] = await _send(base_url, "ctx", "List the processes.") _with_agent(state, steps) diff --git a/tst/integration/cli/run_bundle_pydantic_ai_test.py b/tst/integration/cli/run_bundle_pydantic_ai_test.py index 7953f9dda..d57c62aa2 100644 --- a/tst/integration/cli/run_bundle_pydantic_ai_test.py +++ b/tst/integration/cli/run_bundle_pydantic_ai_test.py @@ -105,12 +105,12 @@ async def run(): asyncio.run(run()) -async def _deployed(context) -> str: +async def _deployed(context) -> tuple[str, dict[str, str]]: await DeployAgentTaskStep(id="agent", version=None, sandbox_type="local", a2a_agent_id=AGENT).execute(context) (agent,) = context.deployed_agents base_url = agent.a2a_url or agent.api_url - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}) - return base_url + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"model": MODEL}, headers=agent.control_headers) + return base_url, agent.control_headers async def _send(base_url: str, context_id: str, text: str) -> dict: @@ -187,7 +187,7 @@ def respond(body): endpoint.respond = answer("pong") async def steps(context): - base_url = await _deployed(context) + base_url, headers = await _deployed(context) endpoint.respond = respond outcomes["first"] = await _send(base_url, "ctx", "Say pong.") outcomes["second"] = await _send(base_url, "ctx", "Look at your saved conversation.") @@ -228,13 +228,13 @@ def respond(body): endpoint.respond = answer("pong") async def steps(context): - base_url = await _deployed(context) + base_url, headers = await _deployed(context) endpoint.respond = respond - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 5}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 5}, headers=headers) started = time.monotonic() outcomes["timed_out"] = await _send(base_url, "ctx", "Sleep.") outcomes["seconds"] = time.monotonic() - started - await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}) + await protocol.post_agent_config(f"{base_url}/ext/agent-config", {"timeout_seconds": 120}, headers=headers) outcomes["after"] = await _send(base_url, "ctx", "List the processes.") _with_agent(state, steps) diff --git a/tst/integration/cli/run_role_models_test.py b/tst/integration/cli/run_role_models_test.py index abfdae4d4..bed763486 100644 --- a/tst/integration/cli/run_role_models_test.py +++ b/tst/integration/cli/run_role_models_test.py @@ -110,8 +110,9 @@ def _reset(): reset() -def _configured_model(url: str) -> str | None: - return httpx.get(f"{url}/ext/agent-config", timeout=30).json()["config"].get("model") +def _configured_model(agent) -> str | None: + return httpx.get(f"{agent.a2a_url}/ext/agent-config", headers=agent.control_headers, + timeout=30).json()["config"].get("model") def test_each_role_runs_on_the_model_its_flag_gives_and_a_rerun_on_others_writes_nothing(bundle): @@ -122,8 +123,8 @@ def test_each_role_runs_on_the_model_its_flag_gives_and_a_rerun_on_others_writes try: [run] = result.runs assert run.outcome is Outcome.PASSED, run.error or run.failed_steps - agents = {agent.agent_name: agent.a2a_url for agent in run.context.deployed_agents} - assert {name: _configured_model(url) for name, url in agents.items()} == { + agents = {agent.agent_name: agent for agent in run.context.deployed_agents} + assert {name: _configured_model(agent) for name, agent in agents.items()} == { "solver": "flag-solver", "user-sim": "flag-user"} assert run.models == {"solver": {"prompt": "flag-solver"}, "user simulator": {"prompt": "flag-user"}, "judge": {"judge": "openai/flag-judge"}} diff --git a/tst/integration/env/task_step/task_steps_test.py b/tst/integration/env/task_step/task_steps_test.py index 54c8a5614..864f02f2e 100644 --- a/tst/integration/env/task_step/task_steps_test.py +++ b/tst/integration/env/task_step/task_steps_test.py @@ -1029,7 +1029,7 @@ async def test_prompt_agent_model_params_reaches_agent(sandbox_provider, multi_e # prompt_agent POSTed the negotiated model_params to /ext/agent-config; read it # back — it must be present (received) but redacted (never echo provider secrets). async with httpx.AsyncClient(timeout=30) as client: - agent_cfg = (await client.get(f"{target_url}/ext/agent-config")).json()["config"] + agent_cfg = (await client.get(f"{target_url}/ext/agent-config", headers=agent.control_headers)).json()["config"] assert agent_cfg.get("model_params") == "***", \ f"expected received-and-redacted model_params, got {agent_cfg}" logger.info("model_params reached the agent and read back redacted") From b3ab70ca5d91fb34a64431f13d9553b4156e1e8c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 10:45:18 -0800 Subject: [PATCH 09/10] test(agents): the triggers e2e builds its run record with the deploy'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 --- tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py b/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py index bb12e6302..2270a1024 100644 --- a/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py +++ b/tst/integration/agent/a2a_agent/agent_triggers_e2e_test.py @@ -166,6 +166,7 @@ async def decide(turn, message="", env=None, ctx="default"): a2a_url=deployed.a2a_url, a2a_card=deployed.agent_card, sandbox_id=deployed.sandbox_id, + control_token=deployed.control_token, ) context = TaskStepContext(deployed_agents=[da]) step = RegisterAgentTriggersStep( @@ -178,6 +179,6 @@ async def decide(turn, message="", env=None, ctx="default"): assert regs[-1]["agent_name"] == "stakeholder" assert "step-reg" in regs[-1]["added"] - async with httpx.AsyncClient(timeout=30) as client: + async with httpx.AsyncClient(timeout=30, headers=deployed.control_headers) as client: state = (await client.get(triggers_url)).json() assert "step-reg" in {t["id"] for t in state["triggers"]} From bc65dfad639c2cd1d8e3210373a6e21ce97a211c Mon Sep 17 00:00:00 2001 From: Edgar Arakelyan Date: Wed, 18 Nov 2026 11:12:12 -0800 Subject: [PATCH 10/10] fix(agents): a refused control token is logged without the response body 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 --- src/agent_env/a2a_agent/protocol.py | 12 ++++++------ tst/unit/a2a_agent/protocol_test.py | 20 ++++++++++++++++++++ 2 files changed, 26 insertions(+), 6 deletions(-) diff --git a/src/agent_env/a2a_agent/protocol.py b/src/agent_env/a2a_agent/protocol.py index 963e8db55..5b458b83e 100644 --- a/src/agent_env/a2a_agent/protocol.py +++ b/src/agent_env/a2a_agent/protocol.py @@ -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( @@ -60,12 +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}" - if response.status_code == 401: - message += " (the agent refused its control token: the record it was sent from has none, or another deployment's)" - logger.warning(message) + 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 diff --git a/tst/unit/a2a_agent/protocol_test.py b/tst/unit/a2a_agent/protocol_test.py index 4c2d803bd..33548d8c5 100644 --- a/tst/unit/a2a_agent/protocol_test.py +++ b/tst/unit/a2a_agent/protocol_test.py @@ -98,6 +98,26 @@ def test_extension_http_error_for_a_request_without_grants_keeps_the_body(): ) +def test_a_refused_control_token_is_named_and_logged_without_the_body(caplog): + response = httpx.Response( + 401, + json={"detail": "this route takes the agent's control token"}, + request=httpx.Request("GET", "https://agent.test/ext/trajectory"), + ) + + with caplog.at_level(logging.WARNING, logger=protocol.__name__), pytest.raises(httpx.HTTPStatusError) as raised: + raise_for_extension_status(response, operation="trajectory read", include_body=True) + + assert str(raised.value) == ( + 'trajectory read failed with HTTP 401: {"detail":"this route takes the agent\'s control token"}' + " (the agent refused its control token: the record it was sent from has none, or another deployment's)" + ) + assert [record.getMessage() for record in caplog.records] == [ + "trajectory read failed with HTTP 401" + " (the agent refused its control token: the record it was sent from has none, or another deployment's)" + ] + + def test_sdk_success_round_trips_through_platform_parser(): result = ( TaskResult.builder()