Open PTC Agent

원문: https://github.com/Chen-zexi/open-ptc-agent/blob/main/README.md#getting-started

Programmatic Tool Calling이란?

이 프로젝트는 Anthropic이 최근 발표한 Programmatic Tool Calling (PTC)의 오픈소스 구현체입니다. PTC는 에이전트가 개별 JSON 툴 호출 대신 코드 실행을 통해 도구를 호출할 수 있도록 합니다. 이 패러다임은 앞서 발표된 엔지니어링 블로그 Code execution with MCP에서도 소개된 바 있습니다.

왜 PTC인가?

LLM은 코드 작성에 탁월합니다! 컨텍스트를 이해하고, 데이터 흐름을 추론하며, 정확한 로직을 생성하는 데 뛰어난 능력을 발휘합니다. PTC는 LLM이 가장 잘하는 일을 할 수 있게 해줍니다 - 한 번에 하나씩 도구를 호출하며 추론하는 대신, 전체 워크플로우를 조율하는 코드를 작성하는 것입니다.
기존의 툴 호출 방식은 전체 결과를 모델의 컨텍스트 윈도우로 반환합니다. 20명의 직원 경비를 분석한다면 2,000개 이상의 항목이 컨텍스트를 오염시키게 되며, 단순한 요약을 생성하는 데만 110,000개 이상의 토큰이 소모됩니다. PTC에서는 코드가 샌드박스에서 실행되고 데이터를 로컬에서 처리하여 최종 출력만 모델로 반환합니다. 결과: 85-98%의 토큰 절감.
PTC는 특히 대량의 구조화된 데이터, 시계열 데이터(금융 시장 데이터 등), 추가 데이터 처리가 필요한 시나리오(필터링, 집계, 변환, 시각화 등)에서 강점을 발휘합니다.

작동 원리

이 프로젝트는 langchain-ai의 deep-agent와 샌드박스 환경을 위한 daytona를 기반으로 구현되었습니다.

사용자 작업
    |
    v
+-------------------+
|    PTCAgent       |  도구 탐색 -> Python 코드 작성
+-------------------+
    |       ^
    v       |
+-------------------+
|  Daytona Sandbox  |  코드 실행
|  +-------------+  |
|  | MCP Tools   |  |  tool() -> 처리 / 필터링 / 집계 -> data/ 디렉토리로 출력
|  | (Python)    |  |
|  +-------------+  |
+-------------------+
    |
    v
+-------------------+
|최종 결과물        |  샌드박스에서 파일 및 데이터 다운로드 가능
+-------------------+

새로운 기능

백그라운드 서브에이전트 실행 - 서브에이전트가 “실행 후 수집(fire and collect)” 패턴을 사용하여 비동기적으로 실행되며, 에이전트가 전달된 작업을 능동적으로 제어할 수 있습니다. 명시적으로 wait()를 호출하지 않아도 완료 시 결과가 자동으로 에이전트에 반환됩니다.
비전/멀티모달 지원 - 새로운 view_image 도구를 통해 비전 기능을 갖춘 LLM이 URL, base64 데이터 또는 샌드박스 파일의 이미지를 분석할 수 있습니다.
작업 모니터링 - 백그라운드 작업 결과 모니터링 및 수집을 위한 wait() 및 task_progress() 도구가 추가되었습니다.

기능

범용 MCP 지원 - 모든 MCP 서버 도구를 Python 함수로 자동 변환합니다.
점진적 도구 탐색 - 필요에 따라 도구를 탐색하여 사전 도구 정의에 소모되는 대량의 토큰을 방지합니다.
커스텀 MCP 업로드 - Python MCP 구현을 샌드박스 세션에 직접 배포할 수 있습니다.
향상된 파일 도구 - LangChain DeepAgent를 기반으로 개선된 glob, grep 및 기타 파일 작업 도구를 제공합니다.
Daytona 백엔드 - 파일시스템 격리 및 스냅샷 지원을 통한 안전한 코드 실행 환경을 제공합니다.
자동 이미지 업로드 - 차트와 이미지를 클라우드 스토리지(Cloudflare R2, AWS S3, Alibaba OSS)에 자동으로 업로드합니다.
LangGraph 지원 - LangGraph Cloud/Studio 배포와 호환됩니다.
다중 LLM 지원 - Anthropic, OpenAI 및 llms.json에 설정한 모든 LLM 제공자와 호환됩니다.

프로젝트 구조

├── src/
│   ├── ptc_core/              # 핵심 인프라
│   │   ├── sandbox.py         # PTCSandbox (glob, grep, read, write)
│   │   ├── mcp_registry.py    # MCP 서버 탐색 및 연결
│   │   ├── tool_generator.py  # MCP 스키마 → Python 함수 변환
│   │   ├── session.py         # 세션 생명주기 관리
│   │   └── config.py          # 설정 클래스
│   │
│   └── agent/                 # 에이전트 구현
│       ├── agent.py           # PTCAgent, PTCExecutor
│       ├── config.py          # AgentConfig
│       ├── tools/             # 네이티브 도구 구현
│       ├── prompts/           # Jinja2 템플릿
│       ├── subagents/         # 리서치 및 범용 서브에이전트
│       ├── middleware/        # 백그라운드 실행, 비전 지원
│       └── backends/          # DaytonaBackend
│
├── mcp_servers/               # 데모용 커스텀 MCP 서버 구현
│   ├── yfinance_mcp_server.py
│   └── tickertick_mcp_server.py
│
├── config.yaml                # 메인 설정 파일
├── llms.json                  # LLM 제공자 정의
└── PTC_Agent.ipynb            # 데모 노트북

