You're on the build & deploy path — install the Python SDK to author your own agent. Just want to call existing agents from your editor instead?

Build & deploy an agent

a2a-pack is the Python SDK and a2a CLI for building agents on a2a cloud. Subclass A2AAgent, annotate methods with @skill, then a2a deploy. Every agent ships with an HTTP API, an MCP endpoint, and a sandboxed microVM runtime.

Python 3.11+macOS · Linux · WindowsPydantic · FastAPIApache-2.0

Install

pipx is recommended for the CLI so it lands in its own venv and is on your $PATH. pip works too if you prefer.

# recommended
pipx install a2a-pack

# or, inside a project venv
pip install a2a-pack

Verify: a2a --help

Quick start

Writes a token to ~/.a2a/credentials.json — the same file @a2a/mcp reads.

a2a signup    # first time
a2a login     # already have an account

Scaffold an agent

a2a init research-agent
cd research-agent

You get agent.py, a2a.yaml, and requirements.txt.

Write a skill

Subclass A2AAgent. Each @skill-decorated async def is exposed as both an HTTP endpoint and an MCP tool.

from a2a_pack import A2AAgent, NoAuth, RunContext, skill


class Research(A2AAgent):
    name = "research-agent"
    description = "Summarizes URLs."

    @skill(description="Summarize the page at `url` in N bullets.")
    async def summarize(
        self, ctx: RunContext[NoAuth], url: str, bullets: int = 5
    ) -> dict:
        text = await fetch_page(url)
        return {"url": url, "bullets": summarize(text, bullets)}

Validate locally

a2a validate          # type-checks the agent + prints skill count
a2a card              # prints the public Agent Card JSON

Ship it

a2a deploy

Tarballs your source, uploads to the control plane, builds the image, runs it on the cloud. Returns the public URL.

Use it

Every deployed agent serves three protocols. Pick the right one for the caller:

# 1. HTTP API
curl https://research-agent.a2acloud.io/.well-known/agent-card

# 2. MCP (in your editor, via the gateway)
a2a mcp-url research-agent

# 3. Python client (for agent-to-agent calls)
from a2a_pack import HttpA2AClient
client = HttpA2AClient("https://research-agent.a2acloud.io")
result = await client.call("summarize", {"url": "https://...", "bullets": 3})

What you get for free

HTTPS endpoint
Per-agent subdomain with a managed TLS cert.
MCP server
POST /mcp on every agent, no extra wiring.
Sandboxed microVM
Skills run isolated; FUSE-mounted workspace.
Agent Card discovery
GET /.well-known/agent-card describes every skill.
Scope-gated calls
ctx.require_scopes + grant negotiation.
Live progress events
SSE on /invoke for streaming updates to clients.
Caller-provided LLM keys
Opt-in: agent can run on the caller's tokens.
Marketplace listing
Public agents auto-appear under /a.

CLI reference

Command	What it does
a2a signup	Create an account on the control plane.
a2a login	Authenticate; cache the JWT locally.
a2a whoami	Show the logged-in account.
a2a init <name>	Scaffold a new agent project.
a2a validate	Load the agent class and validate its declaration.
a2a card	Print the Agent Card JSON for the current project.
a2a run -e module:Class	Run the agent locally on http://127.0.0.1:8000.
a2a deploy	Tarball, upload, build, deploy. Returns the public URL.
a2a agents	List agents visible to your account.
a2a mcp-url <name>	Print the MCP config snippet for a deployed agent.
a2a build	Build a container image locally (advanced).

Project layout

research-agent/
  agent.py          # subclass A2AAgent, decorate methods with @skill
  a2a.yaml          # name, version, entrypoint module:Class
  requirements.txt  # whatever your agent imports

a2a.yaml is the only piece of config you maintain. The control plane derives everything else from the agent class declaration (resources, scopes, MCP routing).

Working with secrets & env

Declare what your agent needs on the class. The deploy flow surfaces missing values up-front instead of failing at first request.

class Research(A2AAgent):
    name = "research-agent"
    required_secrets = ("ANTHROPIC_API_KEY",)
    required_env = ("USER_AGENT",)

Troubleshooting

a2a: command not found? Re-run with pipx ensurepath, then open a new shell.
Deploy hangs at "still building"? Check a2a agents for the current status — first build pulls layers and can take a few minutes.
401 on /invoke? If your agent declared auth_model = APIKeyAuth, set A2A_API_KEY on the agent and send Authorization: Bearer <key>.

Use agents in your editor →Browse the marketplace