Bedrock

이 문서에서는 pydantic-ai에서 Amazon Bedrock을 사용하는 방법을 알려드려요. Bedrock은 여러 프로바이더의 foundation model을 노출하며, Pydantic AI는 두 개의 별도 AWS API를 통해 접근해요. 모델 접두사로 경로를 선택하세요.

출처: 문서

본문

Amazon Bedrock은 여러 프로바이더의 foundation model을 노출하며, Pydantic AI는 두 개의 별도 AWS API를 통해 접근해요. 모델 접두사로 경로를 선택하세요:

Bedrock Converse (bedrock:) -- Bedrock Runtime Converse API를 통해 Anthropic, Amazon, Cohere, Meta, Mistral, DeepSeek, Qwen, 선택된 OpenAI 모델, 그리고 더 많은 모델을 포함한 가장 넓은 카탈로그. 거의 모든 Bedrock 모델의 경로예요.
Bedrock Mantle (bedrock-mantle:) -- Mantle의 OpenAI 호환 API를 통한 OpenAI GPT-5.x 및 GPT-OSS 모델.

두 경로 모두 같은 AWS 자격 증명으로 인증해요. bedrock: 접두사는 항상 Converse를 사용하며, 그것이 서빙하지 않는 OpenAI 모델을 요청하면 bedrock-mantle:를 가리키는 오류가 발생해요.

AWS는 새 애플리케이션에 bedrock-runtime 엔드포인트를 권장해요. Pydantic AI의 bedrock: 경로는 그 엔드포인트에서 Converse를 사용해요. OpenAI 호환 API나 Mantle에서만 사용 가능한 모델이 필요하면 bedrock-mantle:를 선택하세요.

Route

Prefix

Models

Optional group

Model class

Converse

bedrock:

Anthropic, Amazon, Cohere, Meta, Mistral, 선택된 OpenAI 모델, 등등

bedrock

BedrockConverseModel

Mantle

bedrock-mantle:

OpenAI GPT-5.x 및 GPT-OSS

bedrock-mantle

BedrockMantleResponsesModel, BedrockMantleChatModel

OpenAI model routes

GPT-OSS와 GPT-5.6 Sol, Luna, Terra는 두 경로에서 모두 사용 가능해요. GPT-5.4, GPT-5.5, GPT-5.6 Cyber는 Mantle에서만 사용 가능해요.

Converse에서 GPT-5.6은 교차 리전 inference-profile 모델 ID가 필요해요. Sol은 us.openai.gpt-5.6-sol과 global.openai.gpt-5.6-sol을 지원해요. Luna와 Terra는 us., in., global. ID를 지원해요. 현재 엔드포인트와 리전 가용성은 Sol, Luna, Terra의 AWS 모델 카드를 참고하세요.

Bedrock Converse

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

Install

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

Terminal

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

Terminal

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

Configuration

AWS Bedrock을 사용하려면 Bedrock이 활성화되고 적절한 자격 증명이 있는 AWS 계정이 필요해요. AWS 자격 증명을 직접 사용하거나 사전 구성된 boto3 클라이언트를 사용할 수 있어요.

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

Environment variables

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)
...

Customizing Bedrock Runtime API

가드레일 구성과 성능 설정 같은 추가 파라미터로 Bedrock Runtime API 호출을 맞춤 설정할 수 있어요. 구성 가능한 파라미터 전체 목록은 BedrockModelSettings 문서를 참고하세요.

customize_bedrock_model_settings.py

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)

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

Thinking and structured output

적응형 사고와 강제 도구 선택을 지원하는 Claude 모델에서 model_settings={'thinking': True}는 일반 구조화 출력(output_type=MyModel)과 명시적 ToolOutput 둘 다와 함께 동작해요. Pydantic AI는 네이티브나 prompted 출력으로 전환하는 대신 도구 출력을 계속 사용해요. 이것은 적응형 사고가 모델의 기본값일 때도 적용돼요.

강제 도구 응답은 보이는 thinking 블록을 생략할 수 있어요. 출력 도구를 강제하지 않으려면 PromptedOutput 또는 모델이 지원할 때 NativeOutput을 사용하세요.

