销售运营代理 - MCP代码执行模式

在提供给代理更多自主权和灵活性的同时，减少了98%的令牌消耗。

⚠️ 重要提示：保持此仓库为私有

此实现将OAuth凭证存储在./mnt/mcp-creds/中，这些凭证当前已提交到仓库。Agencii平台即将推出适用于MCP服务器的正确OAuth流程。在此之前，请确保您的仓库可见性设置为私有以保护您的凭证。

此实现遵循Anthropic的MCP代码执行模式，其中代理编写代码与MCP服务器交互，而不是直接调用工具。代理通过探索文件系统来发现工具，并仅加载每个任务所需的内容。

为什么采用这种模式？

传统的MCP（直接工具调用）：

• 提前加载所有19个工具定义（约150K令牌）
• 每个中间结果都流经模型上下文
• 示例：复制转录内容消耗32K令牌

代码执行模式：

• 按需从文件系统加载工具（约2K令牌）
• 在执行环境中处理数据
• 同样的任务在使用技能时消耗4K令牌，不使用技能时消耗12K令牌

架构

销售运营代理
├── IPythonInterpreter（代码执行）
├── PersistentShellTool（文件发现）
└── MCP服务器（作为代码API）
    ├── servers/notion/（15个工具）
    │   ├── search.py
    │   ├── fetch.py
    │   └── ...（其他工具）
    └── servers/gdrive/（4个工具）
        ├── search.py
        ├── read_file.py
        ├── read_sheet.py
        └── update_cell.py

快速开始

1. 克隆仓库

git clone <your-repo>
cd code-exec-agent

2. 设置环境

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

3. 配置凭证

添加到.env：

OPENAI_API_KEY=your-openai-key

# Google Drive（必需）
GDRIVE_CREDENTIALS_JSON={"installed":{"client_id":"...","client_secret":"...","redirect_uris":["http://localhost"]}}

# Notion（通过mcp-remote使用OAuth - 自动配置）

获取Google Drive凭证：

1. 创建Google Cloud项目
2. 启用Google Drive API、Google Sheets API、Google Docs API
3. 为“桌面应用”创建OAuth客户端ID
4. 下载JSON并添加到GDRIVE_CREDENTIALS_JSON

4. 认证Google Drive

npx @isaacphi/mcp-gdrive
# 在浏览器中跟随OAuth流程
# 在“设置自动令牌刷新”后按Ctrl+C

5. 测试代理

python agency.py

示例测试任务

任务： 将Google文档中的转录内容添加到Notion页面

将此Google文档中的转录内容 https://docs.google.com/document/d/YOUR_DOC_ID
添加到此Notion页面 https://www.notion.so/YOUR_PAGE_ID

过程：

1. 代理检查./mnt/skills/是否有现有技能
2. 如果未找到，则仅读取所需的工具：
   • servers/gdrive/read_file.py
   • servers/notion/update_page.py
3. 在IPythonInterpreter中编写代码：

from servers.gdrive import read_file
from servers.notion import update_page

# 读取转录内容（保留在执行环境中）
transcript = await read_file(fileId="YOUR_DOC_ID")

# 更新Notion页面
await update_page(data={
    "page_id": "YOUR_PAGE_ID",
    "command": "replace_content",
    "new_str": transcript
})

4. 建议保存为可重用技能
5. 下次使用时：直接使用技能（4K令牌 vs 12K）

使用Cursor将传统MCP代理转换为此模式

按照以下步骤工作流程使用Cursor的AI命令：

第一步：创建代理MVP（如果尚未创建）

创建一个具有2个内置工具的销售运营代理：IPythonInterpreter和PersistentShellTool

为什么选择这些工具：

• IPythonInterpreter - 执行带有顶级await的代码
• PersistentShellTool - 发现文件并读取工具定义

第二步：使用代码执行模式添加MCP服务器

/mcp-code-exec

向销售运营代理添加以下mcp服务器：
https://developers.notion.com/docs/get-started-with-mcp
https://github.com/isaacphi/mcp-gdrive

这会做什么：

