O que foi anunciado

A AWS anunciou a disponibilidade geral do GLM 5.3, modelo desenvolvido pela Z.ai, agora integrado ao Amazon Bedrock. A novidade amplia as opções de modelos de linguagem disponíveis na plataforma, com foco especial em codificação agêntica e tarefas de engenharia de software de longa duração — ou seja, fluxos de trabalho que exigem raciocínio encadeado e execução de múltiplas etapas ao longo de uma sessão.

Quem utiliza o GLM 5.3 pelo Amazon Bedrock conta com o modelo mais recente de pesos abertos da Z.ai, já dentro da postura de segurança e conformidade da AWS.

Características técnicas do modelo

O GLM 5.3 é o modelo principal da Z.ai e traz uma arquitetura mixture-of-experts (MoE) — uma abordagem em que diferentes “especialistas” dentro da rede são ativados de forma seletiva para cada token processado. No total, o modelo conta com 753 bilhões de parâmetros, mas apenas cerca de 40 bilhões ficam ativos por token, o que torna o processamento mais eficiente.

Ele é construído sobre a mesma base do GLM 5.2, com todos os avanços provenientes de um processo de pós-treinamento em escala — sem mudanças no modelo base em si.

Outros destaques técnicos:

• Janela de contexto de 1 milhão de tokens, permitindo processar documentos e conversas muito extensas em uma única chamada.
• Até 128 mil tokens de saída por requisição.
• Raciocínio sempre ativado, com níveis de esforço selecionáveis — o que permite ajustar o equilíbrio entre latência, consumo de tokens e desempenho na tarefa.

Prompt caching para reduzir custos e latência

O suporte ao GLM 5.3 no Bedrock inclui prompt caching explícito com cache points em prompts de sistema e mensagens. Esse recurso é especialmente útil quando o mesmo contexto é reutilizado em múltiplas chamadas ao modelo — ele ajuda a reduzir tanto a latência quanto os custos de tokens de entrada.

Disponibilidade e acesso

O GLM 5.3 está disponível para clientes empresariais elegíveis e pode ser acessado por meio dos perfis de inferência cross-região dos EUA e Global. Para começar a usar, é possível acessar o modelo diretamente pelo console do Amazon Bedrock ou de forma programática pelas APIs suportadas do Bedrock.

Informações sobre regiões AWS suportadas, endpoints, APIs, funcionalidades, perfis de inferência e preços estão disponíveis na documentação do Amazon Bedrock. Para uma visão mais aprofundada sobre o lançamento, a AWS também publicou um blog post de lançamento com mais detalhes.

Fonte

