A2A Hello World Tutorial

Project Overview

This is a simple Hello World agent example based on the A2A (Agent2Agent) SDK. The project demonstrates how to create a basic intelligent agent server that can respond to user messages and return simple greetings.

Dependency Version Requirements

Python Version Requirements

• Python >= 3.10

Core Dependencies

Package	Version	Purpose
a2a-sdk	>= 0.2.5	A2A core SDK, provides agent framework
uvicorn	>= 0.34.2	ASGI server for running web applications
click	>= 8.1.8	Command line interface tool
httpx	>= 0.28.1	Async HTTP client
pydantic	>= 2.11.4	Data validation and serialization
python-dotenv	>= 1.1.0	Environment variable management
langchain-google-genai	>= 2.1.4	Google Generative AI integration
langgraph	>= 0.4.1	Language graph processing framework

Project Structure

helloworld/
├── __init__.py              # Package initialization file
├── __main__.py              # Main program entry point
├── agent_executor.py        # Agent executor implementation
├── test_client.py           # Test client
├── pyproject.toml           # Project configuration and dependencies
├── uv.lock                  # Dependency lock file
└── README.md                # Project documentation

Environment Setup

1. Install UV Package Manager

If you haven't installed UV yet, please install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or use pip
pip install uv

2. Clone the Project

git clone https://github.com/google-a2a/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld

3. Install Dependencies

UV will automatically install all dependencies based on pyproject.toml and uv.lock files:

uv sync

Code Architecture

Core Components

1. HelloWorldAgent (agent_executor.py)

class HelloWorldAgent:
    """Hello World Agent."""
    
    async def invoke(self) -> str:
        return 'Hello World'

2. HelloWorldAgentExecutor (agent_executor.py)

class HelloWorldAgentExecutor(AgentExecutor):
    """Agent executor implementation"""
    
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        result = await self.agent.invoke()
        event_queue.enqueue_event(new_agent_text_message(result))

3. Server Configuration (__main__.py)

• Define agent skills (AgentSkill)
• Configure public and extended agent cards (AgentCard)
• Set up request handlers and task storage
• Start Uvicorn server

Running Steps

1. Start the Agent Server

uv run .

The server will start at http://localhost:9999.

2. Run the Test Client

In another terminal window:

uv run test_client.py

3. Verify the Service

You can verify that the service is running properly through the following methods:

Access Agent Card Information

curl http://localhost:9999/.well-known/agent.json

Access Extended Agent Card (requires authentication)

curl -H "Authorization: Bearer dummy-token-for-extended-card" \
     http://localhost:9999/agent/authenticatedExtendedCard

Project Flow Diagram

A2A Client-Server Interaction Flow

System Architecture Flow Diagram

API Endpoints

Public Endpoints

Endpoint	Method	Description
/.well-known/agent.json	GET	Get public agent card information
/agent/message	POST	Send message to agent
/agent/message/stream	POST	Stream message to agent

Authenticated Endpoints

Endpoint	Method	Description	Authentication
/agent/authenticatedExtendedCard	GET	Get extended agent card	Bearer Token

Skill Configuration

Basic Skills

• ID: hello_world
• Name: Returns hello world
• Description: just returns hello world
• Examples: ['hi', 'hello world']

Extended Skills (requires authentication)

• ID: super_hello_world
• Name: Returns a SUPER Hello World
• Description: A more enthusiastic greeting, only for authenticated users
• Examples: ['super hi', 'give me a super hello']

Troubleshooting

Common Issues

1. Port Already in Use

   # Check port usage
   lsof -i :9999
   # Kill the process
   kill -9 <PID>

2. Dependency Installation Failed

   # Clean cache and reinstall
   uv cache clean
   uv sync --reinstall

3. Python Version Incompatible

   # Check Python version
   python --version
   # Ensure version >= 3.10

Extension Development

Adding New Skills

1. Define new AgentSkill in __main__.py
2. Modify logic handling in agent_executor.py
3. Update agent card configuration

Integrating External APIs

1. Add new dependencies in pyproject.toml
2. Implement API calls in agent_executor.py
3. Handle async responses and errors

Summary

This Hello World example demonstrates the basic usage of the A2A SDK, including:

• Creating and configuring agent servers
• Skill definition and management
• Client-server communication
• Authentication and extended functionality

Through this example, you can quickly understand how to build your own intelligent agent applications.