• 创建servers/notion/，包含15个工具文件
• 创建servers/gdrive/，包含4个工具文件
• 每个工具都是一个Python文件，包含异步函数
• 自动生成用于连接管理的server.py
• 测试服务器连接

第三步：编写代理指令

/write-instructions @sales_ops.py

主要角色：执行团队的操作任务
商业目标：提高效率
过程：
1. 在./mnt/skills文件夹中发现技能
2. 如果匹配任务，则使用技能
3. 如果没有发现技能，则仅读取必要的工具文件
4. 在IPythonInterpreter中导入和组合工具
5. 建议新增技能

保持这些指令简短。不要添加MCP使用示例或列出所有MCP。代理应自主发现它们。

代理还应通过尽可能少地调用工具并仅读取完成任务所需的工具文件来最小化令牌消耗。

输出：总结 + 技能建议

关键工作流程要点：

• 技能优先方法 - 总是先检查./mnt/skills/
• 逐步披露 - 仅读取您需要的工具
• 自我改进 - 随时间创建可重用技能
• 最小化令牌消耗 - 代理不应读取过多文件

第四步：处理认证

如果您看到认证错误：

我添加了密钥，请重新测试Google Drive工具，确保每个工具都准备好生产

然后进行认证：

npx @isaacphi/mcp-gdrive

第五步：测试和部署

# 本地测试
python agency.py

# 部署到Agency Swarm平台
git push origin main
# 转到platform.agency-swarm.ai
# 从仓库创建新的代理
# 添加环境变量

工作原理

传统的直接MCP（对比代理）

用户：将转录内容添加到Notion

代理 → MCP：gdrive.read_file(docId)
MCP → 代理：[完整的50KB转录内容在上下文中]

代理 → MCP：notion.update_page(pageId, transcript)
      [代理再次重写完整的50KB转录内容]

结果：消耗32,000个令牌

代码执行模式（此实现）

用户：将转录内容添加到Notion

代理 → Shell：ls ./mnt/skills/
代理 → Shell：cat servers/gdrive/read_file.py

代理 → IPython：
    from servers.gdrive import read_file
    from servers.notion import update_page
    transcript = await read_file(fileId="...")
    await update_page(data={...})

结果：首次运行12,00-00个令牌，使用技能后4,000个令牌

逐步披露

而不是一开始就加载所有19个工具：

# 传统：所有工具立即加载
✗ 150K令牌 - 上下文中所有19个工具的完整定义

# 代码执行：按需加载
✓ 2K令牌 - 列出目录查看可用工具
✓ 仅读取当前任务所需的2个文件

技能系统

代理构建自己的可重用函数库：

./mnt/skills/
├── copy_gdrive_to_notion.py
├── export_sheet_to_csv.py
└── search_and_email_results.py

技能跨越聊天会话持久存在。每次完成任务都是创建新技能的机会。

性能比较

测试任务： 将Google文档中的转录内容复制到Notion页面

方法	首次运行	使用技能	减少量
直接MCP	32K令牌	32K令牌	-
代码执行	12K令牌	4K令牌	88%

何时使用此方法

✅ 使用代码执行模式：

• 操作代理（数据同步、报告）
• 研究代理（收集、分析、总结）
• 分析代理（查询、转换、可视化）
• 具有10个以上工具的代理
• 处理大量数据的任务

❌ 使用传统MCP：

• 简单客户支持（3-5个工具）
• 单一用途代理
• 需要即时一致性的任务
• 当基础设施开销不可接受时

代理工作流程

代理对每个任务遵循以下过程：

1. 检查技能
   └─ ls ./mnt/skills/
   └─ 如果找到匹配项 → 执行技能 → 完成

2. 确定所需工具
   └─ 根据任务：Notion？Drive？两者？

3. 仅读取必要工具
   └─ cat servers/notion/fetch.py
   └─ cat servers/gdrive/read_file.py
   └─ 不要读取server.py或其他文件

4. 在代码中组合工具
   └─ 在IPythonInterpreter中编写Python代码
   └─ 直接使用await（启用顶级await）

5. 建议新技能
   └─ 分析工作流程
   └─ 提出可重用函数
   └─ 保存到./mnt/skills/

