agentenv-framework-protocol 0.1.281__tar.gz → 0.1.283__tar.gz

{agentenv_framework_protocol-0.1.281 → agentenv_framework_protocol-0.1.283}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.281
+Version: 0.1.283
 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: python-multipart>=0.0.13; extra == 'agent'
 Requires-Dist: regex>=2023.12.25; extra == 'agent'
 Requires-Dist: uvicorn>=0.30; extra == 'agent'
 Provides-Extra: dev
@@ -37,6 +38,7 @@ Requires-Dist: a2a-sdk[http-server]<0.4,>=0.3.26; extra == 'dev'
 Requires-Dist: mcp<2,>=1.25; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=9.0; extra == 'dev'
+Requires-Dist: python-multipart>=0.0.13; extra == 'dev'
 Requires-Dist: regex>=2023.12.25; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -519,9 +521,8 @@ tools with (agent-env relays the env card's name: the MultiEnv's declared name,
 `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
-its model gateway understands (the AgentEnv control plane configures `project_id`
-and `task_id` on agents that declare those config fields). An agent records the
-dimensions it last sent with a model request and returns them from a bodyless
+its model gateway understands. An agent records the dimensions it last sent with a
+model request and returns them from a bodyless
 `POST /ext/attribution-probe` as an `AttributionProbeResponse`:
 `{"last_seen_attribution": {<dimension>: <value>, ...}, "last_seen_at_utc": ...}`.
 The SDK does not record attribution itself, because only the agent knows what it sent.
@@ -611,17 +612,44 @@ that is by the uploading agent. AgentEnv accepts a trajectory upload response
 without reading the object back, and registers a snapshot only once both its
 objects are in the store.
 
-SDK agents advertise only these shapes. AgentEnv reads each Agent Card, sends
-the object variants when the agent advertises them and its object store issues
-grants (the S3 store does, and namespace grants for changelog capture only when
-it signs with long-term credentials), and keeps the older `s3_prefix`, `skill_s3_url` and
-`trajectory_s3_prefix` shapes for agents that advertise those instead. An SDK
-agent built on this protocol therefore needs an agent-env release that includes
-it: an older release sends the older shapes, which such an agent refuses apart
-from inline skills and trajectories. Roll out in this
-order: release agent-env and `agentenv-framework-protocol` together, move every service
-that embeds agent-env to that release, and only then build agents on the new
-SDK. A snapshot or changelog is restored in the form it was captured in: one
-captured as objects only through the object variants, an older one only
-through `s3_prefix`. Do not roll agent-env back once portable snapshots or
-changelogs exist, because older releases cannot load them.
+SDK agents advertise only these shapes, and AgentEnv sends no others. It moves
+a skill bundle, snapshot or changelog only through grants, so the call needs an
+agent that advertises the object variant and an object store that issues grants
+(the S3 store does, and namespace grants for changelog capture only when it
+signs with long-term credentials); otherwise it fails before anything is sent.
+Skills given as SKILL.md text and trajectories returned inline need no grants.
+A snapshot is restored only from the snapshot objects in the table above; one
+that holds the runtime's own files instead cannot be. An
+agent-env release without the object variants sends other shapes, which SDK
+agents refuse apart from inline skills and trajectories, and cannot load
+portable snapshots or changelogs, so do not run one alongside these agents.
+
+#### Staging
+
+When the object store's grants cannot reach the agent, as with a local store
+and an agent on a remote sandbox, AgentEnv moves the objects through the agent
+itself. Every SDK agent serves the staging extension, `urn:agentenv:staging/v1`,
+a small object store at `/ext/staging` on its own server. Before a call
+AgentEnv pushes what the agent will read into it; after the call it pulls what
+the agent wrote. The grants it sends are the ordinary ones above, with URLs
+naming staged paths on the agent's own URL, so handlers and helpers are
+unchanged.
+
+| Route | Does |
+| --- | --- |
+| `PUT /ext/staging/{path}` | stores the body |
+| `GET /ext/staging/{path}` | returns it, with an `ETag` |
+| `POST /ext/staging/{prefix}` | stores a multipart upload's `file` at `{prefix}/{key}`, `key` being a form field sent before it |
+| `GET /ext/staging/{prefix}/` | lists `{objects: [{path, size_bytes, etag}]}` below the prefix |
+| `DELETE /ext/staging/{path}` | removes the object, only while it still matches an `If-Match` tag when one is given |
+| `DELETE /ext/staging/{prefix}/` | removes everything below the prefix |
+
+A path's first segment is an id AgentEnv generates, at least 22 characters, and
+never shares, which is what keeps staged objects private on a public agent URL.
+Everything staged counts against `AGENTENV_STAGING_MAX_BYTES` (16 GiB unless
+set; `0` turns staging off) and lives until AgentEnv removes it or the server
+process ends, in a directory of the process's own (or under
+`AGENTENV_STAGING_DIR` when set) that only the server's user can read. One
+server process owns a staging directory. An agent that doesn't use the SDK can serve the same routes
+and add `{uri: "urn:agentenv:staging/v1", params: {endpoint: "/ext/staging"}}`
+to its card.

{agentenv_framework_protocol-0.1.281 → agentenv_framework_protocol-0.1.283}/README.md

@@ -477,9 +477,8 @@ tools with (agent-env relays the env card's name: the MultiEnv's declared name,
 `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
-its model gateway understands (the AgentEnv control plane configures `project_id`
-and `task_id` on agents that declare those config fields). An agent records the
-dimensions it last sent with a model request and returns them from a bodyless
+its model gateway understands. An agent records the dimensions it last sent with a
+model request and returns them from a bodyless
 `POST /ext/attribution-probe` as an `AttributionProbeResponse`:
 `{"last_seen_attribution": {<dimension>: <value>, ...}, "last_seen_at_utc": ...}`.
 The SDK does not record attribution itself, because only the agent knows what it sent.
@@ -569,17 +568,44 @@ that is by the uploading agent. AgentEnv accepts a trajectory upload response
 without reading the object back, and registers a snapshot only once both its
 objects are in the store.
 
-SDK agents advertise only these shapes. AgentEnv reads each Agent Card, sends
-the object variants when the agent advertises them and its object store issues
-grants (the S3 store does, and namespace grants for changelog capture only when
-it signs with long-term credentials), and keeps the older `s3_prefix`, `skill_s3_url` and
-`trajectory_s3_prefix` shapes for agents that advertise those instead. An SDK
-agent built on this protocol therefore needs an agent-env release that includes
-it: an older release sends the older shapes, which such an agent refuses apart
-from inline skills and trajectories. Roll out in this
-order: release agent-env and `agentenv-framework-protocol` together, move every service
-that embeds agent-env to that release, and only then build agents on the new
-SDK. A snapshot or changelog is restored in the form it was captured in: one
-captured as objects only through the object variants, an older one only
-through `s3_prefix`. Do not roll agent-env back once portable snapshots or
-changelogs exist, because older releases cannot load them.
+SDK agents advertise only these shapes, and AgentEnv sends no others. It moves
+a skill bundle, snapshot or changelog only through grants, so the call needs an
+agent that advertises the object variant and an object store that issues grants
+(the S3 store does, and namespace grants for changelog capture only when it
+signs with long-term credentials); otherwise it fails before anything is sent.
+Skills given as SKILL.md text and trajectories returned inline need no grants.
+A snapshot is restored only from the snapshot objects in the table above; one
+that holds the runtime's own files instead cannot be. An
+agent-env release without the object variants sends other shapes, which SDK
+agents refuse apart from inline skills and trajectories, and cannot load
+portable snapshots or changelogs, so do not run one alongside these agents.
+
+#### Staging
+
+When the object store's grants cannot reach the agent, as with a local store
+and an agent on a remote sandbox, AgentEnv moves the objects through the agent
+itself. Every SDK agent serves the staging extension, `urn:agentenv:staging/v1`,
+a small object store at `/ext/staging` on its own server. Before a call
+AgentEnv pushes what the agent will read into it; after the call it pulls what
+the agent wrote. The grants it sends are the ordinary ones above, with URLs
+naming staged paths on the agent's own URL, so handlers and helpers are
+unchanged.
+
+| Route | Does |
+| --- | --- |
+| `PUT /ext/staging/{path}` | stores the body |
+| `GET /ext/staging/{path}` | returns it, with an `ETag` |
+| `POST /ext/staging/{prefix}` | stores a multipart upload's `file` at `{prefix}/{key}`, `key` being a form field sent before it |
+| `GET /ext/staging/{prefix}/` | lists `{objects: [{path, size_bytes, etag}]}` below the prefix |
+| `DELETE /ext/staging/{path}` | removes the object, only while it still matches an `If-Match` tag when one is given |
+| `DELETE /ext/staging/{prefix}/` | removes everything below the prefix |
+
+A path's first segment is an id AgentEnv generates, at least 22 characters, and
+never shares, which is what keeps staged objects private on a public agent URL.
+Everything staged counts against `AGENTENV_STAGING_MAX_BYTES` (16 GiB unless
+set; `0` turns staging off) and lives until AgentEnv removes it or the server
+process ends, in a directory of the process's own (or under
+`AGENTENV_STAGING_DIR` when set) that only the server's user can read. One
+server process owns a staging directory. An agent that doesn't use the SDK can serve the same routes
+and add `{uri: "urn:agentenv:staging/v1", params: {endpoint: "/ext/staging"}}`
+to its card.

