빠른 시작은 프로젝트 폴더 생성 → SDK 설치 → API 키 설정 → 예제 파일 준비 → 에이전트 코드 작성 → 실행 흐름으로 안내합니다. Node.js 18+ 또는 Python 3.10+가 필요하고, my-agent 같은 새 디렉토리에서 시작하면 됩니다.
프로젝트 시작
mkdir my-agent
cd my-agentSDK는 Python과 TypeScript를 모두 지원합니다. Python은 uv 또는 pip로 설치할 수 있고, TypeScript는 npm install @anthropic-ai/claude-agent-sdk로 설치합니다.
SDK 설치
Python(권장 예시)
uv init
uv add claude-agent-sdk또는
python3 -m venv .venv
source .venv/bin/activate
pip3 install claude-agent-sdkAPI 키 설정
프로젝트 루트에 .env를 만들고 아래를 넣습니다.
ANTHROPIC_API_KEY=your-api-keyBedrock, Vertex AI, Azure Foundry 같은 타사 인증 방식도 지원하지만, 처음 구현은 직접 API 키 방식이 가장 단순합니다.
테스트용 파일 만들기
에이전트가 수정할 대상 파일을 하나 둡니다. 예시로 utils.py를 생성합니다. 문서의 예제에는 일부러 두 가지 버그가 들어 있습니다. 빈 리스트로 평균을 계산하면 0으로 나누기 오류가 나고, None 사용자에 대해 이름을 읽으면 TypeError가 납니다.
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()에이전트 구현
아래는 흐름을 그대로 따라가는 최소 Python 예시입니다. 핵심은 query()를 async for로 돌리면서, 에이전트가 도구를 쓰고 파일을 수정하도록 하는 부분입니다. allowed_tools=["Read", "Edit", "Glob"]와 permission_mode="acceptEdits"를 사용합니다.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
elif hasattr(block, "name"):
print(f"Tool: {block.name}")
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")
asyncio.run(main())실행
python3 agent.py정상이라면 에이전트가 utils.py를 읽고, 문제를 분석한 뒤, 충돌 가능성이 있는 부분을 수정합니다. calculate_average([])와 get_user_name(None) 같은 엣지 케이스를 방어하도록 바뀌는 흐름을 보여 줍니다.
실전형으로 바꾸는 방법
다음처럼 확장할 수 있습니다. WebSearch를 넣어 외부 검색을 허용하거나, system_prompt로 역할을 고정하거나, Bash를 허용해 테스트 실행까지 자동화할 수 있습니다.
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)보안 관점에서는 처음부터 Bash를 열기보다 Read/Edit/Glob만 허용하고, 정말 필요할 때만 범위를 넓히는 편이 안전합니다. 이건 도구/권한 모델을 기준으로 한 운영 권장사항입니다. acceptEdits는 파일 편집을 자동 승인하고, default는 canUseTool 콜백으로 사용자 승인 흐름을 직접 구현하게 되어 있습니다.
운영 기준으로 잡으면 좋은 체크포인트
에이전트를 내부 업무에 넣을 때는 아래처럼 시작하시면 됩니다.
- 파일 접근 범위를 작업 디렉토리로 제한
- 기본은
Read/Edit/Glob만 허용 Bash는 테스트/빌드 같은 검증 단계에서만 허용- 승인 모드는 처음엔
acceptEdits, 민감 작업은default로 전환 - 프롬프트에 “무엇을 수정할지”와 “어떤 기준으로 멈출지”를 명시
my-agent를 실제로 돌릴 수 있는 최소 구성으로 잡으면 아래처럼 가는 것이 가장 깔끔합니다. Agent SDK는 Python/TypeScript로 사용할 수 있고, 파일 읽기·명령 실행·코드 편집 같은 기본 도구를 내장하고 있어서 별도의 툴 실행기를 직접 구현하지 않아도 됩니다. 또한 프로젝트 루트의 파일들에는 기본적으로 접근할 수 있고, CLAUDE.md는 프로젝트 컨텍스트로 자동 로드할 수 있습니다.
권장 폴더 구조
my-agent/
├── .env
├── CLAUDE.md
├── agent.py
├── utils.py
├── requirements.txt
└── README.mdagent.py는 에이전트 진입점, utils.py는 테스트용 대상 코드, CLAUDE.md는 “이 프로젝트에서 어떤 규칙으로 작업해야 하는지”를 적는 곳으로 두면 좋습니다. CLAUDE.md는 프로젝트 수준 지침을 담는 용도이며, SDK가 이를 프로젝트 컨텍스트로 주입합니다.
처음 설치
mkdir my-agent
cd my-agent
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk python-dotenv공식 문서의 기본 전제는 Node.js 18+ 또는 Python 3.10+이며, Python은 pip install claude-agent-sdk 또는 uv add claude-agent-sdk 방식으로 설치할 수 있습니다.
환경변수 설정
.env 파일
ANTHROPIC_API_KEY=your-api-key공식 문서에서는 API 키를 환경변수로 설정하는 방식을 안내하고, Bedrock / Vertex AI / Azure Foundry 같은 대체 인증 방식도 지원한다고 설명합니다. 처음 구성은 API 키 방식이 가장 단순합니다.
CLAUDE.md 만들기
# my-agent 작업 규칙
- 코드는 가능한 한 최소 수정으로 고칩니다.
- 먼저 원인과 영향 범위를 설명한 뒤 수정합니다.
- 파일 수정 후에는 엣지 케이스를 고려합니다.
- 불필요한 파일 생성은 하지 않습니다.
- 작업은 Python 코드 기준으로 진행합니다.CLAUDE.md는 시스템 프롬프트가 아니라 프로젝트 컨텍스트로 들어가므로, 같은 에이전트라도 저장소별 규칙을 따로 유지하기 좋습니다.
테스트용 코드 넣기
utils.py
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()공식 빠른 시작 예제도 일부러 이런 형태의 결함을 넣고, 에이전트가 이를 찾아 수정하는 흐름으로 설명합니다.
에이전트 코드 작성
agent.py
import asyncio
import os
from dotenv import load_dotenv
from claude_agent_sdk import query, ClaudeAgentOptions
load_dotenv()
async def main():
async for message in query(
prompt=(
"Review utils.py for bugs that could cause crashes. "
"Fix the issues with minimal code changes."
),
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt={
"type": "preset",
"preset": "claude_code",
"append": (
"You are a careful code-fixing agent. "
"Prefer small, safe edits. "
"Explain what changed after editing."
),
},
settingSources=["project"],
),
):
print(message)
if __name__ == "__main__":
asyncio.run(main())공식 문서의 핵심 패턴은 query()를 async for로 돌리는 방식이며, 예제에서도 allowed_tools에 Read, Edit, Glob 또는 Bash를 넣어 에이전트가 작업하도록 합니다. 시스템 프롬프트는 claude_code 프리셋을 쓰거나, 필요하면 append로 안전하게 덧붙일 수 있습니다.
실행
python agent.py빠른 시작 문서에서는 이렇게 실행한 뒤 에이전트가 파일을 읽고, 문제를 찾고, 자동으로 수정하는 흐름을 보여 줍니다.
운영용으로 바로 쓰려면
실무에서는 처음부터 Bash를 넓게 열기보다 Read, Edit, Glob만 허용하고 시작하는 편이 안전합니다. 공식 문서도 에이전트가 명령 실행, 웹 검색, 파일 수정 등을 할 수 있다고 설명하므로, 권한 범위를 좁혀 두고 필요한 경우만 확장하는 방식이 적절합니다. 또한 Anthropic은 제약을 우회하는 반복 시도에 대해 입력 검증, 모니터링, 차단 같은 방어를 권장합니다.
추천하는 다음 확장 순서
1. Read/Edit/Glob만으로 코드 수정 에이전트 완성
2. Bash 추가해서 테스트 실행 자동화
3. CLAUDE.md로 저장소별 규칙 분리
4. 로그 저장 추가
5. Git diff 확인 후 최종 승인 단계 추가기본 도구와 세션·권한·후크·MCP 확장을 모두 지원하지만, 처음부터 다 열기보다 작은 권한으로 시작해 점진적으로 넓히는 편이 관리가 쉽기 때문입니다.
댓글