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中创建任务
- 🔍 内置可观察性：通过插件进行全面的日志记录和委派跟踪
- 🔧 代理工具模式：将远程代理包装为可调用的工具，以实现灵活的委派
它的作用
输入：活动简介
"Create Instagram campaign for EcoFlow smart water bottle targeting health-conscious millennials"输出：完成活动，包括：
- 市场调研和竞争对手分析
- 5个带有标题和标签的Instagram帖子
- 每条帖子的AI图像生成提示
- 质量审查和反馈
- 项目时间表和交付成果
- 为项目跟踪创建的概念任务（可选）
______________________________________________________________________
建筑
系统架构
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代理工作流（完成活动）
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)部署架构
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代理通信流程
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 包装器
模式：代理工具+规划优先
关键实施:
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名客服：
User: "Just research the market for eco water bottles"
→ Creative Director calls brand_strategist only复杂请求 → 致电所有5名客服：
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
责任：研究市场趋势、竞争对手和目标受众见解
输出格式:
**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
工具：无（纯法学硕士）
责任：创建引人入胜的社交媒体标题并复制
输入：从对话历史中获得活动简报+品牌策略师见解
输出格式:
### 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图像概念和视觉设计提示
输入：从对话历史中接收撰稿人的帖子
输出格式:
**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
工具：无（纯法学硕士）
责任：审查创造性工作并提供高质量的反馈
输入：从对话历史中接收所有输出（策略、副本、视觉效果）
输出格式:
**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操作是否成功，都会生成文本时间线
输入：从对话历史记录中接收完整的活动详细信息
输出格式:
**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服务器用于远程通信：
# 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代理配合使用
运作原理:
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.克隆和安装
# 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.txt2.配置环境
# Copy environment template
cp .env.example .env编辑 .env 使用您的凭据：
# 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.在本地测试单个代理
# Test brand strategist
cd agents/brand_strategist
python agent.py预期产量：
🎯 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.部署完整系统
# Deploy all agents (specialists + orchestrator) with one command
cd deploy
./deploy_complete_system.sh这将：
- 加载环境变量（包括Notion凭据）
- 将所有5个专业代理部署到Cloud Run（并行）
- 自动收集代理URL
- 将创意总监部署到Vertex AI代理引擎
- 输出资源名称
或者单独部署专家：
# Deploy all specialists only
cd deploy
python3 deploy_all_specialists.py5.替代方案：单独部署编排器
# Deploy orchestrator only (after specialists are deployed)
python3 deploy_orchestrator.py --action deploy这将：
- 使用已部署的专业代理（如果使用了--auto-deploy experts标志，则部署它们）
- 从环境变量中读取代理URL
- 将创意总监部署到Vertex AI代理引擎
- 输出资源名称
复制资源名称 并添加到 .env:
AGENT_ENGINE_RESOURCE_NAME="projects/123456789/locations/us-central1/reasoningEngines/987654321"6.测试整个系统
# Test orchestrator with deployed agents
cd ..
python test_orchestrator.py预期产量：
================================================================================
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!______________________________________________________________________
部署
完整的系统部署（推荐）
只需一个命令即可部署所有内容：
cd deploy
./deploy_complete_system.sh此脚本：
- ✅ 将所有5个专业代理部署到Cloud Run（并行）
- ✅ 自动收集代理URL
- ✅ 使用URL将创意总监部署到代理引擎
- ✅ 输出完整配置
时间： 约10-15分钟完成部署
______________________________________________________________________
替代部署选项
选项1：带自动部署的Python脚本
cd deploy
python3 deploy_orchestrator.py --action deploy --auto-deploy-specialists与上面的shell脚本相同，但为您提供了更多的控制和详细的输出。
选项2：手动部署
如果您更喜欢手动控制每一步：
# 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集成
环境变量设置
部署脚本会自动配置：
# 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呼叫都记录到云日志
- 📊 协议细节：代理名称、时间戳、查询/响应大小
- 🎯 错误检测：自动标记失败的代理呼叫
- 📈 性能跟踪：响应时间和工作流程分析
查看日志:
# 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问题
- 性能监控
日志输出示例:
======================================================================
🔧 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检查器工具（本地和云端运行）：
# 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部署
- 常见问题排查
______________________________________________________________________
使用插件进行本地测试
为了实现深度调试和可观察性：
python test_orchestrator_local_with_plugins.py特性:
- 🔍 登录插件：全面的ADK日志记录
- LLM请求和响应 - 工具调用和结果 - 令牌使用 - 事件时间表
- 📊 AgentDelegationTracker插件：自定义委派跟踪
- 叫了哪些特工 - 通话顺序 - 工作流完成诊断 - 摘要报告
输出:
================================================================================
🔍 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!测试远程部署
# Test deployed orchestrator
python test_orchestrator.py使用 adk web 用于交互式测试
# 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插件记录和跟踪
项目结构
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):
# 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：接收完整的最新背景+总结的早期工作
验证修复:
python deploy/test_deployed_agents.py --test orchestrator
# Should see all 5 agents complete: strategist → copywriter → designer → critic → project_manager2.编排器只调用一个代理
症状：编排器仅在调用brand_strategist后停止
解决方案：确保您使用的是最新版本 agent.py 与：
- ✅
Agent（不是LlmAgent)与AgentTool包装器 - ✅ 规划第一指令模式
- ✅ 逐步确认模式
3.找不到代理URL
症状: RemoteA2aAgent 失败，显示“无法解析代理卡”
解决方案:
# 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 deploy4.超过API配额（429错误）
症状：“您已超出当前配额”错误
解决方案:
- 使用顶点AI部署（无配额限制）
- 升级至付费Gemini API层
- 添加具有指数回退的重试逻辑（已在代码中）
5.云运行代理不可访问
症状：“连接被拒绝”或“服务不可用”
解决方案:
# 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 506.导入错误
症状: ModuleNotFoundError: No module named 'google.adk'
解决方案:
# 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日志记录以获取详细输出：
# Local testing with DEBUG logs
python test_orchestrator_local_with_plugins.py
# View detailed logs
cat orchestrator_test.log______________________________________________________________________
高级用法
自定义插件
创建可观察性的自定义插件：
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...")添加新代理
- 创建代理目录：
agents/new_agent/ - 实施
agent.py和LlmAgent - 创建
app.py使用A2A服务器 - 添加Dockerfile
- 更新编排器的工具
- 部署到云端运行
- 将URL添加到编排器环境
MCP集成
项目经理代理通过模型上下文协议（MCP）与Notion集成：
# 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配置:
# 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：获取数据库架构和详细信息
测试集成:
cd agents/project_manager
python test_local_notion.py______________________________________________________________________
许可证
MIT许可证-有关详细信息，请参阅许可证文件
______________________________________________________________________
致谢
内置：
______________________________________________________________________
问题？ 检查 QUICK_START.md 或者查看上面的架构图。