A2A Samples: Hello World Agent

Project Overview

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

Dependency Version Requirements

Python Version Requirements

• Python >= 3.10

Core Dependencies

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

sequenceDiagram
    participant Client as A2A Client
    participant Server as A2A Server
    participant Agent as HelloWorldAgent
    participant Queue as EventQueue
    
    Note over Client,Server: 1. Service Discovery Phase
    Client->>Server: GET /.well-known/agent.json
    Server-->>Client: Return public agent card
    
    Note over Client,Server: 2. Extended Card Retrieval (Optional)
    Client->>Server: GET /agent/authenticatedExtendedCard<br/>(with Bearer token)
    Server-->>Client: Return extended agent card
    
    Note over Client,Server: 3. Message Sending Flow
    Client->>Server: POST /agent/message<br/>{"message": {"role": "user", "parts": [...]}}
    
    Note over Server,Queue: 4. Server Internal Processing
    Server->>Agent: Call HelloWorldAgentExecutor.execute()
    Agent->>Agent: Execute HelloWorldAgent.invoke()
    Agent-->>Queue: Generate "Hello World" message
    Queue-->>Server: Return event queue result
    
    Note over Client,Server: 5. Response Return
    Server-->>Client: Return message response
    
    Note over Client,Server: 6. Streaming Message Processing (Optional)
    Client->>Server: POST /agent/message/stream
    Server-->>Client: Stream message chunks
    Server-->>Client: Message chunk 1
    Server-->>Client: Message chunk 2
    Server-->>Client: End marker

System Architecture Flow Diagram

graph TB
    subgraph "Client Environment"
        C1[Test Client Startup]
        C2[A2ACardResolver<br/>Parse Agent Card]
        C3[A2AClient<br/>Initialization]
        C4[Send Message Request]
        C5[Process Response]
    end
    
    subgraph "Network Communication"
        N1[HTTP/HTTPS Request]
        N2[JSON Data Transfer]
    end
    
    subgraph "Server Environment"
        S1[A2AStarletteApplication<br/>Web Server]
        S2[DefaultRequestHandler<br/>Request Handler]
        S3[HelloWorldAgentExecutor<br/>Agent Executor]
        S4[HelloWorldAgent<br/>Core Agent Logic]
        S5[InMemoryTaskStore<br/>Task Storage]
        S6[EventQueue<br/>Event Queue]
    end
    
    subgraph "Agent Configuration"
        A1[Public Agent Card<br/>Basic Skills]
        A2[Extended Agent Card<br/>Enhanced Skills]
    end
    
    %% Client flow
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    
    %% Network communication
    C4 --> N1
    N1 --> N2
    N2 --> S1
    S1 --> N2
    N2 --> C5
    
    %% Server flow
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S6
    S6 --> S3
    S3 --> S2
    S2 --> S1
    
    %% Configuration associations
    A1 --> S1
    A2 --> S1
    S2 --> S5
    
    %% Styling
    style C3 fill:#e3f2fd
    style S1 fill:#f3e5f5
    style S4 fill:#e8f5e8
    style N2 fill:#fff3e0

API Endpoints

Public Endpoints

Authenticated Endpoints

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.