Amazon Bedrock

Amazon Bedrock은 여러 provider의 파운데이션 모델을 제공해요. PydanticAI는 여기에 두 개의 개별 AWS API로 접근해요. 모델 프리픽스로 경로를 고르면 되죠.

출처: 공식문서

Bedrock Converse (bedrock:) — Anthropic, Amazon, Cohere, Meta, Mistral, DeepSeek, Qwen 등 훨씬 더 많은 모델을 Bedrock Runtime Converse API를 통해 제공하는 가장 넓은 카탈로그예요. 거의 모든 Bedrock 모델의 경로죠.
Bedrock Mantle (bedrock-mantle:) — Bedrock이 오직 Mantle의 OpenAI 호환 API로만 서빙하는 최신 OpenAI 모델(GPT-5.x, GPT-OSS)이에요.

두 경로 모두 같은 AWS 자격 증명으로 인증해요. bedrock: 프리픽스는 항상 Converse를 쓰고, 그 경로로 frontier OpenAI 모델(GPT-5.4 이상)을 요청하면 Converse가 그 모델을 서빙하지 않으므로 bedrock-mantle:를 가리키는 에러가 나요.

경로	프리픽스	모델	옵션 그룹	모델 클래스
Converse	`bedrock:`	Anthropic, Amazon, Cohere, Meta, Mistral 등 기타	`bedrock`	`BedrockConverseModel`
Mantle	`bedrock-mantle:`	OpenAI GPT-5.x 및 GPT-OSS	`bedrock-mantle`	`BedrockMantleResponsesModel`, `BedrockMantleChatModel`

Bedrock Converse

BedrockConverseModel은 Bedrock Runtime Converse API와 대화해요. 가장 넓은 Bedrock 모델 집합을 서빙하죠.

설치

BedrockConverseModel을 쓰려면 pydantic-ai를 설치하거나 pydantic-ai-slim을 bedrock 옵션 그룹과 함께 설치해야 해요.

Terminal

pip install "pydantic-ai-slim[bedrock]"

Terminal

uv add "pydantic-ai-slim[bedrock]"

설정

AWS Bedrock을 쓰려면 Bedrock이 활성화된 AWS 계정과 적절한 자격 증명이 필요해요. AWS 자격 증명을 직접 쓰거나 미리 구성된 boto3 클라이언트를 쓸 수 있어요.

BedrockModelName에는 Anthropic, Amazon, Cohere, Meta, Mistral 모델을 포함한 사용 가능한 Bedrock 모델 목록이 들어 있어요.

환경 변수

AWS 자격 증명을 환경 변수로 설정할 수 있어요(다른 옵션도 있음).

Terminal

export AWS_BEARER_TOKEN_BEDROCK='your-api-key'
# or:
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
export AWS_DEFAULT_REGION='us-east-1'  # or your preferred region

이제 BedrockConverseModel을 이름으로 쓸 수 있어요.

from pydantic_ai import Agent

agent = Agent('bedrock:anthropic.claude-sonnet-4-5-20250929-v1:0')
...

또는 모델 이름만으로 직접 초기화할 수도 있어요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel

model = BedrockConverseModel('anthropic.claude-sonnet-4-5-20250929-v1:0')
agent = Agent(model)
...

Bedrock Runtime API 커스터마이즈

guardrail 구성과 성능 설정 같은 추가 파라미터를 더해 Bedrock Runtime API 호출을 커스터마이즈할 수 있어요. 구성 가능한 파라미터 전체 목록은 BedrockModelSettings 문서를 참조하세요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel, BedrockModelSettings

# Define Bedrock model settings with guardrail and performance configurations
bedrock_model_settings = BedrockModelSettings(
    bedrock_guardrail_config={
        'guardrailIdentifier': 'v1',
        'guardrailVersion': 'v1',
        'trace': 'enabled'
    },
    bedrock_performance_configuration={
        'latency': 'optimized'
    }
)


model = BedrockConverseModel(model_name='us.amazon.nova-pro-v1:0')

agent = Agent(model=model, model_settings=bedrock_model_settings)

