Claude Code로 만드는 AI 에이전트 입문 | 에이전트 SDK의 기본과 구현 예시

「AI 에이전트 (AI Agent)」라는 말은 자주 듣지만, 실제로 자신의 코드에서 구동하려면 어떻게 해야 할지 모르겠다…… 그렇게 느끼고 계시지 않나요? Claude Code의 이면에서 작동하는 메커니즘은 사실 자신의 Python이나 TypeScript 코드에서 그대로 호출할 수 있습니다. 이 기사에서는 Claude Code를 사용하여 AI 에이전트를 만드는 첫걸음을 설치부터 구현 예시까지 순서대로 해설합니다.

결론부터 말하자면, Claude Code의 CLI를 지탱하고 있는 메커니즘은 「Claude Agent SDK」라는 라이브러리로 Python·TypeScript용으로 공개되어 있습니다. pip install claude-agent-sdk

또는 npm install @anthropic-ai/claude-agent-sdk

를 실행하고, query()

라는 함수에 프롬프트 (Prompt)를 전달하는 것만으로, 파일을 읽고·편집하고·명령어를 실행하는 등의 일련의 작업을 자율적으로 수행하는 AI 에이전트가 움직이기 시작합니다. AI 에이전트를 직접 만드는 것은 힘들 것 같다고 느끼고 계시지 않나요? 실제로는 API 호출 루프 (Loop)를 직접 작성할 필요가 없으며, 생각보다 훨씬 적은 코드로 시작할 수 있습니다.

이유는 Anthropic의 일반적인 Messages API에서는 「모델이 도구 (Tool)를 사용하고 싶다고 하면, 직접 그 도구를 실행하여 결과를 반환한다」라는 루프를 직접 작성해야 하지만, Agent SDK에서는 그 루프 자체를 SDK가 대신 실행해 주기 때문입니다. 즉, 파일 읽기/쓰기나 명령어 실행과 같은 처리를 직접 구현하지 않아도, Claude가 직접 도구를 실행하고 결과만 반환되는 구조로 되어 있습니다. 저는 이 차이를 알았을 때, 생각보다 에이전트 개발의 허들이 낮다고 느꼈습니다.

여기서부터는 실제로 AI 에이전트를 구동하기까지의 흐름을 순서대로 살펴보겠습니다.

Python과 TypeScript 모두 한 줄로 설치할 수 있습니다.

언어	설치 명령어	필요 조건
Python	pip install claude-agent-sdk	Python 3.10 이상
TypeScript	npm install @anthropic-ai/claude-agent-sdk	별도 사항 없음 (CLI 바이너리도 동봉)

설치 후, ANTHROPIC_API_KEY를 환경 변수에 설정하면 인증이 완료됩니다. TypeScript 버전은 Claude Code의 CLI 바이너리를 내부에 동봉하고 있기 때문에, 별도로 Claude Code를 설치할 필요가 없습니다.

최소 구성의 AI 에이전트는 다음과 같은 코드로 작동합니다.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
...

query()는 비동기 제너레이터 (Asynchronous Generator)로, Claude가 생각한 내용·도구 호출·도구 실행 결과·최종 결과까지 일련의 메시지를 순서대로 흘려보내 줍니다. TypeScript에서도 같은 느낌으로 작성할 수 있습니다.

import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "auth.ts의 버그를 찾아 수정해 주세요",
...

allowed_tools (Python) / allowedTools (TypeScript)에 지정한 도구만이 해당 AI 에이전트에서 사용할 수 있게 됩니다. 지정하지 않은 도구는 모델에게 아예 보이지 않기 때문에, 이것이 가장 기본적인 권한 관리 방법이 됩니다.

❌ 모든 도구를 허용한 채로 본番 운용하기

✅ 「조사 전용이라면 Read·Glob·Grep만」「수정도 허용한다면 Edit을 추가」와 같이 용도별로 좁히기

