이 문서는 자라는 중인 질문입니다. 아직 증거를 모으고 있으며, 내용이 바뀔 수 있습니다.
Claude Agent SDK는 에이전트 개발 도구들이 너무 빨리 갈라지는 흐름을 볼 때 남겨 둬야 하는 이름이야. 같은 “에이전트”라도 어떤 도구는 단순한 모델 호출을 감싸고, 어떤 도구는 상태와 사람 승인, 관측까지 맡아. Claude Agent SDK는 그 스펙트럼에서 Anthropic 쪽이 어떤 추상화를 직접 제공하려는지 확인해야 하는 지점이야.
지금 확인된 것은 제한적이야. Anthropic은 에이전트를 만드는 글에서 Claude Agent SDK를 여러 프레임워크 중 하나로 언급하고, 이런 프레임워크가 LLM 호출, 도구 정의와 파싱, 호출 연결 같은 낮은 수준의 작업을 쉽게 시작하게 해 준다고 설명해.1 Microsoft도 Foundry 런타임이 Microsoft 바깥에서 만든 에이전트를 받아들일 수 있다고 말하면서 Claude Agent SDK를 예시 중 하나로 든다.2 그래서 이 페이지는 아직 완성된 제품 설명이 아니라, 앞으로 무엇을 확인해야 하는지 잡아 두는 seed에 가깝다.
한 줄로 말하면
Claude Agent SDK는 Claude 기반 에이전트를 만들 때 모델 호출, 도구 연결, 실행 흐름 같은 반복 작업을 프레임워크로 감싸려는 Anthropic 생태계의 개발 도구로 봐야 해.
무엇인가
Anthropic의 공식 글은 에이전트 시스템을 workflow와 agent로 나눠 설명해. workflow는 LLM과 도구가 미리 정한 코드 경로를 따라 움직이는 시스템이고, agent는 LLM이 자기 과정과 도구 사용을 더 동적으로 지휘하는 시스템이야.1
Claude Agent SDK는 이 구분 안에서 “에이전트를 만들기 쉽게 하는 프레임워크” 쪽에 놓인다. Anthropic은 이런 프레임워크가 시작을 빠르게 해 주지만, 프롬프트와 응답 아래에 추상화 층을 추가해 디버깅을 어렵게 만들 수 있다고도 경고해.1 그러니까 이 SDK를 읽을 때는 기능 목록보다 더 중요한 질문이 있어. 어디까지를 SDK가 대신하고, 어디부터는 개발자가 직접 이해해야 하는가야.
여기서 Model Context Protocol(MCP)과의 관계도 중요해. Anthropic은 도구·외부 시스템과 연결하는 한 방법으로 MCP를 함께 설명해. SDK가 agent loop를 감싸는 쪽이라면, MCP는 에이전트가 외부 도구와 자원을 만나는 연결 규약에 가까워. 둘을 섞어 읽으면 “에이전트를 만든다”는 말 안에 실행 반복과 도구 연결이라는 다른 층이 들어 있다는 점이 보인다.
왜 계속 등장하는가
에이전트 프레임워크는 단순한 개발 편의 도구가 아니야. 어느 프레임워크를 쓰느냐에 따라 도구 결과가 다음 모델 호출에 어떻게 들어가고, 중간 상태를 어디에 보존하고, 오류가 났을 때 어디서 다시 시작하는지가 달라져. 이건 agent loop와 context engineering의 실제 구현 문제야.
Claude Agent SDK가 반복해서 봐야 할 이름인 이유도 여기에 있어. Anthropic은 agentic system을 만들 때 가장 단순한 해결책부터 시작하라고 강조해. 프레임워크는 낮은 수준 작업을 줄여 주지만, 복잡도를 쉽게 늘리는 유혹도 만든다고 말하지.1 이 조언은 Claude Agent SDK를 홍보 문구로만 읽지 말고, 추상화 비용까지 같이 보라는 뜻에 가깝다.
Microsoft Foundry 문맥에서는 이 이름이 또 다른 의미를 가져. Microsoft는 Foundry가 Microsoft Agent Framework뿐 아니라 LangGraph, GitHub Copilot SDK, Claude Agent SDK, custom harness로 만든 에이전트도 실행 대상으로 받을 수 있다고 설명해.2 이건 기업용 런타임이 특정 SDK 하나만 강제하기보다, 여러 에이전트 제작 도구를 통제면 안으로 들이려는 흐름을 보여줘.
이 대상을 볼 때의 핵심 축
첫 번째 축은 실행 반복을 누가 소유하느냐야. SDK가 도구 호출, 결과 반영, 중단 조건, 재시도까지 맡는지, 아니면 개발자가 루프를 직접 짜고 SDK는 모델 호출과 도구 정의만 돕는지 확인해야 해.
두 번째 축은 맥락의 경계야. 대화 기록, 도구 결과, 파일 상태, 사용자 승인, 외부 시스템 응답 중 무엇이 다음 호출의 맥락으로 들어가는지가 중요해. 이 경계가 흐려지면 에이전트는 똑똑해 보이지만 디버깅하기 어려워져.
세 번째 축은 도구와 권한이야. Claude Agent SDK가 MCP와 어떤 방식으로 붙는지, 도구 설명과 권한 범위를 어떻게 드러내는지 봐야 해. 에이전트가 행동하는 순간부터 도구 연결은 편의 기능이 아니라 보안 경계가 된다.
네 번째 축은 관측과 운영이야. 실제 업무에 쓰려면 실행 기록, tracing, 평가, 사람 개입 지점이 필요해. Microsoft가 Foundry에서 evals와 traces를 강조하는 것도 같은 이유야.2
최근 관찰된 신호
Anthropic의 에이전트 구축 글은 Claude Agent SDK를 “복잡한 프레임워크를 쓰라”는 결론으로 내세우지 않아. 오히려 직접 API를 쓰는 단순한 구현에서 시작하고, 프레임워크를 쓰더라도 내부 코드를 이해하라고 말해.1 이건 Anthropic이 에이전트 프레임워크를 제공하더라도, 프레임워크 자체를 만능 해법으로 보지는 않는다는 신호야.
Microsoft Foundry 글은 다른 방향의 신호를 준다. 기업 런타임은 여러 SDK와 harness로 만든 에이전트를 받아들이고, 그 위에 도구 실행, 평가, trace, 보안 정책을 씌우려 해.2 Claude Agent SDK는 이 그림에서 특정 모델 회사의 SDK인 동시에, 기업용 런타임이 받아들여야 할 외부 에이전트 형식 중 하나가 된다.
헷갈리지 말아야 할 점
Claude Agent SDK를 Claude 모델 자체와 섞으면 안 돼. 모델은 추론을 하고, SDK는 그 추론을 도구·상태·흐름과 엮는 개발 계층에 가까워.
또 SDK가 있다고 해서 agentic workflow가 자동으로 잘 설계되는 것도 아니야. Anthropic의 조언은 오히려 반대에 가까워. 먼저 단순한 LLM 호출과 작은 workflow로 충분한지 보고, 더 복잡한 agent 구조는 성능 이득이 지연·비용·디버깅 비용을 이길 때만 붙이라는 쪽이야.
마지막으로, Claude Agent SDK와 LangGraph, OpenAI Agents SDK를 같은 이름표로만 비교하면 놓치는 게 많아. 어떤 도구는 낮은 수준 오케스트레이션에 강하고, 어떤 도구는 모델 회사의 API와 tracing, handoff, session을 더 자연스럽게 묶을 수 있어. 앞으로 봐야 할 것은 이름의 유명세가 아니라, 같은 업무에서 어느 추상화가 상태와 검증을 더 잘 드러내는지야.
이어서 읽기
에이전트 실행 반복의 기본 구조는 agent loop에서 먼저 보면 돼. 업무 전체의 권한·기록·검증 구조는 agentic workflow가 더 큰 지도를 줘.
외부 도구 연결의 표준은 Model Context Protocol(MCP)에서 이어진다. 여러 에이전트가 서로 일을 넘기는 쪽은 multi-agent collaboration과 A2A protocol이 비교점이야. 상태 있는 실행 그래프를 보는 대표 도구는 LangGraph야.
남은 질문들
- Claude Agent SDK의 공식 API는 agent loop, tool call, memory, handoff, tracing을 각각 어디까지 맡을까?
- Claude Agent SDK는 MCP 서버와 어떤 방식으로 연결되고, 도구 권한과 설명 변경을 어떻게 다룰까?
- Claude Code나 Claude Desktop에서 쓰는 실행 모델과 Claude Agent SDK는 같은 구조를 공유할까, 아니면 별도 개발자용 추상화일까?
- LangGraph, OpenAI Agents SDK, Microsoft Agent Framework와 비교하면 Claude Agent SDK의 장점과 디버깅 비용은 어디서 갈릴까?
댓글