基于A2A和ADK的內容規劃代理

項目概述

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."),
)