guardrail 구성에서 trace가 'enabled'로 설정되면(위 예시처럼) Bedrock이 반환한 guardrail 평가가 ModelResponse.provider_details의 'trace' 키 아래에 그대로 저장돼요. 예: result.all_messages()[-1].provider_details['trace'].

커스텀 HTTP 헤더

ModelSettings.extra_headers로 Converse, ConverseStream, CountTokens 요청에 HTTP 헤더를 추가할 수 있어요. 커스텀 헤더가 필요한 API 게이트웨이나 프록시를 통해 요청을 라우팅할 때 유용해요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockModelSettings

agent = Agent(
    'bedrock:us.amazon.nova-micro-v1:0',
    model_settings=BedrockModelSettings(
        extra_headers={'X-Tenant-ID': 'example-tenant'},
    ),
)

extra_headers를 boto3가 관리하는 헤더(Authorization, User-Agent, X-Amz-Date, Host, Content-Length 등)를 덮어쓰는 데 쓰지 마세요. 그 값은 무시되거나 요청 실패를 일으킬 수 있어요.

서비스 티어

Bedrock은 처리량과 비용을 관리하기 위해 service tier 제어를 지원해요. 통합된 service_tier 필드나 provider별 bedrock_service_tier 필드를 쓸 수 있어요. 둘 다 설정되면 bedrock_service_tier가 우선해요.

통합 필드는 Bedrock에서 이렇게 매핑돼요.

'auto': serviceTier 필드가 요청에서 생략돼서 AWS가 서버 측 기본값(Standard 티어)을 적용해요.
'default': {'type': 'default'}로 명시 전송돼요. 향후 서버 측 premium 티어 자동 승격을 거부해요.
'flex': {'type': 'flex'}로 전송돼요.
'priority': {'type': 'priority'}로 전송돼요.

Bedrock의 'reserved' 티어(사전 구매한 용량 예약 필요)를 요청하려면 bedrock_service_tier를 직접 설정하세요. 통합 필드로는 닿을 수 없어요.

프롬프트 캐싱

Bedrock은 Anthropic 모델에서 프롬프트 캐싱을 지원해서 요청 간에 비싼 컨텍스트를 재사용할 수 있게 해줘요. PydanticAI는 프롬프트 캐싱의 네 가지 방법을 제공해요.

CachePoint로 사용자 메시지 캐시하기: CachePoint 마커를 넣어 현재 사용자 메시지에서 그 앞의 모든 것을 캐시해요. 사용자 프롬프트 파트의 시작 부분의 CachePoint는 그 메시지에 앞선 것이 없으므로, 대신 이전 사용자 메시지의 끝까지 모든 것을 캐시해요. CachePoint(ttl='1h')를 넘기면 확장 캐시 기간을 선택할 수 있어요.
시스템 지시 캐시하기: BedrockModelSettings.bedrock_cache_instructions를 True로 설정(기본 5m TTL)하거나 '5m'/'1h'를 직접 지정해요. 정적·동적 지시가 둘 다 있으면 캐시 지점은 마지막 정적 지시 뒤에 놓여서, 동적 지시는 정적 캐시를 무효화하지 않고 바뀔 수 있어요.
도구 정의 캐시하기: BedrockModelSettings.bedrock_cache_tool_definitions를 True로 설정(기본 5m TTL)하거나 '5m'/'1h'를 직접 지정해요.
모든 메시지 캐시하기: BedrockModelSettings.bedrock_cache_messages를 True로 설정(기본 5m TTL)하거나 '5m'/'1h'를 직접 지정해 마지막 사용자 메시지를 자동 캐시해요.

최소 토큰 임계값: AWS는 세그먼트가 provider별 최소 토큰 임계값을 넘을 때만 캐시된 콘텐츠를 서빙해요(Bedrock 프롬프트 캐싱 문서 참조). 그 한도 아래의 짧은 프롬프트나 도구 정의는 캐시를 우회하므로, 아주 작은 페이로드에서 절감을 기대하지 마세요.

예시 1: 자동 메시지 캐싱

bedrock_cache_messages로 마지막 사용자 메시지를 자동 캐시해요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockModelSettings

