Messages API 기초

Claude Code가 완성된 도구라면, Messages API는 직접 도구를 만들 때 쓰는 재료입니다.

가장 단순한 요청

from anthropic import Anthropic

client = Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "이 로그에서 오류 원인을 찾아줘: ..."}
    ],
)

print(message.content[0].text)

max_tokens는 필수입니다. 응답 길이의 상한이며, 실제 사용량이 아니라 한도입니다.

대화 유지

API는 상태를 저장하지 않습니다. 이전 대화를 이어가려면 전체 이력을 매번 보냅니다.

messages = [
    {"role": "user", "content": "파이썬으로 CSV를 읽어줘"},
    {"role": "assistant", "content": "pandas를 쓰면..."},
    {"role": "user", "content": "그럼 pandas 없이는?"},
]

역할은 user와 assistant가 번갈아 나와야 합니다.

시스템 프롬프트

역할과 규칙은 messages가 아니라 system에 넣습니다.

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system="너는 한국어로만 답하는 기술 지원 담당자다. 추측하지 말고 모르면 모른다고 답하라.",
    messages=[...],
)

스트리밍

응답이 길면 사용자를 기다리게 하지 마세요.

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "..."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

도구 호출

Claude가 외부 기능을 쓰게 하려면 도구를 정의해 함께 보냅니다.

tools = [{
    "name": "get_order_status",
    "description": "주문 번호로 배송 상태를 조회한다.",
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string", "description": "주문 번호"}
        },
        "required": ["order_id"],
    },
}]

응답의 stop_reason이 tool_use면 도구를 실행하고, 결과를 tool_result로 다시 보냅니다. 이 왕복이 곧 에이전트 루프입니다.

description이 품질을 좌우합니다. 이름만 보고 언제 쓸지 판단하기 어려우면 잘못 호출됩니다.

비용을 줄이는 세 가지

1. 프롬프트 캐싱 — 반복되는 앞부분을 캐시에 올립니다. 자세히 보기
2. 모델 선택 — 단순 분류·추출에는 더 작은 모델로 충분합니다
3. **max_tokens 조정** — 짧은 답이면 한도도 짧게 잡으세요

오류 처리

재시도는 429와 5xx에만 적용하세요. 400은 몇 번을 보내도 같은 결과입니다.