Messages 요청은 필드와 흐름을 함께 설계해

요청에서 먼저 보이는 다섯 필드

Messages API가 반드시 요구하는 값은 model, max_tokens, messages야. system과 temperature는 선택 항목이지만 실제 제품에서는 자주 써. 여기에 응답 전체를 한 번에 받을지, 생성되는 대로 스트리밍할지 결정하면 기본 요청 모양이 완성돼.

출력 예산은 호출자가 정해

Anthropic은 호출마다 max_tokens를 명시하게 해. 이 값은 단순한 권장 길이가 아니라 비용 상한이자 지연 조절 장치야. 정상 답변을 자르지 않을 만큼 넉넉하되, 모델이 끝없이 생성해도 제품 예산을 넘지 않게 잡아야 해. 작업별 예상 길이를 재고 별도 값을 두는 편이 안전해.

메시지 배열과 시스템 지침은 자리가 달라

messages에는 {role, content} 객체가 들어가고 역할은 user와 assistant가 번갈아 나와. 배열 안에는 system 역할이 없어. 전체 대화에 적용할 지침은 최상위 system 필드에 두고, 특정 턴의 추가 자료는 해당 사용자 메시지 안에 넣어.

원칙: SDK 도우미보다 요청 본문 계약을 먼저 이해해. 편의 함수가 바뀌어도 API의 구조는 남아.

Code

최소 Messages 요청 (Python)·python

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You answer in exactly one sentence, no more.",
    messages=[
        {"role": "user", "content": "Why is max_tokens required by Anthropic but optional by some other providers?"},
    ],
    temperature=0.2,
)
print(response.content[0].text)
print("in:", response.usage.input_tokens, "out:", response.usage.output_tokens)

같은 호출의 raw HTTP (wire format)·bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You answer in exactly one sentence, no more.",
    "messages": [
      {"role": "user", "content": "Why is max_tokens required?"}
    ],
    "temperature": 0.2
  }'

Exercise

프로젝트의 Claude 기능 하나를 골라 model·max_tokens·messages로 가장 작은 유효 요청을 만들고, 정말 필요한 system 또는 temperature 하나만 더해. 각 선택 이유도 짧게 적어.

Hint

temperature를 왜 바꿔야 하는지 설명할 수 없다면 기본값을 써.

요청에서 먼저 보이는 다섯 필드

출력 예산은 호출자가 정해

메시지 배열과 시스템 지침은 자리가 달라

Code

External links

Exercise

Progress

댓글 0