项目概述

Content Planner Agent 是一个基于 Google Agent Development Kit (ADK) 和 Python A2A SDK 构建的智能内容规划代理。该代理能够根据高层次的内容描述，创建详细的内容大纲。

什么是A2A Protocol

A2A Protocol（Agent2Agent 协议）是一种专为 AI 智能体设计的开放标准协议。它的核心目标是实现不同平台、不同技术栈下的智能体之间的互操作性，让它们能够像“同事”一样协作完成任务，无论背后用的是什么技术。

技术栈

Python: 3.10+
UV: Python 包管理器
Google ADK: Google Agent Development Kit
A2A SDK: Agent-to-Agent 通信协议
Gemini 2.5 Flash: 大语言模型
Google Search: 搜索工具
Uvicorn: ASGI 服务器

前置要求

1. 环境准备

确保您的系统已安装以下软件：

# 检查 Python 版本 (需要 3.10+)
python --version# 安装 UV 包管理器 (如果尚未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或使用 pip
pip install uv

2. API 密钥

您需要获取 Google API 密钥以使用 Gemini 模型和 Google Search 功能：

访问 Google AI Studio
创建新的 API 密钥
保存密钥以备后用

项目结构

samples/python/agents/content_planner/
├── __init__.py                 # 包初始化文件
├── __main__.py                # 主入口文件
├── agent_executor.py          # 代理执行器
├── content_planner_agent.py   # 内容规划代理定义
├── pyproject.toml            # 项目配置文件
├── requirements.txt          # 依赖列表
├── .env.example             # 环境变量示例
└── README.md               # 项目说明

快速开始

步骤 1: 克隆项目并导航到目录

# 假设您已经有 a2a-samples 项目
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/content_planner

步骤 2: 配置环境变量

# 复制环境变量示例文件
cp .env.example .env# 编辑 .env 文件，添加您的 Google API 密钥
echo "GOOGLE_API_KEY=your_actual_api_key_here" > .env

步骤 3: 安装依赖并运行代理

# 使用 UV 安装依赖并运行项目
uv run .# 注意：
"gradio>=5.30.0" 在当前 agent 中，是不需要的。

默认情况下，代理将在 http://localhost:10001 启动。

步骤 4: 测试代理 (新终端窗口)

# 导航到 CLI 客户端目录
cd samples/python/hosts/cli# 连接到代理并发送消息
uv run . --agent http://localhost:10001

步骤 5: 与代理交互

在 CLI 客户端中，您可以发送如下消息：

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

代码详解

1. 主入口文件 (`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",],)],)

关键组件说明：

AgentCard: 代理的元数据卡片，包含名称、描述、URL、版本等信息
AgentSkill: 定义代理的技能，包括 ID、名称、描述、标签和示例
AgentCapabilities: 代理的能力配置，如是否支持流式输出

2. 代理定义 (`content_planner_agent.py`)

from google.adk.agents import Agent
from google.adk.tools import google_searchroot_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],
)

关键特性：

模型: 使用 Gemini 2.5 Flash 作为底层 LLM
工具: 集成 Google Search 工具，可以搜索相关信息
指令: 明确定义代理的角色和任务

3. 代理执行器 (`agent_executor.py`)

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

核心功能：

Runner: ADK 运行器，管理代理的执行
服务组件:
- ArtifactService: 管理生成的工件
- SessionService: 管理会话状态
- MemoryService: 管理对话记忆

系统架构流程图

详细执行流程

1. 初始化阶段

2. 请求处理阶段

高级配置

自定义端口

# 在指定端口启动代理
uv run . --port=8080

自定义主机

# 在指定主机和端口启动
uv run . --host=0.0.0.0 --port=8080

环境变量配置

在 .env 文件中可以配置更多选项：

GOOGLE_API_KEY=your_api_key_here
# 可以添加其他配置项
LOG_LEVEL=INFO

故障排除

常见问题

API 密钥错误

错误: Invalid API key
解决: 检查 .env 文件中的 GOOGLE_API_KEY 是否正确

端口占用

错误: Port 10001 is already in use
解决: 使用 --port 参数指定其他端口

依赖安装失败

错误: Failed to install dependencies
解决: 确保 UV 已正确安装，尝试 uv sync

扩展和定制

添加新工具

在 content_planner_agent.py 中添加新工具：

from google.adk.tools import google_search, web_searchroot_agent = Agent(# ... 其他配置tools=[google_search, web_search],  # 添加更多工具
)

修改模型

root_agent = Agent(name="content_planner_agent",model="gemini-1.5-pro",  # 使用不同的模型# ... 其他配置
)

自定义指令

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