a2a-pack 0.1.0__tar.gz

a2a_pack-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__
+*.pyc
+.venv
+.pytest_cache
+*.egg-info
+dist
+build
+node_modules
+
+.env

a2a_pack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 a2a cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

a2a_pack-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: a2a-pack
+Version: 0.1.0
+Summary: Developer SDK + CLI for building, packaging, and deploying A2A agents.
+Project-URL: Homepage, https://a2acloud.io
+Project-URL: Documentation, https://docs.a2acloud.io
+Project-URL: Repository, https://gitea.a2acloud.io/gitea_admin/a2a-pack
+Project-URL: Issues, https://gitea.a2acloud.io/gitea_admin/a2a-pack/issues
+Author-email: a2a cloud <hello@a2acloud.io>
+License: MIT License
+        
+        Copyright (c) 2026 a2a cloud
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: a2a,agent,agents,ai,llm,marketplace,mcp,microvm,model-context-protocol,sandbox
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# a2a-pack
+
+**Developer SDK + CLI for building, packaging, and deploying [A2A](https://a2acloud.io) agents.**
+
+One Python class becomes a sandboxed, discoverable, MCP-compatible AI
+agent on the [a2a cloud](https://a2acloud.io) platform. Other agents
+reach yours via HMAC-signed grants. The platform owns deployment,
+execution, permissions, and (when you're ready) billing.
+
+```bash
+pip install a2a-pack
+a2a signup --email you@example.com --password ...
+a2a init research-agent
+cd research-agent
+a2a deploy
+# → https://research-agent.a2acloud.io   (TLS, MCP, OpenAPI, all wired)
+```
+
+## What an agent looks like
+
+```python
+from pydantic import BaseModel
+from a2a_pack import (
+    A2AAgent, LLMProvisioning, NoAuth, Pricing, RunContext, skill,
+)
+
+
+class GreeterConfig(BaseModel):
+    suffix: str = "!"
+
+
+class Greeter(A2AAgent[GreeterConfig, NoAuth]):
+    name = "greeter"
+    description = "Say hi."
+    version = "0.1.0"
+    config_model = GreeterConfig
+    auth_model = NoAuth
+
+    # Use the caller's own LLM key (forwarded by the platform) — the
+    # author's price stays small; the LLM bill goes to the caller's
+    # provider directly.
+    llm_provisioning = LLMProvisioning.CALLER_PROVIDED
+    pricing = Pricing(price_per_call_usd=0.01, caller_pays_llm=True)
+
+    @skill(description="Greet someone.")
+    async def greet(self, ctx: RunContext[NoAuth], who: str) -> str:
+        await ctx.emit_progress(f"greeting {who}")
+        return f"hello {who}{self.config.suffix}"
+```
+
+That's it. `a2a deploy` packages the source, the control plane builds
+the image, ArgoCD reconciles, you get a public URL.
+
+## Public surface
+
+| Concept | Where |
+|---|---|
+| `A2AAgent` base class + `@skill` decorator | `a2a_pack.agent` |
+| `RunContext`, `ctx.llm`, `ctx.ask`, `ctx.request_scope` | `a2a_pack.context` |
+| Grant mint/verify (HMAC, audience-bound, glob-filtered, time-limited) | `a2a_pack.grants` |
+| Workspace negotiation surface | `a2a_pack.workspace` |
+| Sandbox client (microVM via libkrun) | `a2a_pack.sandbox` |
+| Agent-to-agent client (HTTP, in-memory, custom) | `a2a_pack.a2a_client` |
+| MCP server (skills → tools, mountable into your FastAPI app) | `a2a_pack.mcp` |
+| Lifecycle / Resources / Pricing / LLMProvisioning declarations | `a2a_pack.runtime` |
+| Card schema (auto-derived from your class) | `a2a_pack.card` |
+
+Full reference + auto-generated docs at **https://docs.a2acloud.io**.
+
+## Self-hosting
+
+The platform pieces (control plane, sandbox runtime, gitea, ArgoCD,
+MinIO, LiteLLM) live at
+[gitea.a2acloud.io](https://gitea.a2acloud.io) — the SDK is the only
+piece you need on PyPI. If you want to run the whole stack locally
+or in your own cluster, the bootstrap recipe is in the platform
+[README](https://gitea.a2acloud.io/gitea_admin/a2a-pack).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

a2a_pack-0.1.0/README.md

@@ -0,0 +1,81 @@
+# a2a-pack
+
+**Developer SDK + CLI for building, packaging, and deploying [A2A](https://a2acloud.io) agents.**
+
+One Python class becomes a sandboxed, discoverable, MCP-compatible AI
+agent on the [a2a cloud](https://a2acloud.io) platform. Other agents
+reach yours via HMAC-signed grants. The platform owns deployment,
+execution, permissions, and (when you're ready) billing.
+
+```bash
+pip install a2a-pack
+a2a signup --email you@example.com --password ...
+a2a init research-agent
+cd research-agent
+a2a deploy
+# → https://research-agent.a2acloud.io   (TLS, MCP, OpenAPI, all wired)
+```
+
+## What an agent looks like
+
+```python
+from pydantic import BaseModel
+from a2a_pack import (
+    A2AAgent, LLMProvisioning, NoAuth, Pricing, RunContext, skill,
+)
+
+
+class GreeterConfig(BaseModel):
+    suffix: str = "!"
+
+
+class Greeter(A2AAgent[GreeterConfig, NoAuth]):
+    name = "greeter"
+    description = "Say hi."
+    version = "0.1.0"
+    config_model = GreeterConfig
+    auth_model = NoAuth
+
+    # Use the caller's own LLM key (forwarded by the platform) — the
+    # author's price stays small; the LLM bill goes to the caller's
+    # provider directly.
+    llm_provisioning = LLMProvisioning.CALLER_PROVIDED
+    pricing = Pricing(price_per_call_usd=0.01, caller_pays_llm=True)
+
+    @skill(description="Greet someone.")
+    async def greet(self, ctx: RunContext[NoAuth], who: str) -> str:
+        await ctx.emit_progress(f"greeting {who}")
+        return f"hello {who}{self.config.suffix}"
+```
+
+That's it. `a2a deploy` packages the source, the control plane builds
+the image, ArgoCD reconciles, you get a public URL.
+
+## Public surface
+
+| Concept | Where |
+|---|---|
+| `A2AAgent` base class + `@skill` decorator | `a2a_pack.agent` |
+| `RunContext`, `ctx.llm`, `ctx.ask`, `ctx.request_scope` | `a2a_pack.context` |
+| Grant mint/verify (HMAC, audience-bound, glob-filtered, time-limited) | `a2a_pack.grants` |
+| Workspace negotiation surface | `a2a_pack.workspace` |
+| Sandbox client (microVM via libkrun) | `a2a_pack.sandbox` |
+| Agent-to-agent client (HTTP, in-memory, custom) | `a2a_pack.a2a_client` |
+| MCP server (skills → tools, mountable into your FastAPI app) | `a2a_pack.mcp` |
+| Lifecycle / Resources / Pricing / LLMProvisioning declarations | `a2a_pack.runtime` |
+| Card schema (auto-derived from your class) | `a2a_pack.card` |
+
+Full reference + auto-generated docs at **https://docs.a2acloud.io**.
+
+## Self-hosting
+
+The platform pieces (control plane, sandbox runtime, gitea, ArgoCD,
+MinIO, LiteLLM) live at
+[gitea.a2acloud.io](https://gitea.a2acloud.io) — the SDK is the only
+piece you need on PyPI. If you want to run the whole stack locally
+or in your own cluster, the bootstrap recipe is in the platform
+[README](https://gitea.a2acloud.io/gitea_admin/a2a-pack).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

a2a_pack-0.1.0/a2a_pack/__init__.py

@@ -0,0 +1,144 @@
+"""a2a-pack — developer SDK + CLI for the a2a cloud platform.
+
+See https://docs.a2acloud.io for the full reference.
+"""
+
+# Single source of truth — pyproject.toml reads this via hatch.version.
+__version__ = "0.1.0"
+
+from .a2a_client import (
+    A2AClient,
+    CallResult,
+    HttpA2AClient,
+    InMemoryA2AClient,
+)
+from .agent import (
+    A2AAgent,
+    ParamSpec,
+    SkillInputError,
+    SkillInvocationError,
+    SkillNotFound,
+    SkillSpec,
+    skill,
+)
+from .discovery import (
+    ControlPlaneDiscovery,
+    DiscoveredAgent,
+    DiscoveryClient,
+    InMemoryDiscovery,
+)
+from .grants import Grant, GrantInvalid, mint_grant, sign_grant, verify_grant
+from .mcp import (
+    MCP_PROTOCOL_VERSION,
+    MCPServer,
+    build_http_app as build_mcp_http_app,
+    mount_http as mount_mcp_http,
+    skills_to_tools,
+)
+from .auth import APIKeyAuth, JWTAuth, NoAuth
+from .card import AgentCard, SkillCard
+from .context import (
+    AgentEvent,
+    ArtifactRef,
+    CancelledByCaller,
+    LLMCreds,
+    LocalRunContext,
+    MissingScopes,
+    RunContext,
+)
+from .runtime import (
+    AgentRuntime,
+    EgressPolicy,
+    Lifecycle,
+    LLMProvisioning,
+    Pricing,
+    Resources,
+    Sandbox,
+    SkillPolicy,
+    State,
+)
+from .sandbox import (
+    ExecResult,
+    SandboxClient,
+    SandboxHandle,
+    SandboxSpec,
+    SandboxUnavailable,
+)
+from .workspace import (
+    FileMatch,
+    FileType,
+    LocalWorkspaceClient,
+    LocalWorkspaceView,
+    WorkspaceAccess,
+    WorkspaceClient,
+    WorkspaceDenied,
+    WorkspaceGrant,
+    WorkspaceMode,
+    WorkspacePatch,
+    WorkspaceView,
+)
+
+__all__ = [
+    "A2AAgent",
+    "A2AClient",
+    "APIKeyAuth",
+    "AgentCard",
+    "AgentEvent",
+    "AgentRuntime",
+    "ArtifactRef",
+    "CallResult",
+    "CancelledByCaller",
+    "ControlPlaneDiscovery",
+    "DiscoveredAgent",
+    "DiscoveryClient",
+    "EgressPolicy",
+    "ExecResult",
+    "FileMatch",
+    "FileType",
+    "Grant",
+    "GrantInvalid",
+    "HttpA2AClient",
+    "InMemoryA2AClient",
+    "InMemoryDiscovery",
+    "JWTAuth",
+    "LLMCreds",
+    "LLMProvisioning",
+    "Lifecycle",
+    "LocalRunContext",
+    "MCP_PROTOCOL_VERSION",
+    "MCPServer",
+    "build_mcp_http_app",
+    "mount_mcp_http",
+    "skills_to_tools",
+    "LocalWorkspaceClient",
+    "LocalWorkspaceView",
+    "MissingScopes",
+    "NoAuth",
+    "ParamSpec",
+    "Pricing",
+    "Resources",
+    "RunContext",
+    "Sandbox",
+    "mint_grant",
+    "sign_grant",
+    "verify_grant",
+    "SandboxClient",
+    "SandboxHandle",
+    "SandboxSpec",
+    "SandboxUnavailable",
+    "SkillCard",
+    "SkillInputError",
+    "SkillInvocationError",
+    "SkillNotFound",
+    "SkillPolicy",
+    "SkillSpec",
+    "State",
+    "WorkspaceAccess",
+    "WorkspaceClient",
+    "WorkspaceDenied",
+    "WorkspaceGrant",
+    "WorkspaceMode",
+    "WorkspacePatch",
+    "WorkspaceView",
+    "skill",
+]

a2a_pack-0.1.0/a2a_pack/a2a_client.py

@@ -0,0 +1,170 @@
+"""Agent-to-agent invocation surface available via ``ctx.call(...)``.
+
+An agent never speaks raw HTTP to another agent. It calls
+``ctx.call(target, skill, args, grant=...)`` and the runtime-attached
+:class:`A2AClient` handles transport: HTTP for cross-pod, in-memory for
+local tests, anything else (gRPC, message bus) for future runtimes.
+
+The grant token (see :mod:`a2a_pack.grants`) is the *only* way to hand
+workspace access across agents. Callee-side runtime validates it before
+materializing a :class:`WorkspaceClient`.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .agent import A2AAgent
+    from .context import RunContext
+
+
+@dataclass(frozen=True)
+class CallResult:
+    """What an A2A invocation returns to the calling skill."""
+
+    result: Any
+    events: tuple[dict[str, Any], ...] = ()
+    artifacts: tuple[dict[str, Any], ...] = ()
+    grant_id: str | None = None  # echoed for audit
+
+
+class A2AClient(ABC):
+    """Transport-shaped agent-to-agent client."""
+
+    @abstractmethod
+    async def call(
+        self,
+        target: str,
+        skill: str,
+        *,
+        args: dict[str, Any] | None = None,
+        grant: str | None = None,
+        timeout: float | None = None,
+    ) -> CallResult:
+        """Invoke ``skill`` on ``target`` and return its :class:`CallResult`.
+
+        ``target`` is opaque to this layer — for the HTTP impl it's an agent
+        URL; for the in-memory impl it's an agent name.
+        """
+
+
+# ---------------------------------------------------------------------------
+# In-memory: routes calls to A2AAgent instances in the same process. Useful
+# for the demo + tests.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class InMemoryA2AClient(A2AClient):
+    """Routes calls to agent instances registered by name.
+
+    The receiving agent gets a *new* :class:`RunContext` built by the
+    ``ctx_factory`` callable, so caller and callee don't share state.
+    Pass ``ctx_factory=lambda agent, grant: ...`` to control how scoped
+    workspaces / sandboxes are wired in.
+    """
+
+    agents: dict[str, "A2AAgent"]
+    ctx_factory: Any = None  # Callable[[A2AAgent, str | None], RunContext]
+
+    async def call(
+        self,
+        target: str,
+        skill: str,
+        *,
+        args: dict[str, Any] | None = None,
+        grant: str | None = None,
+        timeout: float | None = None,
+    ) -> CallResult:
+        if target not in self.agents:
+            raise KeyError(f"no agent registered: {target!r}")
+        agent = self.agents[target]
+        ctx = self.ctx_factory(agent, grant) if self.ctx_factory else None
+        if ctx is None:
+            from .context import LocalRunContext
+            from .auth import NoAuth
+
+            ctx = LocalRunContext(auth=NoAuth(), task_id=f"a2a-{target}")
+        result = await agent.invoke_json(skill, ctx, args or {})
+        events = tuple(
+            {"kind": e.kind, "payload": e.payload}
+            for e in getattr(ctx, "events", ())
+        )
+        # surface artifacts captured by LocalRunContext, if present
+        artifacts: tuple[dict[str, Any], ...] = ()
+        local_arts = getattr(ctx, "artifacts", None)
+        if isinstance(local_arts, dict):
+            artifacts = tuple(
+                {"name": name, "size_bytes": len(data)}
+                for name, data in local_arts.items()
+            )
+        return CallResult(
+            result=result,
+            events=events,
+            artifacts=artifacts,
+            grant_id=_grant_id_or_none(grant),
+        )
+
+
+# ---------------------------------------------------------------------------
+# HTTP: posts to <target>/invoke/<skill> with {arguments, grant} body.
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HttpA2AClient(A2AClient):
+    """A2A client that POSTs to the standard /invoke/{skill} endpoint."""
+
+    default_timeout: float = 60.0
+
+    async def call(
+        self,
+        target: str,
+        skill: str,
+        *,
+        args: dict[str, Any] | None = None,
+        grant: str | None = None,
+        timeout: float | None = None,
+    ) -> CallResult:
+        import httpx  # late import: server-side needs no client
+
+        body: dict[str, Any] = {"arguments": args or {}}
+        if grant is not None:
+            body["grant"] = grant
+        url = f"{target.rstrip('/')}/invoke/{skill}"
+        async with httpx.AsyncClient(timeout=timeout or self.default_timeout) as c:
+            resp = await c.post(url, json=body)
+        if resp.status_code >= 400:
+            raise RuntimeError(f"a2a {url} -> {resp.status_code}: {resp.text}")
+        data = resp.json()
+        return CallResult(
+            result=data.get("result"),
+            events=tuple(data.get("events") or ()),
+            artifacts=tuple(data.get("artifacts") or ()),
+            grant_id=_grant_id_or_none(grant),
+        )
+
+
+def _grant_id_or_none(grant: str | None) -> str | None:
+    """Extract grant_id without re-validating the signature (audit only)."""
+    if not grant or "." not in grant:
+        return None
+    try:
+        from .grants import _b64decode
+
+        payload = _b64decode(grant.rsplit(".", 1)[0])
+        import json
+
+        return json.loads(payload).get("grant_id")
+    except Exception:  # noqa: BLE001
+        return None
+
+
+__all__ = [
+    "A2AClient",
+    "CallResult",
+    "HttpA2AClient",
+    "InMemoryA2AClient",
+]