Anthropic은 Claude로 구축할 수 있는 두 가지 방법을 제공하며, 각각 서로 다른 사용 사례에 적합합니다:
| Messages API | Claude 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 오류가 반환됩니다. 요청 페이로드에서 이를 생략하고 대신 프롬프트를 사용하여 모델의 동작을 유도하세요. 마이그레이션 가이드를 참조하세요.
{
"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 메시지를 사용할 수 있습니다.
{
"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
}
}Claude Opus 4.8에서는 사용자 턴 이후에 "role": "system"이 포함된 메시지를 추가하여(배치 규칙 적용) 대화 중간에 새로운 시스템 지시사항을 추가할 수 있습니다. system 메시지는 messages의 첫 번째 항목이 될 수 없습니다. 처음부터 적용되어야 하는 지시사항에는 최상위 system 필드를 사용하세요.
대화 중간의 시스템 메시지는 최상위 system 필드와 동일한 권한을 가지지만, 메시지 기록의 끝에 추가되기 때문에 그 이전에 있던 캐시된 프리픽스를 무효화하지 않습니다. 첫 번째 턴부터 적용되어야 하는 지시사항에는 최상위 system 필드를 사용하고, 나중에야 관련성이 생기는 지시사항에는 대화 중간 시스템 메시지를 사용하세요.
프롬프트 캐싱과 결합하는 방법을 포함한 전체 가이드는 대화 중간 시스템 메시지를 참조하세요.
입력 메시지 목록의 마지막 위치에 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 오류를 반환합니다. 대신 이를 지원하는 모델에서 구조화된 출력을 사용하거나 시스템 프롬프트 지시사항을 사용하세요. 마이그레이션 패턴은 마이그레이션 가이드를 참조하세요.
{
"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입니다. 자세한 내용은 비전 가이드를 참조하세요.
{
"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?
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)