Implantando Claude no Amazon Bedrock: IAM, Provisionamento e Inferência Cross-Region

O Amazon Bedrock coloca o Claude por trás da sua conta AWS existente: o IAM controla quem pode chamá-lo, o acesso ao modelo é solicitado por modelo por região, e alguns modelos precisam de um perfil de inferência cross-region para lidar com capacidade e latência.

Resumo

O Bedrock não é um substituto direto para a API Anthropic direta - é um modelo de autenticação e provisionamento diferente, sobreposto aos mesmos modelos Claude subjacentes.

Antes que qualquer código de aplicação possa chamar o Claude no Bedrock, três coisas devem existir: um principal IAM com permissão para invocar o Bedrock, uma concessão explícita de acesso ao modelo específico que você deseja, e, para alguns modelos, um perfil de inferência cross-region em vez de um ID de modelo simples de região única.

Pular qualquer um desses três passos produz um erro de permissão ou de não encontrado que se parece com um bug de código, mas é na verdade uma lacuna de provisionamento.

Esta página aborda a configuração do IAM, a solicitação de acesso ao modelo e a escolha entre um ID de modelo simples e um perfil de inferência cross-region, em seguida, mostra o formato da solicitação que o código da sua aplicação realmente chama.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from anthropic import AnthropicBedrock
 
client = AnthropicBedrock(aws_region="us-east-1")
 
response = client.messages.create(
    model="anthropic.claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Resuma este ticket em uma frase."}],
)
print(response.content[0].text)

Quando usar isto:

Sua organização já executa cargas de trabalho de produção na AWS e deseja que o uso do Claude flua através do IAM e faturamento existentes.
Você precisa que o tráfego do Claude permaneça dentro de um limite de rede gerenciado pela AWS por motivos de conformidade.
Você deseja que os gastos com o Claude contem contra um Contrato de Desconto Empresarial (Enterprise Discount Program) da AWS existente ou um acordo de uso comprometido.
Você está integrando o Claude a uma aplicação que já assume uma função IAM para todas as outras chamadas de serviço AWS.

Exemplo de Trabalho

import os
from anthropic import AnthropicBedrock
import anthropic
 
# aws_region é obrigatório - não há fallback de região padrão para Bedrock.
client = AnthropicBedrock(aws_region=os.environ.get("AWS_REGION", "us-east-1"))
 
 
def summarize_ticket(ticket_text: str) -> str:
    """Chama o Claude no Bedrock e retorna um resumo de uma frase.
 
    Assume que a função IAM do chamador tem permissão bedrock:InvokeModel e
    que o acesso ao modelo para claude-sonnet-5 foi concedido nesta região.
    """
    try:
        response = client.messages.create(
            model="anthropic.claude-sonnet-5",
            max_tokens=200,
            messages=[
                {
                    "role": "user",
                    "content": f"Resuma este ticket de suporte em uma frase:\n\n{ticket_text}",
                }
            ],
        )
        return response.content[0].text
    except anthropic.PermissionDeniedError:
        raise RuntimeError(
            "A função IAM não tem bedrock:InvokeModel, ou o acesso ao modelo nunca foi "
            "concedido para este modelo nesta região."
        )
    except anthropic.NotFoundError:
        raise RuntimeError(
            "ID do modelo não encontrado - verifique o prefixo anthropic. e confirme "
            "se o modelo está disponível nesta região AWS."
        )
 
 
if __name__ == "__main__":
    ticket = "Cliente relata que a página de login retorna um erro 500 após o último deploy."
    print(summarize_ticket(ticket))

O que isso demonstra:

AnthropicBedrock resolve credenciais AWS através da cadeia padrão (variáveis de ambiente, arquivo de credenciais compartilhado ou uma função IAM assumida) - não há chave de API Anthropic separada envolvida.
O prefixo anthropic. no ID do modelo é obrigatório no Bedrock; o ID claude-sonnet-5 sem prefixo da API direta retorna um 404 aqui.
Capturar PermissionDeniedError e NotFoundError separadamente transforma as duas falhas mais comuns no primeiro deploy em uma mensagem acionável em vez de um stack trace.

Mergulho Profundo

Como Funciona

Cada solicitação do Bedrock é autenticada como um principal IAM da AWS (uma função ou usuário), não por uma chave de API emitida pela Anthropic - o SDK assina as solicitações usando a cadeia de credenciais da AWS, da mesma forma que qualquer outra chamada baseada em boto3 faria.
O principal IAM precisa de uma política anexada concedendo bedrock:InvokeModel (e bedrock:InvokeModelWithResponseStream para streaming) com escopo para os ARNs de modelo específicos que você pretende chamar.
Ter a permissão IAM é necessário, mas não suficiente - cada modelo também requer uma concessão de acesso ao modelo explícita, solicitada por modelo por região AWS no console Bedrock antes da primeira invocação bem-sucedida.
As solicitações de acesso ao modelo são tipicamente aprovadas automaticamente para a maioria dos modelos Claude, mas a concessão ainda é um passo separado da anexação da política IAM, e ambos devem estar em vigor antes que o tráfego flua.
Alguns modelos adicionalmente requerem um perfil de inferência cross-region em vez de um ID de modelo simples - um ID de perfil que permite ao Bedrock rotear uma única solicitação lógica através de múltiplas regiões dentro de uma geografia para capacidade extra e menor latência de fila durante picos de demanda.

