agentenv-framework-protocol 0.1.369__tar.gz → 0.1.370__tar.gz

{agentenv_framework_protocol-0.1.369 → agentenv_framework_protocol-0.1.370}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.369
+Version: 0.1.370
 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
@@ -743,6 +743,51 @@ The answer is agent-wide rather than per caller, and like every extension route
 probe carries no access check of its own, so expose an agent only to the control plane
 that drives it.
 
+`PROXY_V1` hands an agent's turns to a driver outside its sandbox, and `ProxyAgent`
+(`agentenv_protocol.a2a_agent.proxy`) serves it. The proxy has no model: each message it
+gets stays an open turn, its task working, until the driver replies, and every action the
+driver's model takes runs in the proxy, where the agent would work. The driver's first
+`POST /ext/proxy/claim` (`{"token"}`, at least 22 characters) sets the token every later
+call carries in its body. A claim with another token gets 409, and any other call with a
+wrong one 401. The token is held in memory only, never in the environment a command
+inherits. Content travels as parts, `{"kind": "text", "text": ...}`; a message with any
+other part fails as `proxy.unsupported_part` before the driver sees it. The other
+operations:
+
+- `next` (`{"token", "after"}`) waits up to 25 s for the turns' version to pass `after`,
+  then returns `{"version", "turns": [{"task_id", "context_id", "parts", "system_prompt",
+  "skills"}]}`. A turn its sender cancels drops out of the list.
+- `tools` (`{"token", "task_id"}`) lists what the turn can call, with input schemas: the
+  tools of each env server registered through mcp-config, and `bash`. Two servers offering
+  one name are refused with 409.
+- `act` (`{"token", "task_id", "action_id", "action"}`) runs one action: `{"kind": "tool",
+  "server", "name", "arguments"}` calls an env server through `ToolSession`, with the URL
+  and headers registered for it, and `{"kind": "bash", "command"}` runs `bash -c` in the
+  proxy's folder, as its user, in a process group of its own; either takes
+  `"timeout_seconds"` (3600 for `bash`, 600 for a tool by default). The driver picks
+  `action_id`, so a retried `act` returns the action it already started. It answers
+  `{"done", "result"}` at once when the action ends within the long-poll; `result`
+  (`{"token", "action_id"}`) long-polls one that doesn't. A `bash` result is
+  `{"exit_code", "stdout", "stderr", "timed_out"}`, a tool's `{"content", "is_error"}`.
+- `record` (`{"token", "task_id", "message", "model", "usage"}`) records one model call: an
+  OpenAI chat message, an Anthropic message or a string; anything else gets 400. Once a turn
+  records a call, each action must be one the last recorded call made, by name and
+  arguments, and all of them must run before the next `record` or the `reply`, else 409.
+  Calls to tools the turn doesn't offer aren't checked.
+- `reply` (`{"token", "task_id", "parts"}`, or `"error"` in place of `"parts"`) ends the
+  turn: parts complete the task, and an error fails it as `proxy.driver_error`.
+
+A turn's actions belong to it: when it closes, by reply or withdrawal, those still running
+are stopped, their whole process groups killed, and its results forgotten; the app's
+lifespan stops what runs when it shuts down. The proxy writes the turn's trajectory as it
+goes, readable live, as OTel GenAI spans in format `agentenv-proxy/v1`: `chat` for each
+recorded call, `execute_tool` for each action, and `chain` for the turn. Skills it is given
+are written to `~/skills/<name>/`, once each, and a turn names each one's folder.
+`ProxyAgent(shell=False)` is a proxy for an agent that works in no sandbox: it offers no
+`bash` and keeps no skills. It holds the env servers' headers as any agent does, so run it
+with no credentials in its environment and expose it only to the control plane that drives
+it.
+
 Runnable, self-contained reference agents live in [`examples/`](https://github.com/scaleapi/agentenv-framework/tree/main/packages/agentenv-protocol/examples):
 the normal, streaming, and multimodal `run(request)` paths, single- and
 multi-operation custom extensions, and advanced ASGI-lifespan plus

{agentenv_framework_protocol-0.1.369 → agentenv_framework_protocol-0.1.370}/README.md

@@ -697,6 +697,51 @@ The answer is agent-wide rather than per caller, and like every extension route
 probe carries no access check of its own, so expose an agent only to the control plane
 that drives it.
 
+`PROXY_V1` hands an agent's turns to a driver outside its sandbox, and `ProxyAgent`
+(`agentenv_protocol.a2a_agent.proxy`) serves it. The proxy has no model: each message it
+gets stays an open turn, its task working, until the driver replies, and every action the
+driver's model takes runs in the proxy, where the agent would work. The driver's first
+`POST /ext/proxy/claim` (`{"token"}`, at least 22 characters) sets the token every later
+call carries in its body. A claim with another token gets 409, and any other call with a
+wrong one 401. The token is held in memory only, never in the environment a command
+inherits. Content travels as parts, `{"kind": "text", "text": ...}`; a message with any
+other part fails as `proxy.unsupported_part` before the driver sees it. The other
+operations:
+
+- `next` (`{"token", "after"}`) waits up to 25 s for the turns' version to pass `after`,
+  then returns `{"version", "turns": [{"task_id", "context_id", "parts", "system_prompt",
+  "skills"}]}`. A turn its sender cancels drops out of the list.
+- `tools` (`{"token", "task_id"}`) lists what the turn can call, with input schemas: the
+  tools of each env server registered through mcp-config, and `bash`. Two servers offering
+  one name are refused with 409.
+- `act` (`{"token", "task_id", "action_id", "action"}`) runs one action: `{"kind": "tool",
+  "server", "name", "arguments"}` calls an env server through `ToolSession`, with the URL
+  and headers registered for it, and `{"kind": "bash", "command"}` runs `bash -c` in the
+  proxy's folder, as its user, in a process group of its own; either takes
+  `"timeout_seconds"` (3600 for `bash`, 600 for a tool by default). The driver picks
+  `action_id`, so a retried `act` returns the action it already started. It answers
+  `{"done", "result"}` at once when the action ends within the long-poll; `result`
+  (`{"token", "action_id"}`) long-polls one that doesn't. A `bash` result is
+  `{"exit_code", "stdout", "stderr", "timed_out"}`, a tool's `{"content", "is_error"}`.
+- `record` (`{"token", "task_id", "message", "model", "usage"}`) records one model call: an
+  OpenAI chat message, an Anthropic message or a string; anything else gets 400. Once a turn
+  records a call, each action must be one the last recorded call made, by name and
+  arguments, and all of them must run before the next `record` or the `reply`, else 409.
+  Calls to tools the turn doesn't offer aren't checked.
+- `reply` (`{"token", "task_id", "parts"}`, or `"error"` in place of `"parts"`) ends the
+  turn: parts complete the task, and an error fails it as `proxy.driver_error`.
+
+A turn's actions belong to it: when it closes, by reply or withdrawal, those still running
+are stopped, their whole process groups killed, and its results forgotten; the app's
+lifespan stops what runs when it shuts down. The proxy writes the turn's trajectory as it
+goes, readable live, as OTel GenAI spans in format `agentenv-proxy/v1`: `chat` for each
+recorded call, `execute_tool` for each action, and `chain` for the turn. Skills it is given
+are written to `~/skills/<name>/`, once each, and a turn names each one's folder.
+`ProxyAgent(shell=False)` is a proxy for an agent that works in no sandbox: it offers no
+`bash` and keeps no skills. It holds the env servers' headers as any agent does, so run it
+with no credentials in its environment and expose it only to the control plane that drives
+it.
+
 Runnable, self-contained reference agents live in [`examples/`](https://github.com/scaleapi/agentenv-framework/tree/main/packages/agentenv-protocol/examples):
 the normal, streaming, and multimodal `run(request)` paths, single- and
 multi-operation custom extensions, and advanced ASGI-lifespan plus

{agentenv_framework_protocol-0.1.369 → agentenv_framework_protocol-0.1.370}/pyproject.toml

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

{agentenv_framework_protocol-0.1.369 → agentenv_framework_protocol-0.1.370}/src/agentenv_protocol/a2a_agent/__init__.py

@@ -5,6 +5,7 @@ from a2a.types import AgentCapabilities
 from .extensions import (
     AGENT_CONFIG_V1,
     ATTRIBUTION_PROBE_V1,
+    PROXY_V1,
     INSTALL_V1,
     MCP_CONFIG_V1,
     PEER_AGENTS_V1,
@@ -19,6 +20,24 @@ from .extensions import (
     ContextEventsTrajectoryRequest,
     ContextObjectTrajectoryRequest,
     ContextTrajectoryRequest,
+    ProxyActRequest,
+    ProxyActionState,
+    ProxyBashAction,
+    ProxyBashResult,
+    ProxyClaimRequest,
+    ProxyNextRequest,
+    ProxyNextResponse,
+    ProxyRecordRequest,
+    ProxyReplyRequest,
+    ProxyResultRequest,
+    ProxySkill,
+    ProxyTextPart,
+    ProxyTool,
+    ProxyToolAction,
+    ProxyToolResult,
+    ProxyToolsRequest,
+    ProxyToolsResponse,
+    ProxyTurn,
     ExtensionActivation,
     ExtensionConfiguration,
     ExtensionDefinition,
@@ -117,6 +136,7 @@ from ..transfers import (
 __all__ = [
     "AGENT_CONFIG_V1",
     "ATTRIBUTION_PROBE_V1",
+    "PROXY_V1",
     "INSTALL_V1",
     "MCP_CONFIG_V1",
     "PEER_AGENTS_V1",
@@ -139,6 +159,24 @@ __all__ = [
     "ContextEventsTrajectoryRequest",
     "ContextObjectTrajectoryRequest",
     "ContextTrajectoryRequest",
+    "ProxyActRequest",
+    "ProxyActionState",
+    "ProxyBashAction",
+    "ProxyBashResult",
+    "ProxyClaimRequest",
+    "ProxyNextRequest",
+    "ProxyNextResponse",
+    "ProxyRecordRequest",
+    "ProxyReplyRequest",
+    "ProxyResultRequest",
+    "ProxySkill",
+    "ProxyTextPart",
+    "ProxyTool",
+    "ProxyToolAction",
+    "ProxyToolResult",
+    "ProxyToolsRequest",
+    "ProxyToolsResponse",
+    "ProxyTurn",
     "DataPart",
     "DefaultExtensionHandlers",
     "ExtensionActivation",

{agentenv_framework_protocol-0.1.369 → agentenv_framework_protocol-0.1.370}/src/agentenv_protocol/a2a_agent/extensions.py

@@ -10,7 +10,7 @@ from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, field
 from enum import Enum
 from types import MappingProxyType
-from typing import Annotated, Any
+from typing import Annotated, Any, Literal
 
 from pydantic import (
     BaseModel,
@@ -287,6 +287,124 @@ class TriggerDecideRequest(ExtensionRequest):
     env_triggers: dict[str, dict[str, Any]] | None = None
 
 
+PROXY_TOKEN_MIN_LENGTH = 22
+
+
+class ProxyClaimRequest(ExtensionRequest):
+    token: str = Field(min_length=PROXY_TOKEN_MIN_LENGTH)
+
+
+class ProxyNextRequest(ExtensionRequest):
+    token: str
+    after: int = Field(default=0, ge=0)
+
+
+class ProxyTextPart(ExtensionRequest):
+    kind: Literal["text"] = "text"
+    text: str
+
+
+class ProxySkill(ExtensionResponse):
+    name: str
+    description: str
+    path: str
+
+
+class ProxyTurn(ExtensionResponse):
+    task_id: str
+    context_id: str
+    parts: list[ProxyTextPart]
+    system_prompt: str | None = None
+    skills: list[ProxySkill] = Field(default_factory=list)
+
+
+class ProxyNextResponse(ExtensionResponse):
+    version: int
+    turns: list[ProxyTurn]
+
+
+class ProxyToolsRequest(ExtensionRequest):
+    token: str
+    task_id: str
+
+
+class ProxyTool(ExtensionResponse):
+    name: str
+    description: str | None = None
+    input_schema: dict[str, Any] | None = None
+    server: str | None = None  # the env server that offers it; none for bash
+
+
+class ProxyToolsResponse(ExtensionResponse):
+    tools: list[ProxyTool]
+
+
+class ProxyToolAction(ExtensionRequest):
+    kind: Literal["tool"]
+    server: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+    timeout_seconds: float | None = Field(default=None, gt=0)
+
+
+class ProxyBashAction(ExtensionRequest):
+    kind: Literal["bash"]
+    command: str
+    timeout_seconds: float | None = Field(default=None, gt=0)
+
+
+class ProxyActRequest(ExtensionRequest):
+    token: str
+    task_id: str
+    action_id: str = Field(min_length=1, max_length=128)
+    action: Annotated[ProxyToolAction | ProxyBashAction, Field(discriminator="kind")]
+
+
+class ProxyResultRequest(ExtensionRequest):
+    token: str
+    action_id: str
+
+
+class ProxyBashResult(ExtensionResponse):
+    kind: Literal["bash"] = "bash"
+    exit_code: int | None  # none when the command was stopped
+    stdout: str
+    stderr: str
+    timed_out: bool
+
+
+class ProxyToolResult(ExtensionResponse):
+    kind: Literal["tool"] = "tool"
+    content: list[dict[str, Any]]
+    is_error: bool
+
+
+class ProxyActionState(ExtensionResponse):
+    done: bool
+    result: Annotated[ProxyBashResult | ProxyToolResult, Field(discriminator="kind")] | None = None
+
+
+class ProxyRecordRequest(ExtensionRequest):
+    token: str
+    task_id: str
+    message: str | dict[str, Any]
+    model: str | None = None
+    usage: dict[str, Any] | None = None
+
+
+class ProxyReplyRequest(ExtensionRequest):
+    token: str
+    task_id: str
+    parts: list[ProxyTextPart] | None = Field(default=None, min_length=1)
+    error: str | None = None
+
+    @model_validator(mode="after")
+    def _parts_or_error(self) -> ProxyReplyRequest:
+        if (self.parts is None) == (self.error is None):
+            raise ValueError("a reply carries exactly one of parts and error")
+        return self
+
+
 def _tuple(values: Iterable[str]) -> tuple[str, ...]:
     return tuple(dict.fromkeys(values))
 
@@ -1167,6 +1285,33 @@ INSTALL_V1 = ExtensionDefinition(
     configuration_validator=_configure_install,
 )
 
+PROXY_V1 = ExtensionDefinition(
+    uri="urn:agentenv:proxy/v1",
+    description="Hand the agent's turns to a driver outside its sandbox, and run the driver's actions where the agent works.",
+    endpoint="/ext/proxy",
+    core_operations={
+        "claim": _op("claim", "POST", "/ext/proxy/claim", RUNTIME, request_model=ProxyClaimRequest),
+        "next": _op(
+            "next", "POST", "/ext/proxy/next", RUNTIME,
+            request_model=ProxyNextRequest, response_model=ProxyNextResponse,
+        ),
+        "tools": _op(
+            "tools", "POST", "/ext/proxy/tools", RUNTIME,
+            request_model=ProxyToolsRequest, response_model=ProxyToolsResponse,
+        ),
+        "act": _op(
+            "act", "POST", "/ext/proxy/act", RUNTIME,
+            request_model=ProxyActRequest, response_model=ProxyActionState,
+        ),
+        "result": _op(
+            "result", "POST", "/ext/proxy/result", RUNTIME,
+            request_model=ProxyResultRequest, response_model=ProxyActionState,
+        ),
+        "record": _op("record", "POST", "/ext/proxy/record", RUNTIME, request_model=ProxyRecordRequest),
+        "reply": _op("reply", "POST", "/ext/proxy/reply", RUNTIME, request_model=ProxyReplyRequest),
+    },
+)
+
 STANDARD_EXTENSIONS: Mapping[str, ExtensionDefinition] = MappingProxyType(
     {
         extension.uri: extension
@@ -1180,6 +1325,7 @@ STANDARD_EXTENSIONS: Mapping[str, ExtensionDefinition] = MappingProxyType(
             ATTRIBUTION_PROBE_V1,
             TRIGGERS_V1,
             INSTALL_V1,
+            PROXY_V1,
         )
     }
 )