agentenv-framework-protocol 0.1.350__tar.gz → 0.1.351__tar.gz

{agentenv_framework_protocol-0.1.350 → agentenv_framework_protocol-0.1.351}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.350
+Version: 0.1.351
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -30,6 +30,7 @@ Requires-Dist: pydantic>=2.11
 Requires-Dist: starlette>=0.37
 Provides-Extra: agent
 Requires-Dist: a2a-sdk[http-server]<0.4,>=0.3.26; extra == 'agent'
+Requires-Dist: mcp<2,>=1.25; extra == 'agent'
 Requires-Dist: python-multipart>=0.0.13; extra == 'agent'
 Requires-Dist: regex>=2023.12.25; extra == 'agent'
 Requires-Dist: uvicorn>=0.30; extra == 'agent'
@@ -126,6 +127,15 @@ environment-prefixed tools without knowing the name at class-definition time; an
 servers an env deploys behind one gateway: if two serve a name, the gateway serves none of their
 tools and the deploy fails naming it, so prefix with `{environment_name}` when servers may share one.
 
+`@tool(..., hidden_by_default=True)` makes being hidden a fixed property of the tool, for plumbing a
+task drives (a trigger's tool action, a simulated party) that the agent under test must not see. The
+tool is listed with `_meta` `{"agentenv.io/hiddenByDefault": true}` (`HIDDEN_BY_DEFAULT_META_KEY`),
+and the gateway hides it from every role, in its MCP `tools/list` and `/step`, until a tool-access
+step names it. Steps that name it show and hide it as they do any tool. Steps for every tool
+(`tools: "*"`) never show it, but as with any tool they replace earlier steps: one for a role clears
+that role's earlier named steps, and a full reset (`role: "*", tools: "*"`) clears all of them, so
+grant a hidden tool after such steps. Trigger tool actions call it as usual.
+
 `AgentEnvStarletteApplication` mounts the same handler onto a Starlette/FastAPI app instead of
 FastMCP; since those apps have no MCP tool registry, constructing one with `@tool` methods
 raises.
@@ -706,6 +716,21 @@ tools with (agent-env relays the env card's name: the MultiEnv's declared name,
 `env` + 4 random digits, giving e.g. `mcp__env4821__<tool>`); when absent the agent mints
 `mcp_<8 hex>`.
 
+`PEER_AGENTS_V1` lets an agent delegate to the other agents in its task. AgentEnv
+sets the routing table with `POST /ext/peer-agents` (`{"peers": [{"name", "url",
+"card", "description"}]}`; an empty list clears it, and names must be unique), and
+`GET /ext/peer-agents` returns it. An agent that enables the extension without
+handlers of its own gets the SDK's: the SDK serves six MCP tools, `peer_list`,
+`peer_get_card`, `peer_send_message` (send and wait, for at most 50 s, so a call
+answers within the 60 s MCP clients commonly give a request), `peer_start_task`,
+`peer_get_task` and `peer_cancel_task`, at `/ext/peer-agents/mcp` on the agent's
+own port, and adds them to every task's `request.mcp_servers` as `peer_agents`, so
+a harness that connects the task's MCP servers gives its model the tools with no
+code of its own. The tools wrap the peers' A2A `message/send`, `tasks/get` and
+`tasks/cancel`; they answer loopback callers only, while the application's lifespan
+runs, and the name `peer_agents` is reserved from `MCP_CONFIG_V1.add`. An agent that
+overrides both operations keeps the table itself and gets no tools.
+
 `ATTRIBUTION_PROBE_V1.probe` lets a caller check that an agent forwards attribution
 upstream. Attribution is an open map of string dimensions, like AgentEnv's cost
 attribution: the SDK assigns no keys, and each deployment uses whatever dimensions

{agentenv_framework_protocol-0.1.350 → agentenv_framework_protocol-0.1.351}/README.md

@@ -81,6 +81,15 @@ environment-prefixed tools without knowing the name at class-definition time; an
 servers an env deploys behind one gateway: if two serve a name, the gateway serves none of their
 tools and the deploy fails naming it, so prefix with `{environment_name}` when servers may share one.
 
+`@tool(..., hidden_by_default=True)` makes being hidden a fixed property of the tool, for plumbing a
+task drives (a trigger's tool action, a simulated party) that the agent under test must not see. The
+tool is listed with `_meta` `{"agentenv.io/hiddenByDefault": true}` (`HIDDEN_BY_DEFAULT_META_KEY`),
+and the gateway hides it from every role, in its MCP `tools/list` and `/step`, until a tool-access
+step names it. Steps that name it show and hide it as they do any tool. Steps for every tool
+(`tools: "*"`) never show it, but as with any tool they replace earlier steps: one for a role clears
+that role's earlier named steps, and a full reset (`role: "*", tools: "*"`) clears all of them, so
+grant a hidden tool after such steps. Trigger tool actions call it as usual.
+
 `AgentEnvStarletteApplication` mounts the same handler onto a Starlette/FastAPI app instead of
 FastMCP; since those apps have no MCP tool registry, constructing one with `@tool` methods
 raises.
@@ -661,6 +670,21 @@ tools with (agent-env relays the env card's name: the MultiEnv's declared name,
 `env` + 4 random digits, giving e.g. `mcp__env4821__<tool>`); when absent the agent mints
 `mcp_<8 hex>`.
 
+`PEER_AGENTS_V1` lets an agent delegate to the other agents in its task. AgentEnv
+sets the routing table with `POST /ext/peer-agents` (`{"peers": [{"name", "url",
+"card", "description"}]}`; an empty list clears it, and names must be unique), and
+`GET /ext/peer-agents` returns it. An agent that enables the extension without
+handlers of its own gets the SDK's: the SDK serves six MCP tools, `peer_list`,
+`peer_get_card`, `peer_send_message` (send and wait, for at most 50 s, so a call
+answers within the 60 s MCP clients commonly give a request), `peer_start_task`,
+`peer_get_task` and `peer_cancel_task`, at `/ext/peer-agents/mcp` on the agent's
+own port, and adds them to every task's `request.mcp_servers` as `peer_agents`, so
+a harness that connects the task's MCP servers gives its model the tools with no
+code of its own. The tools wrap the peers' A2A `message/send`, `tasks/get` and
+`tasks/cancel`; they answer loopback callers only, while the application's lifespan
+runs, and the name `peer_agents` is reserved from `MCP_CONFIG_V1.add`. An agent that
+overrides both operations keeps the table itself and gets no tools.
+
 `ATTRIBUTION_PROBE_V1.probe` lets a caller check that an agent forwards attribution
 upstream. Attribution is an open map of string dimensions, like AgentEnv's cost
 attribution: the SDK assigns no keys, and each deployment uses whatever dimensions

{agentenv_framework_protocol-0.1.350 → agentenv_framework_protocol-0.1.351}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.350"
+version = "0.1.351"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"
@@ -30,6 +30,7 @@ dependencies = [
 [project.optional-dependencies]
 agent = [
     "a2a-sdk[http-server]>=0.3.26,<0.4",
+    "mcp>=1.25,<2",  # the peer-agents tools' MCP server; 2.0 removed the server API it serves them with
     "python-multipart>=0.0.13",  # the staging extension's upload forms
     "regex>=2023.12.25",
     "uvicorn>=0.30",

{agentenv_framework_protocol-0.1.350 → agentenv_framework_protocol-0.1.351}/src/agentenv_protocol/__init__.py

@@ -4,6 +4,7 @@ from . import client
 from .preflight import intake_fit_check
 from .tool_client import ToolResult, ToolSession, ToolSessionError
 from .agent_env_environment import (
+    HIDDEN_BY_DEFAULT_META_KEY,
     AgentEnvApplication,
     AgentEnvEnvironment,
     AgentEnvFastMCPApplication,
@@ -97,6 +98,7 @@ __all__ = [
     "bound",
     "ROLE_META_KEY",
     "SESSION_META_KEY",
+    "HIDDEN_BY_DEFAULT_META_KEY",
     "ROLE_HEADER",
     "DEFAULT_ROLE",
     "EnvironmentCapabilities",

{agentenv_framework_protocol-0.1.350 → agentenv_framework_protocol-0.1.351}/src/agentenv_protocol/a2a_agent/extensions.py

@@ -1106,11 +1106,11 @@ PEER_AGENTS_V1 = ExtensionDefinition(
             "set",
             "POST",
             "/ext/peer-agents",
-            RUNTIME,
+            SDK,
             request_model=PeerAgentsSetRequest,
         ),
         "list": _op(
-            "list", "GET", "/ext/peer-agents", RUNTIME, response_required=("peers",)
+            "list", "GET", "/ext/peer-agents", SDK, response_required=("peers",)
         ),
     },
 )

{agentenv_framework_protocol-0.1.350 → agentenv_framework_protocol-0.1.351}/src/agentenv_protocol/a2a_agent/framework.py

@@ -34,6 +34,7 @@ from .extensions import (
     AGENT_CONFIG_V1,
     MAX_TRAJECTORY_READ_EVENTS,
     MCP_CONFIG_V1,
+    PEER_AGENTS_V1,
     SKILL_CONFIG_V1,
     TRAJECTORY_V1,
     TRIGGERS_V1,
@@ -45,6 +46,7 @@ from .extensions import (
     ImplementationOwner,
     McpAddRequest,
     OperationReference,
+    PeerAgentsSetRequest,
     TaskEventsTrajectoryRequest,
     TaskObjectTrajectoryRequest,
     TaskTrajectoryRequest,
@@ -54,6 +56,7 @@ from .extensions import (
     TriggerRegisterRequest,
     enable,
 )
+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
 from .tasks.v1 import (
@@ -545,6 +548,8 @@ class _SdkServices:
         self._skill_registration_lock = asyncio.Lock()
         self.card: Any = None
         self.trigger_engine = TriggerEngine()
+        # Set when the SDK serves peer-agents/v1 for this agent.
+        self.peers: PeerAgents | None = None
 
     def task_config(self) -> AgentConfig:
         return self.config_model.model_validate(
@@ -611,6 +616,8 @@ class _SdkServices:
             (AGENT_CONFIG_V1.uri, "get"): self.agent_config_get,
             (MCP_CONFIG_V1.uri, "add"): self.mcp_add,
             (MCP_CONFIG_V1.uri, "list"): self.mcp_list,
+            (PEER_AGENTS_V1.uri, "set"): self.peer_agents_set,
+            (PEER_AGENTS_V1.uri, "list"): self.peer_agents_list,
             (SKILL_CONFIG_V1.uri, "list"): self.skill_list,
             (TRAJECTORY_V1.uri, "get"): self.trajectory_get,
             (TRIGGERS_V1.uri, "register"): self.triggers_register,
@@ -695,6 +702,8 @@ class _SdkServices:
         name = request.name or f"mcp_{uuid.uuid4().hex[:8]}"
         if name in self.mcp_servers:
             raise HTTPException(status_code=409, detail=f"MCP name '{name}' is already registered")
+        if self.peers is not None and name == PEER_MCP_SERVER_NAME:
+            raise HTTPException(status_code=409, detail=f"MCP name '{name}' is the SDK's peer-agents server")
         self.mcp_servers[name] = {
             "url": url,
             "headers": dict(request.headers) if request.headers else None,
@@ -708,10 +717,30 @@ class _SdkServices:
                     "url": registration["url"],
                     "has_headers": bool(registration.get("headers")),
                 }
-                for name, registration in self.mcp_servers.items()
+                for name, registration in self.task_mcp_servers().items()
             }
         }
 
+    def task_mcp_servers(self) -> dict[str, dict[str, Any]]:
+        """The MCP servers a task gets: those registered, and the SDK's peer-agents server when it serves one."""
+        peer_tools = self.peers.registration() if self.peers is not None else None
+        return {**self.mcp_servers, **({PEER_MCP_SERVER_NAME: peer_tools} if peer_tools else {})}
+
+    async def peer_agents_set(self, request: PeerAgentsSetRequest) -> dict[str, Any]:
+        names = [peer.name for peer in request.peers]
+        if len(set(names)) != len(names):
+            raise HTTPException(status_code=400, detail="peer names must be unique")
+        self._served_peers().set(request.peers)
+        return {"status": "updated", "peers": len(names)}
+
+    async def peer_agents_list(self) -> dict[str, Any]:
+        return {"peers": self._served_peers().listing()}
+
+    def _served_peers(self) -> PeerAgents:
+        if self.peers is None:
+            raise HTTPException(status_code=500, detail="the SDK serves no peer-agents tools for this agent")
+        return self.peers
+
     async def skill_list(self) -> dict[str, Any]:
         skills = {
             name: {"description": description}
@@ -874,6 +903,24 @@ class DefaultExtensionHandlers:
         return await _invoke(handler, request)
 
 
+def _serving_peer_tools(
+    peers: PeerAgents,
+    inner: Callable[[Starlette], AbstractAsyncContextManager] | None,
+) -> Callable[[Starlette], AbstractAsyncContextManager]:
+    """The application's lifespan, ``inner``'s if it has one, with the peer-agents tools served throughout."""
+
+    @asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncIterator[Any]:
+        async with peers.serving():
+            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."""
 
@@ -930,6 +977,20 @@ class A2AAgentApplication:
                         f"extension operation {extension.definition.uri}.{operation.definition.name} "
                         f"conflicts with the staging routes below {STAGING_ENDPOINT}"
                     )
+        # The SDK serves peer-agents/v1's tools to an agent that enables it without handlers of its own.
+        peer_agents = next(
+            (extension for extension in self.registry.extensions if extension.definition.uri == PEER_AGENTS_V1.uri),
+            None,
+        )
+        if peer_agents is not None and not peer_agents.operations["set"].overridden:
+            for extension in self.registry.extensions:
+                for operation in extension.operations.values():
+                    if operation.definition.path == PEER_MCP_PATH:
+                        raise ValueError(
+                            f"extension operation {extension.definition.uri}.{operation.definition.name} "
+                            f"conflicts with the peer-agents tools at {PEER_MCP_PATH}"
+                        )
+            self.services.peers = PeerAgents()
         conformance = self.registry.conformance()
         for override in conformance["standard_operation_overrides"]:
             logger.warning(
@@ -965,9 +1026,13 @@ class A2AAgentApplication:
                 )
         if self.staging.max_bytes:
             routes.extend(staging_routes(self.staging))
+        lifespan = definition.lifespan
+        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 definition.lifespan is not None:
-            kwargs["lifespan"] = definition.lifespan
+        if lifespan is not None:
+            kwargs["lifespan"] = lifespan
         self.app = Starlette(**kwargs)
 
         try:
@@ -1171,7 +1236,7 @@ class _StandardExecutor:
                         _from_a2a_part(part) for part in (context.message.parts or [])
                     ),
                     config=task_config,
-                    mcp_servers=self._services.mcp_servers,
+                    mcp_servers=self._services.task_mcp_servers(),
                     skills=tuple(self._services.skills),
                     metadata=metadata,
                     session_ref=self._services.session_ref_for_context(task.context_id),