GLM 5.3 by Z.ai is now generally available on Amazon Bedrock (https://aws.amazon.com/about-aws/whats-new/2026/10/amazon-bedrock-glm-5-3/)

O que foi anunciado

A AWS anunciou uma nova skill chamada aws-ai-ml, disponível por meio do Agent Toolkit for AWS. Essa skill se conecta a agentes de código compatíveis com o Protocolo de Contexto de Modelo (MCP — Model Context Protocol) — como Kiro, Claude Code e Codex — e transforma qualquer um deles em um especialista em otimização de inferência do Amazon SageMaker AI.

Na prática, isso significa que o engenheiro pode descrever o que quer alcançar em linguagem natural — uma meta de latência, um limite de custo, um modelo que precisa avaliar — e o agente gera código executável no SageMaker Python SDK v3, pronto para revisar, ajustar e rodar no próprio ambiente.

O problema que essa skill resolve

O Amazon SageMaker AI oferece uma superfície enorme de opções: hospedagem em tempo real, em lote e assíncrona, capacidade sob demanda e reservada, instâncias heterogêneas, isolamento por Nuvem Privada Virtual (VPC — Virtual Private Cloud), escalonamento automático e integração com todos os fluxos de treinamento do serviço. A riqueza de opções é um ponto forte, mas também representa um desafio: a maioria dos engenheiros chega com um objetivo de negócio, não com conhecimento prévio sobre qual família de instâncias ou contêiner de serving vai atender melhor ao caso de uso.

A skill aws-ai-ml fecha essa lacuna. Em vez de navegar por documentação extensa para tomar uma decisão de infraestrutura, o engenheiro descreve a intenção e o agente age como um arquiteto de soluções: faz perguntas de esclarecimento, gera código baseado em benchmarks reais e adapta as recomendações às restrições de negócio. Tudo permanece visível e auditável — não há nada acontecendo por trás de uma interface opaca.

Como instalar e começar a usar

A skill pode ser utilizada de duas formas: localmente em qualquer agente compatível com MCP, ou dentro de um espaço JupyterLab no Amazon SageMaker Studio.

Opção A: uso com qualquer agente de código (Kiro, Claude Code, Codex ou outro compatível com MCP)

Passo 1 — Instalar o Agent Toolkit for AWS. O toolkit exige a Interface de Linha de Comando da AWS (AWS CLI — AWS Command Line Interface) versão 2.35 ou superior e o uv instalado. Em seguida, execute:

aws configure agent-toolkit

O comando detecta automaticamente os agentes presentes, instala as skills e configura o AWS MCP Server. Para detalhes de configuração por agente, consulte o guia de início rápido do Agent Toolkit for AWS.

Passo 2 — Instalar a skill aws-ai-ml.

npx skills add aws/agent-toolkit-for-aws/skills/aws-ai-ml

Passo 3 — Confirmar e começar. Abra o painel de chat do agente e pergunte: “What skills are available?”. A skill aws-ai-ml deve aparecer na lista. A partir daí, basta descrever o objetivo em linguagem natural.

Pré-requisitos: as credenciais AWS precisam ter permissões para chamar as APIs do SageMaker AI (criação de endpoints, execução de jobs de benchmark e recomendação). Nenhuma configuração adicional de Gerenciamento de Identidade e Acesso da AWS (IAM — AWS Identity and Access Management) é necessária para a skill em si.

Nota: para Kiro e Claude Code, os agentes conseguem descobrir skills em tempo de execução por meio do AWS MCP Server, sem necessidade de instalação local. Basta perguntar ao agente: “Search for AWS skills related to databases.” Consulte o readme para mais detalhes sobre descoberta de skills em tempo de execução.

Opção B: uso dentro do Amazon SageMaker Studio

Passo 1 — Abrir o Amazon SageMaker Studio. Acesse o Studio na conta e região AWS desejadas, selecione o domínio e inicie o IDE a partir do perfil de usuário.

Passo 2 — Criar um espaço JupyterLab. Na página inicial do Studio, escolha JupyterLab e depois Create JupyterLab space. Nomeie o espaço (por exemplo, my-inference-opt) e mantenha o compartilhamento como Private — as skills só sincronizam em espaços privados. No menu Image, selecione a imagem que já inclui a skill de inferência otimizada do SageMaker AI. Essa imagem vem pré-configurada com a skill aws-ai-ml e todas as dependências necessárias. Clique em Run space e aguarde a inicialização (5 a 10 minutos na primeira vez).

Passo 3 — Abrir o JupyterLab e iniciar um terminal.

Passo 4 — Autorizar o agente de código. No terminal, autentique-se com seu agente usando o provedor de identidade. Por exemplo, com o Kiro:

kiro-cli login --license pro --identity-provider <your-IdP-start-URL> --region us-east-1 --use-device-flow

Passo 5 — Confirmar e começar. Abra o painel de chat e pergunte: “What skills are available?”. A skill aws-ai-ml deve estar listada.

Solução de problemas: se o agente reportar que não há skills disponíveis, verifique se o espaço está configurado como Private. Também é possível checar pelo terminal com ls ~/.kiro/skills/. Se o diretório estiver vazio mas /etc/sagemaker/skills/ contiver os arquivos da skill, execute restart-jupyter-server, atualize a página e tente novamente.

O que a skill permite fazer

A experiência agentica cobre todo o ciclo de otimização de inferência. Não é necessário conhecer o nome de cada capacidade — basta descrever o objetivo e o agente identifica o próximo passo ou faz perguntas de esclarecimento.

Fazer benchmark de um endpoint existente

Se já houver um modelo implantado em um endpoint do SageMaker AI, o agente gera um notebook Python que executa um teste de carga usando as APIs Workload.synthetic() e start_benchmark() do SageMaker Python SDK. Antes de rodar qualquer benchmark, o agente confirma que o endpoint pode receber tráfego de teste, pois o processo gera carga real em infraestrutura ativa.

Ao final, o relatório traz métricas quantitativas medidas em condições reais:

• Throughput: requisições por segundo, tokens de saída por segundo
• Latência: p50, p99, tempo até o primeiro token (time-to-first-token), latência entre tokens (inter-token latency)
• Concorrência: número de requisições simultâneas suportadas

O agente também recomenda mecanismos de melhoria, como prefill decoding, para aumentar o desempenho.

Exemplo de prompt: “Benchmark my Llama endpoint on SageMaker AI.”

Encontrar o tipo de instância certo para o modelo

O agente aceita modelos de diferentes origens:

• Modelo customizado no Amazon Simple Storage Service (Amazon S3): forneça o URI do S3 e o objetivo de otimização. Exemplo: “I want to find the cheapest instance type to deploy my fine-tuned model on SageMaker.”
• Modelo de fundação disponível publicamente no Amazon SageMaker JumpStart: forneça o ID do modelo. Exemplo: “Find the best instance for model huggingface-reasoning-qwen3-8b on SageMaker AI.”
• Modelo no Hugging Face Hub: forneça o nome do modelo. Para modelos com acesso restrito (como variantes do Llama), o agente exibe os termos de licença e solicita o token do Hugging Face. Exemplo: “I want to deploy a Llama model from Hugging Face Hub. What’s the cheapest option?”

Em todos os casos, o agente gera código que avalia o modelo em candidatos de instância e retorna opções ranqueadas com métricas concretas: throughput, percentis de latência, tempo até o primeiro token e concorrência.

Comparar execuções de benchmark

Se houver dois benchmarks executados (por exemplo, antes e depois de uma mudança de configuração, ou em dois tipos de instância diferentes), o agente compara os resultados e calcula os deltas nas métricas principais. Valores positivos indicam melhoria. Se um dos benchmarks não existir, o agente se oferece para executá-lo antes de prosseguir com a comparação.

Exemplo de prompt: “I have two benchmark runs and I want to compare them. Which one is faster?”

Exemplo de resultado de comparação

A tabela abaixo compara dois modelos implantados na mesma carga de trabalho de benchmark (512/256 tokens, concorrência 4). A coluna Δ% mostra o quanto o Modelo B (Qwen3-8B) é mais rápido que o Modelo A (Qwen3-1.7B) em cada métrica — valores positivos indicam que o Modelo B é melhor:

Métrica	Qwen3-1.7B (Modelo A)	Qwen3-8B (Modelo B)	Δ%
Throughput de tokens de saída	188,2 tokens/s	271,2 tokens/s	+44,1% ✅
Throughput por usuário	47,5 tokens/s	69,4 tokens/s	+45,9% ✅
Throughput de requisições	0,736 req/s	1,08 req/s	+46,7% ✅
Latência entre tokens	20,9 ms	14 ms	+33,0% ✅
Latência de requisição	5.382 ms	3.658 ms	+32,0% ✅
Tempo até o primeiro token	67,5 ms	166,3 ms	−146,5% ❌

Vale notar que os dois modelos rodam em hardware diferente: o Qwen3-8B usa uma instância ml.g5.12xlarge com 4 GPUs A10G, enquanto o Qwen3-1.7B usa uma única GPU L4 na ml.g6.4xlarge. Os deltas refletem aproximadamente 4x mais poder computacional, não apenas a diferença entre os modelos. O Qwen3-8B entrega cerca de 44 a 47% mais throughput e menor latência fim a fim. O Qwen3-1.7B leva vantagem apenas no tempo até o primeiro token — benefício esperado de um modelo menor em uma única GPU.

Comportamentos esperados do agente

Equipado com a skill aws-ai-ml, o agente segue um conjunto de comportamentos que tornam a experiência previsível e segura:

• Pede o que falta: se alguma informação estiver ausente (como nome do endpoint ou URI do S3), o agente solicita em vez de adivinhar.
• Confirma antes de ações de impacto: antes de executar um benchmark que gera tráfego real em um endpoint ativo, o agente avisa sobre o impacto e pede confirmação explícita.
• Informa quando algo está fora de escopo: se for solicitado algo que o agente não consegue fazer (como implantar um modelo diretamente), ele explica o que pode oferecer em vez disso — como gerar a configuração de implantação.
• Gera código SageMaker Python SDK v3: toda saída é código executável que pode ser inspecionado, modificado e rodado no próprio ambiente do usuário.

Limpeza de recursos

Para evitar cobranças contínuas após os testes, a AWS recomenda:

• Excluir os endpoints do SageMaker AI criados durante os benchmarks ou recomendações.
• Parar ou excluir o espaço JupyterLab caso tenha usado o SageMaker Studio.
• Remover os objetos do S3 armazenados pelos jobs de benchmark e recomendação no bucket padrão do SageMaker AI.

Conclusão

A skill aws-ai-ml é uma adição relevante para equipes que já utilizam agentes de código no dia a dia e querem acelerar decisões de infraestrutura de inferência no SageMaker AI. Em vez de exigir que o engenheiro domine toda a superfície de opções do serviço, a skill transforma o agente em um especialista que gera código concreto a partir de intenções descritas em linguagem natural — com benchmarks reais, recomendações ranqueadas e comparações quantitativas.

Para começar, basta instalar a skill pelo Agent Toolkit for AWS e adicioná-la ao agente de código já em uso, ou iniciar um espaço JupyterLab pré-configurado no Amazon SageMaker Studio. Mais detalhes estão disponíveis na documentação oficial do Amazon SageMaker AI.

Fonte

New agent skill: Amazon SageMaker optimized generative AI inference for your coding agent (https://aws.amazon.com/blogs/machine-learning/new-agent-skill-amazon-sagemaker-optimized-generative-ai-inference-for-your-coding-agent/)

IA assistida para ambientes regulados: o que a AWS está oferecendo

A disponibilização dos modelos Claude Opus 5.5 e Claude Sonnet 5.5 no Amazon Bedrock dentro das regiões AWS GovCloud (US) representa uma novidade relevante para equipes que trabalham com cargas de trabalho sujeitas a requisitos regulatórios. Isso inclui organizações que precisam cumprir normas como o ITAR (Regulamento Internacional sobre Tráfego de Armas) e outras obrigações de conformidade governamental.

Em termos de certificações, o Claude Sonnet 5 já possui certificação FedRAMP Classe D (anteriormente chamada de High) e autorização DoD Nível de Impacto 4 e 5 (IL4/IL5). Já os modelos Claude Opus 5.5 e Claude Sonnet 5.5 possuem certificação FedRAMP Classe D no Amazon Bedrock — vale sempre verificar o status atual de certificação dos modelos diretamente na documentação oficial.

O objetivo desta publicação é mostrar como usar esses modelos no Amazon Bedrock dentro do AWS GovCloud (US) em conjunto com o Claude Code, a ferramenta de codificação agêntica da Anthropic, para acelerar tarefas de desenvolvimento sem abrir mão dos controles de conformidade.

Amazon Bedrock no AWS GovCloud (US)

As regiões AWS GovCloud (US) foram projetadas especificamente para clientes norte-americanos com necessidades elevadas de conformidade. Nelas, é possível executar cargas de trabalho de IA generativa em ambientes sensíveis mantendo os controles exigidos por regulamentações governamentais.

O Amazon Bedrock nesse ambiente oferece recursos de segurança como:

• Proteção de dados integrada: o conteúdo dos clientes não é armazenado, registrado nem utilizado para treinar modelos da AWS ou compartilhado com terceiros.
• Certificação FedRAMP Classe D e caminhos de autorização DoD CSP SRG IL4/IL5, atendendo aos requisitos de conformidade de agências governamentais. Consulte a página de conformidade dos modelos do Amazon Bedrock para o status atualizado.
• Integração com os controles de segurança e frameworks de conformidade disponíveis no AWS GovCloud (US), mantendo os mesmos padrões de segurança das demais regiões AWS.

Dois endpoints disponíveis

O Amazon Bedrock no AWS GovCloud (US) oferece dois endpoints distintos, ambos alimentados pelo mesmo mecanismo de inferência Mantle com arquitetura de Acesso Zero ao Operador (ZOA):

• bedrock-runtime: utiliza o SDK da AWS (APIs InvokeModel e Converse) e suporta Amazon Bedrock Guardrails, Amazon Bedrock Knowledge Bases, Agentes e registro de invocações. É a opção recomendada para a maioria das aplicações novas, especialmente as que precisam de trilhas de auditoria. Está disponível nas duas regiões do AWS GovCloud (US-West e US-East).
• bedrock-mantle: suporta nativamente a API de Mensagens da Anthropic e oferece acesso a capacidades como ferramentas server-side, inferência em segundo plano e Projetos. Disponível apenas no AWS GovCloud (US-West).

Ambos os endpoints estão disponíveis para Claude Opus 5.5, Claude Sonnet 5.5 e Claude Sonnet 5.

O que é o Claude Code

O Claude Code é a ferramenta de codificação agêntica da Anthropic. Ela lê a base de código do projeto, edita arquivos, executa comandos e se integra às ferramentas de desenvolvimento. Funciona diretamente no terminal, em IDEs (Ambientes de Desenvolvimento Integrado) como VS Code e JetBrains, e em segundo plano via Claude Agent SDK.

Entre as principais capacidades do Claude Code estão:

• Escrever código e corrigir bugs em múltiplos arquivos da base de código.
• Responder perguntas sobre arquitetura e lógica do código.
• Executar e corrigir testes, linting e outros comandos.
• Navegar pelo histórico do Git, resolver conflitos de merge e criar commits e pull requests.
• Conectar-se a ferramentas e fontes de dados externas com o Protocolo de Contexto de Modelo (MCP), incluindo a Interface de Linha de Comando da AWS (AWS CLI), Terraform e Kubernetes.
• Criar sub-agentes que trabalham em partes diferentes de uma tarefa ao mesmo tempo.
• Personalizar comportamento com arquivos de memória CLAUDE.md, skills para fluxos de trabalho repetíveis e hooks para automação pré/pós-ação.
• Automatizar tarefas recorrentes e integrar com pipelines de Integração e Entrega Contínua (CI/CD) via GitHub Actions ou GitLab CI/CD.

Para se aprofundar, a Anthropic disponibiliza tutoriais do Claude Code e um guia de boas práticas para codificação agêntica.

Como configurar o Claude Code com Amazon Bedrock no AWS GovCloud (US)

Pré-requisitos

• Uma conta AWS GovCloud (US) com acesso ao Amazon Bedrock.
• Funções e permissões de Gerenciamento de Identidade e Acesso da AWS (IAM) adequadas. No mínimo, a política IAM deve incluir:
  • Para bedrock-runtime: bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListInferenceProfiles e bedrock:GetInferenceProfile.
  • Para bedrock-mantle: bedrock-mantle:CreateInference, bedrock-mantle:GetProject, bedrock-mantle:ListProjects e bedrock-mantle:ListModels. Alternativamente, anexe a política gerenciada AmazonBedrockMantleInferenceAccess.
• Acesso aos modelos do Amazon Bedrock habilitado para Claude Opus 5.5, Claude Sonnet 5.5 e Claude Sonnet 5 na conta AWS GovCloud (US).
• AWS CLI configurado com credenciais de sessão válidas usando chaves de API de curto prazo ou login via AWS SSO.

Instalação do Claude Code

Após configurar a AWS CLI com suas credenciais, instale o Claude Code usando um dos métodos abaixo:

• macOS, Linux, WSL: curl -fsSL https://claude.ai/install.sh | bash
• Windows PowerShell: irm https://claude.ai/install.ps1 | iex
• Windows CMD: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
• Homebrew (macOS/Linux): brew install --cask claude-code

Para métodos adicionais de instalação, consulte a documentação de instalação do Claude Code.

Opção A: Assistente de configuração interativo (recomendado)

Navegue até o projeto e inicie o Claude Code:

cd your-code-project
claude

Execute o assistente de login com /login. No prompt, selecione 3rd-party platform e depois Amazon Bedrock. Siga as instruções para escolher o método de autenticação, a região (us-gov-west-1) e fixar os modelos. A configuração é salva automaticamente no arquivo de configurações. Se já tiver o Claude Code configurado anteriormente, use /setup-bedrock para reabrir o assistente.

Opção B: Configuração manual por variáveis de ambiente

Para implantações automatizadas ou corporativas, defina as seguintes variáveis de ambiente:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION='us-gov-west-1'
export ANTHROPIC_MODEL='us-gov.anthropic.claude-sonnet-5-5'

Para usar o Claude Opus 5.5 como modelo principal:

export ANTHROPIC_MODEL='us-gov.anthropic.claude-opus-5-5'

Para fixar versões específicas dos modelos em implantações de equipe:

export ANTHROPIC_DEFAULT_OPUS_MODEL='us-gov.anthropic.claude-opus-5-5'
export ANTHROPIC_DEFAULT_SONNET_MODEL='us-gov.anthropic.claude-sonnet-5-5'

Em seguida, navegue até o projeto e inicie o Claude Code:

cd your-code-project
claude

Opção C: Usando o endpoint Bedrock Mantle

Para rotear o Claude Code pelo endpoint Mantle:

export CLAUDE_CODE_USE_MANTLE=1
export AWS_REGION='us-gov-west-1'

Quando ambos os endpoints são necessários na mesma sessão:

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_USE_MANTLE=1

Atenção: Guardrails e registro de invocações estão disponíveis exclusivamente pelo endpoint bedrock-runtime. Para implantações que exigem esses recursos de conformidade, use o bedrock-runtime (Opções A ou B).

Verificando a configuração

Confirme que o Claude Code está rodando verificando a mensagem Welcome to Claude Code! no terminal. Execute o comando /status para confirmar o modelo e o provedor. A linha do provedor deve exibir Amazon Bedrock ou Amazon Bedrock (Mantle), dependendo da configuração. Para mais detalhes, consulte a documentação sobre Claude Code no Amazon Bedrock.

Considerações para implantação organizacional

Com o Claude Code disponível para uso geral, o próximo passo é definir como implantá-lo em toda a organização. Alguns pontos importantes a considerar:

• Identidade e acesso centralizado: use o AWS IAM Identity Center para governar centralmente o acesso ao Claude Code. Isso garante que apenas desenvolvedores autorizados tenham acesso e permite o uso de credenciais temporárias baseadas em função, eliminando a necessidade de chaves de acesso estáticas. Antes de abrir o Claude Code, configure a AWS CLI com um perfil do IAM Identity Center: aws configure sso --profile <PROFILE_NAME> e faça login com aws sso login --profile <PROFILE_NAME>.
• Configuração automatizada: considere automatizar as variáveis de ambiente padrão para que o Claude Code se conecte automaticamente ao Amazon Bedrock. As organizações podem começar com instruções de autoatendimento para desenvolvedores ou usar arquivos de configuração para gerenciamento centralizado.
• Implantações empresariais de grande escala: considere implementar a Orientação para Claude Code com Amazon Bedrock. Essa orientação ajuda organizações a implantar o Claude Code mantendo controle rigoroso sobre o acesso a recursos de IA, conectando-se à infraestrutura de identidade existente e fornecendo observabilidade sobre produtividade e padrões de uso.
• Cotas de serviço: revise as cotas de serviço e defina os valores adequados de tokens por minuto (TPM) e requisições por minuto (RPM) com base no número de desenvolvedores ativos. Siga as recomendações de limites de taxa para orientação.
• Fixação de versões de modelos: fixe versões específicas dos modelos para implantações consistentes em equipe. Sem fixação, aliases como sonnet e opus resolvem para os padrões internos do Claude Code, que podem mudar entre versões. O Claude Code usa Claude Opus 5.5 como modelo principal por padrão, portanto uma implantação sem fixação será cobrada pela taxa por token do Opus. Para manter equipes no Claude Sonnet 5.5, defina ANTHROPIC_MODEL com o ID completo do modelo. No AWS GovCloud (US), use o prefixo us-gov. para IDs de perfis de inferência entre regiões.
• Monitoramento de custos: sessões do Claude Code podem ser intensivas em tokens, especialmente com Claude Opus 5.5, que tem custo por token mais alto que o Claude Sonnet 5.5. Implemente guardrails de tokens por usuário para aplicar limites diários por desenvolvedor, com alertas nos limiares de 80% e 100%. Esse padrão usa Amazon CloudWatch, AWS Lambda e Amazon DynamoDB para rastrear e aplicar limites em tempo quase real. Use prompt caching para reduzir custos e melhorar tempos de resposta — opções de TTL de 5 minutos e 1 hora estão disponíveis para modelos suportados. Considere usar Claude Sonnet 5.5 como padrão para equipes (menor custo) e reservar o Claude Opus 5.5 para tarefas que exigem raciocínio mais profundo ou execuções autônomas mais longas. Consulte o Guia de Implementação de Monitoramento do Claude Code para padrões adicionais de observabilidade.
• Permissões, memória e servidores MCP: equipes de segurança podem configurar permissões gerenciadas para o que o Claude Code pode ou não fazer — configurações que não podem ser sobrescritas por configurações locais. Além disso, configure arquivos de memória CLAUDE.md nos projetos para adicionar automaticamente fluxos de trabalho comuns, convenções de estilo e padrões de codificação da organização. Implante o arquivo CLAUDE.md em um diretório corporativo para que todos os desenvolvedores herdem a mesma base. Use hooks para aplicar automações pré/pós-ação, como formatação automática ou verificações de lint.
• Escolha do endpoint adequado: o endpoint bedrock-runtime suporta Guardrails, registro de invocações e inferência entre regiões nas duas regiões do AWS GovCloud (US). O endpoint bedrock-mantle suporta nativamente a API de Mensagens da Anthropic e está disponível no AWS GovCloud (US-West). Como Guardrails e registro de invocações são exclusivos do bedrock-runtime, para implantações que exigem trilhas de auditoria completas e filtragem de conteúdo, o bedrock-runtime é o recomendado.
• Avaliação de segurança: realize uma avaliação de segurança completa antes da implantação. O Amazon Bedrock protege a camada de inferência, mas o Claude Code roda nas máquinas locais dos desenvolvedores e requer avaliação e gestão de risco separadas. Aplique controles como permissões gerenciadas, registro de invocações e limites de tokens por usuário, assim como faria com qualquer outro software de terceiros no ambiente.

Conclusão

A disponibilização do Claude Opus 5.5 e do Claude Sonnet 5.5 no Amazon Bedrock dentro do AWS GovCloud (US) oferece às organizações um caminho alinhado à conformidade para desenvolvimento assistido por IA em cargas de trabalho reguladas. Cada modelo tem seu perfil:

• Claude Sonnet 5, com certificação FedRAMP Classe D e autorização DoD IL4/IL5, oferece a maior cobertura de conformidade para ambientes mais sensíveis.
• Claude Sonnet 5.5, com certificação FedRAMP Classe D, representa um avanço em codificação e trabalho de conhecimento a um custo por tarefa menor.
• Claude Opus 5.5, com certificação FedRAMP Classe D, traz raciocínio mais profundo e capacidades de execução autônoma mais longas para cargas de trabalho onde esse nível de certificação é suficiente.

Combinado com o Claude Code, equipes podem adotar fluxos de trabalho de codificação agêntica diretamente no terminal, na IDE ou em pipelines de CI/CD, mantendo os dados dentro da infraestrutura do AWS GovCloud (US). A escolha entre o endpoint bedrock-runtime — para suporte completo a Guardrails e logging — ou o bedrock-mantle — para acesso nativo à API de Mensagens da Anthropic — permite adaptar a implantação aos requisitos de conformidade e operacionais de cada organização.

Saiba mais

• Amazon Bedrock no AWS GovCloud (US)
• Claude Code no Amazon Bedrock
• Orientação para Claude Code com Amazon Bedrock
• Status de certificação FedRAMP e autorização DoD dos modelos do Amazon Bedrock
• Guardrails de tokens por usuário para Amazon Bedrock em agências governamentais
• Claude Sonnet 5.5 no AWS GovCloud (US)
• Claude Opus 5.5 no AWS GovCloud (US)

Fonte

Supercharge regulated workloads with Claude Code and Amazon Bedrock (https://aws.amazon.com/blogs/machine-learning/supercharge-regulated-workloads-with-claude-code-and-amazon-bedrock/)

O problema com perguntas complexas em RAG

Imagine que um usuário pergunta ao assistente de suporte: “Compare o serviço de checkout e o de inventário em termos de escalonamento de plantão, metas de backup e restauração, e procedimento de rollback de deploy. Onde eles diferem?” Essa única pergunta, na prática, contém seis intenções distintas — dois serviços multiplicados por três dimensões.

O problema é que a busca por similaridade tradicional usa um único vetor para representar todas essas intenções ao mesmo tempo. O resultado é uma espécie de “média” das intenções, e os trechos recuperados, embora topicamente relevantes, cobrem apenas parte do que foi perguntado. A resposta chega concisa, sem erros aparentes, com scores razoáveis — mas incompleta.

É exatamente esse cenário que a recuperação agêntica no Amazon Bedrock Managed Knowledge Base foi projetada para resolver. Em vez de uma única busca, o serviço planeja a recuperação: decompõe a pergunta em sub-consultas, executa cada uma, avalia se as evidências coletadas são suficientes e, se não forem, busca novamente.

Visão geral da solução

O Amazon Bedrock Managed Knowledge Base é a capacidade de Geração Aumentada por Recuperação (RAG) totalmente gerenciada do Amazon Bedrock. Ela elimina a necessidade de gerenciar o próprio armazenamento vetorial, modelos de embedding e re-ranqueamento. Basta configurar uma fonte de dados — neste caso, um bucket do Serviço de Armazenamento Simples da Amazon (Amazon S3) — e o serviço cuida de chunking, embedding, armazenamento e recuperação.

O serviço expõe duas APIs principais:

• Retrieve: executa uma única busca híbrida e retorna trechos com pontuação de relevância.
• AgenticRetrieveStream: executa um loop de planejamento e transmite os passos de volta como eventos de rastreamento.

No pacote langchain-aws, a primeira API se comporta como um retriever LangChain padrão que pode ser encaixado em qualquer chain. A segunda é exposta como uma função standalone, já que o modelo de streaming não se encaixa na interface síncrona do BaseRetriever.

Pré-requisitos e permissões

Para seguir o walkthrough, são necessários: uma conta AWS com acesso ao Amazon Bedrock na região US East (N. Virginia) — us-east-1 —, Python 3.12 ou superior, um bucket S3 com documentos de amostra e os seguintes pacotes instalados:

langchain-aws>=1.6.3
langchain>=1.0
boto3>=1.43.32

A versão do Boto3 importa: a função agentic_retrieve_stream não existia antes da versão 1.43.32. Verifique a documentação da AWS para disponibilidade em outras regiões.

Duas identidades do Controle de Acesso e Identidade (IAM) estão envolvidas e vale separá-las deliberadamente. A service role é assumida pelo Knowledge Base para ler os documentos e chamar o modelo de embedding. A identidade que chama as APIs é a da sua aplicação. Nenhuma precisa das permissões da outra.

A service role precisa de uma política de confiança que permita ao Amazon Bedrock assumi-la, com as condições aws:SourceAccount e aws:SourceArn para evitar o problema de “confused deputy”:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "bedrock.amazonaws.com"},
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {"aws:SourceAccount": "111122223333"},
      "ArnLike": {
        "aws:SourceArn": "arn:aws:bedrock:us-east-1:111122223333:knowledge-base/*"
      }
    }
  }]
}