◎ 편집계 AI 에이전트에는 permission_mode="acceptEdits"와 같은 옵션도 조합하기

내장 도구뿐만 아니라, 직접 정의한 함수를 AI 에이전트가 사용하게 할 수도 있습니다. Python에서는 @tool 데코레이터 (Decorator)로 도구를 정의하고, create_sdk_mcp_server로 한꺼번에 에이전트에게 전달합니다.

from claude_agent_sdk import tool, create_sdk_mcp_server
@tool("get_weather", "지정된 도시의 날씨를 가져옵니다", {"city": str})
async def get_weather(args):
...

사내 시스템이나 독자적인 API와 연동하고 싶은 AI 에이전트를 만들 때, 이 메커니즘이 토대가 됩니다.

최소 구성의 AI 에이전트는 몇 분 만에 구동할 수 있지만, 업무에서 사용할 수 있는 수준으로 키우기 위해서는 한 단계 더 높은 설계가 필요합니다. 제가 실제로 몇 가지 시도해 보며 느낀 포인트들을 정리해 보겠습니다.

설계 포인트	내용	이유
도구 권한을 최소한으로 제한하기	필요한 도구만 allowed_tools에 나열하기	예상치 못한 파일 변경이나 명령 실행을 방지하기 위해
인증은 API 키로 수행하기	claude.ai의 로그인이나 계약 플랜의 Rate Limit(속도 제한)은 SDK를 통한 외부 제공 시 사용할 수 없음	상용 이용 정책상 API 키 인증이 전제되어야 함
CLI와 SDK를 구분하여 사용하기	대화형 개발은 CLI, 자동화 및 본운용은 SDK	용도에 따라 최적의 인터페이스가 다름
MCP 서버로 외부 연동하기	사내 시스템이나 SaaS와의 연동은 MCP를 통해 전달하기	독자적인 도구를 매번 작성하지 않고 재사용할 수 있음

Claude Code를 평소 터미널에서 사용하고 있는 사람일수록, "CLI에서 쓸 수 있는 것은 SDK에서도 그대로 할 수 있을 것"이라고 생각하기 쉽습니다. 하지만 실제로는 대화형 개발에는 CLI가 적합하고, CI/CD 파이프라인이나 자사 서비스로의 임베딩(Embedding)과 같은 자동화에는 SDK가 적합하다는 역할 분담이 되어 있습니다. 저는 처음에 이 차이를 의식하지 않고 진행했다가, 본운용을 상정한 설계를 나중에 다시 수정해야 하는 상황을 겪었습니다. 초기 단계에서 "이것은 사람이 대화하는 용도인가, 아니면 자동화하여 구동하는 용도인가"를 나누어 생각하는 것이 결과적으로 재작업을 줄이는 요령이라고 생각합니다.

처음부터 큰 권한을 부여하는 것이 아니라, Read(읽기) 계열의 도구로만 구동해 보고 동작이 납득되면 조금씩 Write(쓰기) 계열의 도구를 추가해 나가는 방식을 추천합니다. Qiita에서도 다시 찾아보고 싶어질 만한 "키워나가는 AI 에이전트"의 이미지로, 단계적으로 확장해 나가는 것이 안전하다고 느꼈습니다.

• ✅ Claude Agent SDK를 사용하면, 도구 실행 루프(Tool Execution Loop)를 직접 작성하지 않고도 AI 에이전트를 만들 수 있다
• ✅ allowed_tools로 도구를 제한하는 것이 가장 기본적인 권한 관리이다
• ◎ 독자적인 도구는 @tool 데코레이터(Decorator)와 create_sdk_mcp_server로 추가할 수 있다
• ✅ 대화형 개발은 CLI, 자동화 및 본운용은 SDK라는 역할 분담을 의식한다
• ◎ 처음에는 읽기 전용 도구로만 구동하고, 단계적으로 권한을 넓혀간다