开源 PTC 代理

English | 中文

快速入门 | CLI 参考 | 配置 | 更新日志 | 路线图

演示：使用 DeepSeek V3.2 分析 NVDA、AMD 和 SPY 股票的两年数据（超过 15,000 行原始 JSON）

什么是程序化工具调用？

本项目是 Anthropic 最近推出的 程序化工具调用 (PTC) 的开源实现，它使智能体能够通过代码执行来调用工具，而不是逐个发出 JSON 工具调用。这一范式也在他们早期的技术博客 使用 MCP 进行代码执行 中有所体现。

为什么选择 PTC？

1. 大型语言模型在编写代码方面表现出色！它们擅长理解上下文、推理数据流并生成精确的逻辑。PTC 让它们发挥所长——编写协调整个工作流程的代码，而不是一次只处理一个工具调用。

2. 传统的工具调用会将完整的结果返回到模型的上下文窗口中。假设要获取 10 个股票代码一年的日线价格数据，这意味着超过 2,500 个 OHLCV 数据点会污染上下文——仅仅为了计算一个投资组合摘要就需要消耗数万 tokens。而使用 PTC 时，代码会在沙盒环境中运行，在本地处理数据，只有最终输出才会返回给模型。结果是 token 消耗减少了 85% 到 98%。

3. PTC 在处理大量结构化数据、时间序列数据（如金融市场数据）以及需要进一步数据处理——过滤、聚合、转换或可视化后再返回给模型的场景中尤为出色。

工作原理

用户任务
    |
    v
+-------------------+
|    PTCAgent       |  工具发现 -> 编写 Python 代码
+-------------------+
    |       ^
    v       |
+-------------------+
|  Daytona Sandbox  |  执行代码
|  +-------------+  |
|  | MCP Tools   |  |  tool() -> 处理 / 过滤 / 聚合 -> 输出到 data/ 目录
|  | (Python)    |  |
|  +-------------+  |
+-------------------+
    |
    v
+-------------------+
|最终交付物       |  文件和数据可以从沙盒下载
+-------------------+

基于 LangChain DeepAgents 构建——该项目使用了 DeepAgents 的许多组件，并且 CLI 功能是从 deepagent-cli 启动的。特别感谢 LangChain 团队！

沙盒环境由 Daytona 提供。

新特性

• 交互式 CLI - 新增 ptc-agent 命令，支持基于终端的交互，具有会话持久化、计划模式、主题和丰富的 UI 界面
• 后台子代理执行 - 子代理以异步方式运行，并分配任务 ID（Task-1、Task-2 等）。主代理在子代理并行执行的同时继续工作。完成的结果会被缓存，代理会收到通知并通过 task_output() 获取结果
• 任务监控 - wait() 会阻塞直到任务完成；task_output() 可以获取结果或显示进度
• 代理技能 - 通过开放的 Agent Skills 标准扩展能力
• 视觉/多模态支持 - 新增 view_image 工具，使具备视觉能力的大模型能够分析来自 URL、base64 数据或沙盒文件中的图像

特性

• 通用 MCP 支持 - 自动将任何 MCP 服务器工具转换为 Python 函数
• 渐进式工具发现 - 按需发现工具，避免一次性加载大量工具定义带来的高 token 消耗
• 自定义 MCP 上传 - 可直接将 Python 实现的 MCP 部署到沙盒会话中
• 代理技能 - 用于自定义工作流程的技能
• 增强的文件工具 - 优化了 glob、grep 等文件操作工具，专为沙盒环境设计
• Daytona 后端 - 安全的代码执行，具备文件系统隔离和快照支持
• 自动图片上传 - 图表和图片会自动上传到云存储（Cloudflare R2、AWS S3、阿里云 OSS）
• 兼容 LangGraph - 可与 LangGraph Cloud/Studio 部署兼容
• 多 LLM 支持 - 可与 Anthropic、OpenAI 以及您在 llms.json 中配置的任何 LLM 提供商一起使用

