# 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).