agent = Agent(
    'bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0',
    system_prompt='You are a helpful assistant.',
    model_settings=BedrockModelSettings(
        bedrock_cache_messages=True,  # Automatically caches the last message
    ),
)

# The last message is automatically cached - no need for manual CachePoint
result1 = agent.run_sync('What is the capital of France?')

# Subsequent calls with similar conversation benefit from cache
result2 = agent.run_sync('What is the capital of Germany?')
print(f'Cache write: {result1.usage.cache_write_tokens}')
print(f'Cache read: {result2.usage.cache_read_tokens}')

예시 2: 종합 캐싱 전략

최대 절감을 위해 여러 캐시 설정을 결합해요.

from pydantic_ai import Agent, RunContext
from pydantic_ai.models.bedrock import BedrockConverseModel, BedrockModelSettings

model = BedrockConverseModel('us.anthropic.claude-sonnet-4-5-20250929-v1:0')
agent = Agent(
    model,
    system_prompt='Detailed instructions...',
    model_settings=BedrockModelSettings(
        bedrock_cache_instructions=True,       # Cache system instructions
        bedrock_cache_tool_definitions='1h',   # Cache tool definitions with 1h TTL
        bedrock_cache_messages=True,           # Also cache the last message
    ),
)


@agent.tool
def search_docs(ctx: RunContext, query: str) -> str:
    """Search documentation."""
    return f'Results for {query}'


result = agent.run_sync('Search for Python best practices')
print(result.output)

예시 3: CachePoint로 세밀하게 제어하기

수동 CachePoint 마커로 캐시 위치를 정확히 제어해요.

from pydantic_ai import Agent, CachePoint

agent = Agent(
    'bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0',
    system_prompt='Instructions...',
)

# Manually control cache points for specific content blocks
result = agent.run_sync([
    'Long context from documentation...',
    CachePoint(),  # Cache everything up to this point
    'First question'
])
print(result.output)

캐시 사용 통계 접근

RequestUsage로 캐시 사용 통계에 접근해요.

from pydantic_ai import Agent, CachePoint

agent = Agent('bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0')


async def main():
    result = await agent.run(
        [
            'Reference material...',
            CachePoint(),
            'What changed since last time?',
        ]
    )
    usage = result.usage
    print(f'Cache writes: {usage.cache_write_tokens}')
    print(f'Cache reads: {usage.cache_read_tokens}')

캐시 지점 한도

Bedrock은 요청당 캐시 지점을 최대 4개 강제해요. PydanticAI가 이 한도를 자동 관리해서 요청이 항상 에러 없이 규칙을 준수하게 해줘요.

캐시 지점 배분 방식

캐시 지점은 세 곳에 놓일 수 있어요.

시스템 프롬프트: bedrock_cache_instructions 설정을 통해(마지막 시스템 프롬프트 블록에 캐시 지점 추가)
도구 정의: bedrock_cache_tool_definitions 설정을 통해(마지막 도구 정의에 캐시 지점 추가)
메시지: CachePoint 마커나 bedrock_cache_messages 설정을 통해(메시지 콘텐츠에 캐시 지점 추가)

각 설정은 캐시 지점 최대 1개를 쓰지만 결합할 수 있어요.

자동 캐시 지점 제한

모든 원천(설정 + CachePoint 마커)의 캐시 지점이 4를 넘으면, PydanticAI가 오래된 메시지 콘텐츠에서 초과 캐시 지점을 자동 제거해요(가장 최근 것 유지).

from pydantic_ai import Agent, CachePoint
from pydantic_ai.models.bedrock import BedrockModelSettings

agent = Agent(
    'bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0',
    system_prompt='Instructions...',
    model_settings=BedrockModelSettings(
        bedrock_cache_instructions=True,      # 1 cache point
        bedrock_cache_tool_definitions=True,  # 1 cache point
    ),
)

@agent.tool_plain
def search() -> str:
    return 'data'


# Already using 2 cache points (instructions + tools)
# Can add 2 more CachePoint markers (4 total limit)
result = agent.run_sync([
    'Context 1', CachePoint(),  # Oldest - will be removed
    'Context 2', CachePoint(),  # Will be kept (3rd point)
    'Context 3', CachePoint(),  # Will be kept (4th point)
    'Question'
])
# Final cache points: instructions + tools + Context 2 + Context 3 = 4
print(result.output)