A identidade chamadora precisa de um conjunto diferente de permissões. Note que bedrock:AgenticRetrieveStream e bedrock:InvokeModelWithResponseStream não podem ser escopadas a um ARN de knowledge base específico, mas bedrock:Retrieve e bedrock:GetDocumentContent podem:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AgenticRetrievalAndPlannerModel",
      "Effect": "Allow",
      "Action": [
        "bedrock:AgenticRetrieveStream",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    },
    {
      "Sid": "RetrieveAndFullDocumentExpansion",
      "Effect": "Allow",
      "Action": ["bedrock:Retrieve", "bedrock:GetDocumentContent"],
      "Resource": "arn:aws:bedrock::111122223333:knowledge-base/"
    },
    {
      "Sid": "GenerateAnswersInTheChains",
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel", "bedrock:Converse", "bedrock:ConverseStream"],
      "Resource": "*"
    }
  ]
}

Um detalhe frequentemente negligenciado: bedrock:GetDocumentContent é chamado quando o planejador decide que um trecho não tem contexto suficiente e precisa buscar o documento inteiro — etapa chamada de FullDocumentExpansion. Uma política que tem apenas bedrock:Retrieve vai funcionar até o planejador tentar expandir um documento e falhar no meio da consulta.

Criando e populando o Knowledge Base

