Anthropic Messages API로 추론하기

Claude 모델을 Anthropic의 요청·응답 형식 그대로 쓰고 싶다면 Messages API를 이용하면 돼요. Anthropic SDK나 curl로 익숙한 방식으로 Amazon Bedrock의 Claude에 접근할 수 있어서, 기존 Anthropic 코드를 거의 그대로 옮겨올 수 있죠. 이 페이지에서는 Messages API를 쓰는 엔드포인트와 기본 요청, 주요 기능을 안내해 드릴게요.

출처: https://docs.aws.amazon.com/bedrock/latest/userguide/inference-messages-api.html

어느 엔드포인트에서 쓰나요

Messages API는 bedrock-runtime과 bedrock-mantle 두 엔드포인트 모두에서 사용할 수 있어요. 새로 만드는 애플리케이션에는 bedrock-runtime 엔드포인트가 권장돼요.

엔드포인트	베이스 URL	용도
bedrock-runtime	`https://bedrock-runtime.{region}.amazonaws.com/anthropic`	AWS SigV4 자격 증명, 기존 추론 방식
bedrock-mantle	`https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages`	Amazon Bedrock API 키 인증, Workspaces(Anthropic 호환) 지원

bedrock-mantle 엔드포인트는 Bedrock API 키나 AWS SigV4 자격 증명으로 인증할 수 있고요, 모든 요청에는 API 버전이 필요해요. bedrock-runtime에서 InvokeModel을 호출할 때는 요청 본문에 "anthropic_version": "bedrock-2023-05-31"을 설정해야 해요.

기본 요청

Anthropic SDK로 호출할 때는 client.messages.create(...)에 모델 ID와 메시지를 넘겨요. 아래처럼 베이스 URL을 bedrock-runtime으로 바꾸고 토큰을 생성해 넣으면 됩니다.

from anthropic import Anthropic
from aws_bedrock_token_generator import provide_token

token = provide_token(region="us-east-1")

client = Anthropic(
    base_url="https://bedrock-runtime.us-east-1.amazonaws.com/anthropic",
    api_key=token,
)

response = client.messages.create(
    model="global.anthropic.claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain quantum computing in one sentence."}
    ]
)
print(response.content[0].text)

boto3로는 invoke_model에 anthropic_version을 함께 담아 호출해요. 응답의 content[0]["text"]에서 모델 출력을 꺼낼 수 있어요.

스트리밍 응답

모델 출력을 토큰 단위로 받아보려면 스트리밍을 켜면 돼요. Anthropic SDK에서는 client.messages.stream(...)을 쓰고, boto3에서는 invoke_model_with_response_stream을 호출한 뒤 응답 본문을 순회하며 content_block_delta 이벤트의 텍스트를 이어 붙이면 됩니다.

지원되는 주요 기능

Claude 모델과 Messages API를 함께 쓰면 다음 기능을 사용할 수 있어요.

시스템 프롬프트 — system 파라미터로 모델 동작을 설정해요.
멀티 턴 대화 — user와 assistant 메시지를 번갈아 전달해요.
도구 사용(tool use) — 모델이 호출할 도구를 정의해요.
비전(Vision) — content 배열에 텍스트와 함께 이미지를 보내요.
프롬프트 캐싱 — 자주 쓰는 컨텍스트를 캐시해 지연과 비용을 줄여요.

토큰 개수 세기

추론을 보내기 전에 요청이 소비할 입력 토큰 수를 미리 알고 싶다면, bedrock-mantle 엔드포인트의 Anthropic count_tokens 경로를 사용하면 돼요.

Anthropic Messages API로 추론하기