可用工具

Notion MCP（15个工具）

内容操作：

• search() - 在工作区中进行语义搜索
• fetch() - 获取页面/数据库详情
• create_pages() - 创建新页面
• update_page() - 更新属性/内容
• move_pages() - 移动到新父级
• duplicate_page() - 复制页面

数据库操作：

• create_database() - 使用模式创建
• update_database() - 更新模式

评论：

• create_comment() - 添加评论
• get_comments() - 获取所有评论

工作区：

• get_teams() - 列出团队
• get_users() - 列出用户
• list_agents() - 列出自定义代理
• get_self() - 获取机器人信息
• get_user() - 获取特定用户

Google Drive MCP（4个工具）

Drive：

• search() - 搜索文件
• read_file() - 读取内容

Sheets：

• read_sheet() - 读取电子表格
• update_cell() - 更新单元格值

项目结构

code-exec-agent/
├── sales_ops/                    # 主代理
│   ├── sales_ops.py             # 代理配置
│   ├── instructions.md          # 代理提示（性能的关键）
│   └── tools/                   # 内置工具（空 - 使用框架）
├── servers/                     # 作为代码的MCP服务器
│   ├── notion/
│   │   ├── server.py           # 连接管理
│   │   ├── __init__.py         # 导出所有工具
│   │   ├── search.py           # 单个工具
│   │   └── ... (15个工具)
│   └── gdrive/
│       ├── server.py
│       ├── __init__.py
│       └── ... (4个工具)
├── mnt/
│   ├── skills/                  # 代理创建的可重用函数
│   └── mcp-creds/              # OAuth令牌（自动管理）
├── agency.py                    # 入口点
├── .env                         # 凭证
└── requirements.txt

故障排除

代理读取过多文件

问题： 代理读取server.py、README.md等。

解决方案： 更新instructions.md：

**不要** 读取任何其他工具、README或服务器文件，以避免额外的令牌消耗。
仅读取您为特定任务所需的内容。

OAuth/认证错误

问题： 部署后OAuth/认证不起作用。

解决方案：

1. 确保所有OAuth令牌都保存到./mnt/mcp-creds/
2. 确保在“代理”标签下启用了持久存储

或者

1. 本地触发OAuth流程
2. 提交并部署到Agencii.ai
3. 在另一个聊天中测试

代理不使用技能

问题： 没有启用持久存储，因此技能不会被保存。

解决方案：

1. 在Agencii.ai上打开您的代理
2. 在“代理”标签下启用存储
3. 等待构建完成
4. 告诉您的代理保存技能
5. 在另一个聊天中测试

部署

选项1：本地开发

python agency.py

选项2：Agency Swarm平台

1. 推送到GitHub（私有仓库）
2. 转到https://agencii.ai
3. 从仓库创建新的代理
4. 添加环境变量
5. 部署

平台优势：

• 持久的./mnt/存储（技能保留）
• 自动扩展
• 内置跟踪和分析
• 无需管理基础设施

性能技巧

1. 编写清晰的指令 - 提示对于此模式至关重要
2. 逐步构建技能 - 从简单开始，随着时间改进
3. 使用具体的任务描述 - 帮助代理识别所需工具
4. 审查跟踪记录 - 检查平台仪表板以寻找优化机会
5. 从常见工作流程开始 - 为重复任务建立技能库

生产就绪

✅ 如果满足以下条件则准备就绪：

• 您拥有明确且经过充分测试的指令
• 任务是操作性的（不是简单的问答）
• 您监控并优化提示
• 您使用技能进行重复的工作流程

⚠️ 不推荐用于：

• 简单客户支持（使用直接MCP）
• 关键任务实时操作
• 需要<1秒响应时间的任务

参考资料

• Anthropic：MCP代码执行
• Agency Swarm文档
• Notion MCP服务器
• Google Drive MCP服务器

贡献

这是一个代码执行模式的参考实现。欢迎改进：

1. 更好的提示策略
2. 更高效的技能建议
3. 额外的MCP服务器集成
4. 性能优化

许可

MIT

---

使用Agency Swarm实现Anthropic的代码执行模式