O Knowledge Base é criado com managedKnowledgeBaseConfiguration. Definir embeddingModelType como MANAGED usa o modelo de embedding gerenciado pelo serviço. Note a ausência de storageConfiguration na requisição — para um Knowledge Base gerenciado, o Amazon Bedrock é responsável pela camada de armazenamento:

import boto3
import os

REGION = os.environ["AWS_REGION"]
bedrock_agent = boto3.client("bedrock-agent", region_name=REGION)

response = bedrock_agent.create_knowledge_base(
    name=KB_NAME,
    roleArn=KB_ROLE_ARN,
    knowledgeBaseConfiguration={
        "type": "MANAGED",
        "managedKnowledgeBaseConfiguration": {
            "embeddingModelType": "MANAGED",
        },
    },
)
KB_ID = response["knowledgeBase"]["knowledgeBaseId"]

Após criar o Knowledge Base, o bucket S3 é anexado como fonte de dados e um job de ingestão é iniciado. A ingestão é assíncrona — o código abaixo faz polling até o job atingir um estado terminal:

import time

SUCCESS_STATES = frozenset({"COMPLETE"})
FAILURE_STATES = frozenset({"FAILED", "STOPPED"})

def wait_for_ingestion(kb_id, ds_id, job_id, timeout_s=1800):
    """Poll an ingestion job until it reaches a terminal state."""
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        job = bedrock_agent.get_ingestion_job(
            knowledgeBaseId=kb_id,
            dataSourceId=ds_id,
            ingestionJobId=job_id,
        )["ingestionJob"]
        status = job["status"]
        if status in SUCCESS_STATES:
            return job
        if status in FAILURE_STATES:
            reasons = job.get("failureReasons") or ["no reason reported"]
            raise RuntimeError(f"Ingestion job {job_id} finished as {status}: " + "; ".join(reasons))
        time.sleep(15)
    raise TimeoutError(f"Ingestion job {job_id} did not finish in {timeout_s}s")

A configuração completa da fonte de dados e o tratamento de erros estão no repositório de exemplos.

Consulta com o retriever padrão do LangChain

O AmazonKnowledgeBasesRetriever encapsula a API Retrieve e se comporta como qualquer outro retriever LangChain. Para o Managed Knowledge Base, é necessário passar managedSearchConfiguration — e não vectorSearchConfiguration, que é o caminho para knowledge bases com armazenamento vetorial próprio (o que a maioria dos exemplos existentes ainda mostra):

from langchain_aws.retrievers import AmazonKnowledgeBasesRetriever

SIMPLE_QUERY = "What is the restore time objective for the checkout service?"

retriever = AmazonKnowledgeBasesRetriever(
    knowledge_base_id=KB_ID,
    region_name=REGION,
    retrieval_config={
        "managedSearchConfiguration": {
            "numberOfResults": 5,
        }
    },
)

docs = retriever.invoke(SIMPLE_QUERY)

Cada resultado retorna como um Document do LangChain. O score de relevância fica em metadata["score"] e os metadados do documento fonte ficam em metadata["source_metadata"]. Para perguntas com uma única intenção clara, essa é a abordagem correta: uma chamada, latência baixa, controle total sobre como a resposta é gerada.

O limite da busca simples em perguntas complexas

Ao passar a pergunta comparativa com seis intenções para o mesmo retriever, o resultado revela a limitação estrutural. Com cinco chunks retornados, a busca cobre apenas 4 das 6 sub-intenções. Com dez chunks, cobre todas as seis — mas com redundância visível: duas sub-intenções aparecem cobertas duas vezes e um chunk não cobre nenhuma. O problema não é de implementação; é estrutural. Um único vetor não consegue representar seis intenções, e não há etapa no processo que avalie se as evidências retornadas são suficientes para responder a pergunta.

Executando a recuperação agêntica

A recuperação agêntica não é um retriever LangChain, mas uma funcionalidade do Amazon Bedrock Managed Knowledge Base. O pacote langchain-aws a expõe como a função standalone agentic_retrieve:

from langchain_aws.retrievers.bedrock import agentic_retrieve

result = agentic_retrieve(
    knowledge_base_id=KB_ID,
    query=COMPLEX_QUERY,
    region_name=REGION,
    generate_response=True,
    number_of_results=10,
)

print(result["generatedResponse"]["answer"])

Com generate_response=True, o serviço retorna uma resposta fundamentada e citações junto com os chunks recuperados — sem necessidade de uma chamada de modelo separada. Internamente, o serviço planeja, recupera, avalia se as evidências são suficientes e itera se necessário.

Lendo os eventos de rastreamento do planejador

Para observar como o modelo decompõe a pergunta, é necessário chamar agentic_retrieve_stream diretamente no cliente bedrock-agent-runtime do Boto3. Esse é o único ponto do walkthrough em que se contorna o langchain-aws, pois o helper descarta os eventos de rastreamento e não expõe maxAgentIteration nem um modelo de planejador customizado:

runtime = boto3.client("bedrock-agent-runtime", region_name=REGION)

response = runtime.agentic_retrieve_stream(
    messages=[{"role": "user", "content": {"text": COMPLEX_QUERY}}],
    retrievers=[{
        "configuration": {
            "knowledgeBase": {
                "knowledgeBaseId": KB_ID,
                "retrievalOverrides": {"maxNumberOfResults": 10},
            }
        }
    }],
    agenticRetrieveConfiguration={
        "foundationModelType": "MANAGED",
        "rerankingModelType": "MANAGED",
        # 5 is the API default. Below 4 the planner stops decomposing entirely.
        "maxAgentIteration": 5,
    },
    generateResponse=False,
)

for event in response["stream"]:
    if "traceEvent" in event:
        attrs = event["traceEvent"]["attributes"]
        print(f"{attrs.get('step')}: {attrs.get('status')}")
        for action in attrs.get("actions", []) or []:
            if "retrieve" in action:
                query = action["retrieve"].get("inputQuery", {}).get("text", "")
                print(f"  sub-query: {query}")
    elif "result" in event:
        for chunk in event["result"].get("results", []):
            print(chunk.get("content", {}).get("text", "")[:120])

Definir generateResponse como False é recomendado quando o objetivo é apenas inspecionar o plano — evita uma chamada de modelo extra desnecessária.

Cada evento de rastreamento tem um campo step que indica onde o planejador está:

• SpeculativeRetrieval: executa antes do primeiro plano para reduzir latência e não conta contra o orçamento de iterações.
• Planning: o modelo lê a pergunta e os resultados anteriores e emite sub-consultas.
• Retrieval: disparado uma vez por sub-consulta.
• FullDocumentExpansion: aparece quando o modelo decide que um trecho não tem contexto suficiente e busca o documento inteiro.

O texto das sub-consultas — a parte mais valiosa para logging — fica em attributes.actions[].retrieve.inputQuery.text, não nos campos de nível superior do trace. Um handler que lê apenas step e status mostra que o planejamento aconteceu, mas não o que foi decidido.

Dois detalhes importantes antes de construir sobre essa API: a deduplicação se aplica apenas ao evento result — um chunk recuperado por três sub-consultas aparece uma vez no final, mas três vezes nos traces. E ao contrário da API Retrieve, os resultados da recuperação agêntica não têm um campo score tipado. Código que lê result["score"] após trocar de API não vai encontrar nada.

Sobre o parâmetro maxAgentIteration: ele aceita valores entre 2 e 10 e tem padrão 5. Com valores 2 ou 3, o planejador executa apenas um ciclo, não emite sub-consultas e retorna o que a etapa de SpeculativeRetrieval já encontrou — comportamento de busca simples com custo agêntico. A decomposição começa a partir de 4. O planejador frequentemente para antes de atingir o limite quando julga que as evidências são suficientes.

Construindo a RAG chain com LangChain

Para o retriever padrão, a composição usual com a LangChain Expression Language (LCEL) funciona diretamente:

from langchain_aws import ChatBedrockConverse
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough

def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)

llm = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
prompt = ChatPromptTemplate.from_template(PROMPT_TEMPLATE)

chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

Para encaixar a recuperação agêntica na mesma posição, é necessário envolvê-la em um RunnableLambda, já que ela é uma função e não um retriever:

from langchain_core.runnables import RunnableLambda

def agentic_context(question: str) -> str:
    result = agentic_retrieve(
        knowledge_base_id=KB_ID,
        query=question,
        region_name=REGION,
        number_of_results=10,
    )
    return "\n\n".join(
        item.get("content", {}).get("text", "")
        for item in result.get("results", [])
    )