项目结构

├── libs/
│   ├── ptc-agent/             # 核心代理库
│   │   └── ptc_agent/
│   │       ├── core/          # 沙盒、MCP 注册表、工具生成器、会话
│   │       ├── config/        # 配置类和加载器
│   │       ├── agent/         # PTCAgent、工具、提示词、中间件、子代理
│   │       └── utils/         # 云存储上传工具
│   │
│   └── ptc-cli/               # 交互式 CLI 应用程序
│       └── ptc_cli/
│           ├── core/          # 状态、配置、主题设置
│           ├── commands/      # 斜杠命令、Bash 执行
│           ├── display/       # 丰富的终端渲染
│           ├── input/         # 提示词、补全功能、文件引用
│           └── streaming/     # 工具审批、执行
│
├── skills/                    # 演示技能（来自 Anthropic）
│   ├── pdf/                   # PDF 处理
│   ├── xlsx/                  # 电子表格操作
│   ├── docx/                  # 文档创建
│   ├── pptx/                  # 演示文稿制作
│   └── creating-financial-models/  # 金融建模
│
├── mcp_servers/               # 演示 MCP 服务器实现
│   ├── yfinance_mcp_server.py
│   └── tickertick_mcp_server.py
│
├── example/                   # 演示笔记本和脚本
│   ├── PTC_Agent.ipynb
│   ├── Subagent_demo.ipynb
│   └── quickstart.py
│
├── config.yaml                # 主配置文件
└── llms.json                  # LLM 提供商定义

原生工具

该代理拥有原生工具以及来自 deep-agent 的中间件功能：

核心工具

工具	描述	关键参数
execute_code	在具备 MCP 工具访问权限的情况下执行 Python 代码	code
Bash	运行 Shell 命令	command, timeout, working_dir
Read	按行读取文件并附带行号	file_path, offset, limit
Write	写入或覆盖文件	file_path, content
Edit	精确替换字符串	file_path, old_string, new_string
Glob	文件模式匹配	pattern, path
Grep	内容搜索（ripgrep）	pattern, path, output_mode

中间件

中间件	描述	提供的工具
SubagentsMiddleware	将专业任务委托给具有隔离执行环境的子代理	task()
BackgroundSubagentMiddleware	异步执行子代理任务，并通过通知收集结果	wait(), task_output()
ViewImageMiddleware	将图像注入对话中，以支持多模态大模型	view_image()
FilesystemMiddleware	文件系统操作	read_file, write_file, edit_file, glob, grep, ls
TodoListMiddleware	任务规划与进度跟踪（自动启用）	write_todos
SummarizationMiddleware	自动总结对话历史（自动启用）	-

可用子代理（默认）：

• research - 使用 Tavily 进行网络搜索，并结合 think 工具进行战略思考
• general-purpose - 提供完整的 execute_code、文件系统和视觉工具，适用于复杂的多步骤任务

后台执行模型： 当代理调用 task() 时，子代理会被分配顺序编号（Task-1、Task-2 等），并在后台运行。主代理会：

1. 立即收到包含任务 ID 的确认信息
2. 继续执行其他工作，同时子代理并行运行
3. 在任务完成后收到通知
4. 调用 task_output() 获取缓存的结果
5. 如有需要，可使用 wait(task_number=N) 阻塞等待特定任务完成

MCP 集成

演示 MCP 服务器

演示中包含了 3 个在 config.yaml 中配置好的 MCP 服务器：

服务器	传输方式	工具数量	用途
tavily	stdio (npx)	4	网络搜索
yfinance	stdio (python)	21	股票价格、财务数据
tickertick	stdio (python)	7	财经新闻

MCP 工具的呈现方式

在提示词中 - 工具摘要会被注入到系统提示词中：