핵심 포인트:

시스템·도구 캐시 지점은 항상 보존돼요.
bedrock_cache_messages가 만든 캐시 지점은 항상 보존돼요(가장 새로운 메시지 캐시 지점이므로).
메시지의 추가 CachePoint 마커는 한도를 넘으면 오래된 것부터 새 것으로 제거돼요.
이로써 지시·도구 같은 중요한 캐싱이 유지되면서 메시지 수준 캐싱의 이점도 누릴 수 있어요.

`provider` 인자

provider 인자로 커스텀 BedrockProvider를 제공할 수 있어요. 자격 증명을 직접 지정하거나 커스텀 boto3 클라이언트를 쓰고 싶을 때 유용해요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel
from pydantic_ai.providers.bedrock import BedrockProvider

# Using AWS credentials directly
model = BedrockConverseModel(
    'anthropic.claude-sonnet-4-5-20250929-v1:0',
    provider=BedrockProvider(
        region_name='us-east-1',
        aws_access_key_id='your-access-key',
        aws_secret_access_key='your-secret-key',
    ),
)
agent = Agent(model)
...

미리 구성된 boto3 클라이언트도 넘길 수 있어요.

import boto3

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel
from pydantic_ai.providers.bedrock import BedrockProvider

# Using a pre-configured boto3 client
bedrock_client = boto3.client('bedrock-runtime', region_name='us-east-1')
model = BedrockConverseModel(
    'anthropic.claude-sonnet-4-5-20250929-v1:0',
    provider=BedrockProvider(bedrock_client=bedrock_client),
)
agent = Agent(model)
...

AWS 애플리케이션 추론 프로필 사용

AWS Bedrock은 비용 추적과 리소스 관리를 위해 커스텀 애플리케이션 추론 프로필을 지원해요. bedrock_inference_profile을 설정하면 모델 능력 감지를 위해 base 모델 이름을 유지하면서 추론 프로필을 통해 요청을 라우팅해요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel
from pydantic_ai.providers.bedrock import BedrockProvider

provider = BedrockProvider(region_name='us-east-2')

model = BedrockConverseModel(
    'us.anthropic.claude-opus-4-5-20251101-v1:0',
    provider=provider,
    settings={
        'bedrock_inference_profile': 'arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/my-profile',
    },
)

agent = Agent(model)

재시도 구성

이 boto3 재시도는 Bedrock의 provider SDK 재시도 레이어예요. boto3는 반대쪽에서 세기 때문에 Config(retries={'max_attempts': N})는 총 1 + N회 시도를 허용해요. boto3 아래에 httpx2 transport 레이어는 없으므로 이건 에이전트의 재시도 예산과 네트워크 사이의 유일한 재시도 레이어예요. 레이어가 어떻게 쌓이는지 Retry multiplication을 보세요.

Bedrock은 boto3의 내장 재시도 메커니즘을 써요. 재시도 설정이 있는 커스텀 boto3 클라이언트를 넘겨서 재시도 동작을 구성할 수 있어요.

import boto3
from botocore.config import Config

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel
from pydantic_ai.providers.bedrock import BedrockProvider

# Configure retry settings
config = Config(
    retries={
        'max_attempts': 5,
        'mode': 'adaptive'  # Recommended for rate limiting
    }
)

bedrock_client = boto3.client(
    'bedrock-runtime',
    region_name='us-east-1',
    config=config
)

model = BedrockConverseModel(
    'us.amazon.nova-micro-v1:0',
    provider=BedrockProvider(bedrock_client=bedrock_client),
)
agent = Agent(model)

재시도 모드

'legacy' (기본): 5회 시도, 기본 재시도 동작
'standard': 3회 시도, 더 포괄적인 에러 커버리지
'adaptive': 3회 시도 + 클라이언트 측 rate limiting(ThrottlingException 처리에 권장)

boto3 재시도 구성에 대한 자세한 내용은 AWS boto3 문서를 보세요.

