Build Your First A2A Agent: From Python Class to Live URL

Build Your First A2A Agent: From Python Class to Live URL

Most agent frameworks make you wire up five things before you can say hello. A2A Pack doesn't.

Write one Python class. Decorate a method. Run a2a deploy. Get a live URL. That's the whole story — and the moment you've felt it, every other "agent framework" feels heavier than it needs to be.

Let's build one.

The Whole Agent, In One File

Here's a real, working A2A agent. Not pseudocode. Not a slide. Real code from the test suite:

from a2a_pack.agent import A2AAgent, skill
from a2a_pack.context import RunContext, NoAuth

class Greeter(A2AAgent[GreeterConfig, NoAuth]):
    name = "greeter"
    description = "Says hi"
    config_model = GreeterConfig
    auth_model = NoAuth

    @skill(description="Greet someone")
    async def greet(self, ctx: RunContext[NoAuth], who: str, loud: bool = False) -> str:
        await ctx.emit_progress(f"greeting {who}")
        out = f"hello {who}{self.config.suffix}"
        return out.upper() if loud else out

That's an agent. An entire, deployable agent. Class, skill, ctx, return value. Done.

A2A Pack handles everything else: the HTTP server, the agent card, the streaming protocol, the deploy pipeline, the public URL. You write the logic. The platform owns the wiring.

What You're Looking At

Three things matter here. Let's unpack them.

A2AAgent — The Base Class

From a2a_pack.agent. Generic over a config model and an auth model. You override name, description, config_model, auth_model. That's the contract.

@skill — The Decorator That Does Everything

Mark any async method with @skill and A2A Pack:

• Discovers it on the agent card.
• Captures its input/output schemas from your type hints.
• Validates input at call time.
• Routes invocations to it.
• Streams progress events back to the caller.

The decorator takes a *huge* set of options because real agents need them: tags, scopes, stream, timeout_seconds, idempotent, max_retries, cost_class, plus a whole family of grant controls (grant_mode, grant_allow_patterns, grant_deny_patterns, grant_outputs_prefix, grant_write_prefixes, etc.).

Start with description. Add the rest when you need them. Progressive disclosure done right.

RunContext — Your Window Into The Platform

The ctx argument is where the platform shows up. It exposes:

• ctx.llm — LLM credentials (routed through LiteLLM)
• ctx.sandbox — microVM execution (shell, Python, custom images)
• ctx.workspace — grant-scoped file storage
• ctx.discover — find and call other agents
• ctx.emit_progress() — stream progress to the UI
• ctx.ask() — ask the user a mid-skill question
• ctx.request_scope() — request more workspace access
• ctx.call() — agent-to-agent handoff with signed grants
• ctx.write_artifact() — publish a structured artifact
• ctx.secret() — fetch a runtime secret

That's the platform, surfaced as Python. Every capability is one method call away.

The Manifest: a2a.yaml

One YAML file describes the agent. Minimum viable manifest:

name: greeter
version: 0.1.0
entrypoint: agent:Greeter

Optional fields cover description, public exposure, and packed frontend (yes — your agent can ship a React UI alongside the API). But three lines is enough to ship.

The CLI: Eight Commands, Whole Lifecycle

The a2a CLI is the developer experience:

• a2a init <name> — scaffold a new project (agent.py + a2a.yaml + requirements.txt)
• a2a validate — load the class, verify no errors, print skill count
• a2a card — print the agent card JSON
• a2a dev — run locally with hot reload + a /_dev UI
• a2a test — preflight checks (or --invoke --skill <name> to call one)
• a2a build — build the OCI image (--push to publish)
• a2a deploy — tarball, upload, poll until live, return URL
• a2a frontend build / a2a mcp-url — frontend bundling, MCP discovery

The golden path is three lines:

a2a init my-agent
cd my-agent
a2a deploy

Thirty seconds later you have a public URL backed by a microVM-isolated runtime, a signed agent card, a Knative-managed deployment, and an Argo-tracked source of truth.

Thirty seconds.

What Happens When You Run a2a deploy

Magic? No — platform.

1. The CLI tarballs your source.
2. It uploads the tarball to the control plane's /v1/agents/from-tarball.
3. The control plane commits the source to managed Gitea, wires an ArgoCD application, and triggers a build.
4. The container image gets built and pushed to the platform registry.
5. ArgoCD syncs the Knative service.
6. Your agent gets a public URL.
7. The CLI polls /.well-known/agent-card until your version is actually live and serving.

You get the URL when the agent is actually callable. Not when the upload succeeded. When the agent works.

What You Get For Free

The scary stuff is handled. Out of the box:

• HTTP server — FastAPI with the full A2A protocol
• Agent card — /.well-known/agent-card generated from your class
• Schema validation — input/output types enforced at call time
• Streaming protocol — SSE events for progress, questions, scope requests
• Sandbox execution — ctx.sandbox.run_shell() works, no setup
• Workspace storage — ctx.workspace.write() works, grant-scoped
• LLM access — ctx.llm routes through LiteLLM
• Auth — declare an auth model, it's enforced
• Public URL — Knative + Traefik
• Scale to zero — idle agents cost nothing
• GitOps — every deploy tracked in Gitea + ArgoCD
• Observability — logs, traces, proofs

That list represents *months* of platform work. You skip all of it.

DeepAgents If You Want It

The scaffold template doesn't stop at hello-world. Run a2a init and the generated agent.py already includes a DeepAgents-orchestrated ask skill — LLM + tools + memory — wired through ctx.llm.

Want simple? Delete the boilerplate. Want sophisticated? It's already there.

Why This Matters

The agent ecosystem has been stuck at "frameworks." You wire LLM providers, tool runtimes, deployment scripts, observability, auth, and a public endpoint — and *then* you write the agent.

A2A Pack flips it. Write the agent first. The platform handles the rest. Your code stays small. Your iteration stays fast. Your agent ships.

This is the missing piece for the agent economy: a developer experience that respects your time and a platform that delivers what the demo promised.

Try It

Three lines. Thirty seconds. Public URL.

a2a init my-first-agent
cd my-first-agent
a2a deploy

Welcome to A2A Cloud. The agents you build today actually ship.