에이전트 프레임워크, 어느 걸 쓰나 (대개는 안 쓰는 게 답)
멀티에이전트 오케스트레이션·상태 영속·human-in-the-loop 가 필요해서 프레임워크를 고를 때 연다. 결론 먼저: 대부분의 실무 작업은 프레임워크 없이 SDK 직접 루프가 낫다. 아래 "프레임워크 없이 직접 짜는 게 나은 경우" 섹션을 먼저 읽어라.
신선도 경고. 이 판은 릴리스가 주 단위로 도는 영역이다. 버전 번호는 캡처 시점(
(verified 2026-07)) 기준이며 곧 낡는다. 개념·추상화 모델은 오래 가지만 버전은 반드시 원 저장소에서 재확인하라.
추상화 모델별 분류
프레임워크를 고르는 첫 축은 "무엇으로 제어 흐름을 표현하나"다. 이 분류가 러닝커브·디버깅 방식을 결정한다. [inferred]
| 분류 | 프레임워크 | 제어 표현 방식 |
|---|---|---|
| 명시적 그래프형 | LangGraph, ADK 2.0, Mastra, MS Agent Framework | 노드·엣지·상태를 코드로 선언. 결정론적 경로. |
| 역할 + 핸드오프형 | CrewAI, OpenAI Agents SDK | 에이전트가 다른 에이전트에게 위임(handoff). LLM 이 흐름 판단. |
| 타입안전 경량 | Pydantic AI | 단일 에이전트 + tool, 타입 힌트로 정적 검증. |
| Claude Code 라이브러리형 | Claude Agent SDK | 내장 툴·루프·훅을 통째로 라이브러리화. |
프레임워크별 요약 표
| 프레임워크 | 핵심 추상화 | 언어 | 성숙도·최신판 (verified 2026-07) |
|---|---|---|---|
| LangGraph | 그래프(노드/엣지/상태) + 영속성 이중구조 | Python, JS/TS | 성숙. 구체 버전 번호 미확보 (재확인 필요) |
| OpenAI Agents SDK | Agents/Handoffs/Guardrails + Sessions/Tracing | Python 중심 + 별도 JS/TS | Swarm 후속, Responses API 기반. 버전 미확보 (재확인 필요) |
| Google ADK 2.0 | Workflow Runtime(그래프 실행엔진) | Python·TS·Go·Java·Kotlin | Python 2.0 GA 2026-05-19, Go 2.0 GA 2026-06-30. Python 최신 v2.5.0 (재확인 필요, 1.x 병존) |
| CrewAI | Crew(협업 그룹) + Flow(상위 오케스트레이션) | Python | 최신 1.15.6 (stable/latest 구분 재확인 필요) |
| Pydantic AI | 타입안전 에이전트 + Toolsets + pydantic-graph | Python | stable 2.0 = 2026-06-23, 최신 v2.17.0 (빨리 낡음) |
| Mastra | 그래프 워크플로 .then()/.branch()/.parallel() |
TypeScript | v1.0 = 2026-01, 최신 @mastra/core@1.51.0 |
| MS Agent Framework | 그래프 워크플로(seq/concurrent/handoff/group-chat) + checkpointing | .NET, Python | RC 2026-02, 1.0 GA 2026-04-02 (04-03설과 하루차, 재확인 필요) |
| Claude Agent SDK | Claude Code 라이브러리(내장툴·루프·훅·subagents) | Python, TS | 최신 v0.2.127, 상태 라벨 Alpha 계열 |
각 항의 세부 강점:
- LangGraph — 영속성이 이중구조다. Checkpointer(thread 스코프 단기 메모리,
thread_id로 접근)와 Store(cross-thread 장기 메모리)가 별개다. 백엔드는InMemorySaver(개발용, 재시작 시 소실) /PostgresSaver(프로덕션) /SqliteSaver(로컬 파일). 체크포인트가 단조증가 ID 로 스냅샷되어 time travel(되감기)·human-in-the-loop·fault tolerance(중단 후 재개)를 지원한다. - OpenAI Agents SDK — 프리미티브 4개가 전부라 학습이 얕다. Handoff 는 LLM 에게 tool 로 노출된다(
Refund Agent→transfer_to_refund_agent툴). 세션 백엔드 선택지가 넓다(SQLAlchemy/SQLite/Redis/MongoDB/Dapr/암호화). - Google ADK 2.0 — 5개 언어 중 유일하게 폭넓다. 2.0 에서 계층적 executor → 그래프 기반 실행엔진으로 전환했다. Gemini 최적화지만 LiteLLM 으로 타 모델도 붙는다.
- CrewAI — Crew(단일 컨텍스트에서 협업하는 에이전트 그룹) 위에 Flow(조건 로직·상태·이벤트 트리거로 여러 crew 를 엮는 상위 계층)를 얹는 2층 구조.
- Pydantic AI — Pydantic 팀 제작(MIT). 완전 타입 안전 + IDE 지원. 관측성은 Logfire 연동. Toolsets·MCP·HITL tool approval·
pydantic-graph·durable execution 지원. "좁고 잘 정의된 작업"에 가벼운 선택으로 자주 거론된다. - Mastra — TS 진영 대표. 그래프 워크플로를
.then()/.branch()/.parallel()체이닝으로 짠다. Durable Agent 크래시 복구(listActiveRuns()/recoverActiveRuns()로 재시작 후 고아 run 회복)가 차별점. - MS Agent Framework — Semantic Kernel + AutoGen 의 공식 후속(동일 팀). 두 전작은 maintenance mode(버그·보안만)로 들어갔다. MCP + A2A 가 네이티브다.
선택 결정표
| 상황 | 추천 방향 |
|---|---|
| 단일 LLM 호출 + tool 몇 개 | 프레임워크 없이 SDK 직접 (아래 섹션) |
| Claude Code 스타일 코딩 에이전트를 앱에 내장 | Claude Agent SDK (내장 툴·훅 그대로) |
| 이미 Claude API 를 쓰고 루프만 편하게 | Anthropic Tool Runner (베타) |
| TypeScript 웹앱(Next.js 등)에 에이전트 통합 | Mastra |
| Python 타입 안전 + 좁은 작업 | Pydantic AI |
| 복잡한 상태·time travel·중단 후 재개 | LangGraph |
| .NET 생태계 / SK·AutoGen 마이그레이션 | MS Agent Framework |
| Gemini 중심 + 다언어(Go/Java 등) | Google ADK 2.0 |
| 역할 분담형 멀티에이전트를 빠르게 프로토타이핑 | CrewAI / OpenAI Agents SDK |
⭐ 프레임워크 없이 직접 루프 짜는 게 나은 경우 (대부분 여기 해당)
실무 결론부터: 당신이 하려는 일 대부분은 프레임워크가 필요 없다. 아래 조건이면 anthropic-messages-api 또는 vercel-ai-sdk 로 while 루프 하나 도는 게 더 명확하고 디버깅 쉽다. [inferred]
프레임워크 없이 직접 짜라: - 단일 에이전트 + tool 몇 개로 끝난다 (핸드오프·다중 에이전트 없음). - 제어 흐름을 당신이 코드로 쥐고 싶다 — 프레임워크의 그래프 DSL 을 학습·디버깅하기보다. - 상태를 이미 당신 DB(Postgres 등)에 두고 있다 — 프레임워크의 체크포인터 추상화가 오히려 계층을 늘린다. - 스택 추적이 프레임워크 내부로 사라지는 걸 감당할 수 없다.
Anthropic 만 쓴다면 SDK 안에 이미 루프 도구가 있다. 프레임워크 대신 이걸 먼저 봐라:
- Tool Runner (베타): Python @beta_tool + client.beta.messages.tool_runner(...), TS betaZodTool + client.beta.messages.toolRunner(...). 툴 호출 루프만 대신 돌려준다. 내장 툴은 없다. → set-up-tool-use
- 서버측 툴 루프(web_search 등)는 pause_turn 으로 끊긴다. assistant 응답을 그대로 붙여 재요청하면 이어진다("계속해" 메시지 추가 금지).
프레임워크를 쓸 명분은 아래가 실제로 필요할 때뿐이다: 다중 에이전트 오케스트레이션, 상태 영속·time travel, human-in-the-loop, 내장 관측성. 이것 없이 "나중에 필요할지 몰라서" 프레임워크를 까는 건 규격 위반급 과잉 설계다.
Claude Agent SDK vs Tool Runner vs Managed Agents (혼동 주의 박스)
세 개는 완전히 다른 물건이다. Anthropic 사실은 [HIGH] 1차 기준이다.
| 구분 | 정체 | 내장 툴 | 어디서 도나 |
|---|---|---|---|
Claude Agent SDK (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) |
Claude Code 를 라이브러리화한 별개 제품 | 있음 (파일·bash·MCP 등) | 당신 프로세스. agent loop·hooks(PreToolUse 등)·subagents(run_in_background)·sessions 포함 |
| Tool Runner (베타) | 일반 Anthropic SDK 안의 루프 헬퍼 | 없음 | 당신 프로세스. 툴 호출 루프만 대신 돎 |
Managed Agents (베타 managed-agents-2026-04-01) |
Anthropic 이 루프 + 세션별 샌드박스 컨테이너까지 호스팅 | 호스팅 측 | Anthropic 서버. Agent(설정)→Session(실행) 순서 필수, model/system/tools 는 Agent 에 둠 |
claude-code-sdk→claude-agent-sdk로 개명되었다. 옛 이름 문서를 보면 갱신 전 자료다.- Claude Agent SDK Python 최신 v0.2.127
(verified 2026-07)— subagentsrun_in_background, PreToolUse hooks, SDK-MCP,terminal_reason/model_usage반환.
함정 (gotcha)
- 버전 번호를 신뢰하지 마라. 이 영역은 주 단위 릴리스다. 표의 모든 버전은 재확인 대상이다. 특히 Pydantic AI(2.x 가 빠르게 오름)·Claude Agent SDK(0.2.x Alpha 계열).
- LangGraph
thread_id255자 제한. PostgresSaver 의thread_id컬럼이 255자로 제한돼 초과 시 DB 에러가 난다. 긴 복합 키를 thread_id 로 쓰지 마라. - LangGraph Checkpointer ≠ Store. 하나는 thread 단기, 하나는 cross-thread 장기다. 장기 사용자 메모리를 Checkpointer 에 넣으면 thread 밖에서 못 읽는다.
- Google ADK 버전 라인 병존 (재확인 필요). GitHub releases 에 2.x(v2.5.0)와 1.x(v1.36.2)가 동시에 존재한다. 2.x 가 별도 패키지인지 1.x 가 LTS 인지 미확인 — 설치 전 어느 라인을 쓰는지 확인하라.
- OpenAI Handoff 는 tool 이다. 흐름이 코드가 아니라 LLM 판단으로 갈린다. 결정론적 경로가 필요하면 그래프형(LangGraph/Mastra)이 낫다.
- Agent SDK 를 Tool Runner 로 착각하지 마라. 위 박스 참조. 내장 툴이 필요 없는데 Agent SDK 를 깔면 Claude Code 전체를 끌어오는 셈이다.
⛔ 인용 금지 박스. "Claude 구독 플랜에 별도 Agent SDK 크레딧 $20/$100/$200" 는 단일 애그리게이터(helply.com) 출처로 Anthropic 1차·규격서 §7 에서 확인되지 않는다. 각 프레임워크의 GitHub star 수·채택률·벤치마크 정량 점수도 검증 불가·조기 부패 사유로 인용하지 않는다.
참고
- agent-design-patterns — 프레임워크 이전에 알아야 할 에이전트 설계 패턴(루프·평가·오케스트레이션)
- mcp — 대부분 프레임워크가 네이티브 지원하는 툴 연결 프로토콜
- set-up-tool-use — 프레임워크 없이 tool use 루프 직접 짜기 (Tool Runner 포함)
- anthropic-messages-api — 직접 루프의 기반 API
- claude-code-workflow — Claude Agent SDK 의 뿌리인 Claude Code 사용법
- vercel-ai-sdk — TypeScript 에서 직접 루프/에이전트 짜는 대안
출처: 각 프레임워크 공식 docs/GitHub/PyPI 로 확인한 [MED-official] 위주 + 종합 추론 [inferred]. Anthropic 3종 구분은 규격서 §7 [HIGH]. 버전·날짜는 (verified 2026-07), 빠르게 낡는다. 원본 → 2026-07-25-agent-frameworks