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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@
)
from .types import (
CONTROL_TOKEN_ENV,
CONTROL_TOKEN_HEADER,
DATA_OBJECTS_EXTENSION_URI,
INTAKE_EXTENSION_URI,
MCP_PATH,
Expand Down Expand Up @@ -165,6 +166,7 @@
"PROTOCOL_VERSION",
"RPC_PATH",
"CONTROL_TOKEN_ENV",
"CONTROL_TOKEN_HEADER",
"WELL_KNOWN_PATH",
"METHOD_RESET",
"METHOD_ADD",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

from .manifest import INTERFACE_MANIFEST_PATH
from .transfers import WriteNamespaceGrant
from .types import INTAKE_EXTENSION_URI, MCP_PATH, MCP_TRANSPORT, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataResponse, GetDataResponse, Part, ResetDataResponse
from .types import CONTROL_TOKEN_HEADER, INTAKE_EXTENSION_URI, MCP_PATH, MCP_TRANSPORT, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataResponse, GetDataResponse, Part, ResetDataResponse

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -49,6 +49,11 @@ def control_headers(token: str | None) -> dict[str, str]:
return {"Authorization": f"Bearer {token}"} if token else {}


def control_token_headers(token: str | None) -> dict[str, str]:
"""The header that carries an agent's control token to its extension routes; none without one."""
return {CONTROL_TOKEN_HEADER: token} if token else {}


@contextlib.contextmanager
def authorized(grants: dict[str | None, dict[str, str]]) -> Iterator[None]:
"""Within it, a call to an address under one of ``grants``, an env's address and the headers that carry its
Expand Down
2 changes: 2 additions & 0 deletions packages/agentenv-protocol/src/agentenv_protocol/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ def error_body(code: str, message: str, **fields: Any) -> dict:
#: The variable that hands an env the token its framework-only routes take as their bearer, everything it serves but
#: its MCP endpoint and its card; agent-env sets it when it deploys the env, and without it those routes are open.
CONTROL_TOKEN_ENV = "AGENTENV_CONTROL_TOKEN"
#: The header a control token travels in where it must not collide with a front door's own ``Authorization``.
CONTROL_TOKEN_HEADER = "AgentEnv-Control-Token"

# A card declares its MCP endpoint as an `additionalInterfaces` entry with this transport; a card
# without one is reached at MCP_PATH by convention.
Expand Down
5 changes: 5 additions & 0 deletions packages/agentenv-protocol/tests/test_control_token.py
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,11 @@ def test_a_call_sends_its_own_headers_or_else_the_ones_its_grant_gives_an_addres
assert client.control_headers(None) == {} and client.control_headers("") == {}


def test_an_agents_token_travels_in_its_own_header_not_authorization():
assert client.control_token_headers("s3cret") == {"AgentEnv-Control-Token": "s3cret"}
assert client.control_token_headers(None) == {} and client.control_token_headers("") == {}


@pytest.mark.asyncio
async def test_invoke_extension_and_the_data_plane_send_the_token(monkeypatch):
seen = []
Expand Down
11 changes: 11 additions & 0 deletions src/agent_env/a2a_agent/a2a_agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Callable, ClassVar, Optional

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

from agent_env.config import get_config
Expand Down Expand Up @@ -41,6 +42,7 @@
all_sandbox_url_rewrites,
)
from agent_env.attribution import Attribution
from agent_env.env.envs.computer.utils.boot import control_token as new_control_token

if TYPE_CHECKING:
from agent_env.a2a_agent.store import A2AAgentQuery, A2AAgentStore
Expand Down Expand Up @@ -101,6 +103,8 @@ class DeployedA2AAgent:
created_at_utc: str | None = None
expires_at_utc: str | None = None
network_policy: dict | None = None
# The token the agent's extension routes take: agent-env holds it and gives no other agent.
control_token: str | None = None

@classmethod
def from_dict(cls, data: dict) -> "DeployedA2AAgent":
Expand All @@ -115,8 +119,13 @@ def from_dict(cls, data: dict) -> "DeployedA2AAgent":
created_at_utc=data.get("created_at_utc"),
expires_at_utc=data.get("expires_at_utc"),
network_policy=data.get("network_policy"),
control_token=data.get("control_token"),
)

@property
def control_headers(self) -> dict[str, str]:
return protocol_v1.control_token_headers(self.control_token)


@dataclass(frozen=True)
class NegotiatedAgentConfig:
Expand Down Expand Up @@ -261,6 +270,7 @@ async def register_skill(
operation=f"skill add ({name})",
timeout=TRANSFER_TIMEOUT_SECONDS,
store=store,
headers=deployed.control_headers,
)

@staticmethod
Expand Down Expand Up @@ -590,6 +600,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(),
)
from agent_env.a2a_agent.store import get_a2a_agent_instance_store
deployed = get_a2a_agent_instance_store().create_instance(deployed, ttl_seconds)
Expand Down
5 changes: 4 additions & 1 deletion src/agent_env/a2a_agent/object_transfer.py
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,7 @@ async def invoke_transfer(
timeout: float,
response_model: type[_Response] | None = None,
store: ObjectStore | None = None,
headers: Mapping[str, str] | None = None,
) -> Any:
"""Send ``call`` and return the agent's answer, validated against ``response_model`` when
the call carried grants. An error never quotes the answer to such a call, which may echo a
Expand All @@ -186,7 +187,7 @@ async def invoke_transfer(
await staged.push()
async with httpx.AsyncClient() as client:
send = client.post if verb == "POST" else client.put
resp = await send(url, json=call.payload, timeout=timeout)
resp = await send(url, json=call.payload, headers=headers, timeout=timeout)
try:
raise_for_extension_status(resp, operation=operation, include_body=call.mode == "legacy")
except httpx.HTTPStatusError as exc:
Expand Down Expand Up @@ -651,6 +652,7 @@ async def fetch_trajectory(
upload: TrajectoryUpload | None = None,
timeout: float | None = None,
store: ObjectStore | None = None,
headers: Mapping[str, str] | None = None,
) -> FetchedTrajectory:
"""POST one trajectory ``get``. With ``upload`` the agent uploads the trajectory through its
grant, issued by ``store``, and the answer is checked. The default wait covers that upload."""
Expand All @@ -669,6 +671,7 @@ async def fetch_trajectory(
timeout=timeout,
response_model=TrajectoryObjectsResponse,
store=store,
headers=headers,
)
if upload is not None:
return FetchedTrajectory(object_url=upload.object_url)
Expand Down
5 changes: 3 additions & 2 deletions src/agent_env/a2a_agent/protocol.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,8 @@ def raise_for_extension_status(
raise httpx.HTTPStatusError(message, request=exc.request, response=response) from exc


async def post_agent_config(url: str, payload: dict, timeout_seconds: int = 60) -> None:
async def post_agent_config(url: str, payload: dict, timeout_seconds: int = 60, *,
headers: Mapping[str, str] | None = None) -> None:
"""POST to an agent's /ext/agent-config endpoint with retry on transient 404/connect errors.

`url` should be the full endpoint URL (a2a_url + endpoint path from the agent card).
Expand All @@ -77,7 +78,7 @@ async def post_agent_config(url: str, payload: dict, timeout_seconds: int = 60)
for attempt in range(1, max_attempts + 1):
try:
async with httpx.AsyncClient() as client:
resp = await client.post(url, json=payload, timeout=timeout_seconds)
resp = await client.post(url, json=payload, headers=headers, timeout=timeout_seconds)
if resp.status_code == 404:
raise httpx.HTTPStatusError(
f"agent-config endpoint not available (404) at {url} after {max_attempts} "
Expand Down
6 changes: 4 additions & 2 deletions src/agent_env/a2a_agent/trajectory_follower.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
import asyncio
import contextlib
import logging
from collections.abc import Awaitable, Callable
from collections.abc import Awaitable, Callable, Mapping
from contextlib import nullcontext
from dataclasses import dataclass
from typing import Any
Expand Down Expand Up @@ -67,6 +67,7 @@ async def follow_trajectory(
poll_interval_seconds: float,
stop: asyncio.Event,
client: httpx.AsyncClient | None = None,
headers: Mapping[str, str] | None = None,
) -> None:
"""Read task ``task_id``'s trajectory from its first event, handing ``sink`` each page that has
events and the last one, until the task has ended and every event is read.
Expand All @@ -80,7 +81,8 @@ async def follow_trajectory(
while True:
try:
response = await http.post(
endpoint, json={"task_id": task_id, "after": after}, timeout=_READ_TIMEOUT_SECONDS
endpoint, json={"task_id": task_id, "after": after}, headers=headers,
timeout=_READ_TIMEOUT_SECONDS,
)
if response.status_code == 404:
logger.warning("Agent no longer knows task %s; stopped following its trajectory", task_id)
Expand Down
1 change: 1 addition & 0 deletions src/agent_env/a2a_agent/validator.py
Original file line number Diff line number Diff line change
Expand Up @@ -708,6 +708,7 @@ def record(*, supported, advertised, save_ok, apply_ok, roundtrip_ok, note=""):
timeout=TRANSFER_TIMEOUT_SECONDS,
response_model=ObjectChangelogApplyResponse,
store=store,
headers=apply_agent.control_headers,
)
check_changelog_applied(answer, call, agent_name=apply_agent_name)
except Exception as e: # noqa: BLE001
Expand Down
5 changes: 3 additions & 2 deletions src/agent_env/task/episode/proxy.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
import asyncio
import secrets
import threading
from collections.abc import Mapping
from typing import Any, TypeVar

import httpx
Expand Down Expand Up @@ -48,14 +49,14 @@ class ProxyClient:
the proxy, over a connection a tunnel dropped say, is tried again, except ``record``'s, which isn't idempotent.
Answers are read as proxy/v1's models, ignoring fields a newer proxy adds: an agent's protocol isn't pinned."""

def __init__(self, a2a_url: str, card: dict[str, Any]):
def __init__(self, a2a_url: str, card: dict[str, Any], *, headers: Mapping[str, str] | None = None):
proxy = A2AAgent.find_extension(card, PROXY_V1.uri)
if proxy is None:
raise RuntimeError(f"the agent at {a2a_url} isn't a proxy: its card has no {PROXY_V1.uri}")
self._endpoints = {operation: a2a_url + A2AAgent.operation(proxy, operation)[1]
for operation in PROXY_V1.operations}
self._token = secrets.token_urlsafe(24)
self._client = httpx.AsyncClient(timeout=_CALL_TIMEOUT)
self._client = httpx.AsyncClient(timeout=_CALL_TIMEOUT, headers=headers)

async def claim(self) -> None:
await self._call("claim")
Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/task/episode/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ async def _serve_in_process(self, agent: str, role: str | None, mcp_urls: dict[s

async def _attach(self, agent: str, deployed: DeployedAgent) -> None:
"""Claim ``agent``'s proxy and hand out the turns it opens."""
proxy = ProxyClient(deployed.a2a_url, deployed.a2a_card or {})
proxy = ProxyClient(deployed.a2a_url, deployed.a2a_card or {}, headers=deployed.control_headers)
self._proxies.append(proxy)
await proxy.claim()
self._drains.append(asyncio.create_task(self._drain(agent, proxy)))
Expand Down
3 changes: 2 additions & 1 deletion src/agent_env/task/episode/steps.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@ async def execute(self, context: TaskStepContext) -> TaskStepContext:
context.deployed_agents.append(deployed)
if system_prompt := getattr(self.step, "system_prompt", None):
config = A2AAgent.negotiate_agent_config(deployed.a2a_card, {"system_prompt": system_prompt})
await protocol.post_agent_config(deployed.a2a_url + config.endpoint, config.fields)
await protocol.post_agent_config(deployed.a2a_url + config.endpoint, config.fields,
headers=deployed.control_headers)
return context
await asyncio.to_thread(write_installed, PROXY_AGENT_ID)
override = {"a2a_agent_id": PROXY_AGENT_ID} if self.step.type == "deploy_agent" else {PROXY_PARAM: PROXY_AGENT_ID}
Expand Down
9 changes: 9 additions & 0 deletions src/agent_env/task_step/context.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
from dataclasses import dataclass, field
from typing import Any

from agentenv_protocol import client as protocol_v1

from agent_env.config.loader import ENV_REF_PREFIX, SECRET_REF_PREFIX
from agent_env.env.env import DeployedEnv
from agent_env.providers.sandbox_providers.local_docker.provider import LocalSandbox, host_url_for
Expand Down Expand Up @@ -128,6 +130,8 @@ class DeployedAgent:
installed_container: str | None = None
# The envs deploy_agent registered with it, by id.
env_ids: list[str] = field(default_factory=list)
# The token its extension routes take, from the deploy that started it; None for an agent agent-env didn't start.
control_token: str | None = None

@classmethod
def from_dict(cls, data: dict) -> DeployedAgent:
Expand All @@ -144,8 +148,13 @@ def from_dict(cls, data: dict) -> DeployedAgent:
on_host=bool(data.get("on_host", False)),
installed_container=data.get("installed_container"),
env_ids=list(data.get("env_ids") or []),
control_token=data.get("control_token"),
)

@property
def control_headers(self) -> dict[str, str]:
return protocol_v1.control_token_headers(self.control_token)

def url_for(self, sandbox_type: str | None, *, on_host: bool = False) -> str:
"""This agent's A2A URL as an agent on ``sandbox_type`` reaches it, in a container there or, ``on_host``, on
the sandbox's host. A local sandbox's host is this machine, which reaches the URL as it is. An agent outside
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
import logging
import uuid
from dataclasses import dataclass
from collections.abc import Mapping
from typing import Any, Optional

import httpx
Expand Down Expand Up @@ -64,6 +65,7 @@ async def capture_workspace(
artifact_id: str,
timeout_seconds: float,
sandbox_type: str | None,
headers: Mapping[str, str],
) -> WorkspaceCapture:
"""Capture the agent's workspace below a fresh prefix and wrap it as a universe.

Expand Down Expand Up @@ -103,6 +105,7 @@ async def capture_workspace(
timeout=timeout_seconds,
response_model=ObjectSnapshotSaveResponse,
store=store,
headers=headers,
)

# The agent's answer is only a claim: a snapshot missing either object cannot be restored.
Expand Down Expand Up @@ -149,6 +152,7 @@ async def read_partial_trajectory(
timeout_seconds: float,
trajectory_output_prefix: str,
sandbox_type: str | None,
headers: Mapping[str, str],
) -> TrajectoryCapture:
"""Read the trajectory-so-far for an in-progress run.

Expand Down Expand Up @@ -191,7 +195,8 @@ async def read_partial_trajectory(
return TrajectoryCapture(reason="trajectory_grant_unavailable")
try:
fetched = await fetch_trajectory(
a2a_url + get_path, {"context_id": context_id}, upload=upload, timeout=timeout_seconds, store=store
a2a_url + get_path, {"context_id": context_id}, upload=upload, timeout=timeout_seconds, store=store,
headers=headers,
)
except httpx.HTTPStatusError as exc:
if exc.response.status_code == 404:
Expand Down
15 changes: 11 additions & 4 deletions src/agent_env/task_step/snapshot_utils/live_trajectory.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import asyncio
import json
import logging
from collections.abc import AsyncIterator, Awaitable
from collections.abc import AsyncIterator, Awaitable, Mapping
from contextlib import asynccontextmanager

from agentenv_protocol.a2a_agent import TrajectoryState
Expand Down Expand Up @@ -88,8 +88,10 @@ def __init__(
turn_id: str,
poll_interval_seconds: float,
previous_turn_id: str | None,
headers: Mapping[str, str],
) -> None:
self._endpoint = endpoint
self._headers = headers
self._store = store
self._prefix_key = prefix_key
self._turn_id = turn_id
Expand All @@ -112,7 +114,8 @@ def follow(self, task_id: str) -> None:
self.followers.append(
asyncio.create_task(
follow_trajectory(
self._endpoint, task_id, sink, poll_interval_seconds=self._poll_interval_seconds, stop=self.stop
self._endpoint, task_id, sink, poll_interval_seconds=self._poll_interval_seconds, stop=self.stop,
headers=self._headers,
)
)
)
Expand All @@ -130,6 +133,7 @@ async def following_live_trajectory(
turn_id: str,
*,
poll_interval_seconds: float,
headers: Mapping[str, str],
previous_turn_id: str | None = None,
) -> AsyncIterator[LiveTurn]:
"""Yield the turn whose task is followed once its message is sent; then ``previous_turn_id``'s
Expand All @@ -140,7 +144,7 @@ async def following_live_trajectory(
end the follower did not read is marked ended in the state the body reported, else ``canceled``
for a cancelled step or ``failed``, so readers do not wait on it. A follower's own failure is
logged and never fails the turn."""
turn = LiveTurn(endpoint, store, prefix_key, turn_id, poll_interval_seconds, previous_turn_id)
turn = LiveTurn(endpoint, store, prefix_key, turn_id, poll_interval_seconds, previous_turn_id, headers)
stopped_as = TrajectoryState.FAILED

try:
Expand Down Expand Up @@ -179,8 +183,10 @@ class LiveTurns:
"""A step's turns, followed one after another: a turn sent after another is named in that one's
``next.json``, and ``end`` marks the last turn sent as the step's last."""

def __init__(self, endpoint: str, store: ObjectStore, prefix_key: str, *, poll_interval_seconds: float) -> None:
def __init__(self, endpoint: str, store: ObjectStore, prefix_key: str, *, poll_interval_seconds: float,
headers: Mapping[str, str]) -> None:
self._endpoint = endpoint
self._headers = headers
self._store = store
self._prefix_key = prefix_key
self._poll_interval_seconds = poll_interval_seconds
Expand All @@ -195,6 +201,7 @@ async def following(self, turn_id: str) -> AsyncIterator[LiveTurn]:
self._prefix_key,
turn_id,
poll_interval_seconds=self._poll_interval_seconds,
headers=self._headers,
previous_turn_id=self._last_sent,
) as turn:
try:
Expand Down
Loading
Loading