DEV Community

Cover image for Content Planner Agent Based on A2A and ADK
cz
cz

Posted on

Content Planner Agent Based on A2A and ADK

#a2a

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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",
                ],
            )
        ],
    )
Enter fullscreen mode Exit fullscreen mode

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],
)
Enter fullscreen mode Exit fullscreen mode

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(),
        )
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Advanced Configuration

Custom Port 

# Start agent on specified port
uv run . --port=8080
Enter fullscreen mode Exit fullscreen mode

Custom Host 

# Start on specified host and port
uv run . --host=0.0.0.0 --port=8080
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Common Issues

  1. API Key Error 
   Error: Invalid API key
   Solution: Check if GOOGLE_API_KEY in .env file is correct
Enter fullscreen mode Exit fullscreen mode
  1. Port Already in Use 
   Error: Port 10001 is already in use
   Solution: Use --port parameter to specify another port
Enter fullscreen mode Exit fullscreen mode
  1. Dependency Installation Failed 
   Error: Failed to install dependencies
   Solution: Ensure UV is properly installed, try uv sync
Enter fullscreen mode Exit fullscreen mode

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
)
Enter fullscreen mode Exit fullscreen mode

Modify Model 

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

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."
    ),
)
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)