Open Agent SDK 소개
Open Agent SDK는 에이전트 루프 전체를 별도의 서브프로세스나 CLI 없이 애플리케이션과 같은 프로세스 안에서(in-process) 실행하는 오픈소스 Agent SDK입니다. 스스로를 claude-agent-sdk의 대안으로 소개하며, Anthropic API와 OpenAI 호환 API를 모두 지원합니다. CLI 의존성이 없기 때문에 클라우드, 서버리스, Docker, CI/CD 등 어디에든 그대로 배포할 수 있습니다. TypeScript 패키지(@codeany/open-agent-sdk)로 배포되며, 같은 구조의 Go 버전(open-agent-sdk-go)도 별도로 제공됩니다.
모델 선택도 유연합니다. apiType 은 모델 이름에서 자동 감지되어, gpt-, o1, o3, deepseek, qwen, mistral 등이 포함되면 OpenAI 호환 경로를 사용합니다. 덕분에 OpenAI, DeepSeek, Qwen, Mistral은 물론 OpenRouter 같은 Anthropic 호환 프록시까지 환경 변수 몇 개로 연결할 수 있습니다.
Open Agent SDK의 아키텍처
Open Agent SDK는 애플리케이션 코드 바로 아래에 네 개의 계층을 쌓은 구조입니다. 위에서부터 차례로 진입점인 Agent 계층, 에이전트 루프를 도는 QueryEngine, 모델 API 차이를 흡수하는 Provider 계층, 그리고 실제 작업을 수행하는 도구·MCP 계층이 놓입니다.
┌──────────────────────────────────────────┐
│ 사용자 애플리케이션 │
│ import { createAgent } from '...' │
└────────────────────┬───────────────────────┘
│
┌────────▼────────┐
│ Agent │ 세션 상태, 도구 풀,
│ query()/prompt() │ MCP 연결, 훅 관리
└────────┬────────┘
│
┌────────▼────────┐
│ QueryEngine │ 에이전트 루프:
│ submitMessage() │ API 호출 → 도구 실행 → 반복
└────────┬────────┘
│
┌─────────────┼─────────────┐
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Provider │ │ 35+ 도구 │ │ MCP │
│ Anthropic│ │ Bash,Read│ │ 서버들 │
│ OpenAI │ │ Edit,... │ │ stdio/ │
│ DeepSeek │ │ + 스킬 │ │ SSE/HTTP│
└─────────┘ └─────────┘ └─────────┘
- Agent 계층:
createAgent()/query()진입점입니다. 세션 상태, 도구 풀, MCP 연결, 훅을 관리합니다. - QueryEngine: 에이전트 루프의 핵심입니다.
submitMessage()가 API 호출 → 도구 실행 → 결과 반영을 모델이 멈출 때까지 반복하며, 자동 컴팩트·재시도·도구 오케스트레이션이 여기에 통합되어 있습니다. - Provider 계층: Anthropic Messages API와 OpenAI Completions API의 차이를 추상화합니다. DeepSeek, Qwen, Mistral 등 OpenAI 호환 엔드포인트도 이 계층을 거칩니다.
- 도구·MCP 계층: 35종 이상의 내장 도구와 번들 스킬, 그리고 stdio·SSE·HTTP·인-프로세스(SDK)로 연결되는 MCP 서버가 붙습니다.
엔진에는 장시간 실행과 비용 관리를 위한 내부 장치가 함께 들어 있습니다.
| 구성요소 | 설명 |
|---|---|
| 자동 컴팩트(Auto-compact) | 컨텍스트 윈도우가 차면 대화를 요약 |
| 마이크로 컴팩트(Micro-compact) | 과도하게 큰 도구 결과를 잘라냄 |
| 재시도(Retry) | 속도 제한과 일시 오류에 지수 백오프로 대응 |
| 토큰 추정 | Claude, GPT, DeepSeek 모델의 토큰 수와 비용을 대략 추정 |
| 파일 캐시 | 파일 읽기용 LRU 캐시(100개 항목, 25MB) |
| 세션 저장소 | 세션을 디스크에 저장(persistSession)하고 ID로 재개(resume)하거나 분기(forkSession) |
| 컨텍스트 주입 | Git 상태와 AGENT.md 를 시스템 프롬프트에 자동 주입 |
Open Agent SDK의 핵심 구성요소
내장 도구는 35종 이상으로, Bash, Read, Write, Edit, Glob, Grep 같은 파일·셸 도구부터 WebFetch, WebSearch, 서브에이전트를 띄우는 Agent, 작업 관리용 TaskCreate/TaskList 계열, 멀티 에이전트 조율용 TeamCreate·SendMessage, Git 워크트리 격리(EnterWorktree)까지 포함합니다. 여기에 simplify, commit, review, debug, test 다섯 가지 번들 스킬이 기본 제공되며, registerSkill() 로 직접 만든 스킬을 등록할 수 있습니다.
수명주기 훅은 20종입니다. PreToolUse, PostToolUse, SessionStart, Stop, SubagentStart, PermissionRequest, PreCompact 등 엔진의 각 단계에 콜백을 끼워 넣을 수 있고, PreToolUse 훅에서 { block: true } 를 반환하면 도구 실행 자체를 막을 수 있습니다. MCP 서버는 stdio·SSE·HTTP·인-프로세스(SDK) 방식으로 연결되며, Zod 스키마로 정의한 도구를 createSdkMcpServer() 로 묶어 인-프로세스 MCP 서버로 노출할 수도 있습니다.
실행을 제어하는 옵션도 풍부합니다. 도구 허용·차단 목록(allowedTools/disallowedTools)과 권한 모드(default/acceptEdits/dontAsk/bypassPermissions/plan), 호출당 권한을 직접 판단하는 canUseTool 콜백으로 에이전트의 행동 범위를 좁힐 수 있습니다. 비용·시간 측면에서는 최대 턴 수(maxTurns)와 지출 상한(maxBudgetUsd), 추론 노력 단계(effort: low/medium/high/max)와 확장 사고(thinking)를 설정할 수 있고, JSON 스키마로 응답 형식을 강제하는 구조화 출력(outputFormat)과 파일·네트워크 샌드박스(sandbox)도 지원합니다.
세션 관리도 SDK 안에서 처리됩니다. 세션을 디스크에 저장(persistSession)하고, ID로 재개(resume)하거나 분기(forkSession)할 수 있으며, Git 상태와 AGENT.md 가 시스템 프롬프트에 자동 주입됩니다.
Open Agent SDK 설치 및 사용법
설치는 npm 한 줄이고, API 키는 환경 변수로 설정합니다.
npm install @codeany/open-agent-sdk
export CODEANY_API_KEY=your-api-key
createAgent 로 재사용 가능한 에이전트를 만들어 블로킹 방식으로 호출하는 최소 예시는 다음과 같습니다.
import { createAgent } from "@codeany/open-agent-sdk";
const agent = createAgent({ model: "claude-sonnet-4-6" });
const result = await agent.prompt("What files are in this project?");
console.log(result.text);
console.log(
`Turns: ${result.num_turns}, Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`,
);
OpenAI 호환 모델은 apiType 과 baseURL 만 지정하면 됩니다.
const agent = createAgent({
apiType: "openai-completions",
model: "gpt-4o",
apiKey: "sk-...",
baseURL: "https://api.openai.com/v1",
});
스트리밍이 필요하면 query() 제너레이터를 사용합니다. 저장소의 examples/ 에는 스트리밍 쿼리, 멀티턴 세션, 커스텀 도구, MCP 연동, 서브에이전트, 훅 등 14개의 번호별 예제가 들어 있고, examples/web/ 의 내장 웹 채팅 UI는 npx tsx examples/web/server.ts 로 띄워 바로 테스트할 수 있습니다. Node.js 18 이상이 필요합니다.
Open Agent SDK의 라이선스
Open Agent SDK는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
Open Agent SDK GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다!
텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 