Formato da Política IAM

Uma política IAM mínima para invocar o Claude no Bedrock limita a ação aos recursos de modelo específicos em vez de conceder acesso geral ao Bedrock:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-sonnet-5",
        "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4-8"
      ]
    }
  ]
}

Limitar Resource a ARNs de modelo exatos, em vez de "*", significa que adicionar um novo modelo posteriormente requer uma atualização deliberada da política em vez de ser silenciosamente já permitido.
Se você usar um perfil de inferência cross-region, o padrão do ARN do recurso muda para referenciar o perfil de inferência em vez do ARN de modelo de fundação simples - verifique o console Bedrock para o ARN exato assim que o perfil for provisionado.

IDs de Modelo vs. Perfis de Inferência Cross-Region

Forma	Exemplo	Quando usar
ID de modelo simples	`anthropic.claude-sonnet-5`	Escolha padrão; funciona para a maioria dos modelos na maioria das regiões.
Perfil de inferência cross-region	`us.anthropic.claude-sonnet-5`	Necessário para alguns modelos; também útil quando uma única região está atingindo limites de capacidade durante o pico de demanda.

O prefixo de geografia do ID do perfil (us., por exemplo) indica em qual conjunto de regiões o perfil pode rotear - isso não significa que a solicitação sempre sairá da sua região principal, apenas que pode durante alta demanda.
Usar um ID de perfil onde um ID de modelo simples funcionaria é inofensivo; usar um ID de modelo simples onde um perfil é necessário retorna uma ValidationException no momento da solicitação, não um fallback silencioso.

Notas Python

from anthropic import AnthropicBedrock
 
# Prefira a configuração de região orientada por ambiente em vez de uma string codificada,
# para que o mesmo código implante limpo em uma segunda região posteriormente.
client = AnthropicBedrock(aws_region="us-east-1")
 
