内容
ADK A2A Notion-ElevenLabs 集成
本项目演示了使用谷歌的 Agent Development Kit（）构建的多智能体系统，该系统集成了 Notion 进行，并使用 ElevenLabs 进行文本转语音转换。
该系统演示了一种耦的 Agent-to-Agent（A2A）架构。
请随附的 [YouTube 速成课程视频](https://www.youtube.com/watch?v=s6-Ofu-uu2k)。
注意**：此存储库包含用于跟随教程系列的起始代码。有关完整的实现，请查看 `lesson-complete` 分支。
## 🔨 构建者套件
对于希望深入 ADK 开发的人员，我创建了一个可选的构建者套件，其中包括：
- 主代理和工作代理的完整源代码
- ADK 开发和 A2A 模式的备忘单
- .cursor/rules 用于一致的提示工程
- 全面的 pytest 测试套件
- 完整的课程计划
您可以在 [chongdashu.gumroad.com/l/adk-builder-pack-1](https://chongdashu.gumroad.com/l/adk-builder-pack-1) 获取构建者套件。
## ☕ 支持该项目
如果您觉得本教程系列和代码库对您的 AI 智能体开发之旅有所帮助，请考虑请我喝一杯咖啡！您的支持帮助我创建更多关于 AI 和智能体开发的教育内容。
<a href="https://buymeacoffee.com/aioriented" target="_blank">
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" >
</a>
## 架构
该系统由以下部分组成：
- **ElevenLabsAgent（A2A 服务）**：用于文本转语音转换的工作代理。
- **NotionAgent（A2A 服务）**：用于从 Notion 检索信息的工作代理。
- **HostAgent（A2A 服务）**：协调 Notion 和 ElevenLabs 代理的协调器代理。
- **Streamlit 用户界面**：提供了两个独立的用户界面来演示不同的架构模式：
- **嵌入式运行器 UI**：UI 在同一进程中运行 HostAgent。
- **A2A 客户端 UI**：UI 与 HostAgent 作为单独的解耦服务进行通信。
有关详细的架构分解和设计决策，请参阅 `LESSON.md`。
## 先决条件
- Python 3.13+
- Notion 账户和 API 密钥
- ElevenLabs 账户和 API 密钥
- `uv` 包管理器（推荐）或 pip
## 项目结构
```
adk-a2a-mcp/
├── host_agent/ # 协调器代理
│ ├── agent.py # 代理定义（带有委托任务工具）
│ ├── agent_executor # 处理会话管理（context_id -> session_id）
│ ├── prompt.py # 协调指令
│ ├── remote_connections.py # A2A 客户端逻辑
│ ├── tools.py # 用于 A2A 委托的 ADK 工具
│ ├── test_client.py # 独立测试客户端
│ └── __main__.py # A2A 服务入口点
├── notion_agent/ # 工作代理
│ ├── agent.py
│ ├── agent_executor.py
│ ├── prompt.py
│ ├── test_client.py
│ └── __main__.py
├── elevenlabs_agent/ # 工作代理
│ ├── agent.py
│ ├── agent_executor.py
│ ├── prompt.py
│ ├── test_client.py
│ └── __main__.py
├── ui/ # Streamlit 用户界面
│ ├── app.py # 嵌入式运行器 UI
│ └── a2a_app.py # 解耦 A2A 客户端 UI
├── scripts/
│ └── start_agents.py # 方便的脚本来启动所有代理服务
├── tests/ # Pytest 集成测试
│ ├── test_host_agent.py
│ ├── test_notion_agent.py
│ └── test_elevenlabs_agent.py
├── logs/ # 代理日志存储在此
├── .env.example # 环境变量示例
├── pyproject.toml # 项目配置和依赖项（单一真实来源）
└── README.md # 此文件
```
## 设置
1. 克隆存储库：
```bash
git clone <repository-url>
cd adk-a2a-mcp
```
2. 创建并激活虚拟环境：
```bash
python -m venv .venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
```
3. 从单一真实来源 `pyproject.toml` 安装依赖项：
```bash
uv pip install -e ".[dev]"
```
4. 从示例创建 `.env` 文件并添加您的 API 密钥：
```bash
cp .env.example .env
# 现在编辑 .env 并添加您的密钥
```
`.env` 文件应包含：
```env
NOTION_API_KEY="your_notion_api_key_here"
ELEVENLABS_API_KEY="your_elevenlabs_api_key_here"
ANTHROPIC_API_KEY="your_anthropic_api_key_here" # 部分代理需要
# A2A 服务 URL（默认值）
HOST_AGENT_A2A_URL="http://localhost:8001"
NOTION_AGENT_A2A_URL="http://localhost:8002"
ELEVENLABS_AGENT_A2A_URL="http://localhost:8003"
```
## 运行完整系统
这是运行整个多智能体系统的推荐方式。
1. **启动所有代理服务**：
提供了一个方便的脚本来在后台启动 Host、Notion 和 ElevenLabs 代理。它们的日志将保存到 `logs/` 目录中。
```bash
python scripts/start_agents.py
```
您可以使用 `ps aux | grep _agent` 检查代理的状态。
2. **运行 UI 应用程序**：
选择其中一个 UI 与系统交互。
- **对于解耦的 A2A UI（推荐用于测试完整架构）**：
```bash
streamlit run ui/a2a_app.py --server.port 8080
```
- **对于嵌入式运行器 UI**：
```bash
streamlit run ui/app.py --server.port 8080
```
3. **停止服务**：
您可以使用以下命令停止后台代理进程：
```bash
pkill -f "_agent"
```
## 独立测试代理（独立）
对于开发和调试，单独测试每个代理至关重要。每个代理都有一个 `test_client.py`，可以直接与其 A2A 服务通信。
1. **启动目标代理的服务**。例如，要测试 Notion 代理：
```bash
python -m notion_agent --port 8002
```
2. **在单独的终端中，运行其测试客户端**：
```bash
python notion_agent/test_client.py
```
对其他代理遵循相同的模式：
- `python -m elevenlabs_agent --port 8003` -> `python elevenlabs_agent/test_client.py`
- `python -m host_agent --port 8001` -> `python host_agent/test_client.py`
## 自动集成测试（pytest）
`tests/` 目录包含集成测试，使用 `pytest` 自动化测试过程。每个测试文件（例如 `tests/test_notion_agent.py`）
1. 自动在子进程中启动所需的代理的A 服务。
2. 对正在运行的服务执行相应的 `test_client.py` 中的逻辑。
3. 断言通信成功且代理行为符合预期。
运行所有集成测试：
```bash
pytest -v
```
运行特定代理的测试：
pytest -v tests/test_notion_agent.py
```
## 开发工作流
- **代码格式化**：`black .` && `isort .`
- **类型检查**：`mypy .`
- **测试**：`pytest`
## 许可证
该项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
本软件按“原样”提供，不附带任何形式的保证，明确或暗示。
MCP 市场