agentic_chain = (
    {"context": RunnableLambda(agentic_context), "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

Note que generate_response está desativado aqui. Dentro de uma chain, o usual é querer controlar o próprio prompt e modelo — então os chunks são recuperados e a geração acontece downstream. Use a geração do próprio serviço quando quiser uma única chamada com menos código.

Quando usar cada abordagem

A recomendação é rotear com base no formato da consulta, em vez de escolher uma abordagem para tudo:

• Use Retrieve para perguntas curtas e bem delimitadas. É mais barato, mais rápido, funciona com knowledge bases autogerenciados e retorna scores nos resultados. A maior parte do tráfego de produção tem esse formato.
• Use AgenticRetrieveStream quando as perguntas forem multi-parte, comparativas ou exploratórias, ou quando as evidências estiverem espalhadas por mais de um knowledge base. A API suporta até cinco knowledge bases em uma única requisição, roteando sub-consultas com base em descrições em linguagem natural. Custa mais por chamada, faz várias invocações de modelo e tem latência mais alta.

Um classificador ou heurística sobre o formato da pergunta pode enviar a maior parte do tráfego pelo caminho barato e reservar o planejador para as consultas que realmente precisam dele. A AWS avaliou a recuperação agêntica no benchmark público MuSiQue (multi-hop) e observou melhora no recall em relação à busca simples, com os maiores ganhos nas perguntas mais difíceis. Perguntas de um único salto tiveram ganhos abaixo de cinco pontos — o que ilustra bem o trade-off: a decomposição ajuda quando há algo para decompor.

Em produção, o Amazon Bedrock Guardrails pode ser usado para aplicar políticas de conteúdo e verificações de fundamentação nas respostas geradas. Ambos os caminhos de recuperação suportam guardrails — mas a recuperação agêntica usa policyConfiguration.bedrockGuardrailConfiguration e suporta apenas o modo BLOCK. Se o modo MASK for necessário, isso é um motivo para permanecer na API Retrieve.

Limpeza dos recursos

Ao finalizar os experimentos, é importante remover os recursos criados para evitar cobranças contínuas de armazenamento:

bedrock_agent.delete_data_source(knowledgeBaseId=KB_ID, dataSourceId=DS_ID)
bedrock_agent.delete_knowledge_base(knowledgeBaseId=KB_ID)

O repositório de exemplos inclui um script de limpeza que também esvazia o bucket e remove a role.

Conclusão

A recuperação agêntica no Amazon Bedrock Managed Knowledge Base resolve um problema estrutural das aplicações RAG tradicionais: a incapacidade de um único vetor representar múltiplas intenções simultâneas. O loop de planejamento decompõe perguntas complexas, avalia as evidências coletadas e itera quando necessário — entregando cobertura superior em consultas multi-parte.

A integração com LangChain tem algumas arestas: a recuperação agêntica é uma função e não um retriever, então precisa de um RunnableLambda para entrar em uma chain. Os eventos de rastreamento que mostram o plano de consulta exigem uma chamada direta via Boto3. São trade-offs conhecidos que valem a pena para as consultas certas.

Para começar, consulte a documentação do Amazon Bedrock Knowledge Bases e o código de exemplo disponível no repositório de amostras. Consulte também a seção Knowledge Bases da página de preços do Amazon Bedrock antes de colocar a solução em produção.

Fonte

Agentic retrieval with LangChain and Amazon Bedrock Knowledge Bases (https://aws.amazon.com/blogs/machine-learning/agentic-retrieval-with-langchain-and-amazon-bedrock-knowledge-bases/)

O que é o GLM 5.3 e por que ele importa

Tarefas de codificação e fluxos de trabalho agênticos estão exigindo cada vez mais dos modelos de IA: refatorar repositórios com centenas de arquivos, sustentar pipelines de execução autônoma por horas sem perder contexto e raciocinar sobre sistemas complexos com uso de ferramentas em cada etapa. Historicamente, atender a essas demandas com modelos de pesos abertos significava provisionar e operar a própria infraestrutura de inferência.

A AWS anunciou que o GLM 5.3 da Z.ai (Zhipu AI) está agora disponível no Amazon Bedrock. Publicado no Hugging Face Hub, o GLM 5.3 é um modelo de mistura de especialistas (MoE) com 753 bilhões de parâmetros, otimizado para codificação e tarefas agênticas de longa duração. A Z.ai também reportou capacidades notáveis em segurança cibernética. No Amazon Bedrock, o modelo é acessado via APIs totalmente gerenciadas, com inferência entre regiões, cache de prompt e camadas de serviço — sem necessidade de gerenciar infraestrutura. O acesso ao GLM 5.3 no Bedrock está disponível para clientes empresariais elegíveis.

O que mudou em relação ao GLM 5

O GLM 5 já estava disponível no Amazon Bedrock anteriormente. O GLM 5.3 evolui a mesma linhagem com melhorias relevantes em três frentes:

• Codificação mais forte: A Z.ai afirma desempenho competitivo em benchmarks como DeepSWE, Terminal Bench 3.0 e FrontierSWE, além de uma melhoria de 50% sobre o GLM 5.2 em seu benchmark interno de codificação. Comparações diretas com o GLM 5 não foram divulgadas porque a magnitude das melhorias levou à atualização dos próprios testes de benchmark desde o anúncio do GLM 5.1.
• Capacidades emergentes em segurança cibernética: O desempenho reportado em tarefas de segurança é um diferencial, tornando o modelo adequado para fluxos de segurança defensiva. Por exemplo, a Z.ai mediu uma pontuação de 84,5 no benchmark CyberGym no lançamento.
• Integração mais ampla com o Amazon Bedrock: Suporte a perfis de inferência entre regiões, cache de prompt implícito e explícito, e melhor paridade de recursos nas APIs compatíveis com OpenAI (Respostas e Completions de Chat), além das APIs Invoke e Converse nativas do Bedrock.

Principais capacidades

Codificação de fronteira e desempenho agêntico

O GLM 5.3 foi projetado para engenharia de sistemas complexos e tarefas agênticas de longa duração, incluindo raciocínio em múltiplas etapas, fluxos de trabalho com uso de ferramentas e manutenção de contexto em grandes bases de código.

Acesso flexível por API

O modelo pode ser invocado pelas APIs compatíveis com OpenAI (Responses e Chat Completions), ou pelas APIs nativas do Amazon Bedrock (Invoke e Converse).

Cache de prompt

O GLM 5.3 suporta cache de prompt implícito (automático) por padrão e controles de cache explícito nas APIs Responses e Chat Completions. Para fluxos agênticos que reenviam grandes prompts de sistema ou contexto de repositório a cada turno, o cache reduz tanto a latência quanto o custo de tokens de entrada.

Inferência entre regiões

O modelo está disponível por meio de perfis de inferência entre regiões dos EUA (us.zai.glm-5.3) e global (global.zai.glm-5.3). As requisições são enviadas para a região AWS de origem escolhida, e o Amazon Bedrock roteia cada chamada de forma segura. Consulte o Guia do Usuário do Amazon Bedrock para mais detalhes.

Camadas de serviço

É possível escolher entre três opções: Flex para otimizar custo em cargas menos sensíveis ao tempo, Priority para priorizar requisições com latência crítica (com preço mais alto) e Standard para o equilíbrio padrão entre preço e velocidade.

Como começar a usar

Pré-requisitos

Para os exemplos de uso a seguir, são necessários:

• Uma conta AWS com acesso ao Amazon Bedrock.
• Permissões de Gerenciamento de Identidade e Acesso (IAM) para chamar o modelo base e o perfil de inferência de destino: bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream e bedrock:CallWithBearerToken.
• Python 3.10 ou superior (para os exemplos baseados em código).
• Docker e Strix com o extra bedrock instalados (apenas para o demo opcional de testes de segurança).

Testando pelo console do Amazon Bedrock

É possível começar a enviar prompts ao GLM 5.3 diretamente pelo Console de Gerenciamento da AWS, sem precisar escrever código ou instalar ferramentas de desenvolvimento. Basta navegar até o Amazon Bedrock e escolher Test > Playground no menu lateral. A partir daí, selecione o GLM 5.3 na lista de modelos e envie os primeiros prompts pela interface de chat.

Primeiros passos com a API Responses

Via código, o modelo pode ser chamado pelo endpoint bedrock-runtime, que suporta as APIs compatíveis com OpenAI e as APIs nativas do Bedrock. Para novas aplicações, as APIs compatíveis com OpenAI são recomendadas por oferecerem um conjunto mais completo de funcionalidades.

O Amazon Bedrock suporta a geração de chaves de API para integrações que as exijam. No entanto, a recomendação é preferir credenciais de curta duração em vez de chaves de longa duração.

No exemplo abaixo, a API Responses é chamada a partir do Python usando o SDK do OpenAI e a biblioteca aws-bedrock-token-generator para gerar tokens de curta duração a partir das credenciais padrão da Interface de Linha de Comando da AWS (AWS CLI).

Instale os pacotes necessários:

pip install -U openai aws-bedrock-token-generator

Salve o código a seguir como bedrock-request.py:

from aws_bedrock_token_generator import provide_token
from openai import OpenAI

region = "us-west-2"  # Your source AWS Region

client = OpenAI(
    api_key=provide_token(region=region),
    base_url=f"https://bedrock-runtime.{region}.amazonaws.com/openai/v1",
)

resp = client.responses.create(
    input="Refactor this Python function to be iterative instead of recursive: ...",
    model="global.zai.glm-5.3",
)

print(resp.output_text)

Execute o script para ver a saída do modelo:

python bedrock-request.py

Otimizando a inferência com cache de prompt explícito

Fluxos de trabalho de codificação e conhecimento de longa duração frequentemente reenviam contexto estável a cada turno da conversa — como prompts de sistema, definições de ferramentas ou arquivos de repositório. O GLM 5.3 no Amazon Bedrock suporta cache de prompt implícito por padrão, reduzindo latência e custo de tokens de entrada para chamadas repetidas que compartilham o mesmo prefixo inicial de prompt.

Com o modo de cache de prompt explícito, é possível identificar especificamente os prefixos reutilizáveis, o que pode melhorar ainda mais a taxa de acerto do cache em relação ao modo implícito.

Para usar o cache explícito com o GLM 5.3:

• Selecione o modo de cache explícito via prompt_cache_options na requisição.
• Adicione um ou mais marcadores prompt_cache_breakpoint nos blocos de conteúdo de entrada para indicar o fim (inclusive) dos prefixos reutilizáveis. Cada ponto de quebra deve conter pelo menos 1.024 tokens para ser elegível ao cache.

resp = client.responses.create(
    model="global.zai.glm-5.3",
    # Enable explicit caching mode:
    extra_body={"prompt_cache_options": {"mode": "explicit"}},
    input=[
        {
            "type": "message",
            "role": "system",
            "content": [
                {
                    "type": "input_text",
                    "text": SYSTEM_PROMPT,
                    # A long, static system prompt is a great target for caching:
                    "prompt_cache_breakpoint": {"mode": "explicit"},
                },
            ]
        },
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": USER_INPUT,
                    # Multiple breakpoints can also be defined, for layered cache:
                    "prompt_cache_breakpoint": {"mode": "explicit"},
                },
            ],
        },
    ],
)

if resp.usage.input_tokens_details.cached_tokens:
    print("Hit cache!")

Para mais informações, consulte a seção de cache de prompt do Guia do Usuário do Amazon Bedrock.

Caso de uso agêntico: testes de segurança autorizados com o Strix

Um dos casos de uso que se beneficia diretamente dos pontos fortes do GLM 5.3 é a automação de testes de segurança em aplicações próprias. O Strix é um agente de teste de penetração de código aberto que executa código dinamicamente, encontra vulnerabilidades e as valida com testes de prova de conceito. No momento da publicação do post original, a documentação do Strix já usa o GLM 5.3 como modelo padrão.

É possível configurar o Strix para usar o GLM 5.3 no Amazon Bedrock em vez de um provedor de inferência terceiro, mantendo a inferência do modelo sob os controles da conta AWS.

