A2A Protocol Documentation

Appearance

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:

bash
# 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 ​

bash
# 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 ​

bash
# 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 ​

bash
# 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) ​

bash
# 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) ​

python
@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) ​

python
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) ​

python
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 ​

Detailed Execution Flow ​

1. Initialization Phase ​

2. Request Processing Phase ​

Advanced Configuration ​

Custom Port ​

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

Custom Host ​

bash
# 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:

bash
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:

python
from google.adk.tools import google_search, web_search

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

Modify Model ​

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

Custom Instructions ​

python
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 ​

A2A Protocol Documentation

Copyright © 2025 a2aprotocol.ai