수동 확장 thinking(bedrock_additional_model_requests_fields={'thinking': {'type': 'enabled', ...}})은 강제 도구와 여전히 호환되지 않아요. 일반 구조화 출력은 네이티브나 prompted 출력으로 폴백하고, 명시적 ToolOutput는 UserError를 발생시켜요. 강제 도구 선택을 지원하지 않는 모델은 적응형 사고에서도 이 제한을 유지해요. AWS의 적응형 사고 문서와 강제 도구 사용 제한을 참고하세요.

Custom HTTP headers

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'},
    ),
)

boto3가 관리하는 헤더(Authorization, User-Agent, X-Amz-Date, Host, Content-Length 등)를 재정의하려고 extra_headers를 사용하지 마세요. 그 값들은 무시되거나 요청 실패를 초래할 수 있어요.

Service tier

Bedrock은 service tier 제어를 지원해 처리량과 비용을 관리해요. 통합 service_tier 필드나 프로바이더 전용 bedrock_service_tier 필드를 사용할 수 있어요. 둘 다 설정되면 bedrock_service_tier가 통합 필드보다 우선해요.

통합 필드는 Bedrock에 대해 다음과 같이 매핑돼요:

'auto': serviceTier 필드가 요청에서 생략되어 AWS가 서버 측 기본값(Standard tier)을 적용해요.
'default': 명시적으로 {'type': 'default'}로 전송 — 미래의 서버 측 프리미엄 tier 자동 승격을 옵트아웃.
'flex': {'type': 'flex'}로 전송.
'priority': {'type': 'priority'}로 전송.

Bedrock의 'reserved' tier(사전 구매 용량 예약이 필요)를 요청하려면 bedrock_service_tier를 직접 설정하세요 — 통합 필드로는 도달할 수 없어요.

Prompt Caching

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

CachePoint로 사용자 메시지 캐시: 현재 사용자 메시지에서 그것 앞의 모든 것을 캐시하려면 CachePoint 마커를 삽입하세요. 사용자 프롬프트 부분의 시작에 있는 CachePoint는 그 메시지에서 그것 앞에 아무것도 없으므로, 대신 이전 사용자 메시지의 끝까지의 모든 것을 캐시해요. 확장 캐시 기간에 옵트인하려면 CachePoint(ttl='1h')를 전달하세요.
시스템 지침 캐시: BedrockModelSettings.bedrock_cache_instructions를 True로 설정(기본 5m TTL)하거나 '5m'/'1h'를 직접 지정하세요. 정적 및 동적 instructions을 둘 다 가질 때 캐시 지점은 마지막 정적 지침 뒤에 배치되어, 동적 지침이 정적 캐시를 무효화하지 않고 바뀔 수 있어요.
도구 정의 캐시: BedrockModelSettings.bedrock_cache_tool_definitions를 True로 설정(기본 5m TTL)하거나 '5m'/'1h'를 직접 지정하세요.
모든 메시지 캐시: BedrockModelSettings.bedrock_cache_messages를 True로 설정(기본 5m TTL)하거나 '5m'/'1h'를 직접 지정해 마지막 사용자 메시지를 자동으로 캐시하세요.

최소 토큰 임계값

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

Example 1: Automatic Message Caching

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

Example 2: Comprehensive Caching Strategy

여러 캐시 설정을 결합해 절감을 최대화하세요:

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)

Example 3: Fine-Grained Control with 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)

Accessing Cache Usage Statistics

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

Cache Point Limits

Bedrock은 요청당 최대 4개의 캐시 포인트를 강제해요. Pydantic AI는 오류 없이 요청이 항상 준수하도록 이 한도를 자동으로 관리해요.

How Cache Points Are Allocated

캐시 포인트는 세 위치에 배치될 수 있어요:

시스템 프롬프트: bedrock_cache_instructions 설정으로(마지막 시스템 프롬프트 블록에 캐시 포인트 추가)
도구 정의: bedrock_cache_tool_definitions 설정으로(마지막 도구 정의에 캐시 포인트 추가)
메시지: CachePoint 마커 또는 bedrock_cache_messages 설정으로(메시지 콘텐츠에 캐시 포인트 추가)

