Open PTC Agent

English | 中文

Getting Started | CLI Reference | Configuration | Changelog | Roadmap

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), 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.

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 - 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.

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 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:

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:

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 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 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.

# 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:

---
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.

Getting Started

Prerequisites

• Python 3.12+
• Node.js (for MCP servers)
• 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. 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 for all commands and options.

For programmatic usage of PTC Agent, see the ptc-agent documentation.

Demo Notebooks

For Jupyter notebook examples:

• PTC_Agent.ipynb - Quick demo with open-ptc-agent
• Subagent_demo.ipynb - Background subagent execution
• 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:

llm:
  name: "claude-sonnet-4-5"  # Options: claude-sonnet-4-5, gpt-5.1-codex-mini, gemini-3-pro

Enable/disable MCP servers:

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.

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:

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.

Roadmap

Planned features and improvements:

• CLI Version for PTC Agent
• Agent Skills support (agentskills.io open standard)
• 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 to contribute!

Acknowledgements

This project builds on research and tools from:

Research/Articles

• Introducing advanced tool use on the Claude Developer Platform - Anthropic
• Code execution with MCP: building more efficient AI agents - Anthropic
• CodeAct: Executable Code Actions Elicit Better LLM Agents - Wang et al.

Frameworks and Infrastructure

• LangChain DeepAgents - Base Agent Framework
• Daytona - Sandbox infrastructure

Star History

If you find this project useful, please consider giving it a star! It helps others discover this work.

License

MIT License