Importante: teste apenas aplicações que você possui ou para as quais tem permissão escrita explícita. Testes de segurança não autorizados em sistemas de terceiros são ilegais na maioria das jurisdições e violam a Política de Uso Aceitável da AWS.

Nesse walkthrough, o alvo é o OWASP Juice Shop, uma aplicação de exemplo intencionalmente vulnerável rodando localmente na máquina.

Para quem busca testes de segurança contínuos e totalmente gerenciados além de rodar agentes de código aberto, o AWS Continuum oferece testes de penetração sob demanda e outras análises de segurança como serviço gerenciado. As duas abordagens são complementares: agentes de código aberto como o Strix oferecem testes orientados pelo desenvolvedor, com alto grau de customização contra builds locais, enquanto o AWS Continuum executa avaliações gerenciadas em escala.

Executando um teste de segurança autorizado

Inicie a aplicação Juice Shop localmente:

docker run --rm -p 3000:3000 bkimminich/juice-shop

Configure o Strix para usar o GLM 5.3 no Amazon Bedrock. O Strix utiliza o LiteLLM internamente, então as credenciais da AWS CLI são capturadas automaticamente (conforme descrito na documentação do Strix para Amazon Bedrock). Nenhuma chave de API é necessária, mas pode ser útil definir variáveis de ambiente como AWS_PROFILE e AWS_REGION.

No momento da publicação, o LiteLLM ainda não resolve bedrock/global.zai.glm-5.3. Até que isso seja corrigido, é possível especificar explicitamente a rota da API Converse e o ARN (Nome do Recurso Amazon) do perfil de inferência:

# Fill in the REGION and ACCOUNT_ID placeholders below before running!
export STRIX_LLM="bedrock/converse/arn:aws:bedrock:{AWS_REGION}:{AWS_ACCOUNT_ID}:inference-profile/global.zai.glm-5.3"

Execute o Strix contra o alvo local:

strix --target http://localhost:3000

Aguarde o agente raiz do Strix concluir e revise os resultados. O Strix cria uma equipe de sub-agentes para mapear a superfície de ameaças, explorar categorias de vulnerabilidades e tentar validar cada achado com uma prova de conceito funcional. Isso ajuda a minimizar o tempo gasto na triagem de falsos positivos. Uma execução bem-sucedida gera um relatório com severidade, evidências e orientações de remediação para cada achado.

Limpeza do ambiente

Encerre o container do Juice Shop com Ctrl+C no terminal onde ele está rodando, ou execute docker ps para encontrar o ID do container e encerrá-lo com docker stop <container-id>. A inferência no Amazon Bedrock é cobrada por token, sem recursos persistentes, portanto não há cobranças adicionais após a conclusão das requisições. Se uma chave de API do Amazon Bedrock foi gerada para este walkthrough e não é mais necessária, exclua-a pelo console.

Disponibilidade

O GLM 5.3 já pode ser testado no console do Amazon Bedrock, utilizado via assistentes de codificação como o OpenCode (conforme demonstrado no post recente com o Kimi K3), ou integrado a aplicações customizadas pelas APIs suportadas.

Fonte

Introducing GLM 5.3 on Amazon Bedrock (https://aws.amazon.com/blogs/machine-learning/introducing-glm-5-3-on-amazon-bedrock/)

O problema: modelos de IA têm data de corte de conhecimento

O Claude Desktop integrado ao Amazon Bedrock oferece uma experiência poderosa de assistência por IA — mas há uma limitação importante: sem acesso à web, o modelo só consegue responder com base no conhecimento que tinha até a data de corte do seu treinamento. Isso significa que perguntas sobre documentações recentes, preços atualizados ou informações em tempo real ficam sem resposta adequada.

Para resolver esse problema, a AWS disponibilizou uma integração entre o Claude Desktop e o recurso de busca web do Amazon Bedrock AgentCore — uma plataforma para construir, conectar e otimizar agentes de IA em escala, compatível com qualquer framework ou modelo.

O que é o AgentCore Gateway e o Web Search

O AgentCore Gateway é uma capacidade do Amazon Bedrock AgentCore que funciona como ponto de entrada para ferramentas externas. Por meio dele, é possível conectar o Claude Desktop ao recurso de Web Search — uma funcionalidade gerenciada, compatível com o Protocolo de Contexto de Modelo (MCP, do inglês Model Context Protocol), que usa um índice web da Amazon com dezenas de bilhões de documentos.

Um ponto importante para equipes de segurança: todo o tráfego de consultas permanece dentro da infraestrutura AWS. Não há chaves de API externas para gerenciar e nenhuma consulta sai do seu perímetro. Com o Claude Desktop, é possível usar servidores MCP gerenciados para se conectar ao AgentCore Gateway com o alvo de busca web habilitado.

Arquitetura de autenticação

A solução usa uma cadeia de autenticação totalmente dentro da AWS. O fluxo funciona assim:

• O AWS IAM Identity Center atua como fonte de autenticação, gerenciando o acesso via Logon Único (SSO, do inglês Single Sign-On).
• O Amazon Cognito funciona como camada de federação, usando o fluxo de concessão de código de autorização OAuth 2.0.
• O IAM Identity Center autentica o usuário via Linguagem de Marcação para Afirmações de Segurança (SAML).
• O Amazon Cognito emite Tokens Web JSON (JWT), que o AgentCore Gateway valida em cada requisição.

Essa abordagem se alinha à governança de identidade já existente nas organizações que usam AWS. Não são necessárias credenciais separadas nem provedores de identidade de terceiros.

Pré-requisitos

Para seguir o passo a passo descrito pela AWS, são necessários:

• Uma conta AWS com permissões para criar funções do Gerenciamento de Identidade e Acesso AWS (IAM) e recursos do Amazon Bedrock AgentCore.
• Acesso de administrador à conta de gerenciamento no AWS Organizations (para configuração do IAM Identity Center).
• AWS IAM Identity Center pré-configurado para acesso SSO às contas AWS.
• Claude Desktop configurado com o Amazon Bedrock como provedor de inferência.
• Interface de Linha de Comando AWS (AWS CLI) v2 instalada e configurada.
• Python 3.10 ou superior.
• SDK Boto3 atualizado para a versão mais recente.

O Web Search no Amazon Bedrock AgentCore está disponível atualmente nas regiões Leste dos EUA (Norte da Virgínia) — us-east-1, Europa (Irlanda) — eu-west-1, e Pacífico Asiático (Tóquio) — ap-northeast-1.

Configuração passo a passo

Passo 1: Criar um pool de usuários no Amazon Cognito

O primeiro passo é criar um pool de usuários no Amazon Cognito na conta AWS alvo. Ele funcionará como emissor de tokens OpenID Connect (OIDC) para o AgentCore Gateway.

export AWS_REGION=<your-region>

# Create User Pool
aws cognito-idp create-user-pool \
  --pool-name "agentcore-websearch-pool" \
  --region $AWS_REGION \
  --auto-verified-attributes email \
  --schema '[{"Name":"email","Required":true,"Mutable":true,"AttributeDataType":"String"}]' \
  --username-attributes email \
  --username-configuration "CaseSensitive=false" \
  --mfa-configuration "OFF"

# Note the Pool ID
export USER_POOL_ID=$(aws cognito-idp list-user-pools --max-results 10 \
  --region $AWS_REGION \
  --query "UserPools[?Name=='agentcore-websearch-pool'].Id" --output text)
echo "User Pool ID: $USER_POOL_ID"

# Create a domain (must be globally unique)
aws cognito-idp create-user-pool-domain \
  --domain "<your-unique-prefix>" \
  --user-pool-id $USER_POOL_ID \
  --region $AWS_REGION

Guarde os seguintes valores para os próximos passos:

• ID do Pool de Usuários: $USER_POOL_ID
• Domínio: <your-unique-prefix>.auth.<region>.amazoncognito.com
• Audience: urn:amazon:cognito:sp:<user-pool-id>
• URL ACS: https://<your-unique-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse

Passo 2: Configurar aplicação SAML no IAM Identity Center

Na conta de gerenciamento do AWS Organizations, crie uma aplicação SAML que federe com o Cognito. No console do IAM Identity Center, acesse Aplicações, escolha Adicionar aplicação, selecione SAML 2.0 e preencha os detalhes:

• Nome de exibição: AgentCore Web Search
• URL ACS: https://<your-unique-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
• Audience: urn:amazon:cognito:sp:<user-pool-id>

Faça o download do arquivo XML de metadados SAML. Após criar a aplicação, edite os mapeamentos de atributos inserindo os valores Subject (formato Persistente) e Email (formato Básico). Em seguida, atribua os usuários ou grupos que terão acesso ao Web Search.

Passo 3: Registrar o provedor de identidade SAML no Cognito

De volta à conta alvo, registre o IAM Identity Center como provedor de identidade SAML no pool de usuários do Cognito:

# Add IAM Identity Center as SAML IdP
METADATA=$(cat /path/to/downloaded-metadata.xml)
aws cognito-idp create-identity-provider \
  --user-pool-id $USER_POOL_ID \
  --provider-name "IAMIdentityCenterIdP" \
  --provider-type SAML \
  --provider-details "{\"MetadataFile\": $(echo "$METADATA" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')}" \
  --attribute-mapping '{"email": "email"}' \
  --region $AWS_REGION

Passo 4: Criar cliente de aplicação Cognito para o AgentCore

Crie um cliente de aplicação com segredo de cliente. O Claude Desktop usará esse cliente para iniciar o fluxo OAuth, autenticar o usuário via IAM Identity Center e obter um JWT para o AgentCore Gateway:

aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name "agentcore-websearch-client" \
  --generate-secret \
  --supported-identity-providers "IAMIdentityCenterIdP" \
  --callback-urls '["http://localhost:53280/callback"]' \
  --allowed-o-auth-flows code \
  --allowed-o-auth-scopes "openid" "email" "profile" \
  --allowed-o-auth-flows-user-pool-client \
  --region $AWS_REGION

Anote o Client ID e o Client Secret gerados na saída do comando.

Passo 5: Configurar o AgentCore Gateway com a ferramenta Web Search

Neste passo, cria-se um novo AgentCore Gateway com o Tipo de Autenticação de Entrada configurado como Token Web JSON (JWT), usando o ID do pool de usuários e o ID do cliente de aplicação do Cognito criados anteriormente. Execute o script Python abaixo, substituindo todos os valores de exemplo pelos dados reais do seu ambiente:

import boto3
import json
import time

session = boto3.Session(region_name="your-region")
iam_client = session.client("iam")
gateway_client = session.client("bedrock-agentcore-control")

ACCOUNT_ID = "your-target-aws-account-id"
ROLE_NAME = "websearch-gateway-role"
GATEWAY_NAME = "websearch-gateway"
COGNITO_DISCOVERY_URL = "https://cognito-idp.<your-region>.amazonaws.com/<user-pool-id>/.well-known/openid-configuration"
COGNITO_CLIENT_ID = "<cognito-application-client-id>"

# --- Step 1: Create IAM execution role ---
trust_policy = {
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
        "Action": "sts:AssumeRole",
        "Condition": {
            "StringEquals": {"aws:SourceAccount": ACCOUNT_ID}
        }
    }]
}