네이티브 도구

에이전트는 deep-agent의 미들웨어 기능과 함께 네이티브 도구에 접근할 수 있습니다:

핵심 도구

도구	설명	주요 매개변수
execute_code	MCP 도구 접근과 함께 Python 실행	`code`
Bash	셸 명령 실행	`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`

미들웨어 (langchain/deep-agent 제공)

미들웨어	설명	제공되는 도구
SubagentsMiddleware	격리된 실행 환경에서 특화된 작업을 서브에이전트에 위임	`task()`
BackgroundSubagentMiddleware	실행 후 수집 패턴을 사용한 비동기 서브에이전트 실행	`wait()`, `task_progress()`
ViewImageMiddleware	멀티모달 LLM을 위해 대화에 이미지 삽입	`view_image()`
FilesystemMiddleware	파일 작업	`read_file`, `write_file`, `edit_file`, `glob`, `grep`, `ls`
TodoListMiddleware	작업 계획 및 진행 상황 추적 (자동 활성화)	`write_todos`
SummarizationMiddleware	대화 히스토리 자동 요약 (자동 활성화)	-

사용 가능한 서브에이전트:

research - Tavily를 통한 웹 검색 + 전략적 성찰을 위한 think 도구
general-purpose - 복잡한 다단계 작업을 위한 전체 execute_code, 파일시스템, 비전 도구

서브에이전트는 기본적으로 백그라운드에서 실행됩니다 - 메인 에이전트는 위임된 작업이 비동기적으로 실행되는 동안 계속 작업할 수 있습니다.

참고: 도구 탐색 개선을 위해 langchain deep-agent의 내장 파일시스템 미들웨어를 재정의했습니다. config.yaml에서 use_custom_filesystem_tools를 false로 설정하여 비활성화할 수 있습니다.

MCP 통합

데모 MCP 서버

데모에는 config.yaml에 설정된 3개의 활성화된 MCP 서버가 포함되어 있습니다:

서버	전송 방식	도구 수	용도
tavily	stdio (npx)	4	웹 검색
yfinance	stdio (python)	10	주식 가격, 재무제표
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")
 
# 로컬에서 처리 - 토큰 낭비 없음
df = pd.DataFrame(history)
summary = {"mean": df["close"].mean(), "volatility": df["close"].std()}
 
# 요약만 모델로 반환
print(summary)

시작하기

사전 요구사항

Python 3.12+
Node.js (MCP 서버용)
uv 패키지 매니저

설치

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

최소 설정

필수 키가 포함된 .env 파일을 생성합니다:

# LLM 제공자 중 하나 선택
ANTHROPIC_API_KEY=your-key
# 또는
OPENAI_API_KEY=your-key
# 또는
# llms.json과 config.yaml에 설정한 모든 모델
 
# Daytona (필수)
DAYTONA_API_KEY=your-key

Daytona API 키는 Daytona Dashboard에서 받을 수 있습니다. 신규 사용자에게 무료 크레딧을 제공합니다!

확장 설정

전체 기능을 사용하려면 선택적 키를 추가합니다:

# 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을 참조하세요.

데모 노트북

주피터 노트북으로 빠르게 시작하기:

PTC_Agent.ipynb - open-ptc-agent 빠른 데모
example/Subagent_demo.ipynb - 리서치 및 범용 에이전트를 사용한 백그라운드 서브에이전트 실행

선택적으로 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 제공자 추가 등 전체 설정 옵션은 설정 가이드를 참조하세요.

로드맵

계획된 기능 및 개선사항:

자동화된 테스트를 위한 CI/CD 파이프라인
추가 MCP 서버 통합 / 더 많은 예제 노트북
성능 벤치마크 및 최적화
원활한 도구 탐색을 위한 개선된 검색 도구
Claude 스킬 통합
DeepAgents CLI 통합 (가능성 추가 조사 필요)

기여하기

커뮤니티의 기여를 환영합니다! 다음과 같은 방식으로 도움을 주실 수 있습니다:

코드 기여 - 버그 수정, 새로운 기능, 개선사항 (CI/CD 곧 출시 예정)
사용 사례 - 프로덕션 또는 연구에서 PTC를 사용하는 방법 공유
예제 노트북 - 다양한 워크플로우를 보여주는 데모 제작
MCP 서버 - PTC와 잘 작동하는 MCP 서버 구축 또는 추천 (데이터 처리, API 등)
프롬프트 기법 - 에이전트 성능을 향상시키는 프롬프팅 기법 공유

기여하려면 GitHub에서 이슈 또는 PR을 생성해 주세요!

감사의 말

이 프로젝트는 다음 연구 및 도구를 기반으로 합니다:

연구/문서

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.

프레임워크 및 인프라

LangChain DeepAgents - 기본 에이전트 프레임워크
Daytona - 샌드박스 인프라

스타 히스토리

이 프로젝트가 유용하다고 생각하시면 별표를 눌러주세요! 다른 사람들이 이 작업을 발견하는 데 도움이 됩니다.

라이선스

MIT License

Jeongsk

탐색기

README