AI创意工作室
> 一个使用A2A协议、Vertex AI agent引擎和Cloud Run的分布式多代理编排系统,演示了与远程专业代理的代理间通信,用于社交媒体活动生成。
🎬 现场演示
观察整个系统的运行情况: 将分布式多代理系统部署到Google Cloud:现场演示
观看分布式多代理系统的运行:1个创意总监协调器通过A2A协议协调5个专业代理,以生成完整的Instagram活动:从市场研究到Notion时间线(通过MCP集成)。
📋 目录
- 概述
- 建筑
- 代理实施
- 快速开始
- 部署
- 测试和可观察性
- 技术栈
- 故障排除
🚀 快速链接
- 完整部署指南 -全面的分步部署说明
- 修订工作流程指南 -基于评论家反馈的自动质量改进
- 批判性测试提示 -修订工作流程的测试场景
- A2A检查员指南 -使用A2A检查员测试单个试剂
- A2A测井指南 -调试和监控A2A交互
概述
AI创意工作室演示 分布式多代理编排 创建完整的社交媒体活动。它展示了A2A协议,其中部署了部署在Vertex AI Agent Engine上的智能编排器(创意总监),该引擎协调了5个在Cloud Run上运行的专业代理,以处理从市场研究到项目规划的所有事务(通过Notion MCP集成)。
主要特点
- 🌐 分布式多代理系统:Vertex AI代理引擎上的编排器在Cloud Run上协调5个远程专业代理
- 🔄 A2A协议:通过HTTPS进行标准化的代理间通信
- 🎯 智能编排:灵活的路由-简单任务调用1个代理,完整活动调用5个代理
- 📊 规划优先:编排者在委派之前创建执行计划
- 🔁 批判性修订工作流程:自动质量改进循环-评论家反馈在最终交付前触发代理修订
- 🧠 智能上下文压缩:延迟摘要可防止令牌限制失败,同时保持质量
- 📝 MCP集成概念:项目经理通过模型上下文协议直接在Notion中创建任务
- 🔍 内置可观察性:通过插件进行全面的日志记录和委派跟踪
- 🔧 代理工具模式:将远程代理包装为可调用的工具,以实现灵活的委派
它的作用
输入:活动简介```text
"Create Instagram campaign for EcoFlow smart water bottle targeting health-conscious millennials"
**输出**:完成活动,包括:
- 市场调研和竞争对手分析
- 5个带有标题和标签的Instagram帖子
- 每条帖子的AI图像生成提示
- 质量审查和反馈
- 项目时间表和交付成果
- 为项目跟踪创建的概念任务(可选)
______________________________________________________________________
## 建筑
### 系统架构```mermaid
graph TB
subgraph "User Interface"
USER[User/Client]
end
subgraph "Orchestration Layer - Vertex AI Agent Engine"
CD[Creative Director
Orchestrator]
end
subgraph "Specialist Agents - Cloud Run"
BS[Brand Strategist
Market Research]
CW[Copywriter
Social Media Copy]
DS[Designer
Visual Concepts]
CR[Critic
Quality Review]
PM[Project Manager
Timeline & Tasks]
end
subgraph "External Tools"
GS[Google Search]
NOTION[Notion API
via MCP]
end
USER -->|Campaign Brief| CD
CD -->|A2A Protocol| BS
CD -->|A2A Protocol| CW
CD -->|A2A Protocol| DS
CD -->|A2A Protocol| CR
CD -->|A2A Protocol| PM
BS -->|Uses| GS
PM -->|Uses| NOTION
CD -->|Complete Campaign| USER
style CD fill:#4285f4,color:#fff
style BS fill:#34a853,color:#fff
style CW fill:#34a853,color:#fff
style DS fill:#34a853,color:#fff
style CR fill:#34a853,color:#fff
style PM fill:#34a853,color:#fff
代理工作流(完成活动)```mermaid
sequenceDiagram
participant User
participant CreativeDirector
participant BrandStrategist
participant Copywriter
participant Designer
participant Critic
participant ProjectManager
User->>CreativeDirector: Campaign Brief
Note over CreativeDirector: PLANNING PHASE
Creates 5-step plan
CreativeDirector->>User: Present Plan:
1. Research
2. Copy
3. Design
4. Review
5. Timeline
Note over CreativeDirector: EXECUTION PHASE
CreativeDirector->>BrandStrategist: Research market & competitors
BrandStrategist->>CreativeDirector: Audience insights, trends
CreativeDirector->>User: ✓ Research complete
CreativeDirector->>Copywriter: Create posts with insights
Copywriter->>CreativeDirector: 5 Instagram posts
CreativeDirector->>User: ✓ Copywriting complete
CreativeDirector->>Designer: Generate image prompts
Designer->>CreativeDirector: Image concepts
CreativeDirector->>User: ✓ Design complete
CreativeDirector->>Critic: Review all creative work
Critic->>CreativeDirector: Quality feedback
CreativeDirector->>User: ✓ Review complete
CreativeDirector->>ProjectManager: Create timeline
ProjectManager->>CreativeDirector: Project plan
CreativeDirector->>User: ✓ Timeline complete
CreativeDirector->>User: Final Campaign
(All 5 sections)
### 部署架构```mermaid
graph TB
subgraph "Google Cloud Platform"
subgraph "Vertex AI Agent Engine"
AE[Creative Director
Orchestrator Agent]
end
subgraph "Cloud Run Services"
CR1[brand-strategist-agent
Port 8000]
CR2[copywriter-agent
Port 8000]
CR3[designer-agent
Port 8000]
CR4[critic-agent
Port 8000]
CR5[project-manager-agent
Port 8000]
end
subgraph "APIs"
GEMINI[Gemini API
2.5 Flash]
end
end
subgraph "Environment Configuration"
ENV[.env file with:
- Agent URLs
- API Keys
- Project ID]
end
ENV -.->|Agent URLs| AE
AE -->|HTTPS + A2A| CR1
AE -->|HTTPS + A2A| CR2
AE -->|HTTPS + A2A| CR3
AE -->|HTTPS + A2A| CR4
AE -->|HTTPS + A2A| CR5
CR1 & CR2 & CR3 & CR4 & CR5 -->|LLM Calls| GEMINI
style AE fill:#4285f4,color:#fff
style CR1 fill:#34a853,color:#fff
style CR2 fill:#34a853,color:#fff
style CR3 fill:#34a853,color:#fff
style CR4 fill:#34a853,color:#fff
style CR5 fill:#34a853,color:#fff
代理通信流程```mermaid
graph LR
subgraph "Creative Director (Orchestrator)"
LLM1[Gemini 2.5 Flash]
AT1[AgentTool: brand_strategist]
AT2[AgentTool: copywriter]
AT3[AgentTool: designer]
AT4[AgentTool: critic]
AT5[AgentTool: project_manager]
end
subgraph "Remote Agents via A2A"
R1[RemoteA2aAgent
brand_strategist]
R2[RemoteA2aAgent
copywriter]
R3[RemoteA2aAgent
designer]
R4[RemoteA2aAgent
critic]
R5[RemoteA2aAgent
project_manager]
end
LLM1 -->|Function Call| AT1
LLM1 -->|Function Call| AT2
LLM1 -->|Function Call| AT3
LLM1 -->|Function Call| AT4
LLM1 -->|Function Call| AT5
AT1 -->|A2A Protocol
HTTPS| R1
AT2 -->|A2A Protocol
HTTPS| R2
AT3 -->|A2A Protocol
HTTPS| R3
AT4 -->|A2A Protocol
HTTPS| R4
AT5 -->|A2A Protocol
HTTPS| R5
style LLM1 fill:#fbbc04,color:#000
style AT1 fill:#4285f4,color:#fff
style AT2 fill:#4285f4,color:#fff
style AT3 fill:#4285f4,color:#fff
style AT4 fill:#4285f4,color:#fff
style AT5 fill:#4285f4,color:#fff
______________________________________________________________________
## 代理实施
### 代理类型
#### 1.创意总监(编曲)
**文件**: `agents/creative_director/agent.py`
**类型**: `Agent` (不是 `LlmAgent`)与 `AgentTool` 包装器
**模式**:代理工具+规划优先
**关键实施**:```python
from google.adk.agents import Agent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
from google.adk.tools.agent_tool import AgentTool
from google.adk.apps import App
from google.adk.apps.app import EventsCompactionConfig
from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
from google.adk.models import Gemini
# Create remote agents
strategist_agent = RemoteA2aAgent(
name="brand_strategist",
description="Brand strategist for market research",
agent_card=f"{STRATEGIST_URL}/.well-known/agent.json"
)
# Wrap as AgentTool
strategist_tool = AgentTool(agent=strategist_agent)
# Create orchestrator agent
agent = Agent(
name="creative_director",
model="gemini-2.5-flash",
tools=[strategist_tool, copywriter_tool, designer_tool, critic_tool, pm_tool],
instruction=PLANNING_FIRST_INSTRUCTION,
generate_content_config=GenerateContentConfig(
max_output_tokens=20000, # Support full 5-agent workflows
temperature=0.2
)
)
# Configure lazy context compaction for scalability
summarizer = LlmEventSummarizer(llm=Gemini(model_id="gemini-2.5-flash"))
compaction_config = EventsCompactionConfig(
summarizer=summarizer,
compaction_interval=3, # Summarize after every 3 agents
overlap_size=1 # Keep most recent agent's full output
)
# Wrap in App with compaction
app = App(
name="creative_director",
root_agent=agent,
events_compaction_config=compaction_config
)
教学模式:
编排器使用 规划先行 指令模式:
- 了解请求复杂性:确定任务是需要1个代理还是需要全部5个代理
- 委派前创建计划:向用户概述完整的序列
- 按顺序执行:呼叫每个代理,等待响应,确认,继续
- 传递上下文:每个代理从以前的代理接收相关输出
上下文压缩策略:
为了防止长工作流中的令牌限制失败,编排器使用 延迟上下文压缩:
- 当:每完成3个代理后(可配置)
- 如何:使用Gemini Flash总结较旧的代理输出
- 质量:保留最新代理的完整输出(overlap_size=1)
对于5代理工作流:
- 代理人1-3(战略家→ 文案撰写人→ 设计师):保留完整上下文
- Agent 3之后:上下文压缩→ 代理人1-2已总结,代理人3已满
- 代理人4-5(评论家→ PM):查看完整的近期背景+总结的早期工作
好处:
- ✅ 防止多代理工作流中的令牌限制失败
- ✅ 保持质量(始终提供完整的最新上下文)
- ✅ 扩展到10多个代理工作流
- ✅ 经济高效(仅在需要时进行总结)
简单请求 → 呼叫1名客服:```text
User: "Just research the market for eco water bottles"
→ Creative Director calls brand_strategist only
**复杂请求** → 致电所有5名客服:```text
User: "Create complete campaign with posts and timeline"
→ Creative Director executes all 5 steps sequentially
部署:顶点AI代理引擎(在运行时通过环境变量处理代理URL)
2.品牌策略师
文件: agents/brand_strategist/agent.py
类型: LlmAgent
工具: google_search
责任:研究市场趋势、竞争对手和目标受众见解
输出格式:```markdown
Audience Insights:
[Key behaviors, preferences, pain points]
Competitive Analysis:
[2-3 competitors - strengths and weaknesses]
Trending Topics:
[3-5 relevant trends]
Key Strategic Insights:
[High-level themes and positioning]
**部署**:使用A2A服务器进行云运行
______________________________________________________________________
#### 3.文案
**文件**: `agents/copywriter/agent.py`
**类型**: `LlmAgent`
**工具**:无(纯法学硕士)
**责任**:创建引人入胜的社交媒体标题并复制
**输入**:从对话历史中获得活动简报+品牌策略师见解
**输出格式**:```markdown
### 1. Caption Title: [Theme]
**Full Caption Text:**
[Caption with emojis]
**Hashtags:**
#tag1 #tag2 #tag3...
**Suggested CTA:**
[Call to action]
部署:使用A2A服务器进行云运行
4.设计师
文件: agents/designer/agent.py
类型: LlmAgent
工具:无(纯法学硕士)
责任:生成AI图像概念和视觉设计提示
输入:从对话历史中接收撰稿人的帖子
输出格式:```markdown
For Caption 1: [Theme]
Concept A: [Visual Theme]
- Prompt: [Detailed Imagen prompt]
- Style: [minimalist, vibrant, cinematic]
- Colors: [Palette]
- Mood: [energetic, calm, inspiring]
**部署**:使用A2A服务器进行云运行
______________________________________________________________________
#### 5.评论家
**文件**: `agents/critic/agent.py`
**类型**: `LlmAgent`
**工具**:无(纯法学硕士)
**责任**:审查创造性工作并提供高质量的反馈
**输入**:从对话历史中接收所有输出(策略、副本、视觉效果)
**输出格式**:```markdown
**Overall Assessment:**
[Quality score and summary]
**Strengths:**
[What works well]
**Areas for Improvement:**
[Specific suggestions]
**Platform Optimization:**
[Instagram-specific recommendations]
部署:使用A2A服务器进行云运行
修订工作流程:当评论家发现问题时(状态:NEEDS_REVISION),编排者会自动调用相关代理(文案或设计师),并附上评论家的反馈,在继续提交给项目经理之前对作品进行修改。看 docs/REVISION_WORKFLOW.md 了解详情。
6.项目经理
文件: agents/project_manager/agent.py
类型: Agent (使用 Agent 使用MCP工具上课)
工具:概念MCP(模型上下文协议)通过 @notionhq/notion-mcp-server
责任:使用Notion集成创建项目时间表、任务和可交付成果
MCP集成:
- 通过MCP服务器连接到Notion API:
@notionhq/notion-mcp-server - 用途
McpToolset和StdioConnectionParams将MCP服务器作为子进程生成 - 在两个独立的Notion数据库中创建项目和任务页面
MCP在这里是如何工作的:
代理连接到 @notionhq/notion-mcp-server 通过stdio。服务器返回一个工具列表及其描述——LLM读取这些工具并根据任务决定调用哪个。代理中没有硬编码的工具序列。
工具广告由 @notionhq/notion-mcp-server (法学硕士从中挑选):
API-post-page:在数据库(项目或任务)中创建新页面API-patch-page:更新现有页面API-post-search:搜索现有页面API-post-database-query:使用筛选器查询数据库API-retrieve-a-database:获取数据库架构和详细信息
概念数据库结构:
需要两个数据库 --代理在运行时使用以下命令动态发现其模式 API-retrieve-a-database,因此属性名称可以是任何名称。默认模板使用:
- 项目数据库 (ID来自
NOTION_PROJECT_DATABASE_ID环境变量)
- 一个标题属性(活动名称)
- 一个状态属性(例如“进行中”、“已完成”)
- 选择一个属性作为优先级(例如,“高”、“中”、“低”)
- 带有开始和结束的日期属性(例如,活动日期)
- 一个用于摘要的rich_text属性
- 任务数据库 (ID来自
NOTION_TASKS_DATABASE_ID环境变量)
- 一个标题属性(任务描述)
- 一个状态属性(例如,“未开始”、“进行中”、“完成”)
- 优先选择一个属性
- 截止日期的一次性属性
- 一个链接到Projects数据库的关系属性
> 动态模式发现:代理从不硬编码属性名。MCP服务器公开 API-retrieve-a-database 作为一种工具,LLM在写入之前自主调用它来读取精确的属性名和有效值。将属性重命名为任何语言——代理会自动适应。
环境变量:
NOTION_API_KEY:Notion集成令牌(传递为NOTION_TOKEN到MCP服务器)NOTION_PROJECT_DATABASE_ID:的数据库ID 项目 数据库NOTION_TASKS_DATABASE_ID:的数据库ID 任务 数据库
工作流程:
- ADK在启动时将代理连接到MCP服务器——服务器通告其可用工具
- LLM接收任务,并决定调用哪些MCP工具以及调用顺序
- 通常:发现模式→ 创建项目页面→ 创建链接到项目的任务页面
- 无论Notion操作是否成功,都会生成文本时间线
输入:从对话历史记录中接收完整的活动详细信息
输出格式:```markdown
Project Timeline:
[Gantt-style timeline]
Key Milestones:
[Major checkpoints]
Tasks & Deliverables:
[Detailed task list with Notion links]
Team Responsibilities:
[Who does what]
**部署**:与A2A服务器和Notion MCP集成的云运行
______________________________________________________________________
### 代理对代理(A2A)协议
所有专业代理都公开了一个A2A服务器用于远程通信:```python
# agents/[agent_name]/app.py
from google.adk.servers.a2a_server import A2aServer
a2a_server = A2aServer(agent=root_agent)
app = a2a_server.create_app()
if __name__ == "__main__":
a2a_server.run(port=8000)
A2A功能:
- 📡 代理卡:
/.well-known/agent.json-描述代理功能 - 🔄 无状态:每个请求都是独立的
- 🌐 基于HTTP:标准HTTPS通信
- 📝 JSONRPC:结构化消息格式
代理工具模式
编排器使用 代理工具模式 将远程代理包装为可调用工具:
为什么选择AgentTool?
- ✅ 灵活的路由(LLM决定呼叫哪些代理)
- ✅ 可以多次呼叫同一代理(修订版)
- ✅ 在连续调用之间传递上下文
- ✅ 与远程A2A代理配合使用
运作原理:```mermaid
graph LR
A[LLM generates
function call] --> B[AgentTool intercepts]
B --> C[Wraps request in
A2A protocol]
C --> D[Sends HTTPS request
to remote agent]
D --> E[Remote agent
processes]
E --> F[Returns response
via A2A]
F --> G[AgentTool unwraps]
G --> H[Returns to
orchestrator LLM]
______________________________________________________________________
## 快速开始
### 先决条件
- **谷歌云项目** 已启用计费
- **Python 3.11+**
- **Google API密钥** 从 AI工作室
- **gcloud命令行界面** 已安装并配置
- **Node.js和npm** (通过npx用于Notion MCP服务器)
- **通知账户** (可选,用于项目经理集成)
- 在以下位置创建Notion集成 概念开发者
- 创建 **两个数据库** 在Notion中具有以下属性:
**项目数据库:**
- 项目名称(标题)
- 状态(Status)
- 优先级(选择:高、中、低)
- 日期(带开始和结束的日期)
- 摘要(富文本)
**任务数据库:**
- 任务名称(标题)
- 状态(状态:未开始、进行中、完成)
- 优先级(选择:高、中、低)
- 到期日
- 项目(与项目数据库的关系)
- 分享 **两个数据库** 与您的集成
- 复制集成令牌 **项目数据库ID**
- 复制 **任务数据库ID** 并在中更新 `agents/project_manager/agent.py:59`
### 1.克隆和安装```bash
# Clone repository
git clone
cd ai-creative-studio
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
2.配置环境```bash
Copy environment template
cp .env.example .env
编辑 `.env` 使用您的凭据:```bash
# Google Cloud
PROJECT_ID="your-gcp-project-id"
REGION="us-central1"
# Gemini API
GOOGLE_API_KEY="your-gemini-api-key"
# Notion Integration (for Project Manager)
# IMPORTANT: You need TWO databases:
# 1. Projects Database (ID from NOTION_PROJECT_DATABASE_ID)
# 2. Tasks Database (ID from NOTION_TASKS_DATABASE_ID)
NOTION_API_KEY="your-notion-integration-token"
NOTION_PROJECT_DATABASE_ID="your-projects-database-id"
NOTION_TASKS_DATABASE_ID="your-tasks-database-id"
# Agent URLs (will be filled after deployment)
STRATEGIST_AGENT_URL=""
COPYWRITER_AGENT_URL=""
DESIGNER_AGENT_URL=""
CRITIC_AGENT_URL=""
PM_AGENT_URL=""
3.在本地测试单个代理```bash
Test brand strategist
cd agents/brand_strategist
python agent.py
预期产量:```text
🎯 Starting Brand Strategist Agent...
Brief:
Research competitors for eco-friendly water bottles targeting millennials
User > Research competitors for eco-friendly water bottles
brand_strategist > **Audience Insights:**
...
4.部署完整系统```bash
Deploy all agents (specialists + orchestrator) with one command
cd deploy
./deploy_complete_system.sh
这将:
1. 加载环境变量(包括Notion凭据)
1. 将所有5个专业代理部署到Cloud Run(并行)
1. 自动收集代理URL
1. 将创意总监部署到Vertex AI代理引擎
1. 输出资源名称
**或者单独部署专家:**```bash
# Deploy all specialists only
cd deploy
python3 deploy_all_specialists.py
5.替代方案:单独部署编排器```bash
Deploy orchestrator only (after specialists are deployed)
python3 deploy_orchestrator.py --action deploy
这将:
1. 使用已部署的专业代理(如果使用了--auto-deploy experts标志,则部署它们)
1. 从环境变量中读取代理URL
1. 将创意总监部署到Vertex AI代理引擎
1. 输出资源名称
**复制资源名称** 并添加到 `.env`:```bash
AGENT_ENGINE_RESOURCE_NAME="projects/123456789/locations/us-central1/reasoningEngines/987654321"
6.测试整个系统```bash
Test orchestrator with deployed agents
cd ..
python test_orchestrator.py
预期产量:```text
================================================================================
Testing Campaign: EcoFlow Water Bottle (B2C)
================================================================================
creative_director > I'll coordinate our team to create your complete social media
campaign. Here's my plan:
1. Brand Strategist will research the market
2. Copywriter will create 5 Instagram posts
3. Designer will generate image concepts
4. Critic will review quality
5. Project Manager will create timeline
Let's begin with the market research!
[... full campaign output ...]
Total Events: 11+
✓ Success!
部署
完整的系统部署(推荐)
只需一个命令即可部署所有内容:```bash
cd deploy
./deploy_complete_system.sh
此脚本:
1. ✅ 将所有5个专业代理部署到Cloud Run(并行)
1. ✅ 自动收集代理URL
1. ✅ 使用URL将创意总监部署到代理引擎
1. ✅ 输出完整配置
**时间:** 约10-15分钟完成部署
______________________________________________________________________
### 替代部署选项
#### 选项1:带自动部署的Python脚本```bash
cd deploy
python3 deploy_orchestrator.py --action deploy --auto-deploy-specialists
与上面的shell脚本相同,但为您提供了更多的控制和详细的输出。
选项2:手动部署
如果您更喜欢手动控制每一步:```bash
Step 1: Deploy all specialist agents (with public agent cards)
cd deploy
python3 deploy_all_specialists.py
Step 2: Deploy orchestrator with collected URLs
python3 deploy_orchestrator.py --action deploy
### 部署架构详细信息
**专业代理** → 云运行:
- 使用A2A服务器进行集装箱化
- 自动缩放(0-100个实例)
- 公共HTTPS端点(--允许代理卡未经身份验证)
- 使用默认的计算引擎服务帐户
- 环境变量:
- `GOOGLE_GENAI_USE_VERTEXAI=true`
- `GOOGLE_CLOUD_PROJECT` 和 `GOOGLE_CLOUD_LOCATION`
- `NOTION_API_KEY` (仅限项目经理-用于Notion MCP集成)
- `NOTION_PROJECT_DATABASE_ID` (仅限项目经理-项目数据库ID)
**创意总监** → 顶点AI代理引擎:
- 托管代理运行时
- 环境:所有5个代理URL+API密钥
- 无需集装箱化
- 与Vertex AI集成
### 环境变量设置
部署脚本会自动配置:```bash
# For Creative Director (Agent Engine)
GOOGLE_API_KEY="..."
STRATEGIST_AGENT_URL="https://brand-strategist-agent-...-uc.a.run.app"
COPYWRITER_AGENT_URL="https://copywriter-agent-...-uc.a.run.app"
DESIGNER_AGENT_URL="https://designer-agent-...-uc.a.run.app"
CRITIC_AGENT_URL="https://critic-agent-...-uc.a.run.app"
PM_AGENT_URL="https://project-manager-agent-...-uc.a.run.app"
⚠️ 重要:读取代理URL 运行时 使用 os.getenv(),不是在构建时!
测试和可观察性
A2A协议记录
该系统包括所有Agent到Agent(A2A)交互的全面日志记录:
特性:
- 🔍 自动记录:所有A2A呼叫都记录到云日志
- 📊 协议细节:代理名称、时间戳、查询/响应大小
- 🎯 错误检测:自动标记失败的代理呼叫
- 📈 性能跟踪:响应时间和工作流程分析
查看日志:```bash
Fetch recent A2A logs
cd deploy
./fetch_orchestrator_logs.sh 1h
Analyze logs
python3 analyze_agent_logs.py /tmp/orchestrator_logs_*.txt
Monitor live
gcloud logging tail \
'resource.type="aiplatform.googleapis.com/ReasoningEngine"' \
--project=YOUR_PROJECT_ID
**📖 完整指南:** A2A_LOGGING_GUIDE.md
- 如何访问A2A日志
- 日志分析和指标
- 调试A2A问题
- 性能监控
**日志输出示例**:```text
======================================================================
🔧 A2A AGENT CALL: brand_strategist
Timestamp: 2025-12-18T22:45:12.123456
Protocol: Agent-to-Agent (A2A)
Query length: 450 chars
======================================================================
======================================================================
📥 A2A AGENT RESPONSE: brand_strategist - ✅ SUCCESS
Timestamp: 2025-12-18T22:45:19.654321
Response length: 2340 chars
======================================================================
A2A检验员测试
测试单个试剂 使用A2A检查器工具(本地和云端运行):```bash
Setup inspector (one-time)
cd deploy
./setup_inspector.sh
Start inspector
cd ~/a2a-inspector
bash scripts/run.sh
Open http://localhost:5001
Connect to local agent: http://localhost:8080
Or Cloud Run agent with auth token
**📖 请参阅完整指南:** A2A_INSPECTOR_GUIDE.md
- 如何在本地测试代理
- 如何测试Cloud Run部署
- 常见问题排查
______________________________________________________________________
### 使用插件进行本地测试
为了实现深度调试和可观察性:```bash
python test_orchestrator_local_with_plugins.py
特性:
-
🔍 登录插件:全面的ADK日志记录
-
LLM请求和响应
- 工具调用和结果
- 令牌使用
-
事件时间表
-
📊 AgentDelegationTracker插件:自定义委派跟踪
-
叫了哪些特工
- 通话顺序
- 工作流完成诊断
- 摘要报告
输出:```text
🔍 AGENT DELEGATION TRACKER - SUMMARY
📊 AGENT CALLS:
• creative_director: 1 call(s)
• brand_strategist: 1 call(s)
• copywriter: 1 call(s)
• designer: 1 call(s)
• critic: 1 call(s)
• project_manager: 1 call(s)
🎯 EXPECTED SPECIALIST AGENTS:
• brand_strategist: ✅ CALLED
• copywriter: ✅ CALLED
• designer: ✅ CALLED
• critic: ✅ CALLED
• project_manager: ✅ CALLED
🩺 DIAGNOSIS:
✅ SUCCESS: All specialist agents were called!
### 测试远程部署```bash
# Test deployed orchestrator
python test_orchestrator.py
使用 adk web 用于交互式测试```bash
Test orchestrator locally with web UI
cd agents/creative_director
adk web --log_level DEBUG
然后打开 `http://localhost:8000` 通过web界面与代理进行交互。
______________________________________________________________________
## 技术栈
### 核心技术
- **谷歌ADK**:用于构建分布式代理的代理开发工具包
- **双子座2.5闪光灯**:快速、高效的多模式LLM
- **A2A协议**:代理间通信标准
- **顶点AI代理引擎**:编排器的托管代理运行时
- **云运行**:面向专业代理的无服务器容器平台
- **模型上下文协议(MCP)**:工具集成的标准协议
- **API通知**:任务管理和数据库集成
### 关键模式
- **分布式多代理体系结构**:协调器和专业代理分别部署,通过A2A进行通信
- **代理工具模式**:将远程代理包装为灵活编排的工具
- **规划优先**:编排者在执行前创建计划
- **顺序执行**:代理按照上下文传递的顺序执行
- **惰性上下文压缩**:智能摘要在保持质量的同时防止令牌限制
- **MCP集成**:通过模型上下文协议(Notion)进行外部工具集成
- **基于插件的可观察性**:通过ADK插件记录和跟踪
### 项目结构```text
ai-creative-studio/
├── agents/
│ ├── creative_director/ # Orchestrator
│ │ ├── agent.py # Agent definition with AgentTool pattern
│ │ └── app.py # Not used (deployed to Agent Engine)
│ ├── brand_strategist/ # Market research agent
│ │ ├── agent.py # Agent definition
│ │ ├── app.py # A2A server
│ │ └── Dockerfile # Cloud Run deployment
│ ├── copywriter/ # Social media copy agent
│ ├── designer/ # Visual design agent
│ ├── critic/ # Quality review agent
│ ├── project_manager/ # Timeline & planning agent (with Notion MCP)
│ └── common/
│ ├── setup.sh # Local development setup
│ └── test_local.sh # Local A2A testing
├── deploy/
│ ├── deploy_all_specialists.py # Deploy all specialists to Cloud Run
│ ├── deploy_complete_system.sh # One-command full deploy
│ ├── deploy_orchestrator.py # Deploy orchestrator to Agent Engine
│ ├── env_utils.py # Environment variable utilities
│ ├── teardown_gcp.sh # Clean up resources
│ ├── test_agents.sh # Test agents
│ └── test_deployed_agents.py # Comprehensive tests
├── tools/
│ └── a2a-inspector/ # A2A debugging and testing tools
│ ├── setup_inspector.sh # Setup A2A Inspector
│ ├── A2A_INSPECTOR_GUIDE.md # Inspector usage guide
│ ├── A2A_LOGGING_GUIDE.md # Logging guide
│ └── README.md
├── requirements.txt
├── .env.example
├── DEPLOYMENT_GUIDE.md
└── README.md
故障排除
常见问题
1.编排器在2-3个代理后停止(令牌限制)
症状:编排者在呼叫设计器(代理3)后停止,未完成评论家和项目经理
根本原因:编排器在完成所有5个代理之前达到令牌输出限制(默认8192)。每个代理产生1000-3000个令牌输出,编排器呈现完整结果。
解决方案:编排器现在使用 延迟上下文压缩 (实施于 agents/creative_director/agent.py):```python
Increased token limit
max_output_tokens=20000 # From 8192
Lazy context compaction (summarizes after 3 agents)
compaction_config = EventsCompactionConfig(
compaction_interval=3, # Summarize after every 3 agents
overlap_size=1, # Keep most recent agent's full output
summarizer=LlmEventSummarizer(llm=Gemini(model_id="gemini-2.5-flash"))
)
**运作原理**:
- 代理1-3:保留完整上下文
- 在Agent 3:对较老的Agent(1-2)进行总结后,Agent 3保持完整
- 代理人4-5:接收完整的最新背景+总结的早期工作
**验证修复**:```bash
python deploy/test_deployed_agents.py --test orchestrator
# Should see all 5 agents complete: strategist → copywriter → designer → critic → project_manager
2.编排器只调用一个代理
症状:编排器仅在调用brand_strategist后停止
解决方案:确保您使用的是最新版本 agent.py 与:
- ✅
Agent(不是LlmAgent)与AgentTool包装器 - ✅ 规划第一指令模式
- ✅ 逐步确认模式
3.找不到代理URL
症状: RemoteA2aAgent 失败,显示“无法解析代理卡”
解决方案:```bash
Verify URLs are set
echo $STRATEGIST_AGENT_URL
Test URL directly
curl https://your-agent-url/.well-known/agent.json
Redeploy with correct URLs
cd deploy
python3 deploy_orchestrator.py --action deploy
#### 4.超过API配额(429错误)
**症状**:“您已超出当前配额”错误
**解决方案**:
- 使用顶点AI部署(无配额限制)
- 升级至付费Gemini API层
- 添加具有指数回退的重试逻辑(已在代码中)
#### 5.云运行代理不可访问
**症状**:“连接被拒绝”或“服务不可用”
**解决方案**:```bash
# Check Cloud Run service
gcloud run services describe brand-strategist-agent --region us-central1
# Verify agent card is accessible
curl https://brand-strategist-agent-xxxxx-uc.a.run.app/.well-known/agent.json
# Check logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=brand-strategist-agent" --limit 50
6.导入错误
症状: ModuleNotFoundError: No module named 'google.adk'
解决方案:```bash
Reinstall dependencies
pip install -r requirements.txt
Verify ADK installation
python -c "import google.adk; print(google.adk.version)"
### 获取帮助
- **文档**:参见 部署\_ GIDE.md 详细设置
- **A2A调试**:参见 A2A检查员指南 用于调试代理
- **日志记录**:参见 A2A测井指南 用于日志分析
- **建筑**:请参阅本README中的架构图
### 调试模式
启用DEBUG日志记录以获取详细输出:```bash
# Local testing with DEBUG logs
python test_orchestrator_local_with_plugins.py
# View detailed logs
cat orchestrator_test.log
高级用法
自定义插件
创建可观察性的自定义插件:```python
from google.adk.plugins.base_plugin import BasePlugin
class CustomMetricsPlugin(BasePlugin):
async def before_agent_callback(self, *, agent, callback_context):
Your custom logic
print(f"Agent {agent.name} starting...")
### 添加新代理
1. 创建代理目录: `agents/new_agent/`
1. 实施 `agent.py` 和 `LlmAgent`
1. 创建 `app.py` 使用A2A服务器
1. 添加Dockerfile
1. 更新编排器的工具
1. 部署到云端运行
1. 将URL添加到编排器环境
### MCP集成
项目经理代理通过模型上下文协议(MCP)与Notion集成:```python
# agents/project_manager/agent.py
from google.adk.tools.mcp_tool import McpToolset, StdioConnectionParams
from mcp import StdioServerParameters
# Configure Notion MCP server
# IMPORTANT: Notion MCP server expects NOTION_TOKEN, not NOTION_API_KEY
mcp_env = {
"NOTION_TOKEN": os.getenv("NOTION_API_KEY"), # Pass as NOTION_TOKEN
"PATH": os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin")
}
server_params = StdioServerParameters(
command="notion-mcp-server", # Use globally installed version from Dockerfile
args=[],
env=mcp_env
)
# Create MCP toolset
notion_toolset = McpToolset(
connection_params=StdioConnectionParams(
server_params=server_params,
timeout=30.0 # Timeout for MCP server startup
)
)
# Add to agent
agent = Agent(
name="project_manager",
model="gemini-2.5-flash",
tools=[notion_toolset],
instruction=get_system_instruction(database_id=os.getenv("NOTION_PROJECT_DATABASE_ID"))
)
MCP服务器:使用官方 @notionhq/notion-mcp-server 软件包版本 1.9.1
> 重要:Dockerfile将MCP服务器固定到1.9.1版本,以避免2.0.0版本中的UUID重新格式化错误。代理使用全局安装的版本,而不是通过npx下载最新版本。
Dockerfile配置:```dockerfile
Install Notion MCP server globally (pinned to 1.9.1)
RUN npm install -g @notionhq/notion-mcp-server@1.9.1
**需要环境变量**:
- `NOTION_API_KEY`:您的Notion集成令牌(传递为 `NOTION_TOKEN` 到MCP服务器)
- `NOTION_PROJECT_DATABASE_ID`:The **项目** 数据库ID
- **任务数据库ID**:硬编码 `agent.py:59` (默认值: `2ceb1b31123181508894ddb3c597dc48`)
**可用MCP操作**:
- `API-post-page`:在Notion数据库中创建项目/任务页面
- `API-patch-page`:更新现有页面属性
- `API-post-search`:搜索页面
- `API-post-database-query`:使用筛选器查询数据库
- `API-retrieve-a-database`:获取数据库架构和详细信息
**测试集成**:```bash
cd agents/project_manager
python test_local_notion.py
许可证
MIT许可证-有关详细信息,请参阅许可证文件
致谢
内置:
- 谷歌代理开发工具包(ADK)
- 代理对代理协议
- Google Gemini API
问题? 检查 QUICK_START.md 或者查看上面的架构图。
