agentenv-framework-protocol 0.1.425__tar.gz → 0.1.426__tar.gz

{agentenv_framework_protocol-0.1.425 → agentenv_framework_protocol-0.1.426}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.425
+Version: 0.1.426
 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
@@ -1063,6 +1063,23 @@ class MyAgentConfig(AgentConfig):
     provider_token: WriteOnly[str | None] = None
 ```
 
+An agent that can turn its own tools off, such as its shell, file or web tools, takes `builtin_tools`, typed
+`BuiltinTools` over a `Literal` of its tools' names, so its card's schema names them. A task selects them on
+`deploy_agent`: `{"disable": "*"}` turns them all off, `{"disable": [...]}` the ones named, and `{"only": [...]}` keeps
+the ones named; the agent applies `request.config.builtin_tools` to its runtime. The MCP tools AgentEnv gives it are not
+its own and stay. A selection for an agent whose config has
+no `builtin_tools`, or that names a tool its schema doesn't, is refused before the deploy sends it anything.
+
+```python
+from typing import Literal
+
+from agentenv_protocol.a2a_agent import AgentConfig, BuiltinTools
+
+
+class MyAgentConfig(AgentConfig):
+    builtin_tools: BuiltinTools[Literal["shell", "read_file", "web_fetch"]] | None = None
+```
+
 `output_format` is author-owned in v1 rather than a field on the base
 `AgentConfig`. An agent that supports structured output must declare the field
 on its config subclass, apply it to its model or runtime, and return the value

{agentenv_framework_protocol-0.1.425 → agentenv_framework_protocol-0.1.426}/README.md

@@ -1007,6 +1007,23 @@ class MyAgentConfig(AgentConfig):
     provider_token: WriteOnly[str | None] = None
 ```
 
+An agent that can turn its own tools off, such as its shell, file or web tools, takes `builtin_tools`, typed
+`BuiltinTools` over a `Literal` of its tools' names, so its card's schema names them. A task selects them on
+`deploy_agent`: `{"disable": "*"}` turns them all off, `{"disable": [...]}` the ones named, and `{"only": [...]}` keeps
+the ones named; the agent applies `request.config.builtin_tools` to its runtime. The MCP tools AgentEnv gives it are not
+its own and stay. A selection for an agent whose config has
+no `builtin_tools`, or that names a tool its schema doesn't, is refused before the deploy sends it anything.
+
+```python
+from typing import Literal
+
+from agentenv_protocol.a2a_agent import AgentConfig, BuiltinTools
+
+
+class MyAgentConfig(AgentConfig):
+    builtin_tools: BuiltinTools[Literal["shell", "read_file", "web_fetch"]] | None = None
+```
+
 `output_format` is author-owned in v1 rather than a field on the base
 `AgentConfig`. An agent that supports structured output must declare the field
 on its config subclass, apply it to its model or runtime, and return the value

{agentenv_framework_protocol-0.1.425 → agentenv_framework_protocol-0.1.426}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.425"
+version = "0.1.426"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.425 → agentenv_framework_protocol-0.1.426}/src/agentenv_protocol/a2a_agent/__init__.py

@@ -102,6 +102,7 @@ from .registry import (
 from .staging import STAGING_ENDPOINT, STAGING_V1_URI, StagingStore, staging_routes
 from .tasks.v1 import (
     AgentConfig,
+    BuiltinTools,
     AgentRunResult,
     DataPart,
     FilePart,
@@ -154,6 +155,7 @@ __all__ = [
     "AgentIdentity",
     "AgentRunResult",
     "AttributionProbeResponse",
+    "BuiltinTools",
     "BundleSkillRequest",
     "ChangelogIncrement",
     "ContextEventsTrajectoryRequest",

{agentenv_framework_protocol-0.1.425 → agentenv_framework_protocol-0.1.426}/src/agentenv_protocol/a2a_agent/tasks/v1.py

@@ -17,7 +17,7 @@ from pathlib import Path
 from typing import Annotated, Any, Generic, Literal, TypeAlias, TypeVar, Union
 
 from a2a.types import TaskStatusUpdateEvent
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 logger = logging.getLogger(__name__)
 
@@ -127,6 +127,26 @@ class AgentConfig(BaseModel):
     timeout_seconds: int = 600
 
 
+ToolName = TypeVar("ToolName", bound=str)
+
+
+class BuiltinTools(BaseModel, Generic[ToolName]):
+    """Which of an agent's own tools it may use, as a task selects them: ``disable`` turns off the ones it names, or
+    all of them with ``"*"``; ``only`` keeps the ones it names. An agent's config takes it as
+    ``builtin_tools: BuiltinTools[<a Literal of its tools>] | None``, so its card's agent-config schema names them."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    disable: Literal["*"] | list[ToolName] | None = None
+    only: list[ToolName] | None = None
+
+    @model_validator(mode="after")
+    def _one_of(self) -> BuiltinTools:
+        if (self.disable is None) == (self.only is None):
+            raise ValueError("builtin_tools takes exactly one of disable and only")
+        return self
+
+
 ConfigT = TypeVar("ConfigT", bound=AgentConfig)
 
 

{agentenv_framework_protocol-0.1.425 → agentenv_framework_protocol-0.1.426}/tests/test_a2a_agent.py

@@ -6,7 +6,7 @@ import json
 import time
 from dataclasses import FrozenInstanceError
 from functools import wraps
-from typing import Any, Union
+from typing import Any, Literal, Union
 from unittest.mock import MagicMock
 
 import httpx
@@ -44,6 +44,7 @@ from agentenv_protocol.a2a_agent import (
     AgentEnvAgent,
     AgentIdentity,
     AttributionProbeResponse,
+    BuiltinTools,
     BundleSkillRequest,
     ContextObjectTrajectoryRequest,
     ContextTrajectoryRequest,
@@ -1774,6 +1775,26 @@ def test_agent_card_config_schema_omits_literal_defaults() -> None:
     assert "default" not in schema["$defs"]["NestedConfig"]["properties"]["token"]
 
 
+def test_builtin_tools_names_the_agents_own_tools_on_its_card_and_takes_one_selection() -> None:
+    class RuntimeConfig(AgentConfig):
+        builtin_tools: BuiltinTools[Literal["Bash", "Read", "WebFetch"]] | None = None
+
+    @a2a_agent(identity=AgentIdentity(name="tooled", description="test", version="1"), config=RuntimeConfig)
+    class Agent(AgentEnvAgent):
+        async def run(self, request: TaskRequest[RuntimeConfig]) -> TaskResult:
+            return TaskResult.text("ok")
+
+    with TestClient(Agent().create_app()) as client:
+        card = client.get("/.well-known/agent-card.json").json()
+        statuses = [_operation(client, card, AGENT_CONFIG_V1.uri, "set", {"builtin_tools": selection}).status_code
+                    for selection in ({"disable": "*"}, {"only": ["Read"]}, {"disable": ["Glob"]},
+                                      {"disable": "*", "only": ["Read"]}, {})]
+
+    request = _extension(card, AGENT_CONFIG_V1.uri)["params"]["methods"]["set"]["request"]
+    assert "builtin_tools" in request["supported"] and '"enum": ["Bash", "Read", "WebFetch"]' in json.dumps(request)
+    assert statuses == [200, 200, 400, 400, 400]
+
+
 def test_validation_errors_do_not_echo_rejected_values() -> None:
     secret = "sk-live-SUPERSECRET"