참고: HTTP 요청에 httpx를 쓰는 다른 provider와 달리 Bedrock은 boto3의 네이티브 재시도 메커니즘을 써요. Transport 재시도에 설명된 재시도 전략은 Bedrock에 적용되지 않아요.

Bedrock Mantle

Amazon Bedrock Mantle은 OpenAI 모델(GPT-5.x, GPT-OSS)을 OpenAI 호환 API로 서빙해요. bedrock-mantle: 프리픽스를 쓰세요.

from pydantic_ai import Agent

agent = Agent('bedrock-mantle:openai.gpt-5.6-luna')

bedrock-mantle 옵션 그룹이 필요해요.

Terminal

pip install "pydantic-ai-slim[bedrock-mantle]"

Terminal

uv add "pydantic-ai-slim[bedrock-mantle]"

BedrockMantleProvider는 Converse 경로와 같은 AWS 자격 증명으로 인증해요. AWS_BEARER_TOKEN_BEDROCK를 통한 bearer 토큰이나, AWS 액세스 키/프로필을 통한 SigV4예요. 그리고 region_name(또는 AWS_DEFAULT_REGION/AWS_REGION 환경 변수)에서 엔드포인트를 유도해요.

모델 이름이 엔드포인트 군을 결정해요.

모델 이름	인터페이스
GPT-5.4+, 예: `bedrock-mantle:openai.gpt-5.6-luna`	`/openai/v1`에서 OpenAI Responses
GPT-OSS, 예: `bedrock-mantle:openai.gpt-oss-120b`	`/v1`에서 OpenAI Responses
GPT-OSS Safeguard, 예: `bedrock-mantle:openai.gpt-oss-safeguard-20b`	`/v1`에서 OpenAI Chat Completions

커스텀 Mantle origin(예: 프록시)을 쓰려면 BedrockMantleProvider에 base_url을 넘기세요. 그 origin(모든 /openai/v1 또는 /v1 접미사 제거)은 region_name처럼 모델별로 두 엔드포인트 군 사이를 라우팅하는 데 쓰여요.

from pydantic_ai import Agent
from pydantic_ai.models.bedrock_mantle import BedrockMantleResponsesModel
from pydantic_ai.providers.bedrock_mantle import BedrockMantleProvider

provider = BedrockMantleProvider(base_url='https://bedrock-mantle.us-east-1.api.aws/openai/v1')
model = BedrockMantleResponsesModel('openai.gpt-5.6-luna', provider=provider)
agent = Agent(model)

기능 지원

Mantle 모델은 PydanticAI의 OpenAI 모델 클래스로 서빙돼요. BedrockMantleResponsesModel과 BedrockMantleChatModel이죠. 그래서 직접 OpenAI 모델과 같은 설정(OpenAIResponsesModelSettings, OpenAIChatModelSettings)을 받아요.

위의 Converse 경로 기능들 — 프롬프트 캐싱, 서비스 티어, 애플리케이션 추론 프로필 — 은 Converse API에 특화된 것으로 Mantle 경로에는 적용되지 않아요. 특히 bedrock_service_tier는 Converse 설정이고, Mantle 모델은 OpenAI 모델 클래스로 서빙되므로 통합된 service_tier를 같은 이름의 OpenAI 파라미터로 전달해요.

더 알아보기 (Learn more)

Bedrock 프롬프트 캐싱 문서 — 최소 토큰 임계값·캐시 지점 한도
boto3 재시도 구성 — 재시도 모드·시도 수
Retry multiplication — 레이어가 겹치는 방식

Amazon Bedrock

Amazon Bedrock

Bedrock Converse

설치

설정

환경 변수

Bedrock Runtime API 커스터마이즈

커스텀 HTTP 헤더

서비스 티어

프롬프트 캐싱

예시 1: 자동 메시지 캐싱

예시 2: 종합 캐싱 전략

예시 3: CachePoint로 세밀하게 제어하기

캐시 사용 통계 접근

캐시 지점 한도

캐시 지점 배분 방식

자동 캐시 지점 제한

provider 인자

AWS 애플리케이션 추론 프로필 사용

재시도 구성

재시도 모드

Bedrock Mantle

기능 지원

더 알아보기 (Learn more)

`provider` 인자