MessagesClaude로 빌드하기

Messages API 사용하기

Messages API를 효과적으로 사용하기 위한 실용적인 패턴과 예제

Anthropic은 Claude로 구축할 수 있는 두 가지 방법을 제공하며, 각각 서로 다른 사용 사례에 적합합니다:

	Messages API	Claude Managed Agents
설명	모델 프롬프팅에 대한 직접 액세스	관리형 인프라에서 실행되는 사전 구축된 구성 가능한 에이전트 하네스
적합한 용도	커스텀 에이전트 루프 및 세밀한 제어	장기 실행 작업 및 비동기 작업
자세히 알아보기	Messages API 문서	Claude Managed Agents 문서

이 가이드는 기본 요청, 멀티턴 대화, 프리필 기법, 비전 기능을 포함하여 Messages API를 사용하는 일반적인 패턴을 다룹니다. 전체 API 사양은 Messages API 레퍼런스를 참조하세요.

이 기능은 Zero Data Retention (ZDR)의 적용 대상입니다. 조직에 ZDR 계약이 체결되어 있는 경우, 이 기능을 통해 전송된 데이터는 API 응답이 반환된 후 저장되지 않습니다.

기본 요청 및 응답

temperature, top_p, top_k 샘플링 매개변수는 Claude Opus 4.8을 포함하여 Claude Opus 4.7 이후 모델에서 지원되지 않습니다. 이를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 요청 페이로드에서 이를 생략하고 대신 프롬프트를 사용하여 모델의 동작을 유도하세요. 마이그레이션 가이드를 참조하세요.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Claude Opus 4.7 이후 모델에서는 거부 응답(stop_reason: "refusal")에 거부를 유발한 정책 카테고리를 식별하는 stop_details 객체도 포함됩니다. 필드 레퍼런스와 예제 처리 코드는 중지 사유 처리하기를 참조하세요.

여러 대화 턴

Messages API는 상태를 저장하지 않으므로 항상 전체 대화 기록을 API로 전송해야 합니다. 이 패턴을 사용하여 시간이 지남에 따라 대화를 구축할 수 있습니다. 이전 대화 턴이 반드시 실제로 Claude에서 생성된 것일 필요는 없습니다. 합성 assistant 메시지를 사용할 수 있습니다.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

메시지 내 system 역할

Claude Opus 4.8에서는 사용자 턴 이후에 "role": "system" 메시지를 포함하여(배치 규칙 적용) 대화 중간에 새로운 시스템 지침을 추가할 수 있습니다. system 메시지는 messages의 첫 번째 항목이 될 수 없습니다. 처음부터 적용되어야 하는 지침에는 최상위 system 필드를 사용하세요.

대화 중간 시스템 메시지는 최상위 system 필드와 동일한 권한을 가지지만, 메시지 기록의 끝에 추가되기 때문에 그 이전에 있던 캐시된 프리픽스를 무효화하지 않습니다. 첫 번째 턴부터 적용되어야 하는 지침에는 최상위 system 필드를 사용하고, 나중에야 관련성이 생기는 지침에는 대화 중간 시스템 메시지를 사용하세요.

프롬프트 캐싱과 결합하는 방법을 포함한 전체 가이드는 대화 중간 시스템 메시지를 참조하세요.

Claude의 응답 미리 채우기

입력 메시지 목록의 마지막 위치에 Claude의 응답 일부를 미리 채울 수 있습니다. 이를 통해 Claude의 응답을 원하는 방향으로 유도할 수 있습니다. 아래 예제는 "max_tokens": 1을 사용하여 Claude로부터 단일 객관식 답변을 얻습니다.

프리필은 Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서 지원되지 않습니다. 이러한 모델에서 프리필을 사용하는 요청은 400 오류를 반환합니다. 대신 이를 지원하는 모델에서 구조화된 출력을 사용하거나 시스템 프롬프트 지침을 사용하세요. 마이그레이션 패턴은 마이그레이션 가이드를 참조하세요.

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

비전

Claude는 요청에서 텍스트와 이미지를 모두 읽을 수 있습니다. 이미지는 base64, url, file 소스 타입을 사용하여 제공할 수 있습니다. file 소스 타입은 Files API를 통해 업로드된 이미지를 참조합니다. 지원되는 미디어 타입은 image/jpeg, image/png, image/gif, image/webp입니다. 자세한 내용은 비전 가이드를 참조하세요.

import base64
import httpx

# 옵션 1: Base64로 인코딩된 이미지
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# 옵션 2: URL로 참조된 이미지
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

다음 단계

중지 사유 및 폴백

각 stop_reason 값을 처리하고 응답이 종료될 때 수행할 작업을 결정하세요.

Claude와 함께 도구 사용

Messages API 내에서 외부 서비스와 API를 호출할 수 있는 도구를 Claude에 제공하세요.

컴퓨터 사용 도구

Messages API로 데스크톱 컴퓨터 환경을 제어하세요.

구조화된 출력

Claude로부터 스키마 검증이 보장된 JSON 출력을 받으세요.

작업 예산

output_config.task_budget으로 전체 에이전트 루프에 걸쳐 권고 토큰 예산을 설정하세요.

Was this page helpful?

MessagesClaude로 빌드하기

Messages API 사용하기

Messages API를 효과적으로 사용하기 위한 실용적인 패턴과 예제

Anthropic은 Claude로 구축할 수 있는 두 가지 방법을 제공하며, 각각 서로 다른 사용 사례에 적합합니다:

	Messages API	Claude Managed Agents
설명	모델 프롬프팅에 대한 직접 액세스	관리형 인프라에서 실행되는 사전 구축된 구성 가능한 에이전트 하네스
적합한 용도	커스텀 에이전트 루프 및 세밀한 제어	장기 실행 작업 및 비동기 작업
자세히 알아보기	Messages API 문서	Claude Managed Agents 문서

기본 요청 및 응답

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Output

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

여러 대화 턴

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

메시지 내 system 역할

프롬프트 캐싱과 결합하는 방법을 포함한 전체 가이드는 대화 중간 시스템 메시지를 참조하세요.

Claude의 응답 미리 채우기

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)

Output

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

비전

import base64
import httpx

# 옵션 1: Base64로 인코딩된 이미지
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# 옵션 2: URL로 참조된 이미지
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

Output

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

다음 단계

중지 사유 및 폴백

각 stop_reason 값을 처리하고 응답이 종료될 때 수행할 작업을 결정하세요.

Claude와 함께 도구 사용

Messages API 내에서 외부 서비스와 API를 호출할 수 있는 도구를 Claude에 제공하세요.

컴퓨터 사용 도구

Messages API로 데스크톱 컴퓨터 환경을 제어하세요.

구조화된 출력

Claude로부터 스키마 검증이 보장된 JSON 출력을 받으세요.

작업 예산

output_config.task_budget으로 전체 에이전트 루프에 걸쳐 권고 토큰 예산을 설정하세요.

Was this page helpful?

기본 요청 및 응답

여러 대화 턴

메시지 내 system 역할

Claude의 응답 미리 채우기

비전

다음 단계

기본 요청 및 응답

여러 대화 턴

메시지 내 system 역할

Claude의 응답 미리 채우기

비전

다음 단계

기본 요청 및 응답

여러 대화 턴

메시지 내 system 역할

Claude의 응답 미리 채우기

비전

다음 단계

기본 요청 및 응답

여러 대화 턴

메시지 내 system 역할

Claude의 응답 미리 채우기

비전

다음 단계