Quick Start

This tutorial will help you set up the environment and run your first A2A agent application in 5 minutes.

Environment Setup

System Requirements

Python 3.8+ or Node.js 14+
Git
Internet connection

Install CLI Tool

Choose one of the following installation methods:

# Using pip
pip install a2a-cli

# Or using npm
npm install -g @a2a/cli

Create Project

1. Initialize Project

# Create project directory
a2a init my-first-agent
cd my-first-agent

Directory structure:

my-first-agent/
├── src/
│   ├── agent.py      # Agent implementation
│   └── config.py     # Configuration file
├── tests/            # Test files
├── requirements.txt  # Dependencies
└── README.md        # Project documentation

2. Configure Environment

Create configuration file .env:

A2A_API_KEY=your-api-key
A2A_API_URL=https://api.a2acn.com

Install dependencies:

pip install -r requirements.txt

Develop Agent

1. Implement Agent Logic

Edit src/agent.py:

from a2a import Agent, Task

class AssistantAgent(Agent):
    def __init__(self):
        super().__init__(name="assistant")
        
    async def handle_chat(self, task: Task):
        message = task.input.get("message", "")
        return {
            "reply": f"You said: {message}"
        }

    async def handle_task(self, task: Task):
        if task.type == "chat":
            return await self.handle_chat(task)
        return {
            "error": "Unsupported task type"
        }

2. Start Service

Run the following command to start the agent service:

a2a start

The service runs at http://localhost:8000 by default.

Test Functionality

1. Using CLI

# Send test message
a2a chat "Hello, I'm John"

2. Using SDK

Create test script test.py:

from a2a import Agent, Task

async def main():
    # Create client
    client = Agent()
    
    # Send message
    task = await client.create_task(
        type="chat",
        input={"message": "Hello, I'm John"}
    )
    
    # Wait for result
    result = await task.wait()
    print(f"Received reply: {result.output['reply']}")

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Run test:

python test.py

3. Using API

curl -X POST http://localhost:8000/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "type": "chat",
    "input": {
      "message": "Hello, I'm John"
    }
  }'

Add Features

1. Support More Task Types

Modify agent.py to add new functionality:

class AssistantAgent(Agent):
    # ...existing code...

    async def handle_translate(self, task: Task):
        text = task.input.get("text", "")
        target = task.input.get("target", "en")
        # Implement translation logic
        return {
            "translated": f"Translation result: {text}"
        }

    async def handle_task(self, task: Task):
        handlers = {
            "chat": self.handle_chat,
            "translate": self.handle_translate
        }
        handler = handlers.get(task.type)
        if handler:
            return await handler(task)
        return {
            "error": "Unsupported task type"
        }

2. Add Tool Integration

from a2a.tools import WebSearch, Calculator

class AssistantAgent(Agent):
    def __init__(self):
        super().__init__(name="assistant")
        self.search = WebSearch()
        self.calc = Calculator()
    
    async def handle_chat(self, task: Task):
        message = task.input.get("message", "")
        
        # Handle search requests
        if "search" in message.lower():
            results = await self.search.search(message)
            return {"reply": f"Search results: {results}"}
            
        # Handle calculation requests
        if "calculate" in message.lower():
            expr = message.replace("calculate", "").strip()
            result = await self.calc.evaluate(expr)
            return {"reply": f"Calculation result: {result}"}
            
        return {"reply": f"You said: {message}"}

Deploy Service

1. Build Docker Image

Create Dockerfile:

FROM python:3.8-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["a2a", "start"]

Build image:

docker build -t my-first-agent .

2. Run Container

docker run -d \
  -p 8000:8000 \
  -e A2A_API_KEY=your-api-key \
  my-first-agent

Next Steps

Congratulations! You’ve successfully created and run your first A2A agent. Next, you can:

Learn more about Core Concepts
Explore the API Documentation
Check out Example Projects
Join the Developer Community

Common Issues

Q: What if the service fails to start?

Check the following:

Environment variables are set correctly
Port is not in use
Python version meets requirements
Dependencies are installed completely

Q: How to handle API errors?

Verify API key is correct
Confirm API endpoint is accessible
Check detailed error logs
Refer to Troubleshooting Guide

💡 Tips: When encountering issues:
Use a2a doctor to check environment
View logs with a2a logs
Submit issues on GitHub

Protocol Introduction A2A Protocol Frequently Asked Questions (FAQ)