tavily: 用于查找最新信息的网络搜索引擎
  - 模块：tools/tavily.py
  - 可用工具：4 个
  - 导入语句：from tools.tavily import <tool_name>

在沙盒中 - 会生成完整的 Python 模块：

/home/daytona/
├── tools/
│   ├── mcp_client.py      # MCP 通信层
│   ├── tavily.py          # from tools.tavily import search
│   ├── yfinance.py        # from tools.yfinance import get_stock_history
│   └── docs/              # 自动生成的文档
│       ├── tavily/*.md
│       └── yfinance/*.md
├── results/               # 代理输出
└── data/                  # 输入数据

在代码中 - 代理可以直接导入并使用工具：

from tools.yfinance import get_stock_history
import pandas as pd

# 获取数据 - 数据保留在沙盒内
history = get_stock_history(ticker="AAPL", period="1y")

# 在本地处理 - 不浪费任何 token
df = pd.DataFrame(history)
summary = {"mean": df["close"].mean(), "volatility": df["close"].std()}

# 只将摘要返回给模型
print(summary)

技能

Agent Skills 是 Anthropic 推出的一项开放标准，用于将领域专业知识打包成可重用的指令和资源文件夹。技能通过渐进式披露动态加载——启动时仅加载元数据，内容则按需加载。

包含的演示技能

为演示目的，包含了来自 anthropics/skills 的以下技能：

技能	描述
pdf	PDF 文档操作 - 提取文本/表格、创建、合并/拆分、填写表单
xlsx	使用公式、格式化及数据分析创建电子表格
docx	创建、编辑和格式化文档
pptx	创建、编辑和分析演示文稿
creating-financial-models	DCF 分析、敏感性测试、蒙特卡洛模拟

配置

技能默认启用，加载路径如下：

1. 用户目录：~/.ptc-agent/skills/
2. 项目目录：.ptc-agent/skills/（或旧版中的 skills/）

当名称冲突时，项目技能会覆盖用户技能。

# config.yaml
skills:
  enabled: true
  user_skills_dir: "~/.ptc-agent/skills"
  project_skills_dir: ".ptc-agent/skills"

创建自定义技能

每个技能是一个包含 SKILL.md 文件的文件夹，其中包含 YAML 前言和说明：

---
name: my-skill
description: "清晰描述该技能的作用及适用场景"
---

# 我的技能

Claude 在此技能激活时遵循的指令、工作流程和示例。

## 指导原则
- 指导原则 1
- 指导原则 2

此外，还可以将其他文件（如 reference.md、脚本等）与 SKILL.md 一同打包，并根据需要引用。技能会被上传至沙盒中的 /home/daytona/skills/<skill-name>/ 目录。

有关详细指南，请参阅 Anthropic 的技能创作最佳实践。

开始使用

先决条件

• Python 3.12+
• Node.js（用于 MCP 服务器）
• uv 包管理器

安装

git clone https://github.com/Chen-zexi/open-ptc-agent.git
cd open-ptc-agent
uv sync
source .venv/bin/activate  # Windows 系统：.venv\Scripts\activate

最小配置

创建一个 .env 文件，包含最低要求的密钥：

# 选择一个 LLM 提供商
ANTHROPIC_API_KEY=your-key
# 或
OPENAI_API_KEY=your-key
# 或
# 任何您已在 llms.json 和 config.yaml 中配置的模型
# 您也可以在此处使用 Minimax 和 GLM 的编程计划！

# Daytona（必需）
DAYTONA_API_KEY=your-key

请从 Daytona 控制台获取您的 Daytona API 密钥。他们为新用户提供了免费额度！

扩展配置

若需完整功能，可添加以下可选密钥：

# MCP 服务器
TAVILY_API_KEY=your-key          # 网络搜索
ALPHA_VANTAGE_API_KEY=your-key   # 财务数据

# 云存储（选择一个提供商）
R2_ACCESS_KEY_ID=...             # Cloudflare R2
AWS_ACCESS_KEY_ID=...            # AWS S3
OSS_ACCESS_KEY_ID=...            # Alibaba OSS

# 跟踪（可选）
LANGSMITH_API_KEY=your-key

完整环境变量选项列表请参阅 .env.example。

运行 CLI

启动交互式 CLI：

ptc-agent

有关所有命令和选项，请参阅 ptc-cli 文档。

如需以编程方式使用 PTC Agent，请参阅 ptc-agent 文档。

演示笔记本

以下是 Jupyter 笔记本示例：

• PTC_Agent.ipynb - 使用 open-ptc-agent 的快速演示
• Subagent_demo.ipynb - 后台子代理执行
• quickstart.py - Python 脚本快速入门

您还可以选择使用 LangGraph API 部署该代理。

配置

该项目使用两个配置文件：

• config.yaml - 主配置文件（LLM 选择、MCP 服务器、Daytona、安全性和存储）
• llms.json - LLM 提供商定义

快速配置

在 config.yaml 中选择您的 LLM：

llm:
  name: "claude-sonnet-4-5"  # 可选：claude-sonnet-4-5、gpt-5.1-codex-mini、gemini-3-pro

启用或禁用 MCP 服务器：

mcp:
  servers:
    - name: "tavily"
      enabled: true  # 设置为 false 可禁用

有关完整的配置选项，包括 Daytona 设置、安全策略以及添加自定义 LLM 提供商，请参阅 配置指南。

CLI 参考

ptc-agent 命令提供交互式终端界面，具备以下功能：

• 会话持久化和沙箱复用
• 斜杠命令（/help、/files、/view、/download）
• 使用 !command 执行 Bash 命令
• 使用 @path/to/file 引用文件
• 可自定义的主题和颜色方案

快速入门：

ptc-agent                    # 启动交互式会话
ptc-agent --plan-mode        # 启用执行前的计划审批
ptc-agent list               # 列出可用代理

有关完整的 CLI 文档，包括所有选项、命令、键盘快捷键和主题配置，请参阅 CLI 参考。

路线图

计划中的功能和改进：

• PTC 代理的 CLI 版本
• 支持代理技能（agentskills.io 开放标准）
• 自动化测试的 CI/CD 管道
• 更多 MCP 服务器集成 / 更多示例笔记本
• 性能基准测试和优化
• 改进的搜索工具，以更流畅地发现工具

贡献

我们欢迎社区的贡献！以下是一些您可以帮助的方式：

• 代码贡献 - 修复 bug、新增功能、改进（CI/CD 即将推出）
• 用例 - 分享您如何在生产或研究中使用 PTC
• 示例笔记本 - 创建展示不同工作流的演示
• MCP 服务器 - 构建或推荐与 PTC 配合良好的 MCP 服务器（数据处理、API 等）
• 提示技巧 - 分享能够提升代理性能的提示技术

请在 GitHub 上提交问题或拉取请求以参与贡献！

致谢

本项目基于以下研究和工具：

研究/文章

• 在 Claude 开发者平台上引入高级工具使用 - Anthropic
• 使用 MCP 进行代码执行：构建更高效的 AI 代理 - Anthropic
• CodeAct：可执行代码操作可激发更好的 LLM 代理 - Wang 等人

框架和基础设施

• LangChain DeepAgents - 基础代理框架
• Daytona - 沙盒基础设施

星标历史

如果您觉得这个项目有用，请考虑给它一个星标！这有助于让更多人发现这项工作。

许可证

MIT 许可证

Open PTC Agent 快速上手指南

Open PTC Agent 是一个开源项目，实现了 Anthropic 提出的程序化工具调用 (Programmatic Tool Calling, PTC) 范式。它允许 AI 代理通过编写和执行 Python 代码来调用工具和处理数据，而非传统的单步 JSON 工具调用。这种方式能显著减少 Token 消耗（尤其在处理大量数据时），并利用 LLM 强大的代码生成能力来编排复杂工作流。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐 WSL2)
• Python 版本: Python 3.12 或更高版本
  • 注意：该项目强依赖 Python 3.12+ 的新特性。
• 包管理器: pip 或 uv (推荐)
• 网络环境: 需要能够访问 GitHub 以克隆代码，以及访问配置的 LLM 提供商（如 Anthropic, OpenAI 等）。

安装步骤

1. 克隆项目

首先从 GitHub 克隆源代码：

git clone https://github.com/Chen-zexi/open-ptc-agent.git
cd open-ptc-agent

2. 创建虚拟环境

推荐使用 venv 或 uv 创建隔离的 Python 环境：

# 使用 python venv
python3.12 -m venv .venv
source .venv/bin/activate  # Windows 用户请使用: .venv\Scripts\activate

# 或者使用 uv (如果已安装)
# uv venv --python 3.12
# source .venv/bin/activate

3. 安装依赖

安装项目核心库及 CLI 工具依赖：

pip install -e libs/ptc-agent
pip install -e libs/ptc-cli

提示: 如果下载速度较慢，可临时使用国内镜像源： pip install -e libs/ptc-agent -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 配置密钥

项目根目录包含 config.yaml 和 llms.json。您需要配置 LLM API Key 才能运行。

1. 复制示例配置文件（如果需要）：

   cp llms.json.example llms.json  # 如果存在示例文件
   

2. 编辑 llms.json 或直接在环境变量中设置 Key。以最常用的 Anthropic Claude 为例，导出环境变量：

export ANTHROPIC_API_KEY="your-api-key-here"

或者编辑 config.yaml 确保启用了所需的 MCP 服务器（默认配置已包含演示用的 tavily, yfinance, tickertick）。

基本使用

安装完成后，您可以通过交互式命令行界面 (CLI) 或 Python 脚本与 Agent 交互。

方式一：使用交互式 CLI (推荐)

启动终端界面，该界面支持会话持久化、计划模式和丰富的 UI 展示：

ptc-agent

启动后，您可以直接输入自然语言任务。例如，分析股票数据：

分析过去两年 NVDA, AMD 和 SPY 的股票数据，计算它们的波动率并生成对比图表。

CLI 特色功能：

• 后台子代理: 输入任务后，主代理会分配 Task-1, Task-2 给子代理在后台异步执行，主代理可同时处理其他逻辑。
• 任务监控: 使用 wait() 等待任务完成，或使用 task_output() 获取结果。
• 多模态支持: 如果配置了视觉模型，可直接发送图片路径让 Agent 分析。

方式二：使用 Python 脚本

您也可以直接在 Python 代码中实例化 Agent 进行调用。创建一个 test_agent.py：

from ptc_agent.agent import PTCAgent
from ptc_agent.config import load_config

# 加载配置
config = load_config()

# 初始化 Agent
agent = PTCAgent(config=config)

# 定义任务
task = "查询苹果公司 (AAPL) 最近一年的股价历史，计算平均收盘价，并将结果保存到 data/aapl_summary.json"

# 运行任务
response = agent.run(task)

print(response)

运行脚本：

python test_agent.py

核心工作流程说明

1. 工具发现: Agent 根据需求动态加载 MCP 工具（如 yfinance），将其转换为 Python 函数。
2. 代码生成: Agent 编写 Python 代码，在安全的 Daytona Sandbox 环境中执行。
3. 本地处理: 数据获取、清洗、聚合均在沙箱内完成，仅将最终结论或少量关键数据返回给 LLM，极大节省 Token。
4. 结果交付: 生成的文件（如 CSV, 图表图片）会自动上传至配置的对象存储（如 S3, OSS）或保留在沙箱中供下载。

---

更多高级配置（如自定义 Skills、MCP 服务器部署）请参考项目目录下的 docs/CONFIGURATION.md。