# Open Agent SDK: CLI 없이 프로세스 내에서 실행되는 오픈소스 에이전트 SDK

**URL:** <https://discuss.pytorch.kr/t/open-agent-sdk-cli-sdk/10587>\
**Category:** 읽을거리&정보공유\
**Tags:** open-agent-sdk, llm-agent, openai-compatible, agent-sdk, anthropic, typescript, mcp\
**Created:** [6월 10, 2026, 3:30오전 UTC](https://discuss.pytorch.kr/t/open-agent-sdk-cli-sdk/10587 "2026-06-10T03:30:08Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![9bow](https://discuss.pytorch.kr/user_avatar/discuss.pytorch.kr/9bow/32/16301_2.png) [@9bow](https://discuss.pytorch.kr/u/9bow)\
**Post date:** [6월 10, 2026, 3:30오전 UTC](https://discuss.pytorch.kr/t/open-agent-sdk-cli-sdk/10587/1 "2026-06-10T03:30:08Z")

</div>

![Open Agent SDK: CLI 없이 인-프로세스로 도는 오픈소스 에이전트 SDK](https://discuss.pytorch.kr/uploads/default/original/3X/7/5/75bb4201bf8adae843336f67cab4b2456aa2de90.jpeg)

## 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](https://github.com/codeany-ai/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 계층이 놓입니다.

```auto
┌──────────────────────────────────────────┐
│ 사용자 애플리케이션 │
│ 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의 핵심 구성요소

 ![Open Agent SDK의 핵심 구성요소 다이어그램](https://discuss.pytorch.kr/uploads/default/original/3X/0/6/064d238661535bb046b8d2a1e0f4e2a6b439f301.jpeg)

내장 도구는 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 키는 환경 변수로 설정합니다.

```bash
npm install @codeany/open-agent-sdk
export CODEANY_API_KEY=your-api-key

```

`createAgent` 로 재사용 가능한 에이전트를 만들어 블로킹 방식으로 호출하는 최소 예시는 다음과 같습니다.

```typescript
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` 만 지정하면 됩니다.

```typescript
const agent = createAgent({
  apiType: "openai-completions",
  model: "gpt-4o",
  apiKey: "sk-...",
  baseURL: "https://api.openai.com/v1",
});

```

스트리밍이 필요하면 `query()` 제너레이터를 사용합니다. 저장소의 [`examples/`](https://github.com/codeany-ai/open-agent-sdk-typescript/tree/main/examples) 에는 스트리밍 쿼리, 멀티턴 세션, 커스텀 도구, MCP 연동, 서브에이전트, 훅 등 14개의 번호별 예제가 들어 있고, [`examples/web/`](https://github.com/codeany-ai/open-agent-sdk-typescript/tree/main/examples/web) 의 내장 웹 채팅 UI는 `npx tsx examples/web/server.ts` 로 띄워 바로 테스트할 수 있습니다. Node.js 18 이상이 필요합니다.

## Open Agent SDK의 라이선스

Open Agent SDK는 [MIT 라이선스](https://github.com/codeany-ai/open-agent-sdk-typescript/blob/main/LICENSE)로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

## :github: Open Agent SDK GitHub 저장소

> **[GitHub - codeany-ai/open-agent-sdk-typescript: Agent-SDK without CLI dependencies, as an...](https://github.com/codeany-ai/open-agent-sdk-typescript)**
>
> Agent-SDK without CLI dependencies, as an alternative to claude-agent-sdk, completely open source

## 더 읽어보기

- [Pydantic AI Harness: Pydantic AI 에이전트를 위한 공식 기능 라이브러리](https://discuss.pytorch.kr/t/pydantic-ai-harness-pydantic-ai/10479)

- [Claude Code 동적 워크플로우(Dynamic Workflows): 작업마다 하네스를 직접 짜는 병렬 오케스트레이션](https://discuss.pytorch.kr/t/claude-code-dynamic-workflows/10519)

- [Nango: AI 에이전트와 제품을 800여 개 API에 연결하는 통합 플랫폼](https://discuss.pytorch.kr/t/nango-ai-800-api/10492)

- [Odysseus: 내 하드웨어에서 데이터까지 직접 관리하는 자체 호스팅 AI 워크스페이스](https://discuss.pytorch.kr/t/odysseus-ai/10522)

* * *

_이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다._ 🤗

[:pytorch:파이토치 한국 사용자 모임🇰🇷](https://pytorch.kr/)이 정리한 이 글이 유용하셨나요? [회원으로 가입](https://discuss.pytorch.kr/signup)하시면 주요 글들을 이메일💌로 보내드립니다!  
[텔레그램(Telegram)](https://t.me/pytorchkr)이나 [Slack/Discord/Teams/Dooray/GoogleChat 등](https://discuss-noti.pytorch.kr)으로도 새 글 알림을 받으실 수 있습니다. 😃

🎁 아래↘쪽에 좋아요👍를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 🤩