각 설정은 최대 1개의 캐시 포인트를 사용하지만, 결합할 수 있어요.

Automatic Cache Point Limiting

모든 소스(설정 + CachePoint 마커)의 캐시 포인트가 4를 초과하면 Pydantic AI는 더 오래된 메시지 콘텐츠에서 초과 캐시 포인트를 자동으로 제거해요(가장 최근 것 유지).

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` argument

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)
...

Using AWS Application Inference Profiles

AWS Bedrock은 비용 추적과 리소스 관리를 위한 커스텀 애플리케이션 inference 프로파일을 지원해요. 모델 능력 감지에 기본 모델 이름을 유지하면서 inference 프로파일을 통해 요청을 라우팅하려면 bedrock_inference_profile을 설정하세요:

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)

Configuring Retries

이 boto3 재시도는 Bedrock의 프로바이더 SDK 재시도 계층이에요. boto3는 반대쪽에서 세므로 Config(retries={'max_attempts': N})은 총 1 + N회 시도를 허용하며, boto3 아래에는 httpx2 전송 계층이 없어서 에이전트의 재시도 예산과 네트워크 사이의 유일한 재시도 계층이에요. 계층이 어떻게 쌓이는지는 재시도 곱셈을 참고하세요.

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)

Retry Modes

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

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

Note

HTTP 요청에 httpx를 사용하는 다른 프로바이더와 달리, Bedrock은 boto3의 네이티브 재시도 메커니즘을 사용해요. 전송 재시도에 설명된 재시도 전략은 Bedrock에 적용되지 않아요.

Bedrock Mantle

Amazon Bedrock Mantle은 OpenAI 호환 API를 통해 OpenAI GPT-5.x 및 GPT-OSS 모델을 서빙해요. Converse에서도 사용 가능한 모델은 OpenAI 모델 경로를 참고하세요. 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 토큰, 또는 SigV4를 통한 AWS 액세스 키/프로필 — 그리고 region_name(또는 AWS_DEFAULT_REGION/AWS_REGION 환경 변수)에서 엔드포인트를 파생해요.

모델 이름이 엔드포인트 계열을 결정해요:

Model name

Interface

GPT-5.4+, 예: bedrock-mantle:openai.gpt-5.6-luna

OpenAI Responses at /openai/v1

GPT-OSS, 예: bedrock-mantle:openai.gpt-oss-120b

OpenAI Responses at /v1

GPT-OSS Safeguard, 예: bedrock-mantle:openai.gpt-oss-safeguard-20b

OpenAI Chat Completions at /v1

커스텀 Mantle 오리진(예: 프록시)을 사용하려면 BedrockMantleProvider에 base_url을 전달하세요. 그 오리진(어떤 /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)

Feature support

Mantle 모델은 Pydantic AI의 OpenAI 모델 클래스 — BedrockMantleResponsesModel과 BedrockMantleChatModel — 로 서빙되므로 직접 OpenAI 모델(OpenAIResponsesModelSettings과 OpenAIChatModelSettings)과 같은 설정을 받아요.

위의 Converse 경로 기능 — 프롬프트 캐싱, service tier, 애플리케이션 inference 프로파일 — 은 Converse API 전용이며 Mantle 경로에는 적용되지 않아요. 특히 bedrock_service_tier는 Converse 설정이며, Mantle 모델은 OpenAI 모델 클래스로 서빙되므로 통합 service_tier를 같은 이름의 OpenAI 파라미터로 전달해요.

더 알아보기 (Learn more)

pydantic-ai 문서

Bedrock

Bedrock

본문

OpenAI model routes

Bedrock Converse

Install

Configuration

Environment variables

Customizing Bedrock Runtime API

Thinking and structured output

Custom HTTP headers

Service tier

Prompt Caching

Example 1: Automatic Message Caching

Example 2: Comprehensive Caching Strategy

Example 3: Fine-Grained Control with CachePoint

Accessing Cache Usage Statistics

Cache Point Limits

How Cache Points Are Allocated

Automatic Cache Point Limiting

provider argument

Using AWS Application Inference Profiles

Configuring Retries

Retry Modes

Bedrock Mantle

Feature support

더 알아보기 (Learn more)

`provider` argument