A2A Project Setup
Before writing code
Fetch live docs:
- Fetch
https://a2a-protocol.org/latest/specification/ for the latest protocol overview
- Web-search
site:github.com a2aproject a2a-python README or a2aproject a2a-js README for the target SDK's current installation and quickstart
- Web-search
site:github.com a2aproject a2a-samples for official sample project structures
- Fetch the SDK's PyPI/npm page for the latest version number
Conceptual Architecture
What Setup Involves
A2A project setup creates the foundation for a multi-agent system:
- Install the A2A SDK for your language (Python, JS/TS, Go, Java, .NET)
- Create directory structure — agent server, client, Agent Card, configuration
- Define the Agent Card — the discovery document describing your agent
- Create a minimal server — HTTP endpoint that handles JSON-RPC 2.0 A2A methods
- Create a minimal client — code to discover and call another A2A agent
Python Project Structure
my-a2a-agent/
├── agent_card.json # Agent Card (also served at /.well-known/agent-card.json)
├── server.py # A2A server entry point
├── client.py # A2A client for testing
├── agent/
│ ├── __init__.py
│ └── handler.py # Task processing logic
├── pyproject.toml # or requirements.txt
└── tests/
└── test_agent.py
JS/TS Project Structure
my-a2a-agent/
├── agent-card.json
├── src/
│ ├── server.ts # A2A server entry point
│ ├── client.ts # A2A client for testing
│ └── handler.ts # Task processing logic
├── package.json
├── tsconfig.json
└── tests/
└── agent.test.ts
Agent Card Skeleton
Every A2A agent needs an Agent Card. Minimal structure:
{
"name": "My Agent",
"description": "What this agent does",
"url": "http://localhost:8000",
"version": "1.0.0",
"protocolVersion": "0.2.1",
"capabilities": {
"streaming": false,
"pushNotifications": false,
"stateTransitionHistory": false
},
"skills": [
{
"id": "skill-1",
"name": "Skill Name",
"description": "What this skill does",
"tags": ["tag1", "tag2"],
"examples": ["Example input"]
}
],
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"]
}
Key Setup Decisions
- Language/SDK — Python (
a2a-sdk), JS/TS (@a2a-js/sdk), Go, Java, .NET
- HTTP framework — The SDK may provide a built-in server or integrate with frameworks (FastAPI, Express, etc.)
- Capabilities — Decide upfront: streaming? push notifications? state history?
- Authentication — None for local dev; API key or OAuth2 for production
- Agent Card hosting — Serve at
/.well-known/agent-card.json or via a registry
Best Practices
- Start with a minimal Agent Card and expand as you add skills
- Use the SDK's built-in server utilities rather than building raw JSON-RPC handling
- Keep the Agent Card in a separate file, loaded at server startup
- Add proper logging from the start — A2A debugging requires visibility into message flow
- Set up a test client alongside the server for rapid development
Fetch the SDK README for exact installation commands, class names, and quickstart code before scaffolding.
1---2name: a2a-setup3description: Scaffold a new A2A project — install the SDK, create directory structure, configure the Agent Card, and set up a basic server/client. Use when starting a new A2A multi-agent project from scratch.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/a2a-setup7---89# A2A Project Setup1011## Before writing code1213**Fetch live docs**:141. Fetch `https://a2a-protocol.org/latest/specification/` for the latest protocol overview152. Web-search `site:github.com a2aproject a2a-python README` or `a2aproject a2a-js README` for the target SDK's current installation and quickstart163. Web-search `site:github.com a2aproject a2a-samples` for official sample project structures174. Fetch the SDK's PyPI/npm page for the latest version number1819## Conceptual Architecture2021### What Setup Involves2223A2A project setup creates the foundation for a multi-agent system:241. **Install the A2A SDK** for your language (Python, JS/TS, Go, Java, .NET)252. **Create directory structure** — agent server, client, Agent Card, configuration263. **Define the Agent Card** — the discovery document describing your agent274. **Create a minimal server** — HTTP endpoint that handles JSON-RPC 2.0 A2A methods285. **Create a minimal client** — code to discover and call another A2A agent2930### Python Project Structure3132```33my-a2a-agent/34├── agent_card.json # Agent Card (also served at /.well-known/agent-card.json)35├── server.py # A2A server entry point36├── client.py # A2A client for testing37├── agent/38│ ├── __init__.py39│ └── handler.py # Task processing logic40├── pyproject.toml # or requirements.txt41└── tests/42 └── test_agent.py43```4445### JS/TS Project Structure4647```48my-a2a-agent/49├── agent-card.json50├── src/51│ ├── server.ts # A2A server entry point52│ ├── client.ts # A2A client for testing53│ └── handler.ts # Task processing logic54├── package.json55├── tsconfig.json56└── tests/57 └── agent.test.ts58```5960### Agent Card Skeleton6162Every A2A agent needs an Agent Card. Minimal structure:6364```json65{66 "name": "My Agent",67 "description": "What this agent does",68 "url": "http://localhost:8000",69 "version": "1.0.0",70 "protocolVersion": "0.2.1",71 "capabilities": {72 "streaming": false,73 "pushNotifications": false,74 "stateTransitionHistory": false75 },76 "skills": [77 {78 "id": "skill-1",79 "name": "Skill Name",80 "description": "What this skill does",81 "tags": ["tag1", "tag2"],82 "examples": ["Example input"]83 }84 ],85 "defaultInputModes": ["text/plain"],86 "defaultOutputModes": ["text/plain"]87}88```8990### Key Setup Decisions9192- **Language/SDK** — Python (`a2a-sdk`), JS/TS (`@a2a-js/sdk`), Go, Java, .NET93- **HTTP framework** — The SDK may provide a built-in server or integrate with frameworks (FastAPI, Express, etc.)94- **Capabilities** — Decide upfront: streaming? push notifications? state history?95- **Authentication** — None for local dev; API key or OAuth2 for production96- **Agent Card hosting** — Serve at `/.well-known/agent-card.json` or via a registry9798### Best Practices99100- Start with a minimal Agent Card and expand as you add skills101- Use the SDK's built-in server utilities rather than building raw JSON-RPC handling102- Keep the Agent Card in a separate file, loaded at server startup103- Add proper logging from the start — A2A debugging requires visibility into message flow104- Set up a test client alongside the server for rapid development105106Fetch the SDK README for exact installation commands, class names, and quickstart code before scaffolding.