permissions_policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GetGateway",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetGateway",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:gateway/*"
        },
        {
            "Sid": "GetConfigBundle",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:GetConfigurationBundleVersion",
            "Resource": f"arn:aws:bedrock-agentcore:us-east-1:{ACCOUNT_ID}:configuration-bundle/*"
        },
        {
            "Sid": "InvokeWebSearch",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:InvokeWebSearch",
            "Resource": "arn:aws:bedrock-agentcore:us-east-1:aws:tool/web-search.v1"
        }
    ]
}

try:
    iam_client.create_role(
        RoleName=ROLE_NAME,
        AssumeRolePolicyDocument=json.dumps(trust_policy),
        Description="Execution role for web search AgentCore gateway",
    )
    print(f"✓ Role '{ROLE_NAME}' created.")
except iam_client.exceptions.EntityAlreadyExistsException:
    print(f"✓ Role '{ROLE_NAME}' already exists, reusing.")

iam_client.put_role_policy(
    RoleName=ROLE_NAME,
    PolicyName="websearch-gateway-policy",
    PolicyDocument=json.dumps(permissions_policy),
)
print(f"✓ Inline policy attached to '{ROLE_NAME}'.")

# --- Step 2: Create the gateway ---
response = gateway_client.create_gateway(
    name=GATEWAY_NAME,
    description="AgentCore gateway with managed Web Search connector",
    roleArn=f"arn:aws:iam::{ACCOUNT_ID}:role/{ROLE_NAME}",
    protocolType="MCP",
    protocolConfiguration={
        "mcp": {
            "supportedVersions": ["2025-03-26"],
        }
    },
    authorizerType="CUSTOM_JWT",
    authorizerConfiguration={
        "customJWTAuthorizer": {
            "discoveryUrl": COGNITO_DISCOVERY_URL,
            "allowedClients": [COGNITO_CLIENT_ID],
        }
    },
)

gateway_id = response["gatewayId"]
gateway_url = response.get("gatewayUrl")
print(f"✓ Gateway created: {gateway_id}")
print(f"  URL: {gateway_url}")

# --- Step 3: Wait for gateway to become READY ---
print(" Waiting for gateway to reach READY status...", end="", flush=True)
for i in range(40):  # up to ~10 minutes
    resp = gateway_client.get_gateway(gatewayIdentifier=gateway_id)
    status = resp.get("status")
    if status == "READY":
        print(f" READY (after {(i+1)*15}s)")
        break
    elif status == "FAILED":
        print(f"\n✗ Gateway entered FAILED status.")
        reasons = resp.get("statusReasons", [])
        for r in reasons:
            print(f"  Reason: {r}")
        exit(1)
    print(".", end="", flush=True)
    time.sleep(15)
else:
    print(f"\n✗ Gateway did not reach READY within 10 minutes (last status: {status})")
    exit(1)

# --- Step 4: Attach the managed Web Search connector target ---
gateway_client.create_gateway_target(
    gatewayIdentifier=gateway_id,
    name="web-search-tool",
    description="Managed Web Search connector",
    targetConfiguration={
        "mcp": {
            "connector": {
                "source": {"connectorId": "web-search"},
                "configurations": [{"name": "WebSearch", "parameterValues": {}}],
            }
        }
    },
    credentialProviderConfigurations=[
        {"credentialProviderType": "GATEWAY_IAM_ROLE"}
    ],
)
print("✓ Web search target attached.")

print()
print("=" * 60)
print(f"  Gateway ID:  {gateway_id}")
print(f"  Gateway URL: {gateway_url}")
print(f"  Auth:        CUSTOM_JWT (Cognito)")
print(f"  Target:      web-search (managed connector)")
print("=" * 60)

Ao final, o AgentCore Gateway estará criado com a ferramenta Web Search e autorização de entrada baseada em JWT.

Passo 6: Configurar o Claude Desktop

Com o gateway pronto, o próximo passo é conectar o Claude Desktop a ele. Acesse a janela de configuração do Claude Desktop com Amazon Bedrock, vá até Conectores e Extensões, escolha Adicionar servidor e selecione Em branco. Preencha os seguintes campos:

• Nome: websearchtool
• Transporte: Streamable HTTP
• URL: URL do recurso do AgentCore Gateway criado no Passo 5
• OAuth: Traga seu próprio cliente
• Client ID: ID do cliente de aplicação criado no Passo 4
• Client Secret: Segredo do cliente criado no Passo 4
• Servidor de Autorização: ["https://<your-unique-prefix>.auth.<region>.amazoncognito.com/oauth2/authorize"]
• Scope: openid
• Callback host: localhost
• Callback port: 53280

Ao finalizar e clicar em Entrar e testar, um navegador será aberto redirecionando para a tela de login do AWS IAM Identity Center SSO. Após autenticação bem-sucedida, uma mensagem confirmará que a autorização foi concluída. De volta ao Claude Desktop, uma mensagem de registro MCP bem-sucedido será exibida.

A partir desse ponto, o Claude Desktop descobrirá a ferramenta WebSearchTool por meio da chamada tools/list do MCP e a invocará automaticamente sempre que precisar de informações atuais da web.

Teste e validação

Para validar a integração, basta enviar uma consulta que exija informações recentes. O Claude Desktop apresentará uma caixa de aprovação de execução da ferramenta, indicando que a ferramenta Web Search foi descoberta com sucesso. O diálogo mostra a consulta que o Claude pretende executar e oferece três opções: Negar, Permitir para esta tarefa ou Permitir uma vez. Após aprovação, os resultados da busca web são incluídos na resposta.

Limpeza dos recursos

Caso tenha seguido o passo a passo apenas para testes, a AWS recomenda excluir os recursos criados para evitar cobranças desnecessárias:

# Delete the gateway target
aws bedrock-agentcore-control delete-gateway-target --gateway-identifier <gateway-id> --target-id <target-id> --region $AWS_REGION

# Delete the gateway (only if it was created for this walkthrough)
aws bedrock-agentcore-control delete-gateway --gateway-identifier <gateway-id> --region $AWS_REGION

# Delete the IAM policy (only if it was created for this walkthrough)
aws iam delete-role-policy --role-name websearch-gateway-role --policy-name websearch-gateway-policy

# Delete the IAM role (only if it was created for this walkthrough)
aws iam delete-role --role-name websearch-gateway-role

# Delete the Cognito application client
aws cognito-idp delete-user-pool-client --user-pool-id $USER_POOL_ID --client-id <client-id> --region $AWS_REGION

# Delete the Cognito identity provider
aws cognito-idp delete-identity-provider --user-pool-id $USER_POOL_ID --provider-name IAMIdentityCenterIdP --region $AWS_REGION

# Delete the Cognito pool domain
aws cognito-idp delete-user-pool-domain --user-pool-id $USER_POOL_ID --domain <your-unique-prefix> --region $AWS_REGION

# Delete the cognito pool
aws cognito-idp delete-user-pool --user-pool-id $USER_POOL_ID --region $AWS_REGION

Por fim, no console do IAM Identity Center na conta de gerenciamento, exclua a aplicação SAML criada no Passo 2.

Conclusão

A integração entre o Web Search do AgentCore e o Claude Desktop resolve de forma elegante o problema da data de corte de conhecimento dos modelos de linguagem, sem introduzir dependências externas. Todo o fluxo de autenticação — do IAM Identity Center ao Cognito, até o JWT validado pelo gateway — permanece dentro da AWS.

Vale destacar que o padrão descrito não está limitado ao IAM Identity Center: qualquer provedor de identidade compatível com SAML ou OIDC pode ser configurado como fonte de federação no Amazon Cognito, tornando a solução adaptável a diferentes contextos corporativos.

Para configurações avançadas de gateway, consulte o Guia do Desenvolvedor do AgentCore Gateway. Para saber mais sobre o Web Search, acesse a documentação do Web Search.

Fonte

Add secure Web Search to Claude Desktop with Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/add-secure-web-search-to-claude-desktop-with-amazon-bedrock-agentcore/)

O problema com agentes de busca baseados em LLMs

Agentes de busca alimentados por grandes modelos de linguagem (LLMs) estão mudando a forma como empresas recuperam informações. Em vez de exigir que o usuário formule a consulta perfeita, esses agentes decidem autonomamente o que buscar, qual estratégia de recuperação usar e quando parar — tudo isso ao longo de múltiplas rodadas de interação, refinando a abordagem com base no que já foi recuperado.

O problema é que fazer esse comportamento multi-etapas funcionar de forma confiável não é trivial. Nenhum modelo base chega pronto conhecendo as suas ferramentas ou o seu ambiente. Modelos menores raramente entregam comportamento multi-turn consistente. Modelos de fronteira funcionam, mas cobram caro em latência e custo.

O fine-tuning surge como um terceiro caminho: você ensina diretamente a um modelo menor as ferramentas e o ambiente específicos do seu caso de uso. O resultado é a velocidade e o custo de um modelo menor com a confiabilidade que, de outra forma, só um modelo de fronteira entregaria.

As abordagens tradicionais de fine-tuning, porém, têm limitações claras. O Ajuste Fino Supervisionado (SFT) depende de demonstrações de especialistas com trajetórias multi-turn ideais — caras de coletar e raramente disponíveis. O Aprendizado por Reforço (RL) de turno único, como o RL com recompensas verificáveis (RLVR), avalia uma resposta de cada vez. Mas um agente de busca toma decisões interdependentes ao longo de vários turnos, e otimizar um único passo de forma isolada ignora completamente essas dependências.

O que se precisa é de uma abordagem que otimize o agente ao longo de toda a trajetória multi-turn. O sinal de recompensa só precisa refletir se o resultado final foi bom. É exatamente isso que o Aprendizado por Reforço Multi-turn (MTRL) oferece.

O que é o Amazon SageMaker AI MTRL

O Amazon SageMaker AI MTRL permite fazer fine-tuning de LLMs usando aprendizado por reforço em cenários de interação multi-turn. Ele enquadra uma tarefa agêntica como uma sequência de decisões, usa rollouts multi-turn para gerar dados de treinamento e otimiza o modelo com algoritmos de gradiente de política.

Entre os principais recursos que a AWS destaca para o serviço:

• Interface modular agente-ambiente: você define recompensas personalizadas, loops de ferramentas e formatos de conversa multi-turn com pouco código.
• Execução serverless: RL agêntico em escala de produção com precificação por token, sem necessidade de provisionar ou gerenciar clusters de GPU.
• Rollout assíncrono e coleta de trajetórias: geração e atualizações de gradiente rodam em paralelo com controle de desatualização off-policy, mantendo o treinamento rápido sem se afastar demais da política atual.
• Biblioteca nativa de algoritmos: suporte a Otimização de Política Proximal (PPO), Otimização de Política por Amostragem de Importância Recortada (CISPO) e perdas de amostragem de importância (IS), combinadas com estimadores de vantagem baseados em grupos (GRPO, GRPO pass@k, RLOO e outros).
• Treinamento retomável: execuções longas podem ser divididas em múltiplos jobs, superando o limite de tempo de um único job.
• Observabilidade de trajetórias e recompensas: é possível inspecionar o que o agente fez turno a turno e ao longo dos passos de treinamento no MLflow gerenciado pelo Amazon SageMaker AI.
• Jobs de avaliação: métricas de recompensa, pass@k e trajetórias podem ser verificadas antes do deploy em um endpoint do Amazon SageMaker AI ou no Amazon Bedrock.

Ambiente e configuração do experimento

O experimento descrito pela AWS utilizou os seguintes componentes:

• Uma conta AWS com acesso ao Amazon SageMaker AI na região US West (Oregon) — us-west-2.
• Datasets de treinamento e validação enviados ao Amazon Simple Storage Service (Amazon S3) no formato exigido pelo serviço.
• Um endpoint de agente implantado que expõe ferramentas de busca BM25 e vetorial para o ambiente MTRL chamar durante os rollouts.

O modelo escolhido para o fine-tuning foi o Qwen3.6-27B, suportado na região us-west-2. O agente de busca foi configurado com duas ferramentas disponíveis:

• Busca lexical (BM25): encontra correspondências exatas de palavras-chave contando frequências de termos. Ideal para consultas com termos específicos ou identificadores.
• Busca vetorial: converte consultas e documentos em vetores de embedding e calcula similaridades. Recomendada para consultas semânticas ou conceituais.

O número de turnos por interação também foi limitado, evitando respostas excessivamente longas e incentivando um comportamento de busca mais eficiente.

Datasets utilizados

Para treinamento e teste, foram utilizados os seguintes conjuntos de dados públicos:

• FRAMES (treino — HuggingFace): perguntas factuais multi-hop que exigem síntese de múltiplos artigos da Wikipedia.
• BRIGHT (treino — HuggingFace): recuperação intensiva em raciocínio em 12 domínios, onde a relevância exige raciocínio e não apenas sobreposição de palavras-chave.
• Enterprise RAG (treino — GitHub): benchmark com mais de 500.000 documentos corporativos sintéticos e 500 perguntas para treinar e avaliar sistemas de Geração Aumentada por Recuperação (RAG) em conhecimento interno de empresas.
• ESCI (treino — GitHub): dataset multilíngue de busca de produtos que rotula pares consulta–produto como Exato, Substituto, Complementar ou Irrelevante.
• Musique (treino — GitHub): dataset de perguntas e respostas construído compondo questões de um único salto em problemas desafiadores de raciocínio multi-hop.
• MLQA (treino — HuggingFace): benchmark de perguntas e respostas extrativas paralelo em sete idiomas para avaliar compreensão entre línguas.
• FreshStack (teste — HuggingFace): perguntas e respostas recentes de desenvolvedores sobre Stack Overflow e documentações em cinco tópicos.
• WixQA (teste — HuggingFace): perguntas e respostas de suporte sobre a base de conhecimento da Wix.
• BrowseComp-Plus (teste — GitHub): consultas de pesquisa profunda sobre aproximadamente 100.000 documentos da web verificados por humanos.
• Wands (teste — HuggingFace): dataset de busca de produtos da Wayfair com mais de 42.000 julgamentos de relevância rotulados como Exato, Parcial ou Irrelevante.

Os datasets foram pré-processados no formato reconhecido pelo serviço MTRL conforme a documentação oficial. Além disso, 5% das instâncias de treinamento de cada dataset foram reservadas para validação.

Função de recompensa

A métrica principal utilizada foi o nDCG@10 (Ganho Cumulativo Descontado Normalizado no rank 10). Trata-se de uma métrica padrão de recuperação de informações que mede o quão bem os 10 documentos recuperados correspondem ao ranking ideal. Ela recompensa sistemas que colocam documentos altamente relevantes no topo da lista — pontuação 1.0 significa ranking perfeito, 0.0 significa nenhum documento relevante recuperado.

O nDCG@10 foi usado diretamente como função de recompensa no MTRL. É uma recompensa no nível da trajetória: o agente conclui toda a sua busca multi-turn e a recompensa reflete o quão bem os documentos finais recuperados correspondem ao gabarito.

Quando o agente atinge o número máximo de turnos ou o limite de tokens de amostragem em um único turno, é atribuída uma recompensa de -1 para ensinar explicitamente o modelo a evitar esses modos de falha. Esse tipo de design de recompensa baseado em penalidade é eficaz para afastar o modelo de comportamentos indesejados sem precisar criar recompensas intermediárias complexas.

Configuração do job de treinamento

Um dos pontos destacados pela AWS é o baixo esforço de configuração necessário para começar. No experimento, apenas três hiperparâmetros foram alterados — todo o restante ficou nos valores padrão. O trecho de código abaixo mostra como configurar e iniciar o job de treinamento usando o SDK MultiTurnRLTrainer:

from sagemaker.modules.train import MultiTurnRLTrainer

trainer = MultiTurnRLTrainer(
    model_id="qwen3.6-27b",
    agent_endpoint="<your-agent-endpoint>",
    training_dataset_s3_uri="s3://amzn-s3-demo-bucket/datasets/train/",
    validation_dataset_s3_uri="s3://amzn-s3-demo-bucket/datasets/validation/",
    hyperparameters={
        "max_epochs": 1,
        "global_batch_size": 128,
        "rollout_max_concurrency": 32,
    },
    output_s3_uri="s3://amzn-s3-demo-bucket/output/",
)

trainer.train()

Os três hiperparâmetros modificados foram:

• max_epochs: 1 — controla quantas passagens completas sobre os dados de treinamento são realizadas.
• global_batch_size: 128 — define o número de prompts por passo de treinamento.
• rollout_max_concurrency: 32 — controla quantos rollouts rodam em paralelo durante a coleta de trajetórias.

Decisões que normalmente exigem expertise em RL — como o algoritmo, o estimador de vantagem e os limites de desatualização off-policy — rodam com os valores padrão. Toda a jornada do modelo base até os resultados descritos a seguir exigiu apenas essa configuração.

Vale mencionar que o treinamento MTRL pode durar vários dias e o serviço tem um limite de tempo padrão de 24 horas, ajustável pelo esquema JSON do CreateJob. Caso um job seja interrompido ou falhe por timeout ou erro de infraestrutura, é possível retomar o treinamento a partir de um checkpoint anterior com o suporte a retomada.

Resultados obtidos

O fine-tuning com MTRL melhorou o agente de busca em três dos quatro benchmarks de teste e o tornou substancialmente mais confiável em todos eles. Os maiores ganhos vieram no BrowseComp-Plus (+23,7% de nDCG@10) e no WixQA (+18,4%), com ganho menor no Wands e uma leve regressão no FreshStack.

A melhoria na confiabilidade foi o resultado mais expressivo. No BrowseComp-Plus, a taxa de falhas caiu de 22,89% para 0,68%. Isso significa que o agente aprendeu não apenas a buscar melhor, mas também a concluir a tarefa dentro do orçamento de turnos e tokens.

A tabela abaixo compara o modelo fine-tuned com o Qwen3.6-27B original nos quatro datasets de teste. As colunas são: tamanho do dataset (número de perguntas), nDCG@10 (o Ganho Cumulativo Descontado Normalizado — tarefas com falha recebem nDCG@10 igual a 0), taxa de falhas (percentual de perguntas onde o agente excede o limite de turnos ou tokens) e média de turnos por pergunta.

• WixQA (400 perguntas): Qwen3.6-27B → 0,5725 | Qwen3.6-27B-finetune → 0,6781 (+18,4%) | Falhas: 0,67% → 0,17% | Turnos médios: 4,3 → 4,5
• Wands (147 perguntas): Qwen3.6-27B → 0,5762 | Qwen3.6-27B-finetune → 0,6112 (+6%) | Falhas: 0,00% → 0,00% | Turnos médios: 2,2 → 2,9
• FreshStack (672 perguntas): Qwen3.6-27B → 0,4112 | Qwen3.6-27B-finetune → 0,4089 (-0,6%) | Falhas: 0,20% → 0,05% | Turnos médios: 3,1 → 2,8
• BrowseComp-Plus (830 perguntas): Qwen3.6-27B → 0,5136 | Qwen3.6-27B-finetune → 0,6354 (+23,7%) | Falhas: 22,89% → 0,68% | Turnos médios: 7,0 → 6,3

Dois padrões se destacam nos dados: a melhora na qualidade de busca foi consistente na maioria dos benchmarks, e a redução de falhas foi dramática — especialmente no BrowseComp-Plus, que é o benchmark mais desafiador do conjunto.

Principais aprendizados

Com base nos resultados apresentados, a AWS destaca os seguintes pontos sobre o Amazon SageMaker AI MTRL:

• Baixa barreira de entrada: as configurações padrão funcionam bem e não é necessária expertise profunda em RL para começar.
• Infraestrutura serverless: sem necessidade de provisionar GPUs ou gerenciar clusters de treinamento distribuído — o modelo de cobrança é por token.
• Treinamento retomável: execuções longas podem ser divididas em múltiplos jobs.
• Otimização direta: o treinamento ocorre contra a métrica real da tarefa, não contra perdas proxy.
• Observabilidade completa: é possível inspecionar trajetórias turno a turno no MLflow gerenciado pelo Amazon SageMaker AI para entender o que o agente aprendeu.

Próximos passos

Para quem quiser explorar essa abordagem, a AWS indica os seguintes pontos de partida:

• Consultar a documentação do Amazon SageMaker AI MTRL.
• Preparar o dataset no formato exigido pelo serviço.
• Definir o agente e a função de recompensa com base na métrica específica da sua tarefa.
• Começar com as configurações padrão, que funcionaram bem no experimento descrito.
• Avaliar e iterar.

Após explorar a abordagem, lembre-se de limpar os recursos para evitar cobranças contínuas: interromper ou excluir o job de treinamento MTRL no console do Amazon SageMaker AI, remover os artefatos do modelo no Amazon S3 se não forem mais necessários e excluir os endpoints implantados para avaliação.

Fonte

Fine-tune a search agent with multi-turn RL on Amazon SageMaker AI (https://aws.amazon.com/blogs/machine-learning/fine-tune-a-search-agent-with-multi-turn-rl-on-amazon-sagemaker-ai/)