# O streaming funciona de forma idêntica à API direta - apenas a classe do cliente difere.
with client.messages.stream(
    model="anthropic.claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "Esboce uma nota de lançamento curta."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

AnthropicBedrock expõe os mesmos métodos messages.create e messages.stream que o cliente da API direta - o código escrito contra a API direta precisa apenas de uma mudança na construção do cliente para rodar no Bedrock.
O cliente legado AnthropicBedrock usa o caminho bedrock-runtime InvokeModel; verifique a documentação mais recente do SDK para o cliente mais novo baseado em Mantle se você precisar da superfície da API Messages mais recente no Bedrock.

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`aws_region`	`str`	Argumento obrigatório do construtor. Sem padrão - Bedrock não tem fallback de região implícito.
`model`	`str`	ID do modelo Bedrock, seja `anthropic.<modelo>` ou um perfil de inferência cross-region como `us.anthropic.<modelo>`.
`max_tokens`	`int`	Mesmo significado que a API direta - o limite máximo de tokens de saída para esta solicitação.

Armadilhas

Esquecer o prefixo anthropic. no ID do modelo. Um claude-sonnet-5 sem prefixo que funciona na API direta retorna um 404 no Bedrock. Correção: sempre prefixe os IDs de modelo Bedrock com anthropic..
Política IAM anexada, mas o acesso ao modelo nunca foi solicitado. A função tem bedrock:InvokeModel, mas a conta nunca solicitou acesso a esse modelo específico no console Bedrock. Correção: verifique a página Acesso ao Modelo no console Bedrock para esse modelo e região antes de assumir que é um problema de IAM.
Discrepância de região entre a política IAM e a construção do cliente. A política IAM limita o ARN do modelo a us-east-1, mas AnthropicBedrock(aws_region="us-west-2") é usado em tempo de execução. Correção: mantenha os ARNs de recurso da política IAM e o aws_region do cliente sincronizados, ou limite a política a várias regiões deliberadamente.
Usar um ID de modelo simples onde um perfil de inferência cross-region é necessário. Alguns modelos rejeitam um ID de modelo anthropic. simples com um erro de validação. Correção: verifique o console Bedrock para saber se o modelo requer um ID de perfil de inferência antes de configurar a integração.
Assumir que a aprovação de acesso ao modelo é instantânea. Alguns modelos ou regiões podem ter um atraso na revisão antes que o acesso seja concedido. Correção: solicite acesso ao modelo bem antes de uma data de lançamento, não no dia da implantação.
Codificar uma única região sem plano de fallback. Uma interrupção regional do Bedrock ou um limite de capacidade então não tem mitigação. Correção: considere um perfil de inferência cross-region, ou um caminho de fallback para outra plataforma, para cargas de trabalho sensíveis à latência ou disponibilidade.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
API Direta Anthropic	Você quer o caminho mais rápido para novos modelos e recursos, sem dependência da AWS.	Sua organização exige que o tráfego permaneça dentro da governança IAM e de rede gerenciada pela AWS.
Google Cloud Vertex AI	Sua organização está padronizada em GCP em vez de AWS.	Você não tem presença GCP e estaria adicionando um novo fornecedor de nuvem apenas para isso.
Um gateway auto-hospedado na frente do Bedrock	Você quer adicionar cache, limitação de taxa centralizada ou fallback para outro provedor sem tocar no código da aplicação.	Você tem uma única carga de trabalho simples onde a infraestrutura adicionada não vale o custo operacional.

FAQs

Preciso de uma chave de API Anthropic para usar o Claude no Bedrock?

Não. A autenticação é totalmente baseada em IAM - o SDK assina as solicitações com suas credenciais AWS, e não há chave de API separada emitida pela Anthropic envolvida.

Por que minha solicitação retorna um 404 mesmo que o nome do modelo pareça correto?

Os IDs de modelo Bedrock requerem o prefixo anthropic.. Um ID de modelo sem prefixo copiado do código da API direta, como claude-sonnet-5, não é um ID de modelo Bedrock válido por si só.

Qual é a diferença entre uma política IAM e acesso ao modelo?

A política IAM concede a permissão para chamar bedrock:InvokeModel em geral.
O acesso ao modelo é uma concessão separada, por modelo, por região, solicitada no console Bedrock.
Ambos devem estar em vigor - ter um sem o outro ainda falha.

Quando preciso de um perfil de inferência cross-region em vez de um ID de modelo simples?

Alguns modelos o exigem explicitamente, e também é útil para modelos sob forte demanda regional, pois o perfil pode rotear uma solicitação por várias regiões dentro de uma geografia para capacidade extra.

Como sei se minha conta tem acesso ao modelo para um determinado modelo?

Verifique a página Acesso ao Modelo no console Bedrock para sua conta e região de destino. Uma concessão ausente lá causa um erro de permissão no momento da solicitação, mesmo com uma política IAM corretamente escopada.

O mesmo código de aplicação pode rodar tanto na API direta quanto no Bedrock?

Na maioria das vezes, sim. Ambos os clientes expõem os mesmos métodos messages.create e messages.stream - as diferenças são a construção do cliente (chave de API vs. credenciais AWS mais região) e o formato do ID do modelo.

O que acontece se eu usar um ID de modelo simples onde um perfil é necessário?

A solicitação falha com um erro de validação no momento da chamada em vez de fazer um fallback silencioso para um modelo simples - verifique o console Bedrock para saber se o seu modelo de destino requer um ID de perfil antes de implantar.

O Bedrock suporta streaming da mesma forma que a API direta?

Sim. client.messages.stream(...) em AnthropicBedrock se comporta da mesma forma que no cliente da API direta, incluindo o iterador de conveniência text_stream.

Uma incompatibilidade de região entre a política IAM e a construção do cliente é uma falha comum?

Sim. Se a política IAM limita os ARNs de modelo a uma região, mas o cliente é construído com um aws_region diferente, as solicitações falham mesmo que a política pareça correta em uma leitura rápida.

Devo escopar políticas IAM para ARNs de modelo específicos ou usar um wildcard?

Escope para ARNs de modelo específicos. Um wildcard concede acesso a qualquer modelo que sua conta possa obter acesso posteriormente, o que é mais amplo do que a maioria das equipes pretendem e mais difícil de auditar.

A solicitação de acesso ao modelo tem algum custo por si só?

Não. O acesso ao modelo é uma concessão de permissão, não uma compra - a cobrança só ocorre quando você realmente invoca o modelo.

Por que uma equipe escolheria o Bedrock em vez da API direta, mesmo que seja mais configuração?

Para manter o tráfego do Claude dentro da governança IAM e de rede existente da AWS, e para que os gastos contem contra um acordo de faturamento ou desconto AWS existente em vez de um novo relacionamento com o fornecedor.

Relacionado

Escolhendo entre API Direta, Bedrock e Vertex AI para Claude - decida se o Bedrock é a plataforma certa antes de provisioná-lo.
Noções Básicas de Implantação Empresarial - a primeira chamada mínima em todas as três plataformas, incluindo Bedrock.
Executando Claude no Google Cloud Vertex AI: Quotas e Contas de Serviço - os passos de provisionamento equivalentes no GCP.
Checklist de Residência de Dados e Fixação de Região para Cargas de Trabalho Regulamentadas - como a escolha da região no Bedrock interage com os requisitos de conformidade.
Comparando Bedrock, Vertex AI e Acesso Direto à API Anthropic - trade-offs entre as três plataformas em uma tabela.

Versões da Pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o SDK oficial anthropic Python (última versão 0.x). Nomes de modelos, preços e versões de SDK mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.