Anthropic은 Claude로 구축할 수 있는 두 가지 방법을 제공하며, 각각 서로 다른 사용 사례에 적합합니다:
| Messages API | Claude Managed Agents | |
|---|---|---|
| 설명 | 모델 프롬프팅에 대한 직접 액세스 | 관리형 인프라에서 실행되는 사전 구축된 구성 가능한 에이전트 하네스 |
| 적합한 용도 | 커스텀 에이전트 루프 및 세밀한 제어 | 장기 실행 작업 및 비동기 작업 |
| 자세히 알아보기 | Messages API 문서 | Claude Managed Agents 문서 |
이 가이드는 기본 요청, 다중 턴 대화, 프리필 기법, 비전 기능을 포함하여 Messages API를 사용하는 일반적인 패턴을 다룹니다. 전체 API 사양은 Messages API 레퍼런스를 참조하세요.
"zero data retention"(제로 데이터 보존), 즉 ZDR이 이 기능에 어떻게 적용되는지는 API 및 데이터 보존을 참조하세요.
temperature, top_p, top_k 샘플링 매개변수는 Claude 4.7 이상 모델과 Claude Mythos Preview에서 지원되지 않습니다. 이를 기본값이 아닌 값으로 설정하면 400 오류가 반환됩니다. 요청 페이로드에서 이를 생략하고 대신 프롬프팅을 사용하여 모델의 동작을 유도하세요. 마이그레이션 가이드를 참조하세요.
message = anthropic.Anthropic().messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message){
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}거부 응답(stop_reason: "refusal")에는 모든 모델에서 거부를 유발한 정책 카테고리를 식별하는 stop_details 객체도 포함됩니다. 필드 레퍼런스와 예제 처리 코드는 중지 이유 처리하기를 참조하세요.
Messages API는 상태를 저장하지 않으므로(stateless) 항상 전체 대화 기록을 API에 전송해야 합니다. 이 패턴을 사용하여 시간이 지남에 따라 대화를 구성할 수 있습니다. 이전 대화 턴이 반드시 실제로 Claude에서 생성된 것일 필요는 없습니다. 합성된 assistant 메시지를 사용할 수 있습니다.
message = anthropic.Anthropic().messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message){
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Sure, I'd be happy to provide..."
}
],
"model": "claude-opus-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 30,
"output_tokens": 309
}
}Claude Fable 5, Claude Mythos 5, Claude Opus 4.8, Claude Opus 5에서는 사용자 턴 이후에 "role": "system"이 포함된 메시지를 추가하여(배치 규칙에 따라) 대화 도중에 새로운 시스템 지시를 추가할 수 있습니다. system 메시지는 messages의 첫 번째 항목이 될 수 없으며, 처음부터 적용되는 지시에는 최상위 system 필드를 사용하세요.
대화 중간의 시스템 메시지는 최상위 system 필드와 동일한 권한을 가지지만, 메시지 기록의 끝에 추가되기 때문에 그 이전에 있던 캐시된 접두사를 무효화하지 않습니다. 첫 번째 턴부터 적용되어야 하는 지시에는 최상위 system 필드를 사용하고, 나중에야 관련성이 생기는 지시에는 대화 중간의 시스템 메시지를 사용하세요.
프롬프트 캐싱과 결합하는 방법을 포함한 전체 가이드는 대화 중간 시스템 메시지를 참조하세요.
입력 메시지 목록의 마지막 위치에 Claude 응답의 일부를 미리 채울 수 있습니다. 이 기법을 사용하여 Claude의 응답을 원하는 형태로 유도할 수 있습니다. 다음 예제는 "max_tokens": 1을 사용하여 Claude로부터 단일 객관식 답변을 얻습니다.
프리필은 Claude 4.6 이상 모델과 Claude Mythos Preview에서 지원되지 않습니다. 이러한 모델에서 프리필을 사용하는 요청은 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){
"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-5",
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-5",
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){
"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-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1551,
"output_tokens": 71
}
}각 stop_reason 값을 처리하고 응답이 종료될 때 수행할 작업을 결정합니다.
Messages API 내에서 외부 서비스와 API를 호출할 수 있는 도구를 Claude에 제공합니다.
Messages API로 데스크톱 컴퓨터 환경을 제어합니다.
Claude로부터 스키마 검증이 보장된 JSON 출력을 얻습니다.
output_config.task_budget으로 전체 에이전트 루프에 걸쳐 권고 토큰 예산을 설정합니다.
Was this page helpful?