A2A Protocol

Content Planner Agent Based on A2A and ADK

deutschEnglishfrançaisहिंदी日本語한국어中文
MILO•
Share
ADK
Content Planner Agent Based on A2A and ADK

Project Overview

The Content Planner Agent is an intelligent content planning agent built on Google Agent Development Kit (ADK) and Python A2A SDK. This agent can create detailed content outlines based on high-level content descriptions.

What is A2A Protocol

A2A Protocol (Agent2Agent Protocol) is an open standard protocol specifically designed for AI agents. Its core goal is to achieve interoperability between agents across different platforms and technology stacks, enabling them to collaborate like "colleagues" to complete tasks, regardless of the underlying technology.

Tech Stack

  • Python: 3.10+
  • UV: Python package manager
  • Google ADK: Google Agent Development Kit
  • A2A SDK: Agent-to-Agent communication protocol
  • Gemini 2.5 Flash: Large language model
  • Google Search: Search tool
  • Uvicorn: ASGI server

Prerequisites

1. Environment Setup

Ensure your system has the following software installed:

# Check Python version (requires 3.10+)
python --version

# Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or use pip
pip install uv

2. API Keys

You need to obtain Google API keys to use Gemini models and Google Search functionality:

  1. Visit Google AI Studio
  2. Create a new API key
  3. Save the key for later use

Project Structure

samples/python/agents/content_planner/
├── __init__.py                 # Package initialization file
├── __main__.py                # Main entry file
├── agent_executor.py          # Agent executor
├── content_planner_agent.py   # Content planner agent definition
├── pyproject.toml            # Project configuration file
├── requirements.txt          # Dependencies list
├── .env.example             # Environment variables example
└── README.md               # Project documentation

Quick Start

Step 1: Clone the project and navigate to the directory

# Assuming you already have the a2a-samples project
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/content_planner

Step 2: Configure environment variables

# Copy the environment variables example file
cp .env.example .env

# Edit the .env file and add your Google API key
echo "GOOGLE_API_KEY=your_actual_api_key_here" > .env

Step 3: Install dependencies and run the agent

# Use UV to install dependencies and run the project
uv run .

# Note:
"gradio>=5.30.0" is not needed in the current agent.

By default, the agent will start at http://localhost:10001.

Step 4: Test the agent (new terminal window)

# Navigate to the CLI client directory
cd samples/python/hosts/cli

# Connect to the agent and send a message
uv run . --agent http://localhost:10001

Step 5: Interact with the agent

In the CLI client, you can send messages like:

Create an outline for a short, upbeat, and encouraging X post about learning Java

Code Explanation

1. Main Entry File (__main__.py)

@click.command()
@click.option("--host", default="localhost")
@click.option("--port", default=10001)
def main(host, port):
    # Agent card (metadata)
    agent_card = AgentCard(
        name='Content Planner Agent',
        description=content_planner_agent.description,
        url=f'http://{host}:{port}',
        version="1.0.0",
        defaultInputModes=["text", "text/plain"],
        defaultOutputModes=["text", "text/plain"],
        capabilities=AgentCapabilities(streaming=True),
        skills=[
            AgentSkill(
                id="content_planner",
                name="Creates outlines for content",
                description="Creates outlines for content given a high-level description of the content",
                tags=["plan", "outline"],
                examples=[
                    "Create an outline for a short, upbeat, and encouraging X post about learning Java",
                ],
            )
        ],
    )

Key Components Explanation:

  • AgentCard: Agent metadata card containing name, description, URL, version, etc.
  • AgentSkill: Defines agent skills including ID, name, description, tags, and examples
  • AgentCapabilities: Agent capability configuration, such as streaming support

2. Agent Definition (content_planner_agent.py)

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="content_planner_agent",
    model="gemini-2.5-flash",
    description=("Planning agent that creates a detailed and logical outline for a piece of content,"
                 "given a high-level description."),
    instruction=("You are an expert content planner. Your task is to create a detailed and logical outline for a piece"
                 "of content, given a high-level description."),
    tools=[google_search],
)

Key Features:

  • Model: Uses Gemini 2.5 Flash as the underlying LLM
  • Tools: Integrates Google Search tool for relevant information retrieval
  • Instructions: Clearly defines the agent's role and tasks

3. Agent Executor (agent_executor.py)