{agentenv_framework_protocol-0.1.281 → agentenv_framework_protocol-0.1.283}/THIRD_PARTY_NOTICES.md

@@ -191,6 +191,13 @@ The runtime dependencies of `agentenv-protocol` and its `agent` extra, at the ve
 - Source: <https://github.com/pydantic/pydantic-core>
 - [License text 2](#license-text-2)
 
+### python-multipart 0.0.32
+
+- License: Apache-2.0
+- Author: Andrew Dunham <andrew@du.nham.ca>
+- Source: <https://github.com/Kludex/python-multipart>
+- [License text 1](#license-text-1)
+
 ### regex 2026.6.28
 
 - License: Apache-2.0 AND CNRI-Python

{agentenv_framework_protocol-0.1.281 → agentenv_framework_protocol-0.1.283}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.281"
+version = "0.1.283"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"
@@ -30,11 +30,13 @@ dependencies = [
 [project.optional-dependencies]
 agent = [
     "a2a-sdk[http-server]>=0.3.26,<0.4",
+    "python-multipart>=0.0.13",  # the staging extension's upload forms
     "regex>=2023.12.25",
     "uvicorn>=0.30",
 ]
 dev = [
     "a2a-sdk[http-server]>=0.3.26,<0.4",
+    "python-multipart>=0.0.13",
     "regex>=2023.12.25",
     "pytest>=9.0",
     "pytest-asyncio>=0.23.0",

{agentenv_framework_protocol-0.1.281 → agentenv_framework_protocol-0.1.283}/src/agentenv_protocol/a2a_agent/__init__.py

@@ -76,6 +76,7 @@ from .registry import (
     RegisteredOperation,
     build_registry,
 )
+from .staging import STAGING_ENDPOINT, STAGING_V1_URI, StagingStore, staging_routes
 from .tasks.v1 import (
     AgentConfig,
     AgentRunResult,
@@ -116,6 +117,8 @@ __all__ = [
     "PEER_AGENTS_V1",
     "SKILL_CONFIG_V1",
     "SNAPSHOT_V1",
+    "STAGING_ENDPOINT",
+    "STAGING_V1_URI",
     "STANDARD_EXTENSIONS",
     "TRAJECTORY_V1",
     "TRIGGERS_V1",
@@ -172,6 +175,7 @@ __all__ = [
     "SnapshotReadObjects",
     "SnapshotUploadedObjects",
     "SnapshotWriteObjects",
+    "StagingStore",
     "TaskError",
     "TaskObjectTrajectoryRequest",
     "TaskOutcome",
@@ -204,5 +208,6 @@ __all__ = [
     "extension",
     "request_fields",
     "serve",
+    "staging_routes",
     "upload",
 ]

{agentenv_framework_protocol-0.1.281 → agentenv_framework_protocol-0.1.283}/src/agentenv_protocol/a2a_agent/framework.py

@@ -45,6 +45,7 @@ from .extensions import (
     enable,
 )
 from .registry import RegisteredOperation, build_registry
+from .staging import STAGING_ENDPOINT, StagingStore, staging_routes
 from .tasks.v1 import (
     AgentConfig,
     AgentRunResult,
@@ -873,6 +874,15 @@ class A2AAgentApplication:
                 ("/.well-known/agent-card.json", "GET"): "Agent Card",
             }
         )
+        # Objects agent-env moves through the agent when its object store's grants cannot reach it.
+        self.staging = StagingStore()
+        for extension in self.registry.extensions if self.staging.max_bytes else ():
+            for operation in extension.operations.values():
+                if operation.definition.path.startswith(STAGING_ENDPOINT + "/"):
+                    raise ValueError(
+                        f"extension operation {extension.definition.uri}.{operation.definition.name} "
+                        f"conflicts with the staging routes below {STAGING_ENDPOINT}"
+                    )
         conformance = self.registry.conformance()
         for override in conformance["standard_operation_overrides"]:
             logger.warning(
@@ -906,6 +916,8 @@ class A2AAgentApplication:
                         methods=[operation.definition.method],
                     )
                 )
+        if self.staging.max_bytes:
+            routes.extend(staging_routes(self.staging))
         kwargs = {"routes": routes}
         if definition.lifespan is not None:
             kwargs["lifespan"] = definition.lifespan
@@ -953,6 +965,8 @@ class A2AAgentApplication:
             AgentExtension.model_validate(item)
             for item in self.registry.card_extensions()
         ]
+        if self.staging.max_bytes:
+            extensions.append(AgentExtension.model_validate(self.staging.card_extension()))
         resolved_capabilities = AgentCapabilities(
             streaming=self.streaming,
             push_notifications=False,