A2A for Developers: Deploy an Agent in 15 Minutes with a2a cloud

A2A for Developers: Deploy an Agent in 15 Minutes with a2a cloud

A2A stands for Agent-to-Agent. The practical idea is simple: an agent should describe what it can do, expose typed skills, accept structured inputs, and be callable by humans, apps, and other agents without custom glue code each time.

The fastest way to build one is not to hand-write a manifest from scratch. Use the A2A Pack template, change one skill, run it locally, then deploy.

This guide is the developer path from zero to a hosted agent.

What You Will Build

You will build a small support-agent with one typed skill called summarize.

By the end you will have:

• a scaffolded A2A Pack project
• a typed Python skill
• a local dev server
• an Agent Card
• an OpenAPI spec for the skill API
• an optional generated TypeScript client
• a deployed a2a cloud URL

Prerequisites

You need Python and the A2A Pack CLI:

python -m pip install --upgrade a2a-pack

Log in before deploying:

a2a login

If you are creating a frontend too, install Node.js 20 or newer.

Step 1: Scaffold From the Template

Create the agent from the starter template:

a2a init support-agent --description "Summarizes support tickets and suggests a next action."
cd support-agent
python -m pip install -r requirements.txt

The template creates the project shape for you:

support-agent/
  a2a.yaml
  agent.py
  requirements.txt
  README.md
  Dockerfile

The important files are:

• agent.py: your agent class and skills
• a2a.yaml: the project manifest used by local dev and deploy
• requirements.txt: Python dependencies installed during build

Do not start by writing Kubernetes YAML, Docker packaging, or Agent Card JSON. The template and CLI generate the boring parts.

Step 2: Add a Real Skill

Open agent.py. The generated template includes a starter DeepAgents skill. For a first deploy, replace or add one small typed skill so the runtime path is easy to test.

from a2a_pack import A2AAgent, NoAuth, RunContext, skill


class SupportAgent(A2AAgent):
    name = "support-agent"
    description = "Summarizes support tickets and suggests a next action."
    version = "0.1.0"
    auth_model = NoAuth

    @skill(description="Summarize a support ticket and suggest the next action.")
    async def summarize(
        self,
        ctx: RunContext[NoAuth],
        ticket: str,
        urgency: str = "normal",
    ) -> dict:
        await ctx.emit_progress("reading ticket")
        clean_ticket = " ".join(ticket.strip().split())
        summary = clean_ticket[:240] or "No ticket text was provided."

        return {
            "summary": summary,
            "urgency": urgency,
            "next_action": "Reply with an owner, timeline, and one concrete next step.",
        }

Typed skill arguments matter. A2A Pack uses them to produce JSON Schema, local forms, direct invoke endpoints, and OpenAPI contracts.

Step 3: Run It Locally

Start the local dev server:

a2a dev

Open the dev UI:

http://127.0.0.1:8000/_dev

The dev server loads your project, exposes the same local Agent Card and invoke routes as production, and gives you a browser form for running skills.

You can also test from the CLI:

a2a test --invoke \
  --skill summarize \
  --args-json '{"ticket":"Customer cannot log in after password reset.","urgency":"high"}'

A successful response should look like this:

{
  "summary": "Customer cannot log in after password reset.",
  "urgency": "high",
  "next_action": "Reply with an owner, timeline, and one concrete next step."
}

Step 4: Check the Agent Contract

Print the Agent Card:

a2a card

Generate the OpenAPI spec for direct skill APIs:

a2a openapi spec --out openapi.json

The spec includes a per-skill endpoint such as:

POST /invoke/summarize

That gives frontend teams and other services a normal HTTP contract instead of forcing them to learn the internal Python code.

Step 5: Generate a Frontend Client

If you want a typed TypeScript client, use the built-in OpenAPI client command:

a2a openapi client \
  --out frontend/src/a2a-client \
  --spec-out frontend/src/a2a-client/openapi.json

Under the hood, the CLI runs @hey-api/openapi-ts against the generated skill spec.

To export only one skill, pass --skill:

a2a openapi client \
  --skill summarize \
  --out frontend/src/a2a-client

This is useful when a frontend should only depend on a narrow public surface.

Step 6: Deploy

Deploy from the project root:

a2a deploy

The CLI packages your source, uploads it, and lets a2a cloud build and run the agent. When the deploy finishes, you get a hosted URL for the agent.

The deployed agent exposes the standard surfaces:

• /.well-known/agent-card.json
• /.well-known/openapi.json
• /invoke/summarize
• /_a2a/mcp
• /healthz

The exact hostname depends on your account and project name.

Optional: Start With a Server-Rendered Next.js App

If your agent should include a human-facing app, scaffold the frontend with the agent:

a2a init support-agent \
  --frontend nextjs \
  --frontend-mode server-rendered \
  --auth platform

That creates a Next.js frontend under frontend/ and configures the manifest for a server-rendered packed frontend:

frontend:
  type: server-rendered
  framework: nextjs
  path: frontend
  build: npm run build
  start: node server.js
  port: 3000
  mount: /
  auth: platform

For local frontend development:

cd frontend
npm install
npm run dev

For deploy, go back to the agent root and use the same command:

a2a deploy

The platform builds the frontend and serves it from the same deployed agent hostname, while A2A runtime routes stay available under the agent API paths.

What a2a cloud Handles

a2a cloud handles the production work around the A2A protocol:

• packaging the project
• building the runtime image
• deploying the hosted service
• exposing the Agent Card
• serving OpenAPI for skills
• serving MCP for tool clients
• enforcing app auth when configured
• wiring caller-scoped LLM and workspace grants

You keep the agent behavior in code. The platform handles the repeatable runtime shape.

Common First-Deploy Fixes

If a first deploy fails, check these first:

• Run commands from the folder that contains a2a.yaml.
• Install dependencies locally with python -m pip install -r requirements.txt.
• Make sure the entrypoint in a2a.yaml matches the Python module and class.
• Keep build output, caches, .venv, node_modules, and .next out of the upload.
• If your skill uses ctx.llm, add an LLM credential in a2a cloud or set the local credential expected by the template.
• If your app uses --auth platform, test with a logged-in browser session.

Where to Go Next

Once the starter agent works, the next useful steps are:

1. Add one real integration.
2. Keep inputs typed so schemas and clients stay useful.
3. Generate a frontend client with a2a openapi client.
4. Add platform auth for user-specific workflows.
5. Connect the deployed MCP endpoint to an agent client or developer tool.

A2A is not about making every agent complicated. It is about giving useful agents a predictable shape: discoverable, typed, callable, and deployable.

Start with the template. Prove the path. Then spend your time on the behavior that makes the agent valuable.