a2adocsMenu
Start here
Concepts
Languages
Reference
quickstart
For LLMs
/llms.txt/llms-full.txt
a2a docs›quickstart

Quickstart

Pick the path that matches what you are building. All three paths use the same deploy command and produce a hosted A2A + MCP service.

1. Python Tool Agent

Use this when you want the smallest possible agent: one Python class, one or more typed @a2a.tool methods, no custom UI. Tools are published in the agent card's skills array (A2A spec vocabulary); @skill remains a supported alias of @a2a.tool.

pip install a2a-pack
a2a signup --email you@example.com --password ...

a2a init research-agent
cd research-agent
a2a dev

Open the local console:

http://127.0.0.1:8000/_dev

The console shows detected tools, lets you upload files into .a2a/workspace/inputs, streams progress, and previews output files. When the agent is ready:

a2a deploy

You get:

https://research-agent.a2acloud.io

2. Agent With A React App

Use this when the agent needs a real workflow UI: upload controls, review screens, approval flows, reports, or visual output.

pip install a2a-pack
a2a signup --email you@example.com --password ...

a2a init chart-agent --frontend react
cd chart-agent
a2a dev

In another terminal, run the Vite frontend:

cd frontend
npm install
npm run dev

The Vite app proxies /app/config.json, /invoke, /auth, /mcp, and /.well-known to the local agent runtime. The generated app reads the tool contract from the runtime, so Python type hints become UI-callable schemas.

Deploy both together:

a2a deploy

You get:

https://chart-agent.a2acloud.io/app

3. OpenAPI Auto-Agent

Use this when you already have an HTTP API and want an agent that can call it. The generator turns operations into tools and adds an auto tool for natural-language goals.

pip install a2a-pack
a2a signup --email you@example.com --password ...

a2a openapi generate https://api.example.com/openapi.json \
  --name api-agent \
  --base-url https://api.example.com

cd api-agent
a2a dev

Open the local console:

http://127.0.0.1:8000/_dev

If the generated agent needs API credentials or local LLM credentials, the local console asks for them before tool calls are enabled. Values are saved in ~/.a2a/credentials.json; shell env and .env.local still take precedence.

For an OpenAI-compatible local LLM, the fields are:

AGENT_LLM_KEY=your_openai_or_compatible_key
AGENT_LLM_URL=https://api.openai.com/v1
AGENT_LLM_MODEL=gpt-4o

On A2A Cloud, saved dashboard keys route through LiteLLM's compatibility layer. Use the model dropdown when adding an LLM key; it is populated from LiteLLM's chat/completion model catalog and lets the platform keep routing, usage, and pricing aligned. See LLM credentials & model compatibility.

Deploy when the generated operations and prompts look right:

a2a deploy

You get:

https://api-agent.a2acloud.io

Running Local Dev

a2a dev is the normal development loop for every agent type.

cd your-agent
a2a dev

It starts the agent runtime on http://127.0.0.1:8000 and prints the local URLs:

url:    http://127.0.0.1:8000
dev ui: http://127.0.0.1:8000/_dev
card:   http://127.0.0.1:8000/.well-known/agent-card

Use /_dev for the built-in local console. It can:

  • run any detected tool
  • stream progress and final results
  • upload files into .a2a/workspace/inputs
  • preview files from .a2a/workspace/outputs
  • prompt for missing local credentials before tool calls are enabled

If port 8000 is busy:

a2a dev --port 8010

Local credentials

Local dev loads setup in this order:

  1. Shell environment variables.
  2. .env.local in the agent project.
  3. Saved values in ~/.a2a/credentials.json.

For generated OpenAPI agents or DeepAgents-based agents that use ctx.llm, the local console asks for LLM credentials and saves them for future runs:

AGENT_LLM_KEY=your_openai_or_compatible_key
AGENT_LLM_URL=https://api.openai.com/v1
AGENT_LLM_MODEL=gpt-4o

Hosted chat and caller-provided agent LLM calls use the same OpenAI-compatible shape, but the control plane forwards them through LiteLLM so usage and pricing are tracked consistently across compatible providers.

Agent-specific setup fields, such as BLOG_API_KEY, are also saved per agent in ~/.a2a/credentials.json. Project .env.local still wins if both are set.

Docker chat with local resources

Use a2a chat when you want the smallest Docker-backed loop for one agent and its declared resources. It starts the same local console as a2a dev, plus Qdrant when vector memory is declared and Postgres when Neon/Postgres databases are declared.

a2a chat --env-file .env.local --detach

Open:

http://127.0.0.1:8000/_dev

For this declaration:

resources:
  memory:
    tiers: [vector]
  databases:
    - name: app
      provider: neon
      engine: postgres
      env:
        url: DATABASE_URL

the harness sets:

A2A_MEMORY_VECTOR_URL=http://qdrant:6333
DATABASE_URL=postgresql://a2a:a2a@postgres:5432/app

If your env file contains OPENAI_API_KEY, local Docker chat maps it to AGENT_LLM_KEY for ctx.llm unless AGENT_LLM_KEY is already set.

Stop and remove local resource volumes:

a2a chat --down --volumes

Local React frontend

Packed frontends use two local processes during active UI development:

# terminal 1: Python agent runtime + A2A/MCP endpoints
a2a dev

# terminal 2: Vite frontend with hot reload
cd frontend
npm install
npm run dev

Open the Vite URL, usually:

http://127.0.0.1:5173

The Vite dev server proxies these runtime paths to a2a dev:

/app/config.json
/invoke
/auth
/mcp
/.well-known

Before deploy, verify the packed static bundle:

a2a frontend build
a2a dev

When frontend/dist/index.html exists, a2a dev also serves the packed app at the configured mount path, usually:

http://127.0.0.1:8000/app

Common Commands

a2a card                         # print the Agent Card JSON
a2a openapi spec --out openapi.json
a2a openapi client --out frontend/src/a2a-client
a2a test                         # validate local project wiring
a2a test --invoke                # run one local tool call
a2a dev --port 8010              # use another local port
a2a chat --detach                # run one agent with local Docker resources
a2a agents                       # list deployed agents
a2a mcp-url research-agent       # print MCP config for a deployed agent

What Deploy Creates

  • Public URL with TLS.
  • Full A2A surfaces for Agent Card discovery, tasks, messages, artifacts, files, structured data, streaming, auth, JSON-RPC, REST, and protocol errors.
  • /healthz, /.well-known/agent-card, /, /message:send, /message:stream, /tasks/{id}, /invoke/{skill}, and /mcp.
  • Optional /app, /app/config.json, /app/a2a-client.js, and /.well-known/a2a-skills.json when the project declares a packed frontend.
  • /.well-known/openapi.json for OpenAPI 3.1 tool contracts.
  • Auto-derived JSON Schema validation from Python type hints.
  • Discoverability from other agents through scoped, signed grants.

Next