From 674f93723879f646629c48567da1c308f630274a Mon Sep 17 00:00:00 2001 From: kaihackney-scale Date: Thu, 19 Nov 2026 21:31:24 -0500 Subject: [PATCH] deploy_agent: a peer_tools option to leave out the peer_agents tools A deploy_agent step can already narrow an agent's own tools with builtin_tools, but every claude-code turn still got the SDK's peer_agents MCP tools, and only code (the always-on verifier's judge) could turn them off. A task now sets peer_tools: false on the step. It is checked against the agent's agent-config before the first request (an agent that can't take it fails the deploy), sent with the identity, kept on the card, and sent again on each prompt_agent and always_on turn like builtin_tools, including to a peer user sim, which until now got neither again. Co-Authored-By: Claude Opus 5.5 --- src/agent_env/agents/README.md | 4 +- .../task_step/task_steps/always_on.py | 2 +- .../task_step/task_steps/deploy_agent.py | 27 ++++++++++++- .../task_step/task_steps/prompt_agent.py | 10 +++-- .../test_deploy_agent_role_delivery.py | 38 ++++++++++++++++++ .../test_prompt_agent_builtin_tools.py | 39 +++++++++++++++++-- 6 files changed, 110 insertions(+), 10 deletions(-) diff --git a/src/agent_env/agents/README.md b/src/agent_env/agents/README.md index 10d858f57..87c50fb3b 100644 --- a/src/agent_env/agents/README.md +++ b/src/agent_env/agents/README.md @@ -29,7 +29,9 @@ mostly the lxml and Pillow they depend on, and their pins match the Codex and Ge task's documents read the same way in each. A `deploy_agent` `builtin_tools` selection picks the CLI's own tools: `{"disable": "*"}` and `{"only": [...]}` become its `--tools` list, a list to turn off becomes `--disallowedTools`, which keeps the CLI's defaults for the rest, and any selection adds -`--strict-mcp-config`, so its MCP servers are only the task env's. Tool search is off unless the agent's environment sets +`--strict-mcp-config`, so its MCP servers are only the task env's. A `deploy_agent` `peer_tools: false` also leaves out the peer_agents MCP +server, so the agent can't message the task's other agents; an agent whose agent-config takes no `peer_tools` fails +the deploy. Tool search is off unless the agent's environment sets `ENABLE_TOOL_SEARCH`, so the CLI sends the env's tools and its own up front. The names are `ClaudeCodeTool`'s in `claude_bridge.py`: every tool the pinned CLI has, though which it offers by default depends on the model. A test fails when the Dockerfile's `CLAUDE_CODE_VERSION` moves, until `ClaudeCodeTool` and `TOOLS_CLI_VERSION` move with it. diff --git a/src/agent_env/task_step/task_steps/always_on.py b/src/agent_env/task_step/task_steps/always_on.py index 09d99bedc..5c071875b 100644 --- a/src/agent_env/task_step/task_steps/always_on.py +++ b/src/agent_env/task_step/task_steps/always_on.py @@ -585,7 +585,7 @@ async def _configure_agents(self) -> None: "max_thinking_tokens": overrides.get("agent_max_thinking_tokens") or step.max_thinking_tokens, "output_format": step.output_format, "timeout_seconds": step.timeout_seconds, "task_id": ctx.metadata.get("task_id"), "agentenv_tools": step.agentenv_tools, - "builtin_tools": card.get("builtin_tools")} + "builtin_tools": card.get("builtin_tools"), "peer_tools": card.get("peer_tools")} desired = {k: v for k, v in desired.items() if v is not None} model_params = get_config().get_model_params(step.model_params) if model_params: diff --git a/src/agent_env/task_step/task_steps/deploy_agent.py b/src/agent_env/task_step/task_steps/deploy_agent.py index cbb4adb95..3f27c65f4 100644 --- a/src/agent_env/task_step/task_steps/deploy_agent.py +++ b/src/agent_env/task_step/task_steps/deploy_agent.py @@ -151,10 +151,15 @@ def _skill_fields(skill: dict) -> dict: +def _config_request(agent_config: dict | None) -> dict: + """The ``set`` request description of a card's agent-config extension.""" + return ((agent_config or {}).get("params") or {}).get("methods", {}).get("set", {}).get("request", {}) + + def _check_builtin_tools(agent_config: dict | None, agent_name: str, selection: dict) -> None: """Refuse a selection of the agent's own tools that its card's agent-config extension can't take: it has no ``builtin_tools``, or its schema doesn't name a tool the selection does.""" - request = ((agent_config or {}).get("params") or {}).get("methods", {}).get("set", {}).get("request", {}) + request = _config_request(agent_config) if "builtin_tools" not in request.get("supported", []): raise RuntimeError(f"Agent '{agent_name}' cannot have its own tools selected: its card's " f"{AGENT_CONFIG_V1.uri} takes no 'builtin_tools'") @@ -165,6 +170,14 @@ def _check_builtin_tools(agent_config: dict | None, agent_name: str, selection: if error is not None: raise RuntimeError(f"Agent '{agent_name}' can't take builtin_tools {selection}: {error.message}") + +def _check_peer_tools(agent_config: dict | None, agent_name: str) -> None: + """Refuse to turn off the peer_agents tools of an agent whose card's agent-config extension can't take + ``peer_tools``: it would keep them.""" + if "peer_tools" not in _config_request(agent_config).get("supported", []): + raise RuntimeError(f"Agent '{agent_name}' cannot have its peer_agents tools turned off: its card's " + f"{AGENT_CONFIG_V1.uri} takes no 'peer_tools'") + class DeployAgentTaskStep(TaskStep): type: ClassVar[str] = "deploy_agent" entity_refs = ( @@ -208,6 +221,7 @@ def __init__( network_policy: Optional[dict] = None, role: Optional[str] = None, builtin_tools: Optional[dict] = None, + peer_tools: Optional[bool] = None, enable_agent_changelog: bool = False, agent_changelog_toolcall_position_exclusive: Optional[int] = None, sandbox_name: Optional[str] = None, @@ -241,6 +255,10 @@ def __init__( self.role = role or None self.builtin_tools = (None if builtin_tools is None else BuiltinTools[str].model_validate(builtin_tools).model_dump(exclude_none=True)) + # False: the agent gets no peer_agents MCP tools, so it can't message the task's other agents. + if peer_tools is not None and not isinstance(peer_tools, bool): + raise ValueError(f"peer_tools must be true or false, not {peer_tools!r}") + self.peer_tools = peer_tools self.enable_agent_changelog = enable_agent_changelog self.agent_changelog_object_url = agent_changelog_object_url self.agent_changelog_toolcall_position_exclusive = agent_changelog_toolcall_position_exclusive @@ -279,6 +297,7 @@ def to_dict(self) -> dict: base["network_policy"] = self.network_policy base["role"] = self.role base["builtin_tools"] = self.builtin_tools + base["peer_tools"] = self.peer_tools base["enable_agent_changelog"] = self.enable_agent_changelog base["agent_changelog_object_url"] = self.agent_changelog_object_url base["agent_changelog_toolcall_position_exclusive"] = self.agent_changelog_toolcall_position_exclusive @@ -312,6 +331,7 @@ def from_dict(cls, data: dict) -> DeployAgentTaskStep: network_policy=data.get("network_policy"), role=data.get("role"), builtin_tools=data.get("builtin_tools"), + peer_tools=data.get("peer_tools"), enable_agent_changelog=data.get("enable_agent_changelog", False), agent_changelog_object_url=data.get("agent_changelog_object_url"), agent_changelog_toolcall_position_exclusive=data.get("agent_changelog_toolcall_position_exclusive"), @@ -464,6 +484,11 @@ async def _execute(self, context: TaskStepContext, deployed_agents: list) -> Tas _check_builtin_tools(A2AAgent.find_extension(card, A2AAgent.EXT_AGENT_CONFIG), self.agent_name, self.builtin_tools) identity_payload["builtin_tools"] = self.builtin_tools + if self.peer_tools is not None: + if not self.peer_tools: + # Before the first request to the agent, as for builtin_tools. + _check_peer_tools(A2AAgent.find_extension(card, A2AAgent.EXT_AGENT_CONFIG), self.agent_name) + identity_payload["peer_tools"] = self.peer_tools identity = A2AAgent.negotiate_agent_config(card, identity_payload) if self.role is not None: carried_by = [via for via, carried in ( diff --git a/src/agent_env/task_step/task_steps/prompt_agent.py b/src/agent_env/task_step/task_steps/prompt_agent.py index 64f862c81..2aa97970e 100644 --- a/src/agent_env/task_step/task_steps/prompt_agent.py +++ b/src/agent_env/task_step/task_steps/prompt_agent.py @@ -549,7 +549,7 @@ async def _converse( "task_id": context.metadata.get("task_id"), "agentenv_tools": self.agentenv_tools, # Again each turn, so an agent that restarted since deploy_agent sent it doesn't get its own tools back. - "builtin_tools": card.get("builtin_tools"), + "builtin_tools": card.get("builtin_tools"), "peer_tools": card.get("peer_tools"), } desired_config = {k: v for k, v in desired_config.items() if v is not None} model_params = get_config().get_model_params(self.model_params) @@ -568,8 +568,12 @@ async def _converse( elif is_user_sim: user_output_format = self.user_output_format or _DEFAULT_USER_SIM_OUTPUT_FORMAT user_model = self._resolve_user_model(context) - user_config = {k: v for k, v in {"output_format": user_output_format, "model": user_model}.items() if v is not None} - negotiated = A2AAgent.negotiate_agent_config(user_sim.a2a_card or {}, user_config) + user_card = user_sim.a2a_card or {} + # Its own tools and peer tools as deploy_agent set them, again, as for the agent above. + user_config = {k: v for k, v in {"output_format": user_output_format, "model": user_model, + "builtin_tools": user_card.get("builtin_tools"), + "peer_tools": user_card.get("peer_tools")}.items() if v is not None} + negotiated = A2AAgent.negotiate_agent_config(user_card, user_config) if negotiated: await protocol.post_agent_config(user_url + negotiated.endpoint, negotiated.fields, headers=user_sim.control_headers) diff --git a/tst/unit/task_step/test_deploy_agent_role_delivery.py b/tst/unit/task_step/test_deploy_agent_role_delivery.py index 3e605df0f..8c2db9611 100644 --- a/tst/unit/task_step/test_deploy_agent_role_delivery.py +++ b/tst/unit/task_step/test_deploy_agent_role_delivery.py @@ -229,6 +229,44 @@ async def test_a_selection_the_agent_cannot_take_fails_before_any_request(wiring assert wiring.agent.close.await_count == 1 +PEER_CONFIG = _agent_config(["name", "description", "peer_tools"]) + + +@pytest.mark.asyncio +async def test_peer_tools_off_is_sent_once_with_its_identity_and_kept_on_the_card(wiring): + context = await wiring.deploy(_card(HEADERS_MCP, PEER_CONFIG), role=None, peer_tools=False) + + assert wiring.bodies("/ext/agent-config") == [{"name": "solver", "peer_tools": False}] + assert context.deployed_agents[0].a2a_card["peer_tools"] is False + + +@pytest.mark.asyncio +async def test_peer_tools_left_unset_sends_none(wiring): + await wiring.deploy(_card(HEADERS_MCP, PEER_CONFIG), role=None) + + assert wiring.bodies("/ext/agent-config") == [{"name": "solver"}] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("card", [_card(HEADERS_MCP, ROLE_CONFIG), _card(HEADERS_MCP)], + ids=["config-without-it", "no-agent-config"]) +async def test_peer_tools_off_on_an_agent_that_cannot_take_it_fails_before_any_request(wiring, card): + with pytest.raises(RuntimeError, match="takes no 'peer_tools'"): + await wiring.deploy(card, role=None, peer_tools=False) + + assert wiring.requests == [] + assert wiring.agent.close.await_count == 1 + + +def test_peer_tools_is_a_bool_and_round_trips(): + with pytest.raises(ValueError): + DeployAgentTaskStep(id="ag", version=None, peer_tools="no") + step = DeployAgentTaskStep(id="ag", version=None, peer_tools=False) + assert DeployAgentTaskStep.from_dict({**step.to_dict(), "version": 1}).peer_tools is False + assert DeployAgentTaskStep.from_dict({**DeployAgentTaskStep(id="ag", version=None).to_dict(), + "version": 1}).peer_tools is None + + def test_a_selection_takes_exactly_one_of_disable_and_only(): for selection in ({}, {"disable": "*", "only": ["Read"]}, {"enable": ["Read"]}): with pytest.raises(ValueError): diff --git a/tst/unit/task_step/test_prompt_agent_builtin_tools.py b/tst/unit/task_step/test_prompt_agent_builtin_tools.py index cadbfe19f..f441bb811 100644 --- a/tst/unit/task_step/test_prompt_agent_builtin_tools.py +++ b/tst/unit/task_step/test_prompt_agent_builtin_tools.py @@ -1,6 +1,6 @@ -"""prompt_agent sends the agent's selection of its own tools again on every turn, as deploy_agent recorded it on the -agent's card, so an agent that restarted since its deploy doesn't get its own tools back; an agent deployed without -one is sent none.""" +"""prompt_agent sends the agent's selection of its own tools, and peer_tools, again on every turn, as deploy_agent +recorded them on the agent's card, so an agent that restarted since its deploy doesn't get its tools back; an agent +deployed without them is sent none. A user sim gets its own the same way.""" from unittest.mock import MagicMock @@ -12,7 +12,7 @@ from agent_env.task_step.task_steps import prompt_agent as pa_mod from agent_env.task_step.task_steps.prompt_agent import PromptAgentTaskStep -SUPPORTED = ["model", "builtin_tools"] +SUPPORTED = ["model", "builtin_tools", "peer_tools"] @pytest.fixture @@ -81,3 +81,34 @@ async def post_agent_config(url, fields, headers=None): await PromptAgentTaskStep(id="one", version=None, prompt="one", agent_name="solver").execute(context) assert sent == [{"AgentEnv-Control-Token": "tok"}] + + +@pytest.mark.asyncio +async def test_every_turn_sends_peer_tools_off_as_deploy_agent_recorded(posted): + context = _context(peer_tools=False) + + for turn in ("one", "two"): + await PromptAgentTaskStep(id=turn, version=None, prompt=turn, agent_name="solver").execute(context) + + assert [fields.get("peer_tools") for fields in posted] == [False, False] + + +@pytest.mark.asyncio +async def test_a_user_sim_is_sent_its_own_tools_and_peer_tools_each_turn(posted, monkeypatch): + context = _context() + user_card = {**context.deployed_agents[0].a2a_card, "builtin_tools": {"disable": "*"}, "peer_tools": False} + context.deployed_agents.append(DeployedAgent(agent_name="usersim", api_url="http://usersim", + a2a_url="http://usersim", a2a_card=user_card)) + step = PromptAgentTaskStep(id="one", version=None, prompt="one", agent_name="solver", user_agent_name="usersim") + calls = [] + + async def post_agent_config(url, fields, headers=None): + calls.append((url, fields)) + + monkeypatch.setattr(pa_mod.protocol, "post_agent_config", post_agent_config) + + await step.execute(context) + + user_fields = [fields for url, fields in calls if url.startswith("http://usersim")] + assert user_fields and all(f.get("builtin_tools") == {"disable": "*"} and f.get("peer_tools") is False + for f in user_fields)