class ADKAgentExecutor(AgentExecutor):
    def __init__(self, agent, status_message="Processing request...", artifact_name="response"):
        self.agent = agent
        self.status_message = status_message
        self.artifact_name = artifact_name
        self.runner = Runner(
            app_name=agent.name,
            agent=agent,
            artifact_service=InMemoryArtifactService(),
            session_service=InMemorySessionService(),
            memory_service=InMemoryMemoryService(),
        )

Core Functionality:

  • Runner: ADK runner that manages agent execution
  • Service Components:
    • ArtifactService: Manages generated artifacts
    • SessionService: Manages session state
    • MemoryService: Manages conversation memory

System Architecture Flow Chart

graph TB
    A[User Request] --> B[A2A CLI Client]
    B --> C[HTTP Request]
    C --> D[A2A Starlette Application]
    D --> E[DefaultRequestHandler]
    E --> F[ADKAgentExecutor]
    F --> G[ADK Runner]
    G --> H[Content Planner Agent]
    H --> I[Gemini 2.5 Flash Model]
    H --> J[Google Search Tool]
    I --> K[Generate Content Outline]
    J --> K
    K --> L[Response Artifact]
    L --> M[Task Completion]
    M --> N[Return Result to User]
    
    subgraph "ADK Components"
        O[InMemoryArtifactService]
        P[InMemorySessionService]
        Q[InMemoryMemoryService]
    end
    
    G --> O
    G --> P
    G --> Q

Detailed Execution Flow

1. Initialization Phase

sequenceDiagram
    participant Main as __main__.py
    participant Agent as content_planner_agent
    participant Executor as ADKAgentExecutor
    participant Server as A2AStarletteApplication
    
    Main->>Agent: Load agent configuration
    Main->>Executor: Create executor instance
    Main->>Server: Create A2A server
    Server->>Server: Start Uvicorn server

2. Request Processing Phase

sequenceDiagram
    participant Client as CLI Client
    participant Server as A2A Server
    participant Handler as DefaultRequestHandler
    participant Executor as ADKAgentExecutor
    participant Runner as ADK Runner
    participant Model as Gemini 2.5 Flash
    participant Search as Google Search
    
    Client->>Server: Send content planning request
    Server->>Handler: Route request
    Handler->>Executor: Execute agent task
    Executor->>Runner: Start ADK runner
    Runner->>Model: Call Gemini model
    Runner->>Search: Execute Google search
    Model->>Runner: Return generated content
    Search->>Runner: Return search results
    Runner->>Executor: Merge results
    Executor->>Handler: Return artifact
    Handler->>Server: Complete task
    Server->>Client: Return content outline

Advanced Configuration

Custom Port

# Start agent on specified port
uv run . --port=8080

Custom Host

# Start on specified host and port
uv run . --host=0.0.0.0 --port=8080

Environment Variable Configuration

You can configure more options in the .env file:

GOOGLE_API_KEY=your_api_key_here
# You can add other configuration items
LOG_LEVEL=INFO

Troubleshooting

Common Issues

  1. API Key Error

    Error: Invalid API key
Solution: Check if GOOGLE_API_KEY in .env file is correct

  2. Port Already in Use

    Error: Port 10001 is already in use
Solution: Use --port parameter to specify another port

  3. Dependency Installation Failed

    Error: Failed to install dependencies
Solution: Ensure UV is properly installed, try uv sync

Extension and Customization

Adding New Tools

Add new tools in content_planner_agent.py:

from google.adk.tools import google_search, web_search

root_agent = Agent(
    # ... other configurations
    tools=[google_search, web_search],  # Add more tools
)

Modify Model

root_agent = Agent(
    name="content_planner_agent",
    model="gemini-1.5-pro",  # Use different model
    # ... other configurations
)

Custom Instructions

root_agent = Agent(
    # ... other configurations
    instruction=(
        "You are a specialized content planner for technical documentation. "
        "Create detailed outlines that include code examples and best practices."
    ),
)

Best Practices

  1. Security:

    • Always store API keys in environment variables
    • Don't commit .env files to version control

  2. Performance Optimization:

    • Use appropriate model sizes
    • Properly configure memory and session services

  3. Error Handling:

    • Implement proper error handling and logging
    • Provide meaningful error messages

  4. Testing:

    • Write unit tests and integration tests
    • Test agent responses with different inputs

Summary

The Content Planner Agent demonstrates how to build intelligent agents using Google ADK and A2A Protocol. Through this guide, you should be able to:

  • Understand the overall project architecture
  • Successfully run and test the agent
  • Customize and extend as needed
  • Resolve common issues

This agent can serve as a foundation for building more complex multi-agent systems, such as complete content creation workflows.

More A2A Protocol Examples