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.
Badge for your README
Markdown
[](/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
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)
- # Open PTC Agent
- [English](README.md) | [中文](docs/zh/README.md)
- [](https://opensource.org/licenses/MIT)
- [](https://www.python.org/downloads/)
- [](https://github.com/langchain-ai/langchain)
- [](https://github.com/Chen-zexi/open-ptc-agent/stargazers)
- [Getting Started](#getting-started) | [CLI Reference](#cli-reference) | [Configuration](docs/CONFIGURATION.md) | [Changelog](docs/CHANGELOG.md) | [Roadmap](#roadmap)
- <video src="https://github.com/user-attachments/assets/cca8c6ee-0c6f-4a97-ad7d-08bad250c006" controls width="800"></video>
- *Demo: Analyzing 2 years of NVDA, AMD & SPY stock data (15,000+ lines of raw JSON) using DeepSeek V3.2*
- ## What is Programmatic Tool Calling?
- 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).
- ## Why PTC?
- 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.
- 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.
- 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.
- ## How It Works
- ```
- User Task
- |
- v
- +-------------------+
- | PTCAgent | Tool discovery -> Writes Python code
- +-------------------+
- | ^
- v |
- +-------------------+
- | Daytona Sandbox | Executes code
- | +-------------+ |
- | | MCP Tools | | tool() -> process / filter / aggregate -> dump to data/ directory
- | | (Python) | |
- | +-------------+ |
- +-------------------+
- |
- v
- +-------------------+
- |Final deliverables | Files and data can be downloaded from sandbox
- +-------------------+
- ```
- > **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!
- > **Sandbox environment provided by [Daytona](https://www.daytona.io/)**.
- ## What's New
- - **Interactive CLI** - New `ptc-agent` command for terminal-based interaction with session persistence, plan mode, themes, and rich UI
- - **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()`
- - **Task Monitoring** - `wait()` blocks until task(s) complete; `task_output()` retrieves results or shows progress
- - **Agent Skills** - Extensible capabilities via the open [Agent Skills](https://agentskills.io) standard
- - **Vision/Multimodal Support** - New `view_image` tool enables vision-capable LLMs to analyze images from URLs, base64 data, or sandbox files
- ## Features
- - **Universal MCP Support** - Auto-converts any MCP server tools to Python functions
- - **Progressive Tool Discovery** - Tools discovered on-demand; avoids large number of tokens of upfront tool definitions
- - **Custom MCP Upload** - Deploy Python MCP implementations directly into sandbox sessions
- - **Agent Skills** - Skills for custom workflows
- - **Enhanced File Tools** - Refined glob, grep and other file operation tools optimized for sandbox environment
- - **Daytona Backend** - Secure code execution with filesystem isolation and snapshot support
- - **Auto Image Upload** - Charts and images auto-uploaded to cloud storage (Cloudflare R2, AWS S3, Alibaba OSS)
- - **LangGraph Ready** - Compatible with LangGraph Cloud/Studio deployment
- - **Multi-LLM Support** - Works with Anthropic, OpenAI, and Any LLM provider you configure in `llms.json`
- ## Project Structure
- ```
- ├── libs/
- │ ├── ptc-agent/ # Core agent library
- │ │ └── ptc_agent/
- │ │ ├── core/ # Sandbox, MCP registry, tool generator, session
- │ │ ├── config/ # Configuration classes and loaders
- │ │ ├── agent/ # PTCAgent, tools, prompts, middleware, subagents
- │ │ └── utils/ # Cloud storage uploaders
- │ │
- │ └── ptc-cli/ # Interactive CLI application
- │ └── ptc_cli/
- │ ├── core/ # State, config, theming
- │ ├── commands/ # Slash commands, bash execution
- │ ├── display/ # Rich terminal rendering
- │ ├── input/ # Prompt, completers, file mentions
- │ └── streaming/ # Tool approval, execution
- │
- ├── skills/ # Demo skills (from Anthropic)
- │ ├── pdf/ # PDF manipulation
- │ ├── xlsx/ # Spreadsheet operations
- │ ├── docx/ # Document creation
- │ ├── pptx/ # Presentation creation
- │ └── creating-financial-models/ # Financial modeling
- │
- ├── mcp_servers/ # Demo MCP server implementations
- │ ├── yfinance_mcp_server.py
- │ └── tickertick_mcp_server.py
- │
- ├── example/ # Demo notebooks and scripts
- │ ├── PTC_Agent.ipynb
- │ ├── Subagent_demo.ipynb
- │ └── quickstart.py
- │
- ├── config.yaml # Main configuration
- └── llms.json # LLM provider definitions
- ```
- ## Native Tools
- The agent has access to native tools plus middleware capabilities from [deep-agent](https://github.com/langchain-ai/deepagents):
- ### Core Tools
- | Tool | Description | Key Parameters |
- |------|-------------|----------------|
- | **execute_code** | Execute Python with MCP tool access | `code` |
- | **Bash** | Run shell commands | `command`, `timeout`, `working_dir` |
- | **Read** | Read file with line numbers | `file_path`, `offset`, `limit` |
- | **Write** | Write/overwrite file | `file_path`, `content` |
- | **Edit** | Exact string replacement | `file_path`, `old_string`, `new_string` |
- | **Glob** | File pattern matching | `pattern`, `path` |
- | **Grep** | Content search (ripgrep) | `pattern`, `path`, `output_mode` |
- ### Middleware
- | Middleware | Description | Tools Provided |
- |------------|-------------|----------------|
- | **SubagentsMiddleware** | Delegates specialized tasks to sub-agents with isolated execution | `task()` |
- | **BackgroundSubagentMiddleware** | Async subagent execution with background tasks and notification-based collection | `wait()`, `task_output()` |
- | **ViewImageMiddleware** | Injects images into conversation for multimodal LLMs | `view_image()` |
- | **FilesystemMiddleware** | File operations | `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `ls` |
- | **TodoListMiddleware** | Task planning and progress tracking (auto-enabled) | `write_todos` |
- | **SummarizationMiddleware** | Auto-summarizes conversation history (auto-enabled) | - |
- **Available Subagents (Default):**
- - `research` - Web search with Tavily + think tool for strategic reflection
- - `general-purpose` - Full execute_code, filesystem, and vision tools for complex multi-step tasks
- **Background Execution Model:**
- When the agent calls `task()`, subagents are assigned sequential IDs (Task-1, Task-2, etc.) and run in the background. The main agent:
- 1. Receives immediate confirmation with the Task ID
- 2. Continues with other work while subagents execute in parallel
- 3. Gets notified when tasks complete
- 4. Calls `task_output()` to retrieve cached results
- 5. Uses `wait(task_number=N)` to block for specific tasks if needed
- ## MCP Integration
- ### Demo MCP Servers
- The demo includes 3 enabled MCP servers configured in `config.yaml`:
- | Server | Transport | Tools | Purpose |
- |--------|-----------|-------|---------|
- | **tavily** | stdio (npx) | 4 | Web search |
- | **yfinance** | stdio (python) | 21 | Stock prices, financials |
- | **tickertick** | stdio (python) | 7 | Financial news |
- ### How MCP Tools Appear
- **In Prompts** - Tool summaries are injected into the system prompt:
- ```
- tavily: Web search engine for finding current information
- - Module: tools/tavily.py
- - Tools: 4 tools available
- - Import: from tools.tavily import <tool_name>
- ```
- **In Sandbox** - Full Python modules are generated:
- ```
- /home/daytona/
- ├── tools/
- │ ├── mcp_client.py # MCP communication layer
- │ ├── tavily.py # from tools.tavily import search
- │ ├── yfinance.py # from tools.yfinance import get_stock_history
- │ └── docs/ # Auto-generated documentation
- │ ├── tavily/*.md
- │ └── yfinance/*.md
- ├── results/ # Agent output
- └── data/ # Input data
- ```
- **In Code** - Agent imports and uses tools directly:
- ```python
- from tools.yfinance import get_stock_history
- import pandas as pd
- # Fetch data - stays in sandbox
- history = get_stock_history(ticker="AAPL", period="1y")
- # Process locally - no tokens wasted
- df = pd.DataFrame(history)
- summary = {"mean": df["close"].mean(), "volatility": df["close"].std()}
- # Only summary returns to model
- print(summary)
- ```
- ## Skills
- [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
- ### Included Demo Skills
- Skills from [anthropics/skills](https://github.com/anthropics/skills) are included for demonstration:
- | Skill | Description |
- |-------|-------------|
- | **pdf** | PDF manipulation - extract text/tables, create, merge/split, fill forms |
- | **xlsx** | Spreadsheet creation with formulas, formatting, and data analysis |
- | **docx** | Document creation, editing, and formatting |
- | **pptx** | Presentation creation, editing, and analysis |
- | **creating-financial-models** | DCF analysis, sensitivity testing, Monte Carlo simulations |
- ### Configuration
- Skills are enabled by default and loaded from:
- 1. User directory: `~/.ptc-agent/skills/`
- 2. Project directory: `.ptc-agent/skills/` (or `skills/` for legacy)
- Project skills override user skills when names conflict.
- ```yaml
- # config.yaml
- skills:
- enabled: true
- user_skills_dir: "~/.ptc-agent/skills"
- project_skills_dir: ".ptc-agent/skills"
- ```
- ### Creating Custom Skills
- Each skill is a folder with a `SKILL.md` file containing YAML frontmatter and instructions:
- ```markdown
- ---
- name: my-skill
- description: "Clear description of what this skill does and when to use it"
- ---
- # My Skill
- Instructions, workflows, and examples that Claude follows when this skill is active.
- ## Guidelines
- - Guideline 1
- - Guideline 2
- ```
- 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>/`.
- For detailed guidance, see [Anthropic's skill authoring best practices](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).
- ## Getting Started
- ### Prerequisites
- - Python 3.12+
- - Node.js (for MCP servers)
- - [uv](https://docs.astral.sh/uv/) package manager
- ### Installation
- ```bash
- 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:
- ```bash
- # 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:
- ```bash
- # 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:
- ```bash
- 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.
- ## Configuration
- The project uses two configuration files:
- - **config.yaml** - Main configuration (LLM selection, MCP servers, Daytona, security, storage)
- - **llms.json** - LLM provider definitions
- ### Quick Config
- Select your LLM in `config.yaml`:
- ```yaml
- llm:
- name: "claude-sonnet-4-5" # Options: claude-sonnet-4-5, gpt-5.1-codex-mini, gemini-3-pro
- ```
- Enable/disable MCP servers:
- ```yaml
- mcp:
- servers:
- - name: "tavily"
- enabled: true # Set to false to disable
- ```
- For complete configuration options including Daytona settings, security policies, and adding custom LLM providers, see the [Configuration Guide](docs/CONFIGURATION.md).
- ## CLI Reference
- The `ptc-agent` command provides an interactive terminal interface with:
- - Session persistence and sandbox reuse
- - Slash commands (`/help`, `/files`, `/view`, `/download`)
- - Bash execution with `!command`
- - File mentions with `@path/to/file`
- - Customizable themes and color palettes
- Quick start:
- ```bash
- ptc-agent # Start interactive session
- ptc-agent --plan-mode # Enable plan approval before execution
- ptc-agent list # List available agents
- ```
- For complete CLI documentation including all options, commands, keyboard shortcuts, and theming configuration, see the **[CLI Reference](libs/ptc-cli/README.md)**.
- ## Roadmap
- Planned features and improvements:
- - [x] CLI Version for PTC Agent
- - [x] Agent Skills support ([agentskills.io](https://agentskills.io) open standard)
- - [x] CI/CD pipeline for automated testing
- - [ ] Additional MCP server integrations / More example notebooks
- - [ ] Performance benchmarks and optimizations
- - [ ] Improved search tool for smoother tool discovery
- ## Contributing
- We welcome contributions from the community! Here are some ways you can help:
- - **Code Contributions** - Bug fixes, new features, improvements (CI/CD coming soon)
- - **Use Cases** - Share how you're using PTC in production or research
- - **Example Notebooks** - Create demos showcasing different workflows
- - **MCP Servers** - Build or recommend MCP servers that work well with PTC (data processing, APIs, etc.)
- - **Prompt Tricks** - Share prompting techniques that improve agent performance
- Open an issue or PR on [GitHub](https://github.com/Chen-zexi/open-ptc-agent) to contribute!
- ## Acknowledgements
- This project builds on research and tools from:
- **Research/Articles**
- - [Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) - Anthropic
- - [Code execution with MCP: building more efficient AI agents](https://www.anthropic.com/engineering/code-execution-with-mcp) - Anthropic
- - [CodeAct: Executable Code Actions Elicit Better LLM Agents](https://arxiv.org/abs/2402.01030) - Wang et al.
- **Frameworks and Infrastructure**
- - [LangChain DeepAgents](https://github.com/langchain-ai/deepagents) - Base Agent Framework
- - [Daytona](https://www.daytona.io/) - Sandbox infrastructure
- ## Star History
- If you find this project useful, please consider giving it a star! It helps others discover this work.
- [](https://star-history.com/#Chen-zexi/open-ptc-agent&Date)
- ## License
- MIT License
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.