Skip to content
Back to search

open-ptc-agent

An open source implementation of code execution with MCP (Programatic Tool Calling)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chen-zexi--open-ptc-agent/badge.svg)](/listings/chen-zexi--open-ptc-agent)

HTML

<a href="/listings/chen-zexi--open-ptc-agent"><img src="/api/listings/chen-zexi--open-ptc-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.12+ - Node.js (for MCP servers) - [uv](https://docs.astral.sh/uv/) package manager

Installation

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

Minimal Configuration

Create a `.env` file with the minimum required keys:

# One LLM provider (choose one)
ANTHROPIC_API_KEY=your-key
# or
OPENAI_API_KEY=your-key
# or
# Any model you configured in llms.json and config.yaml
# You can also use Coding plans from Minimax and GLM here!

# Daytona (required)
DAYTONA_API_KEY=your-key

Get your Daytona API key from [Daytona Dashboard](https://app.daytona.io/dashboard/keys). They provide free credits for new users!

Extended Configuration

For full functionality, add optional keys:

# MCP Servers
TAVILY_API_KEY=your-key          # Web search
ALPHA_VANTAGE_API_KEY=your-key   # Financial data

# Cloud Storage (choose one provider)
R2_ACCESS_KEY_ID=...             # Cloudflare R2
AWS_ACCESS_KEY_ID=...            # AWS S3
OSS_ACCESS_KEY_ID=...            # Alibaba OSS

# Tracing (optional)
LANGSMITH_API_KEY=your-key

See `.env.example` for the complete list of environment variables options.

Run the CLI

Start the interactive CLI:

ptc-agent

See the **[ptc-cli documentation](libs/ptc-cli/README.md)** for all commands and options.

For programmatic usage of PTC Agent, see the [ptc-agent documentation](libs/ptc-agent/README.md).

Demo Notebooks

For Jupyter notebook examples:

- **[PTC_Agent.ipynb](example/PTC_Agent.ipynb)** - Quick demo with open-ptc-agent - **[Subagent_demo.ipynb](example/Subagent_demo.ipynb)** - Background subagent execution - **[quickstart.py](example/quickstart.py)** - Python script quickstart

Optionally, use the LangGraph API to deploy the agent.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 431 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Open PTC Agent
  2. [English](README.md) | [中文](docs/zh/README.md)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  5. [![LangChain](https://img.shields.io/badge/LangChain-1c3c3c?logo=langchain&logoColor=white)](https://github.com/langchain-ai/langchain)
  6. [![GitHub stars](https://img.shields.io/github/stars/Chen-zexi/open-ptc-agent?style=social)](https://github.com/Chen-zexi/open-ptc-agent/stargazers)
  7. [Getting Started](#getting-started) | [CLI Reference](#cli-reference) | [Configuration](docs/CONFIGURATION.md) | [Changelog](docs/CHANGELOG.md) | [Roadmap](#roadmap)
  8. <video src="https://github.com/user-attachments/assets/cca8c6ee-0c6f-4a97-ad7d-08bad250c006" controls width="800"></video>
  9. *Demo: Analyzing 2 years of NVDA, AMD & SPY stock data (15,000+ lines of raw JSON) using DeepSeek V3.2*
  10. ## What is Programmatic Tool Calling?
  11. This project is an open source implementation of Anthropic recently introduced [Programmatic Tool Calling (PTC)](https://www.anthropic.com/engineering/advanced-tool-use), which enables agents to invoke tools with code execution rather than making individual JSON tool calls. This paradigm is also featured in their earlier engineering blog [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp).
  12. ## Why PTC?
  13. 1. LLMs are exceptionally good at writing code! They excel at understanding context, reasoning about data flows, and generating precise logic. PTC lets them do what they do best - write code that orchestrates entire workflows rather than reasoning through one tool call at a time.
  14. 2. Traditional tool calling returns full results to the model's context window. Suppose fetching 1 year of daily stock prices for 10 tickers. This means 2,500+ OHLCV data points polluting context - tens of thousands of tokens just to compute a portfolio summary. With PTC, code runs in a sandbox, processes data locally, and only the final output returns to the model. Result: 85-98% token reduction.
  15. 3. PTC particularly shines when working with large volumes of structured data, time series data (like financial market data), and scenarios requiring further data processing - filtering, aggregating, transforming, or visualizing results before returning them to the model.
  16. ## How It Works
  17. ```
  18. User Task
  19. |
  20. v
  21. +-------------------+
  22. | PTCAgent | Tool discovery -> Writes Python code
  23. +-------------------+
  24. | ^
  25. v |
  26. +-------------------+
  27. | Daytona Sandbox | Executes code
  28. | +-------------+ |
  29. | | MCP Tools | | tool() -> process / filter / aggregate -> dump to data/ directory
  30. | | (Python) | |
  31. | +-------------+ |
  32. +-------------------+
  33. |
  34. v
  35. +-------------------+
  36. |Final deliverables | Files and data can be downloaded from sandbox
  37. +-------------------+
  38. ```
  39. > **Built on [LangChain DeepAgents](https://github.com/langchain-ai/deepagents)** - This project uses many components from DeepAgents and cli feature was bootstrapped from deepagent-cli. Special thanks to the LangChain team!
  40. > **Sandbox environment provided by [Daytona](https://www.daytona.io/)**.
  41. ## What's New
  42. - **Interactive CLI** - New `ptc-agent` command for terminal-based interaction with session persistence, plan mode, themes, and rich UI
  43. - **Background Subagent Execution** - Subagents run asynchronously with Task IDs (Task-1, Task-2, etc.). The main agent continues working while subagents execute in parallel. Completed results are cached and the agent is notified to retrieve them via `task_output()`
  44. - **Task Monitoring** - `wait()` blocks until task(s) complete; `task_output()` retrieves results or shows progress
  45. - **Agent Skills** - Extensible capabilities via the open [Agent Skills](https://agentskills.io) standard
  46. - **Vision/Multimodal Support** - New `view_image` tool enables vision-capable LLMs to analyze images from URLs, base64 data, or sandbox files
  47. ## Features
  48. - **Universal MCP Support** - Auto-converts any MCP server tools to Python functions
  49. - **Progressive Tool Discovery** - Tools discovered on-demand; avoids large number of tokens of upfront tool definitions
  50. - **Custom MCP Upload** - Deploy Python MCP implementations directly into sandbox sessions
  51. - **Agent Skills** - Skills for custom workflows
  52. - **Enhanced File Tools** - Refined glob, grep and other file operation tools optimized for sandbox environment
  53. - **Daytona Backend** - Secure code execution with filesystem isolation and snapshot support
  54. - **Auto Image Upload** - Charts and images auto-uploaded to cloud storage (Cloudflare R2, AWS S3, Alibaba OSS)
  55. - **LangGraph Ready** - Compatible with LangGraph Cloud/Studio deployment
  56. - **Multi-LLM Support** - Works with Anthropic, OpenAI, and Any LLM provider you configure in `llms.json`
  57. ## Project Structure
  58. ```
  59. ├── libs/
  60. │ ├── ptc-agent/ # Core agent library
  61. │ │ └── ptc_agent/
  62. │ │ ├── core/ # Sandbox, MCP registry, tool generator, session
  63. │ │ ├── config/ # Configuration classes and loaders
  64. │ │ ├── agent/ # PTCAgent, tools, prompts, middleware, subagents
  65. │ │ └── utils/ # Cloud storage uploaders
  66. │ │
  67. │ └── ptc-cli/ # Interactive CLI application
  68. │ └── ptc_cli/
  69. │ ├── core/ # State, config, theming
  70. │ ├── commands/ # Slash commands, bash execution
  71. │ ├── display/ # Rich terminal rendering
  72. │ ├── input/ # Prompt, completers, file mentions
  73. │ └── streaming/ # Tool approval, execution
  74. │
  75. ├── skills/ # Demo skills (from Anthropic)
  76. │ ├── pdf/ # PDF manipulation
  77. │ ├── xlsx/ # Spreadsheet operations
  78. │ ├── docx/ # Document creation
  79. │ ├── pptx/ # Presentation creation
  80. │ └── creating-financial-models/ # Financial modeling
  81. │
  82. ├── mcp_servers/ # Demo MCP server implementations
  83. │ ├── yfinance_mcp_server.py
  84. │ └── tickertick_mcp_server.py
  85. │
  86. ├── example/ # Demo notebooks and scripts
  87. │ ├── PTC_Agent.ipynb
  88. │ ├── Subagent_demo.ipynb
  89. │ └── quickstart.py
  90. │
  91. ├── config.yaml # Main configuration
  92. └── llms.json # LLM provider definitions
  93. ```
  94. ## Native Tools
  95. The agent has access to native tools plus middleware capabilities from [deep-agent](https://github.com/langchain-ai/deepagents):
  96. ### Core Tools
  97. | Tool | Description | Key Parameters |
  98. |------|-------------|----------------|
  99. | **execute_code** | Execute Python with MCP tool access | `code` |
  100. | **Bash** | Run shell commands | `command`, `timeout`, `working_dir` |
  101. | **Read** | Read file with line numbers | `file_path`, `offset`, `limit` |
  102. | **Write** | Write/overwrite file | `file_path`, `content` |
  103. | **Edit** | Exact string replacement | `file_path`, `old_string`, `new_string` |
  104. | **Glob** | File pattern matching | `pattern`, `path` |
  105. | **Grep** | Content search (ripgrep) | `pattern`, `path`, `output_mode` |
  106. ### Middleware
  107. | Middleware | Description | Tools Provided |
  108. |------------|-------------|----------------|
  109. | **SubagentsMiddleware** | Delegates specialized tasks to sub-agents with isolated execution | `task()` |
  110. | **BackgroundSubagentMiddleware** | Async subagent execution with background tasks and notification-based collection | `wait()`, `task_output()` |
  111. | **ViewImageMiddleware** | Injects images into conversation for multimodal LLMs | `view_image()` |
  112. | **FilesystemMiddleware** | File operations | `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `ls` |
  113. | **TodoListMiddleware** | Task planning and progress tracking (auto-enabled) | `write_todos` |
  114. | **SummarizationMiddleware** | Auto-summarizes conversation history (auto-enabled) | - |
  115. **Available Subagents (Default):**
  116. - `research` - Web search with Tavily + think tool for strategic reflection
  117. - `general-purpose` - Full execute_code, filesystem, and vision tools for complex multi-step tasks
  118. **Background Execution Model:**
  119. When the agent calls `task()`, subagents are assigned sequential IDs (Task-1, Task-2, etc.) and run in the background. The main agent:
  120. 1. Receives immediate confirmation with the Task ID
  121. 2. Continues with other work while subagents execute in parallel
  122. 3. Gets notified when tasks complete
  123. 4. Calls `task_output()` to retrieve cached results
  124. 5. Uses `wait(task_number=N)` to block for specific tasks if needed
  125. ## MCP Integration
  126. ### Demo MCP Servers
  127. The demo includes 3 enabled MCP servers configured in `config.yaml`:
  128. | Server | Transport | Tools | Purpose |
  129. |--------|-----------|-------|---------|
  130. | **tavily** | stdio (npx) | 4 | Web search |
  131. | **yfinance** | stdio (python) | 21 | Stock prices, financials |
  132. | **tickertick** | stdio (python) | 7 | Financial news |
  133. ### How MCP Tools Appear
  134. **In Prompts** - Tool summaries are injected into the system prompt:
  135. ```
  136. tavily: Web search engine for finding current information
  137. - Module: tools/tavily.py
  138. - Tools: 4 tools available
  139. - Import: from tools.tavily import <tool_name>
  140. ```
  141. **In Sandbox** - Full Python modules are generated:
  142. ```
  143. /home/daytona/
  144. ├── tools/
  145. │ ├── mcp_client.py # MCP communication layer
  146. │ ├── tavily.py # from tools.tavily import search
  147. │ ├── yfinance.py # from tools.yfinance import get_stock_history
  148. │ └── docs/ # Auto-generated documentation
  149. │ ├── tavily/*.md
  150. │ └── yfinance/*.md
  151. ├── results/ # Agent output
  152. └── data/ # Input data
  153. ```
  154. **In Code** - Agent imports and uses tools directly:
  155. ```python
  156. from tools.yfinance import get_stock_history
  157. import pandas as pd
  158. # Fetch data - stays in sandbox
  159. history = get_stock_history(ticker="AAPL", period="1y")
  160. # Process locally - no tokens wasted
  161. df = pd.DataFrame(history)
  162. summary = {"mean": df["close"].mean(), "volatility": df["close"].std()}
  163. # Only summary returns to model
  164. print(summary)
  165. ```
  166. ## Skills
  167. [Agent Skills](https://agentskills.io) is an open standard by Anthropic for packaging domain expertise into reusable folders of instructions and resources. Skills load dynamically via **progressive disclosure** - only metadata at startup, full content on-demand
  168. ### Included Demo Skills
  169. Skills from [anthropics/skills](https://github.com/anthropics/skills) are included for demonstration:
  170. | Skill | Description |
  171. |-------|-------------|
  172. | **pdf** | PDF manipulation - extract text/tables, create, merge/split, fill forms |
  173. | **xlsx** | Spreadsheet creation with formulas, formatting, and data analysis |
  174. | **docx** | Document creation, editing, and formatting |
  175. | **pptx** | Presentation creation, editing, and analysis |
  176. | **creating-financial-models** | DCF analysis, sensitivity testing, Monte Carlo simulations |
  177. ### Configuration
  178. Skills are enabled by default and loaded from:
  179. 1. User directory: `~/.ptc-agent/skills/`
  180. 2. Project directory: `.ptc-agent/skills/` (or `skills/` for legacy)
  181. Project skills override user skills when names conflict.
  182. ```yaml
  183. # config.yaml
  184. skills:
  185. enabled: true
  186. user_skills_dir: "~/.ptc-agent/skills"
  187. project_skills_dir: ".ptc-agent/skills"
  188. ```
  189. ### Creating Custom Skills
  190. Each skill is a folder with a `SKILL.md` file containing YAML frontmatter and instructions:
  191. ```markdown
  192. ---
  193. name: my-skill
  194. description: "Clear description of what this skill does and when to use it"
  195. ---
  196. # My Skill
  197. Instructions, workflows, and examples that Claude follows when this skill is active.
  198. ## Guidelines
  199. - Guideline 1
  200. - Guideline 2
  201. ```
  202. Additional files (e.g., `reference.md`, scripts) can be bundled alongside `SKILL.md` and referenced as needed. Skills are uploaded to the sandbox at `/home/daytona/skills/<skill-name>/`.
  203. For detailed guidance, see [Anthropic's skill authoring best practices](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
  204. ## Getting Started
  205. ### Prerequisites
  206. - Python 3.12+
  207. - Node.js (for MCP servers)
  208. - [uv](https://docs.astral.sh/uv/) package manager
  209. ### Installation
  210. ```bash
  211. git clone https://github.com/Chen-zexi/open-ptc-agent.git
  212. cd open-ptc-agent
  213. uv sync
  214. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  215. ```
  216. ### Minimal Configuration
  217. Create a `.env` file with the minimum required keys:
  218. ```bash
  219. # One LLM provider (choose one)
  220. ANTHROPIC_API_KEY=your-key
  221. # or
  222. OPENAI_API_KEY=your-key
  223. # or
  224. # Any model you configured in llms.json and config.yaml
  225. # You can also use Coding plans from Minimax and GLM here!
  226. # Daytona (required)
  227. DAYTONA_API_KEY=your-key
  228. ```
  229. Get your Daytona API key from [Daytona Dashboard](https://app.daytona.io/dashboard/keys). They provide free credits for new users!
  230. ### Extended Configuration
  231. For full functionality, add optional keys:
  232. ```bash
  233. # MCP Servers
  234. TAVILY_API_KEY=your-key # Web search
  235. ALPHA_VANTAGE_API_KEY=your-key # Financial data
  236. # Cloud Storage (choose one provider)
  237. R2_ACCESS_KEY_ID=... # Cloudflare R2
  238. AWS_ACCESS_KEY_ID=... # AWS S3
  239. OSS_ACCESS_KEY_ID=... # Alibaba OSS
  240. # Tracing (optional)
  241. LANGSMITH_API_KEY=your-key
  242. ```
  243. See `.env.example` for the complete list of environment variables options.
  244. ### Run the CLI
  245. Start the interactive CLI:
  246. ```bash
  247. ptc-agent
  248. ```
  249. See the **[ptc-cli documentation](libs/ptc-cli/README.md)** for all commands and options.
  250. For programmatic usage of PTC Agent, see the [ptc-agent documentation](libs/ptc-agent/README.md).
  251. ### Demo Notebooks
  252. For Jupyter notebook examples:
  253. - **[PTC_Agent.ipynb](example/PTC_Agent.ipynb)** - Quick demo with open-ptc-agent
  254. - **[Subagent_demo.ipynb](example/Subagent_demo.ipynb)** - Background subagent execution
  255. - **[quickstart.py](example/quickstart.py)** - Python script quickstart
  256. Optionally, use the LangGraph API to deploy the agent.
  257. ## Configuration
  258. The project uses two configuration files:
  259. - **config.yaml** - Main configuration (LLM selection, MCP servers, Daytona, security, storage)
  260. - **llms.json** - LLM provider definitions
  261. ### Quick Config
  262. Select your LLM in `config.yaml`:
  263. ```yaml
  264. llm:
  265. name: "claude-sonnet-4-5" # Options: claude-sonnet-4-5, gpt-5.1-codex-mini, gemini-3-pro
  266. ```
  267. Enable/disable MCP servers:
  268. ```yaml
  269. mcp:
  270. servers:
  271. - name: "tavily"
  272. enabled: true # Set to false to disable
  273. ```
  274. For complete configuration options including Daytona settings, security policies, and adding custom LLM providers, see the [Configuration Guide](docs/CONFIGURATION.md).
  275. ## CLI Reference
  276. The `ptc-agent` command provides an interactive terminal interface with:
  277. - Session persistence and sandbox reuse
  278. - Slash commands (`/help`, `/files`, `/view`, `/download`)
  279. - Bash execution with `!command`
  280. - File mentions with `@path/to/file`
  281. - Customizable themes and color palettes
  282. Quick start:
  283. ```bash
  284. ptc-agent # Start interactive session
  285. ptc-agent --plan-mode # Enable plan approval before execution
  286. ptc-agent list # List available agents
  287. ```
  288. For complete CLI documentation including all options, commands, keyboard shortcuts, and theming configuration, see the **[CLI Reference](libs/ptc-cli/README.md)**.
  289. ## Roadmap
  290. Planned features and improvements:
  291. - [x] CLI Version for PTC Agent
  292. - [x] Agent Skills support ([agentskills.io](https://agentskills.io) open standard)
  293. - [x] CI/CD pipeline for automated testing
  294. - [ ] Additional MCP server integrations / More example notebooks
  295. - [ ] Performance benchmarks and optimizations
  296. - [ ] Improved search tool for smoother tool discovery
  297. ## Contributing
  298. We welcome contributions from the community! Here are some ways you can help:
  299. - **Code Contributions** - Bug fixes, new features, improvements (CI/CD coming soon)
  300. - **Use Cases** - Share how you're using PTC in production or research
  301. - **Example Notebooks** - Create demos showcasing different workflows
  302. - **MCP Servers** - Build or recommend MCP servers that work well with PTC (data processing, APIs, etc.)
  303. - **Prompt Tricks** - Share prompting techniques that improve agent performance
  304. Open an issue or PR on [GitHub](https://github.com/Chen-zexi/open-ptc-agent) to contribute!
  305. ## Acknowledgements
  306. This project builds on research and tools from:
  307. **Research/Articles**
  308. - [Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) - Anthropic
  309. - [Code execution with MCP: building more efficient AI agents](https://www.anthropic.com/engineering/code-execution-with-mcp) - Anthropic
  310. - [CodeAct: Executable Code Actions Elicit Better LLM Agents](https://arxiv.org/abs/2402.01030) - Wang et al.
  311. **Frameworks and Infrastructure**
  312. - [LangChain DeepAgents](https://github.com/langchain-ai/deepagents) - Base Agent Framework
  313. - [Daytona](https://www.daytona.io/) - Sandbox infrastructure
  314. ## Star History
  315. If you find this project useful, please consider giving it a star! It helps others discover this work.
  316. [![Star History Chart](https://api.star-history.com/svg?repos=Chen-zexi/open-ptc-agent&type=Date)](https://star-history.com/#Chen-zexi/open-ptc-agent&Date)
  317. ## License
  318. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.