• Messages
  • Managed Agents
  • 관리자

Search...
⌘K
첫 단계
Claude 소개빠른 시작
Claude로 빌드하기
기능 개요Messages API 사용하기중지 이유 및 폴백거부 및 폴백폴백 크레딧
모델 기능
확장 사고적응형 사고Effort작업 예산 (베타)고속 모드 (리서치 프리뷰)구조화된 출력인용스트리밍 메시지배치 처리검색 결과스트리밍 거부다국어 지원임베딩
도구
개요도구 사용 작동 방식튜토리얼: 도구 사용 에이전트 빌드하기도구 정의도구 호출 처리병렬 도구 사용Tool Runner (SDK)엄격한 도구 사용프롬프트 캐싱과 함께 도구 사용서버 도구문제 해결웹 검색 도구웹 가져오기 도구코드 실행 도구어드바이저 도구메모리 도구Bash 도구컴퓨터 사용 도구텍스트 편집기 도구
도구 인프라
도구 레퍼런스도구 컨텍스트 관리도구 조합도구 검색프로그래밍 방식 도구 호출세분화된 도구 스트리밍
컨텍스트 관리
컨텍스트 윈도우압축컨텍스트 편집프롬프트 캐싱대화 중 시스템 메시지오케스트레이션 모드 빌드하기캐시 진단 (베타)토큰 계산
파일 작업
Files APIPDF 지원이미지 및 비전
스킬
개요빠른 시작모범 사례엔터프라이즈용 스킬API에서의 스킬
MCP
원격 MCP 서버MCP 커넥터
클라우드 플랫폼의 Claude
Amazon BedrockAmazon Bedrock (레거시)AWS의 Claude PlatformMicrosoft FoundryVertex AI

Log in
Messages API 사용하기
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Claude on AWS
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
Messages/Claude로 빌드하기

Messages API 사용하기

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

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

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

이 가이드는 기본 요청, 멀티턴 대화, 프리필(prefill) 기법, 비전 기능을 포함하여 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 오류가 반환됩니다. 요청 페이로드에서 이를 생략하고 대신 프롬프트를 사용하여 모델의 동작을 유도하세요. 마이그레이션 가이드를 참조하세요.

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

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로부터 단일 객관식 답변을 얻습니다.



프리필(prefilling)은 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 오류를 반환합니다. 대신 이를 지원하는 모델에서 구조화된 출력을 사용하거나 시스템 프롬프트 지시사항을 사용하세요. 마이그레이션 패턴은 마이그레이션 가이드를 참조하세요.

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입니다. 자세한 내용은 비전 가이드를 참조하세요.

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
  }
}

도구 사용 및 컴퓨터 사용

Messages API에서 도구를 사용하는 방법에 대한 예제는 도구 사용 가이드를 참조하세요. Messages API로 데스크톱 컴퓨터 환경을 제어하는 방법에 대한 예제는 컴퓨터 사용 가이드를 참조하세요. 보장된 JSON 출력에 대해서는 구조화된 출력을 참조하세요. 전체 에이전트 루프에 걸친 권고성 토큰 예산을 설정하려면 output_config.task_budget을 설정하세요. 작업 예산을 참조하세요.

Was this page helpful?

  • 기본 요청 및 응답
  • 여러 대화 턴
  • 메시지 내 system 역할
  • Claude의 응답 미리 채우기
  • 비전
  • 도구 사용 및 컴퓨터 사용
message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
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)
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)
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)