Blog

O problema que o HyperPod InstantStart resolve

Quem trabalha com cargas de trabalho de modelos de fundação (FM — Foundation Models) no Amazon SageMaker HyperPod sabe que a operação raramente é uma tarefa única. É uma cadeia de etapas dependentes: criar a rede e o plano de controle, anexar capacidade de aceleradores, instalar dependências do cluster na ordem correta, preparar armazenamento e identidade, manter jobs distribuídos vivos durante falhas de hardware, implantar servidores de modelos e monitorar tudo isso. Cada etapa tem sua própria API, seus próprios modos de falha e seu próprio tempo de espera. A maior parte da dor operacional vive justamente nas transições entre essas etapas.

O Amazon SageMaker HyperPod já elimina uma parte significativa dessa carga, oferecendo computação gerenciada e resiliente com monitoramento de saúde, autoscaling de nós, recuperação de treinamento e inferência integrados ao Amazon Elastic Kubernetes Service (Amazon EKS). O EKS permanece como superfície de orquestração gerenciada pelo usuário, o que dá acesso direto ao Kubernetes — mas também torna a equipe responsável por compor recursos AWS, add-ons, cargas de trabalho e operações de dia dois em um todo coerente.

É exatamente esse problema de composição que o HyperPod InstantStart foi projetado para resolver. Trata-se de um plano de controle open source que oferece duas formas de operar a mesma infraestrutura: uma interface web e uma interface de agente de IA. Ambas chamam os mesmos backends, passam pelas mesmas validações e leem o mesmo estado persistido — nenhuma tem lógica privada que a outra não tenha.

Arquitetura da solução

O HyperPod InstantStart roda como um único contêiner de gerenciamento fora de banda na conta AWS do usuário. Ele chama APIs de serviços AWS e a API do Kubernetes, mas não fica no caminho de dados de um job de treinamento ou de uma requisição de inferência. Tudo que ele cria é um recurso padrão AWS ou Kubernetes, inspecionável via AWS CLI e kubectl.

A arquitetura tem um único ponto de entrada para a equipe de infraestrutura. A interface web, a API REST e as ferramentas do Protocolo de Contexto de Modelo (MCP — Model Context Protocol) usadas pelo agente de IA são três faces do mesmo contêiner. Por trás delas, fica a lógica de provisionamento em estágios e reconciliação idempotente.

O plano de controle chama duas superfícies de API. Do lado Kubernetes, está o Amazon EKS — gerenciado pelo usuário — com os operadores de treinamento e inferência do HyperPod instalados como add-ons EKS. Do lado AWS, está o Amazon SageMaker HyperPod — gerenciado pela AWS — com capacidades divididas em quatro grupos: infraestrutura (monitoramento de saúde, verificações profundas de saúde e recuperação automática de nós), capacidade (provisionamento contínuo e autoscaling gerenciado via Karpenter), treinamento (recuperação em nível de processo e checkpointing em camadas gerenciado) e inferência (roteamento inteligente e cache KV em camadas).

As integrações AWS ao redor desse caminho incluem o Amazon Simple Storage Service (Amazon S3), Amazon FSx for Lustre e Amazon Elastic Container Registry (Amazon ECR) para imagens, dados e checkpoints, além do Amazon Managed Service for Prometheus e Amazon Managed Grafana para saúde e utilização.

Criando um cluster: conversa e console

Partir de uma conta vazia até ter capacidade HyperPod utilizável envolve vários estágios longos e dependentes entre si: criação do plano de controle EKS, seleção do cluster ativo, reconciliação de dependências, criação do cluster HyperPod e configuração de armazenamento. O InstantStart separa deliberadamente esses estágios — uma falha em um estágio posterior não desfaz um estágio anterior que já foi concluído com sucesso.

Pela interface web, isso é gerenciado na página de Cluster Management. Pelo agente, todo o pipeline é uma conversa. A seguir, um trecho condensado de uma sessão real com o hypd-inst-agent, uma configuração de agente para o Kiro CLI que carrega o servidor MCP e as skills do projeto:

[hypd-inst-agent] > Help me create a new HyperPod cluster
> Creating a HyperPod cluster is a multi-step process:
1. Create EKS cluster (approximately 8-12 minutes)
2. Switch to the new cluster and verify
3. Install dependencies
4. Create HyperPod cluster
5. Configure S3 storage
6. Final verification
Let me first check the existing cluster situation:
Running tool cluster_list_all (from mcp server: hypd-inst)
> There are currently 2 existing clusters. Would you like to give the new cluster a tag name, or should I auto-generate one?

[hypd-inst-agent] > Go ahead
Running tool cluster_create_eks {"clusterTag": "hypd-0304b"}
...
> Step 1 complete! EKS cluster hypd-0304b created successfully.
...
> Step 3 complete! All dependencies installed successfully.
Now I need the following information from you to create HyperPod:
Availability Zone, GPU instance type, instance count, and capacity type (On-Demand or Training Plan)?

[hypd-inst-agent] > us-west-2c, one g6.4xl
Running tool hyperpod_create {"AcceleratedInstanceType": "ml.g6.4xlarge", "AcceleratedInstanceCount": 1, "availabilityZone": "us-west-2c", ...}
...
> HyperPod cluster creation fully complete! Summary:
| EKS Cluster    | eks-cluster-hypd-0304b |
| HyperPod Cluster | hp-cluster-hypd-0304b |
| Node           | 1x ml.g6.4xlarge (On-Demand) |
| Node Status    | Ready / Schedulable |
| S3 Storage     | s3-claim mounted |

Três comportamentos nessa conversa vêm de regras de workflow codificadas na skill do agente, não de improviso: o agente faz polling até a conclusão (nunca para no meio e pede para o usuário verificar depois); o agente faz apenas perguntas de nível de decisão (Zona de Disponibilidade, tipo de instância, tipo de capacidade são decisões do usuário — CIDRs de sub-rede, tabelas de rota e ordem de instalação não são); e o agente inspeciona antes de criar, listando clusters existentes e consultando Zonas de Disponibilidade e tipos de instância válidos antes de oferecer opções.

Gerenciamento de capacidade e resiliência

O InstantStart cria clusters HyperPod com recuperação automática de nós habilitada por padrão. O HyperPod pode reinicializar ou substituir nós com falha com base em descobertas do agente de monitoramento de saúde, verificações básicas de saúde e, quando configurado, verificações profundas de saúde que testam GPUs e conectividade EFA (Elastic Fabric Adapter) antes que os nós aceitem trabalho.

Ao adicionar um grupo de instâncias, o sistema trata toda a decisão de capacidade como uma única operação no momento da criação. As escolhas incluem:

• Tipo de capacidade: On-Demand, Instâncias Spot do Amazon EC2 para cargas tolerantes a falhas, ou capacidade reservada via plano de treinamento do SageMaker.
• Modo de interface de rede: tipos de instância com múltiplas placas de rede podem solicitar interfaces exclusivamente EFA, conservando endereços IP da VPC. Essa configuração é imutável após a criação do grupo.
• Posicionamento de sub-rede: por padrão, grupos compartilham a sub-rede de computação por Zona de Disponibilidade. Um grupo grande pode solicitar uma sub-rede dedicada para evitar esgotamento de IPs.

Autoscaling gerenciado com Karpenter

Um grupo de instâncias estático define quanta capacidade o usuário possui. O autoscaling de nós gerenciado pelo HyperPod baseado em Karpenter decide quanto disso está em execução em cada momento. A AWS opera o próprio controlador Karpenter, e os nós são lançados a partir de grupos de instâncias HyperPod escalados a partir de zero — não de instâncias EC2 brutas. A capacidade autoscalada herda, portanto, o monitoramento de saúde e a recuperação automática de nós já mencionados.

Capacidades gerenciadas como estado reconciliado

O HyperPod inclui diversas capacidades gerenciadas — operador de treinamento, operador de inferência, checkpointing em camadas gerenciado e autoscaling gerenciado. O InstantStart expõe todas elas em um painel de Recursos Avançados, onde cada toggle mapeia para uma operação de backend consciente de dependências.

Habilitar o checkpointing em camadas gerenciado, por exemplo, faz mais do que alterar uma configuração do cluster. Ele provisiona uma cadeia de identidade completa: uma service account do Kubernetes, uma role e policy IAM, um relacionamento de confiança OpenID Connect (OIDC) e a anotação que os vincula. Desabilitar remove a mesma cadeia. A operação é fechada em ambas as direções — IRSA (Funções IAM para Contas de Serviço) parcialmente provisionado é um dos problemas mais difíceis de depurar no EKS.

O painel também implementa um contrato de diff explícito: a interface envia apenas os campos que o usuário efetivamente tocou. O backend verifica a presença dos campos, lê o estado real do cluster e não faz nada quando o estado real e o solicitado já coincidem. Esse contrato se aplica igualmente a requisições da interface web e a chamadas de ferramentas MCP.

Pelo agente, o painel inteiro é uma única troca:

[hypd-inst-agent] > Help me install tiered storage and training operator
Running tool hyperpod_get_advanced_features
> Currently both are not enabled. I'll enable them together.
Running tool hyperpod_update_advanced_features {"tieredStorage": {"enabled": true, "configMode": "default"}, "trainingOperator": {"enabled": true}}
> Both features have been successfully enabled.

Treinamento: dois caminhos de submissão e uma camada de receitas

A superfície de treinamento separa duas decisões: como um job é submetido e mantido vivo é uma delas; qual framework o job executa é outra.

Operador de treinamento HyperPod

O primeiro caminho é o operador de treinamento do Amazon SageMaker HyperPod. Ele adiciona recuperação de falhas em nível de processo, detecção de jobs travados via monitoramento de padrões de log e detecção de outliers para treinamento distribuído. Um único processo com falha não custa mais o reinício completo de um job multi-nó. O InstantStart o instala como add-on EKS e submete trabalho como recursos HyperPodPyTorchJob, com a política de recuperação visível na especificação da carga de trabalho:

runPolicy:
  jobMaxRetryCount: 5
  restartPolicy:
    numRestartBeforeFullJobRestart: 3
    evalPeriodSeconds: 21600
    maxFullJobRestarts: 1
    cleanPodPolicy: All

Isso define um orçamento de recuperação: até três reinicializações de processo in-place dentro de uma janela de avaliação de seis horas; depois, o operador escala para um único reinício completo do job.

KubeRay para cargas nativas do Ray

O segundo caminho é o KubeRay padrão, instalado sob demanda pelo painel de Recursos Avançados. Algumas cargas de trabalho são nativas do Ray por design — notavelmente o aprendizado por reforço, onde um nó head coordena trabalhadores de rollout e treinamento. Clusters e jobs Ray são submetidos como cargas de trabalho de primeira classe nos mesmos nós HyperPod, com os mesmos mounts de armazenamento e as mesmas visualizações de monitoramento.

Camada de receitas

Sobre a camada de tarefas, o projeto fornece receitas que integram frameworks de treinamento amplamente usados: scripts PyTorch simples, LLaMA-Factory, MS-Swift e VERL para aprendizado por reforço (esse último no caminho KubeRay). Mudar de framework muda um formulário, não o modelo operacional. As receitas compartilham um contrato de dados: o mesmo bucket S3 é montado em ~/workspace/s3 no ambiente de desenvolvimento e em /s3 dentro dos pods. Logs de jobs fazem streaming para o browser via WebSocket, e cada receita pode reportar métricas ao MLflow gerenciado no Amazon SageMaker AI.

Inferência: dois modelos de propriedade

Para inferência, o plano de controle oferece dois caminhos com modelos de propriedade genuinamente diferentes.

O caminho gerenciado delega o ciclo de vida ao operador de inferência do HyperPod. O usuário descreve o endpoint de forma declarativa — localização do modelo no S3, imagem do worker, porta de invocação, recursos de GPU e réplicas. O operador reconcilia isso em workers de modelo, balanceamento de carga e TLS. Duas capacidades gerenciadas são o principal motivo para escolher esse caminho:

kvCacheSpec:
  enableL1Cache: true
  enableL2Cache: true
  l2CacheSpec:
    l2CacheBackend: tieredstorage
intelligentRoutingSpec:
  enabled: true
  routingStrategy: prefixaware

O cache KV em camadas gerenciado mantém um cache L1 na memória CPU com uma camada L2 suportada por Redis ou armazenamento em camadas gerenciado do SageMaker. O roteamento inteligente oferece estratégias prefix-aware, KV-aware, por sessão e round-robin.

O caminho autogerenciado implanta um contêiner de serving de escolha do usuário — vLLM, SGLang ou próprio — como um deployment Kubernetes padrão. Oferece três formatos de serviço: load balancer externo, serviço interno ao cluster ou um pool de modelos. O pool mantém workers GPU aquecidos rotulados como business=unassigned; reatribuir um worker a um serviço muda um label em vez de recriar um pod e recarregar pesos.

A implantação via agente mostra as proteções no contrato da ferramenta — a skill de implantação proíbe inferir a contagem de GPUs a partir de um flag de paralelismo tensorial:

[hypd-inst-agent] > Help me deploy: vllm serve Qwen/Qwen3-0.6B --max-model-len 1280 --tensor-parallel-size 1
> Before deploying I need to confirm: how many GPUs should this deployment request?
(--tensor-parallel-size is a model-parallelism parameter; I need you to confirm the actual GPU allocation.)
Running tool cluster_get_status
> The cluster currently has 1 ml.g6.4xlarge node with 1 GPU available.

[hypd-inst-agent] > 1
Running tool inference_deploy_container {"deploymentCommand": "vllm serve Qwen/Qwen3-0.6B --max-model-len 1280 --tensor-parallel-size 1", "gpuCount": 1, "serviceType": "clusterip", ...}
> Deployment created. Let me test it:
Running tool inference_call_model {"service_name": "vllm-model-260304-100458-service", "prompt": "Hello! Can you briefly introduce yourself?"}
> Model test successful. Response: "Hello! I'm a language model designed to assist with tasks like answering questions..."

O que torna um plano de controle pronto para agentes

A interface de agente — que o projeto chama de infraestrutura de IA conduzida por agente — é onde as escolhas de design pagam dividendos novamente. A implementação tem três camadas:

• Skills do agente definem workflows completos. Uma skill é um playbook em markdown que o agente lê antes de agir. A skill de criação de cluster sequencia o pipeline de seis estágios e define como sondar o estado atual e retomar um workflow interrompido. Skills são arquivos versionados no repositório — conhecimento operacional mantido como código revisável.
• Ferramentas MCP expõem operações de domínio delimitadas. O servidor publica 38 ferramentas cobrindo ciclo de vida do cluster, grupos de instâncias, recursos gerenciados, armazenamento, download de modelos, implantação de inferência, jobs e operações de nós. Toda ferramenta mutante nomeia a ferramenta de status que determina a conclusão, tornando a regra de polling-até-estado-terminal mecânica.
• As ferramentas reutilizam a API do backend. Adicionar um grupo de instâncias via MCP entra no mesmo código de gerenciador que o browser usa, com a mesma resolução de sub-rede, a mesma normalização de campos e a mesma persistência de status.

Comparado com apontar um agente de codificação diretamente para chamadas AWS CLI ou SDK, essa arquitetura oferece três vantagens concretas: boas práticas embutidas (as ferramentas envolvem as APIs do backend do projeto, então configurações seguem as regras codificadas do plano de controle); orquestração de workflow por design (skills definem os processos de negócio em múltiplos passos, tornando workflows reproduzíveis entre execuções e versões de modelos); e zero configuração local (o backend e o servidor MCP são enviados no mesmo contêiner).

Os contratos de confiabilidade que a interface web precisava são exatamente o que um agente também precisa: operações persistem sua fase antes do início do polling, uma query de status não compete com o processo que possui transições de estado, e o contrato de diff explícito significa que um agente habilitando uma capacidade não carrega intenção oculta sobre as outras.

Observabilidade

Uma operação não está completa só porque uma API a aceitou. A página de Monitoramento expõe saúde dos nós, totais e disponibilidade de GPUs e visualizações ao vivo de pods, serviços, deployments, recursos InferenceEndpointConfig e HyperPodPyTorchJob — e o agente lê o mesmo estado via ferramentas de status. Para métricas de frota, o HyperPod publica no Amazon Managed Service for Prometheus, com dashboards no Amazon Managed Grafana via add-on de observabilidade do HyperPod.

Igualmente importante: o plano de controle não se torna o único lugar onde o estado existe. Recursos customizados gerados, deployments, labels de nós e recursos AWS permanecem inspecionáveis com kubectl e AWS CLI.

Considerações antes de adotar

• A superfície de orquestração EKS continua sendo responsabilidade do usuário para segurança: acesso ao Kubernetes, autorização de cargas de trabalho, egresso de rede e IAM devem seguir políticas de menor privilégio.
• Skills de agente são código operacional — versione-as, revise-as e teste-as contra as APIs que invocam.
• Nem toda capacidade de treinamento se compõe: o treinamento elástico atualmente exclui Instâncias Spot, checkpointing em camadas gerenciado e treinamento sem checkpoint.
• Custos e cotas abrangem vários serviços: Amazon EKS, instâncias HyperPod, armazenamento, balanceamento de carga, observabilidade gerenciada e MLflow gerenciado aparecem na conta. Cotas de uso de cluster do SageMaker HyperPod e reservas de plano de treinamento para tipos de GPU de alto desempenho precisam ser providenciadas antes do primeiro cluster.

Como começar

Para começar com o HyperPod no Amazon EKS, a AWS disponibiliza a documentação de suporte ao Amazon EKS no SageMaker HyperPod. Para um tutorial completo cobrindo gerenciamento de clusters e treinamento de FM, há o Workshop de Suporte ao Amazon EKS no Amazon SageMaker HyperPod. Para implantar a solução descrita, seja pela interface web ou pelo agente, o ponto de partida é o repositório HyperPod-InstantStart e seu guia de lançamento.

Fonte

Run agent-driven Amazon SageMaker HyperPod operations with InstantStart (https://aws.amazon.com/blogs/machine-learning/run-agent-driven-amazon-sagemaker-hyperpod-operations-with-instantstart/)

O problema com documentos complexos em soluções RAG

Equipes de atendimento ao cliente que lidam com grandes volumes de documentos — como contas de serviços públicos, faturas e extratos — enfrentam um desafio persistente: extrair informações corretas de arquivos com formatos variados, tabelas densas e layouts inconsistentes. Quando o volume cresce, a ineficiência se multiplica e os erros se tornam inevitáveis.

A AWS publicou um guia técnico detalhando como resolver esse problema combinando o Amazon Textract com o Amazon Bedrock. A proposta é substituir a busca manual por documentos por consultas programáticas, extraindo insights de contas de serviços públicos em escala e tornando as interações com clientes mais rápidas e precisas.

Por que o RAG simples não é suficiente

A abordagem inicial mais comum para esse tipo de problema é implementar uma solução de Geração Aumentada por Recuperação (RAG — Retrieval Augmented Generation) alimentando os documentos brutos diretamente no modelo. Só que essa estratégia apresenta falhas sérias na prática.

Ao carregar as contas diretamente no modelo, os times enfrentaram três problemas principais:

• Extração incompleta de dados: o Modelo de Linguagem de Grande Escala (LLM — Large Language Model) deixava de capturar informações críticas, como datas de vencimento, valores devidos e números de conta.
• Alucinações: o modelo gerava informações incorretas ou irrelevantes, causando erros nas respostas ao cliente.
• Variação de formato: documentos em PDF, DOCX, TXT, HTML e XLSX produziam resultados inconsistentes, já que cada formato impõe desafios diferentes para o LLM.

A conclusão foi direta: simplesmente alimentar documentos brutos em um pipeline RAG não é suficiente para garantir respostas confiáveis. É necessário um pré-processamento robusto antes de qualquer interação com o modelo.

A solução: Amazon Textract + Amazon Bedrock

A arquitetura proposta pela AWS integra o Amazon Textract ao Amazon Bedrock para resolver exatamente esses gargalos. O Textract atua como a camada de pré-processamento inteligente, enquanto o Bedrock fornece as capacidades de recuperação e geração de respostas.

Essa integração oferece três benefícios centrais:

• Extração avançada de texto: o Textract processa os documentos antes de qualquer consulta ao LLM, capturando texto de múltiplos formatos e garantindo que todas as informações relevantes sejam preservadas.
• Limpeza e enriquecimento dos dados: o conteúdo extraído passa por um processo de higienização, removendo ruídos e informações irrelevantes para que apenas os dados pertinentes cheguem ao modelo.
• Compreensão contextual: o Textract rotula e etiqueta o conteúdo extraído com contexto semântico, facilitando o trabalho do LLM na hora de processar e gerar respostas precisas.

Formatos de arquivo suportados

A solução suporta os seguintes tipos de arquivo:

• PDF (Formato de Documento Portátil): o Textract extrai texto de PDFs com múltiplas páginas, incluindo documentos com layouts complexos e imagens incorporadas.
• DOCX (Documento Microsoft Word): o serviço interpreta e extrai texto de arquivos Word, incluindo tabelas, imagens e outros objetos incorporados.
• TXT (Arquivos de Texto Simples): arquivos de texto puro são processados diretamente para extração de conteúdo.
• HTML (Linguagem de Marcação de Hipertexto): o Textract extrai texto de arquivos HTML, incluindo dados estruturados dentro das tags.
• XLSX (Planilha Microsoft Excel): o serviço extrai texto de planilhas Excel, incluindo conteúdo de células e dados tabulares.
• PNG (Gráfico de Rede Portátil): o Textract também processa imagens PNG para extração de texto.

Como implantar a solução

A AWS disponibilizou o código completo no GitHub para facilitar a implementação. A implantação é feita por meio de um script shell que cria automaticamente uma pilha do AWS CloudFormation com todos os recursos necessários.

Passo a passo da implantação

Para executar o script de implantação, siga estas etapas:

• Clone o repositório do GitHub.
• Navegue até o diretório custom-knowledge-base.
• Abra um terminal e execute bash custom_kb_deployment_setup.sh.

O script cria a pilha do CloudFormation automaticamente. Os recursos provisionados na sua conta incluem:

• Função de execução do AWS Lambda
• Camada (layer) do Lambda utilizada pelas funções
• Duas funções Lambda
• Um bucket do Amazon Simple Storage Service (Amazon S3)
• Um cluster do Amazon OpenSearch Serverless
• Uma base de conhecimento do Amazon Bedrock
• Função do AWS Identity and Access Management (IAM) para a base de conhecimento do Bedrock

Configuração pós-implantação

Após a conclusão da implantação da pilha, é necessário configurar o Amazon S3. Acesse o console do S3, localize o bucket criado com o nome document-<stack-name>-<partial-stack-id>, crie uma pasta chamada raw_files e faça o upload das contas de serviços públicos do repositório para essa pasta.

Processamento automatizado

A partir do momento em que um arquivo é carregado no bucket, o pipeline entra em ação automaticamente:

• O upload aciona a função Lambda document-parser.
• Os jobs do Amazon Textract processam os arquivos brutos.
• Os arquivos processados são salvos na pasta parsed_files.
• Uma segunda função Lambda converte os arquivos para o formato TXT.
• O resultado final é salvo na pasta parsed_kb_documents.

Configuração da base de conhecimento

Com os documentos processados, o próximo passo é configurar a base de conhecimento no Amazon Bedrock. Acesse o console do Bedrock, navegue até Knowledge Bases no painel de navegação, selecione a base de conhecimento recém-criada, escolha a fonte de dados e clique em Sync. Aguarde a sincronização ser concluída.

Testando a aplicação

Para validar a solução, acesse o console do Amazon Bedrock, selecione a base de conhecimento e escolha Text Knowledge Base. Nas configurações, selecione o modelo Amazon Nova Micro. Para verificar a disponibilidade do modelo por região da AWS, consulte a documentação de modelos suportados por região no Amazon Bedrock. Com tudo configurado, é possível fazer perguntas diretamente relacionadas às contas de serviços públicos carregadas.

Considerações sobre IA responsável

A AWS destaca que, ao implantar soluções RAG em produção, é fundamental implementar salvaguardas para garantir saídas confiáveis. O Amazon Bedrock Guardrails oferece controles configuráveis para filtrar conteúdo prejudicial, bloquear tópicos não permitidos e redigir informações sensíveis tanto nas entradas quanto nas saídas do modelo. Além disso, a validação de fundamentação (grounding validation) ajuda a detectar e reduzir alucinações, avaliando se as respostas do modelo são suportadas pelos documentos de origem recuperados.

Para ambientes de produção, a recomendação é ativar esses controles para manter precisão, conformidade e confiança dos usuários nas interações com a base de conhecimento.

Conclusão

A solução demonstrada pela AWS mostra como a integração entre múltiplos serviços pode transformar um pipeline RAG simples — e problemático — em um sistema de processamento de documentos robusto e escalável. O uso do CloudFormation garante uma infraestrutura consistente e reproduzível entre diferentes ambientes, enquanto o pipeline automatizado cuida de todo o fluxo, desde o upload do arquivo bruto até a integração com a base de conhecimento.

A abordagem é especialmente valiosa para organizações que lidam com grandes volumes de documentos estruturados. O potencial de expansão é amplo: é possível adicionar novos tipos de documentos, integrar outros serviços AWS para análises mais complexas ou desenvolver uma interface de usuário para facilitar a interação com a base de conhecimento.

Fonte

Customizing your knowledge base on Amazon Bedrock for large and complex documents using Amazon Textract (https://aws.amazon.com/blogs/machine-learning/customizing-your-knowledge-base-on-amazon-bedrock-for-large-and-complex-documents-using-amazon-textract/)

O que foi anunciado

A AWS anunciou a disponibilidade do conector nativo do ServiceNow para o Amazon Bedrock Managed Knowledge Base, seu serviço gerenciado de Geração Aumentada por Recuperação (RAG). Com essa novidade, equipes que já utilizam o ServiceNow como repositório de conhecimento corporativo podem agora alimentar seus agentes de IA diretamente com esse conteúdo — sem precisar construir nenhuma infraestrutura de ingestão por conta própria.

O problema que o conector resolve

Até então, quem queria trazer o conteúdo do ServiceNow para o Bedrock Knowledge Bases precisava desenvolver e manter pipelines de ingestão customizados. Isso significava mais código, mais manutenção e mais pontos de falha. Com o novo conector nativo, basta fornecer as credenciais da instância ServiceNow — o serviço cuida de todo o restante: rastreamento dos dados, extração de metadados e sincronização incremental automática.

O que o conector é capaz de fazer

O conector de dados do ServiceNow rastreia dois tipos principais de conteúdo:

• Artigos de conhecimento — o conteúdo das bases de conhecimento mantidas no ServiceNow
• Itens do catálogo de serviços — incluindo anexos de arquivos vinculados a esses registros

Além disso, é possível delimitar o escopo do rastreamento usando listas de inclusão por sys ID, o que permite selecionar apenas bases de conhecimento específicas, categorias de artigos ou catálogos de serviços relevantes. Isso garante que apenas o conteúdo pertinente seja ingerido na base de conhecimento.

Casos de uso práticos

Com esse conector, fica muito mais simples construir assistentes de IA voltados para uso interno ou externo, como:

• Assistentes de TI para funcionários, com respostas baseadas nos artigos de conhecimento da empresa
• Helpdesks de RH alimentados pelo conteúdo atualizado do ServiceNow
• Agentes de suporte ao cliente com acesso ao catálogo de serviços vigente

Em todos esses cenários, os agentes de IA passam a ter acesso ao conhecimento institucional já mantido no ServiceNow — sem duplicação de esforço ou risco de informações desatualizadas.

Onde aprender mais

Para quem quiser se aprofundar, a AWS disponibiliza documentação detalhada sobre o conector na seção do Amazon Bedrock User Guide. Mais informações sobre o serviço como um todo estão disponíveis na página do produto Amazon Bedrock Knowledge Bases.

Fonte

Amazon Bedrock Managed Knowledge Base now supports ServiceNow as a native data source connector (https://aws.amazon.com/about-aws/whats-new/2026/09/amazon-bedrock-managed-knowledge-base-servicenow-native-data-source-connector/)

O que mudou no Amazon Bedrock Managed Knowledge Base

A AWS anunciou uma atualização relevante para o Amazon Bedrock Managed Knowledge Base, seu serviço totalmente gerenciado de Geração Aumentada por Recuperação (RAG — Retrieval-Augmented Generation). A novidade é o suporte a agendamento automático de sincronização para conectores nativos de fontes de dados.

Para quem ainda não conhece o serviço: o Amazon Bedrock Managed Knowledge Base cuida de toda a parte pesada de ingestão de dados, otimização de armazenamento e recuperação avançada de informações — sem que a equipe precise gerenciar bancos de dados vetoriais ou pipelines de dados manualmente.

Qual era o problema antes

Até então, manter uma base de conhecimento atualizada exigia que as equipes disparassem a sincronização manualmente sempre que os dados de origem mudavam — ou então que construíssem uma solução customizada de agendamento por conta própria. Isso gerava retrabalho, risco de desatualização e overhead operacional desnecessário.

Como funciona o agendamento automático

Com a nova funcionalidade, é possível configurar ciclos de sincronização diários, semanais ou mensais diretamente nos conectores nativos de fontes de dados. Dessa forma, os agentes de IA sempre recuperam as informações mais recentes, sem intervenção manual.

A ideia é que a frequência de sincronização seja ajustada de acordo com o ritmo de atualização do conteúdo de cada fonte. O anúncio da AWS traz três exemplos práticos:

• Sincronização diária para uma base de suporte ao cliente no Confluence, que muda com frequência;
• Sincronização semanal para documentos de políticas no SharePoint, que são atualizados periodicamente;
• Sincronização mensal para materiais de referência armazenados no Amazon S3, com baixa frequência de alteração.

Qual é o benefício prático

O principal ganho é a eliminação da necessidade de construir e manter soluções de agendamento customizadas. Isso reduz a sobrecarga operacional das equipes e garante que as aplicações de RAG permaneçam fundamentadas em dados corporativos atuais — algo crítico para a confiabilidade das respostas geradas por agentes de IA.

Onde encontrar mais informações

Para se aprofundar na configuração do recurso, a AWS disponibiliza a documentação Agendamento de sincronização para fontes de dados no Amazon Bedrock User Guide. Informações gerais sobre o serviço podem ser encontradas na página do produto Amazon Bedrock Knowledge Bases.

Fonte

Amazon Bedrock Managed Knowledge Base now supports automatic sync scheduling for data source connectors (https://aws.amazon.com/about-aws/whats-new/2026/09/amazon-bedrock-managed-knowledge-base-automatic-sync-scheduling-data-source-connectors/)

O que mudou

A AWS anunciou suporte à configuração gerenciada pelo usuário — conhecida como 3LO (Three-Legged OAuth) — para as fontes de dados SharePoint, OneDrive e Confluence no Amazon Bedrock Managed Knowledge Base. A novidade simplifica bastante o processo de integração dessas plataformas com bases de conhecimento gerenciadas na AWS.

Qual era o problema antes

Até então, conectar essas fontes de dados ao Amazon Bedrock exigia a geração de credenciais 2LO (Two-Legged OAuth) diretamente nos sistemas de terceiros. Esse processo era demorado e, muitas vezes, inacessível para usuários que não tinham permissões de administrador no SharePoint, OneDrive ou Confluence. Na prática, qualquer time que quisesse prototipar um assistente de IA precisava acionar o time de TI para obter credenciais de conta de serviço — um gargalo desnecessário para quem está em fase de experimentação.

Como funciona agora

Com a configuração 3LO, o processo ficou muito mais direto: basta fazer login com as suas credenciais existentes da plataforma de terceiros, e o próprio Amazon Bedrock Managed Knowledge Base cuida da autenticação. A configuração da fonte de dados pode ser concluída em poucos minutos, sem depender de credenciais administrativas ou da intervenção do time de TI.

Vale destacar que essa nova opção não substitui o método anterior baseado em conta de serviço. As duas abordagens coexistem: o 3LO oferece um caminho mais rápido para quem está em fase de prototipagem, enquanto a autenticação via conta de serviço segue disponível para cargas de trabalho em produção que exigem uma abordagem mais programática e robusta.

Por que isso importa para times de IA

Equipes que querem construir assistentes de IA fundamentados em documentação corporativa — seja em wikis do Confluence, arquivos do OneDrive ou bases do SharePoint — agora têm um caminho de entrada muito menos burocrático. A redução de fricção no início do processo é especialmente valiosa em contextos de prototipagem rápida, onde cada hora de espera por acesso administrativo representa atraso no aprendizado e na validação da solução.

Como começar

A AWS disponibilizou guias específicos na documentação oficial do Amazon Bedrock para cada uma das plataformas suportadas:

• Configuração gerenciada pelo usuário para SharePoint — Guia do Usuário do Amazon Bedrock
• Configuração gerenciada pelo usuário para OneDrive — Guia do Usuário do Amazon Bedrock
• Configuração gerenciada pelo usuário para Confluence — Guia do Usuário do Amazon Bedrock

Fonte

Amazon Bedrock Managed Knowledge Base introduces user-managed setup for SharePoint, OneDrive, and Confluence data sources (https://aws.amazon.com/about-aws/whats-new/2026/09/amazon-bedrock-managed-knowledge-base-user-managed-setup-sharepoint-onedrive-confluence/)

Um assistente de pedidos direto no WhatsApp

A AWS publicou um guia técnico detalhado mostrando como implantar um assistente de pedidos multimodal no WhatsApp usando o Amazon Bedrock AgentCore e o Amazon Nova 2. A proposta resolve um problema real de redes de restaurantes e estabelecimentos de atendimento rápido: cada canal de pedido — app, site, telefone, balcão — é um sistema separado, com histórico fragmentado. O cliente parece um estranho em cada canal.

A solução apresentada pela AWS concentra tudo em um único número do WhatsApp Business. O cliente pode enviar mensagens de texto, mandar um áudio ou fazer uma ligação — tudo a partir da mesma conversa, sem instalar nada ou criar login. Os três canais compartilham o mesmo backend e a mesma memória entre canais. Quem fizer um pedido por texto hoje e ligar amanhã é reconhecido como a mesma pessoa.

Visão geral da arquitetura

O design separa três responsabilidades: a camada do WhatsApp gerencia a conversa, três runtimes de agentes processam cada canal, e o backend cuida do cardápio, carrinhos, pedidos e localização. O tráfego de entrada chega em um único webhook HTTPS, é confirmado imediatamente com um status 200 e depois processado de forma assíncrona — nenhuma requisição bloqueia a resposta.

A porta de entrada do cliente é a Meta WhatsApp Business Platform, que expõe o webhook da Cloud API, a Messages API, a Media API e a Calling API. Toda a infraestrutura AWS é provisionada pelo AWS Kit de Desenvolvimento em Nuvem (AWS CDK).

Os principais serviços AWS utilizados na solução são:

• Amazon API Gateway: duas APIs REST — um webhook HTTPS público e uma API de backend autorizada por Gerenciamento de Identidade e Acesso (IAM).
• AWS Lambda: executa a ingestão do webhook, o worker, o remetente de mensagens e a lógica de negócio dos pedidos.
• Amazon Serviço de Filas Simples (Amazon SQS): fila de entrada com fila de mensagens mortas (DLQ) para desacoplar o reconhecimento rápido do restante do processamento.
• AgentCore runtime: hospeda os três agentes, cada conversa rodando em sua própria microVM com sessões isoladas.
• Amazon Nova 2 Lite (texto via Amazon Bedrock Converse API) e Amazon Nova 2 Sonic (voz para voz em tempo real), invocados via Amazon Bedrock.
• AgentCore Gateway: servidor do Protocolo de Contexto de Modelo (MCP) gerenciado que expõe a API do backend como ferramentas MCP acessíveis pelos agentes por nome.
• AgentCore memory: registro compartilhado entre canais, indexado por um ID de cliente com hash.
• Amazon DynamoDB: armazena perfis de clientes, pedidos, itens do cardápio, carrinhos e localizações.
• Amazon Location Service: geocodificação e busca de localização mais próxima.
• Amazon Kinesis Video Streams (Amazon KVS): canal de sinalização para o relay TURN gerenciado que transporta a mídia das chamadas de voz.
• Amazon Nuvem Privada Virtual (Amazon VPC): caminho de saída para o runtime de chamadas de voz — o único runtime que precisa de VPC.
• AWS Secrets Manager e AWS Systems Manager Parameter Store: armazenam tokens e segredos da Meta e o pepper do ID do cliente.
• Amazon Registro de Contêiner Elástico (Amazon ECR), AWS CodeBuild e Amazon Simple Storage Service (Amazon S3): constroem e armazenam as imagens de contêiner ARM64 dos agentes.
• Amazon CloudWatch e AWS Serviço de Gerenciamento de Chaves (AWS KMS): monitoramento e criptografia em repouso.

Como cada canal funciona

Os três canais compartilham a mesma porta de entrada, as mesmas ferramentas de backend e a mesma memória. O que muda é o tipo de mídia e o runtime responsável por cada um.

Mensagem de texto

A mensagem chega pelo webhook. O worker deriva o customer_id, invoca o runtime de chat, que lê a memória, processa via Amazon Nova 2 Lite pela Converse API e chama as ferramentas do backend pelo gateway MCP. A resposta é enviada pelo Lambda remetente, e os eventos são gravados na memória ao final da sessão.

Nota de voz (voz para voz)

O áudio chega como mensagem de áudio no formato OGG Opus. O worker baixa os bytes e invoca o runtime de nota de voz. Após ler a memória, o áudio é decodificado para PCM a 16 kHz e alimentado em uma sessão de voz para voz do Amazon Nova 2 Sonic. Não há serviço de transcrição no caminho — é voz de entrada, voz de saída. A resposta falada é devolvida como mensagem de voz no WhatsApp.

Chamada de voz (WebRTC)

Quando o cliente inicia uma chamada, a Calling API da Meta entrega um webhook de conexão com a oferta de Protocolo de Descrição de Sessão (SDP) via Comunicação em Tempo Real pela Web (WebRTC). O worker repassa essa oferta para o runtime de chamada de voz, que opera em modo turnOnly por não ter IP público. As credenciais TURN vêm do Amazon KVS. A mídia flui via Segurança da Camada de Transporte de Datagrama e Protocolo de Transporte Seguro em Tempo Real (DTLS/SRTP) pelo relay TURN gerenciado do KVS. O Amazon Nova 2 Sonic conduz a conversa.

Reconhecimento rápido e processamento assíncrono

A Meta exige uma resposta HTTP 200 em poucos segundos. Como processar um pedido completo — buscar mídia, invocar um agente, retransmitir sinalização de chamada — leva mais tempo do que esse janela permite, o trabalho é dividido em duas etapas. O Lambda de ingestão do webhook faz apenas a parte rápida: verifica a assinatura, enfileira no Amazon SQS e retorna 200. O Lambda worker consome a fila e executa o restante. Se o worker falhar em uma mensagem, ela retorna à fila e é reprocessada. Após algumas tentativas, vai para a fila de mensagens mortas para inspeção posterior.

Memória única para todos os canais

O que faz a solução parecer um único assistente é a memória compartilhada. Um único recurso de AgentCore memory é indexado pelo customer_id com hash, e os três runtimes usam a mesma chave. Cada runtime lê os insights de longo prazo do cliente no início da sessão e grava os eventos ao final. Os insights incluem pedidos anteriores, itens favoritos e preferências mencionadas. Como todos os canais resolvem o mesmo cliente para a mesma memória, não há estado entre canais para reconciliar.

Conectando agentes ao backend com MCP

Nenhum runtime do AgentCore chama diretamente as funções Lambda do backend. O AgentCore Gateway é um servidor MCP gerenciado. Cada runtime se conecta a ele como cliente MCP via HTTPS, autenticado com o papel IAM do runtime, e descobre as ferramentas por nome. Cada runtime carrega seu próprio papel, então o gateway concede apenas o acesso que aquele runtime precisa. O gateway expõe a API REST do backend e gera uma ferramenta MCP por endpoint. Quando um agente chama uma ferramenta como PlaceOrder, o gateway traduz isso em uma requisição REST que o backend API Gateway roteia para o Lambda correspondente. Como os agentes falam com ferramentas nomeadas em vez de funções específicas, é possível alterar um handler ou adicionar uma ferramenta sem mudar nenhum agente.

Identificando o cliente sem login

Um cliente do WhatsApp não faz login, então o sistema usa o número de telefone como base de identidade. Ele aplica hash ao número no formato E.164 com um pepper secreto armazenado no AWS Systems Manager Parameter Store, e o resultado vira o customer_id ("wa-" + sha256(E164 || Pepper)[:16]). O número bruto não é armazenado na memória nem no estado da sessão, o que ajuda a atender requisitos de Informações de Identificação Pessoal (PII). Se o cliente for reconhecido, o agente o cumprimenta pelo nome e lembra suas preferências. Caso contrário, ele faz o pedido como novo cliente.

Exemplo de conversa

Não há interface web ou cliente de teste. A interação acontece diretamente no WhatsApp. Um exemplo típico de troca:

Cliente: What's on the menu near 75201?
Agente: [ferramentas: GeocodeAddress, GetNearestLocations, GetMenu]
Here's what's available at Amazing Burgers - Dallas:
- Burger Combo ($8.99)
- Chicken Tenders ($6.49)
...

Cliente: A burger combo and a milkshake, please.
Agente: [ferramentas: AddToCart, GetCart]
Added to your cart:
- 1x Burger Combo - $8.99
- 1x Milkshake - $3.49
Total: $12.48. Want me to place the order?

Cliente: Yes.
Agente: [ferramenta: PlaceOrder]
Your order is placed and is being prepared for pickup at Amazing Burgers - Dallas.

Notas de voz e chamadas de voz seguem o mesmo fluxo via Amazon Nova 2 Sonic — o cliente fala o pedido e o agente responde com voz.

Pré-requisitos e implantação

Para implantar a solução, são necessários uma conta AWS ativa com acesso habilitado aos modelos Amazon Nova 2 Lite (amazon.nova-2-lite-v1:0) e Amazon Nova 2 Sonic (amazon.nova-2-sonic-v1:0) na região de implantação, além de permissões IAM para criar os recursos da solução, incluindo AgentCore runtime, Gateway e memory. Localmente, é preciso ter Node.js 24.x ou superior, AWS CLI 2.x configurado e git. O bootstrap do AWS CDK na conta e região alvo também é necessário. A região Leste dos EUA (Norte da Virgínia) — us-east-1 — é um bom ponto de partida. Para disponibilidade dos modelos por região, consulte os modelos suportados por região no Amazon Bedrock.

No lado da Meta, é preciso ter um App de Desenvolvedor Meta com o produto WhatsApp adicionado, vinculado a um portfólio de negócios. Para testes, o número de sandbox da Meta é suficiente, sem necessidade de verificação de negócio ou número de produção. Consulte como começar com a Cloud API para o procedimento completo. Para chamadas de voz, é necessário habilitar a WhatsApp Calling API no número.

A solução completa está no repositório de exemplo no GitHub. Para implantar:

git clone https://github.com/aws-samples/sample-multimodal-whatsapp-restaurant-agent.git
cd sample-multimodal-whatsapp-restaurant-agent
./scripts/preflight-check.sh
./scripts/deploy-all.sh --deploymentPrefix qsr-wa

O script provisiona todas as stacks em ordem de dependência: VPC compartilhada, backend (DynamoDB, Location Service, Lambdas e API REST), AgentCore Gateway e memória compartilhada, build das imagens ARM64 com CodeBuild, push para ECR, implantação dos três runtimes, webhook do WhatsApp e notificador de pedidos, e por fim a alimentação dos dados de cardápio e localização. O primeiro build de cada contêiner leva aproximadamente 8 a 12 minutos.

Os segredos da Meta (Access Token, App Secret e Verify Token) são armazenados em containers vazios do Secrets Manager criados pelo CDK e preenchidos fora de banda — nunca como parâmetros do CDK, o que evitá-los de aparecer no template sintetizado.

Custos e considerações para produção

Os custos escalam principalmente com o volume de conversas e a proporção de tráfego de voz, que consome mais recursos por sessão do que texto. Limitar a implantação a canais específicos pode reduzir o custo base. Para estimativas detalhadas por região, use a Calculadora de Preços da AWS e consulte a página de preços da Meta WhatsApp Business Platform.

Para implantações em produção, a AWS recomenda habilitar o Amazon Bedrock Guardrails para adicionar filtragem de conteúdo e validação de fundamentação, garantindo que as respostas do agente permaneçam dentro dos limites da política e reduzindo saídas alucinadas.

Vale notar que o WhatsApp também recebe imagens e documentos. Esta solução foca em pedidos e não processa esses anexos, mas o Amazon Nova 2 Lite já é multimodal — o agente poderia ler a foto de um cartão fidelidade ou um PDF de pedido de catering e transformá-lo em um pedido estruturado. O padrão também vai além de restaurantes: os mesmos blocos construtores se encaixam em suporte ao varejo, triagem de saúde, agendamento de serviços de campo e outros domínios, bastando trocar as ferramentas e dados do backend.

Limpeza dos recursos

Para evitar cobranças contínuas, a AWS disponibiliza um script de limpeza que destrói as stacks na ordem inversa:

./scripts/cleanup-all.sh --dry-run  # visualiza sem remover nada
./scripts/cleanup-all.sh            # exclui todas as stacks criadas

A limpeza é destrutiva: exclui o histórico de pedidos no DynamoDB, o pepper no Parameter Store, os segredos no Secrets Manager e as imagens no ECR. Faça backup do que quiser manter antes. O lado da Meta não é afetado — cancele a inscrição do webhook e revogue os tokens no console da Meta separadamente. Ao final, confirme no console do AWS CloudFormation que as stacks foram removidas.

Fonte

Deploy a multimodal WhatsApp ordering assistant with Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/deploy-a-multimodal-whatsapp-ordering-assistant-with-amazon-bedrock-agentcore/)

Controle centralizado para agentes de codificação com IA generativa

À medida que as organizações avançam da experimentação individual para a adoção gerenciada de agentes de IA, surge uma necessidade prática: controlar o acesso aos modelos de forma consistente entre desenvolvedores e equipes. O OpenAI ChatGPT Codex, combinado com o LiteLLM, oferece exatamente isso — um ponto de controle centralizado para roteamento de modelos, identidade com escopo definido, orçamentos, limites de uso e telemetria.

A AWS publicou um guia completo mostrando como implantar um gateway LiteLLM operado pelo próprio cliente no Serviço de Contêiner Elástico da Amazon (Amazon ECS), conectá-lo a um modelo OpenAI no Amazon Bedrock e configurar o Codex para enviar requisições por esse gateway. A implementação completa está disponível no repositório guidance-codex. Para o caminho principal, o recomendado é seguir o guia de início rápido do LiteLLM na AWS.

Visão geral da arquitetura

A solução posiciona o LiteLLM entre o Codex e o Amazon Bedrock. O gateway se torna o ponto de controle compartilhado para autenticação de modelos, roteamento, orçamentos, limites de taxa e telemetria. O Codex mantém a responsabilidade pelo loop local de execução de tarefas e ferramentas na estação de trabalho do desenvolvedor.

O fluxo de requisição ocorre em cinco etapas:

• O Codex envia o contexto da tarefa atual e as definições de ferramentas disponíveis para o endpoint /v1/responses do gateway.
• O Balanceador de Carga de Aplicação (ALB) e o AWS WAF aplicam controles de rede e de camada web antes de encaminhar a requisição ao LiteLLM no AWS Fargate.
• O LiteLLM autentica o chamador, verifica o modelo configurado e a política de consumo, e usa a função de tarefa do ECS para invocar o modelo aprovado no Amazon Bedrock.
• O Amazon Bedrock retorna texto ou uma chamada de função através do LiteLLM. Se o modelo solicitar uma ferramenta, o Codex a executa localmente sob sua política de sandbox e aprovação.
• O Codex envia o resultado da ferramenta pelo LiteLLM na próxima requisição Responses, e o loop continua.

A implantação de referência também utiliza: Amazon RDS para PostgreSQL (para estado, uso e dados de orçamento do LiteLLM), AWS Secrets Manager e AWS KMS para armazenamento de chaves, Amazon CloudWatch para logs e alarmes, Amazon ECR para imagem imutável do gateway, e proteções opcionais do AWS WAF.

Por que usar o LiteLLM nesse padrão?

O LiteLLM é um gateway de IA de código aberto que fornece roteamento de modelos, chaves virtuais, orçamentos, limites de taxa e telemetria de uso por trás de endpoints compatíveis com a API. Nesse padrão, o cliente opera o LiteLLM e sua infraestrutura de suporte dentro da própria conta AWS.

O acesso direto ao Amazon Bedrock é a opção de menor complexidade quando identidade nativa da AWS, políticas do Gerenciamento de Identidade e Acesso (IAM) e logs do AWS CloudTrail atendem aos requisitos. Um gateway se torna útil quando a equipe de sistemas precisa de controles adicionais consistentes entre desenvolvedores, equipes ou provedores de modelos. O LiteLLM é uma boa opção quando é necessário:

• Permitir apenas aliases de modelos aprovados.
• Emitir chaves de gateway com escopo por usuário ou equipe.
• Aplicar orçamentos fixos e limites de requisições por minuto ou tokens por minuto.
• Centralizar política de roteamento e fallback.
• Operar o gateway, banco de dados, rede, logs e processo de atualização na própria conta AWS.

A principal contrapartida é a responsabilidade operacional: a equipe fica responsável pela disponibilidade do gateway, ciclo de vida do banco de dados, atualizações de versão, resposta a incidentes e planejamento de capacidade.

Implantando o gateway LiteLLM no Amazon ECS

Pré-requisitos

Para o passo a passo, são necessários: uma conta AWS com permissões para criar Rede Virtual Privada (VPC), Amazon ECS, Elastic Load Balancing, Amazon RDS, Amazon ECR, AWS WAF, IAM, AWS KMS, Secrets Manager e recursos do CloudWatch; acesso ao modelo OpenAI selecionado no Amazon Bedrock na região de implantação; Interface de Linha de Comando da AWS (AWS CLI) versão 2 com perfil autenticado; Docker com Buildx; Codex CLI; e Python 3. Para implantação com HTTPS, é necessária uma zona hospedada pública no Amazon Route 53 ou um certificado existente no AWS Certificate Manager (ACM) na mesma região.

Nota de custos: A solução cria recursos faturáveis, incluindo um ALB, tarefas Fargate, Amazon RDS, AWS WAF, logs e inferência de modelos. Consulte o AWS Pricing Calculator para sua região e siga a seção de limpeza após o passo a passo.

Implantando o LiteLLM no Amazon ECS

Clone o repositório e crie um arquivo de ambiente de implantação local:

git clone https://github.com/openai-on-aws/guidance-codex.git
cd guidance-codex
git checkout feat/enterprise-gateway-readiness
cp deployment/litellm/.env.deploy.example \
   deployment/litellm/.env.deploy

Configure o perfil AWS, regiões, CIDR de origem e valores de DNS ou certificado. O trecho a seguir mostra as configurações orientadas à produção:

AWS_PROFILE=your-profile
AWS_REGION=us-east-1
BEDROCK_REGION=us-east-1
ENABLE_TLS=true
GATEWAY_DOMAIN_NAME=codex-gateway.example.com
ROUTE53_HOSTED_ZONE_ID=Z0123456789EXAMPLE
ALB_CERTIFICATE_ARN=
ALLOWED_CIDR=203.0.113.10/32
ENABLE_WAF=true
DB_MULTI_AZ=true
DESIRED_COUNT=2
MIN_TASK_COUNT=2
MAX_TASK_COUNT=10

Execute a verificação prévia somente leitura:

make litellm-check

Construa a imagem LiteLLM revisada e envie para o Amazon ECR:

CONFIRM_AWS_WRITE=1 make litellm-build

Crie um conjunto de alterações do CloudFormation sem executá-lo:

make litellm-plan

Revise o conjunto de alterações e, em seguida, implante:

CONFIRM_AWS_WRITE=1 make litellm-deploy
make litellm-status

Criando uma identidade de gateway com escopo definido

Não distribua a chave mestra do LiteLLM para os desenvolvedores. Configure uma identidade de usuário ou equipe no arquivo de implantação:

CODEX_API_SECRET_ID=codex-litellm-gateway/alice-key
CODEX_KEY_ALIAS=alice@example.com
CODEX_KEY_USER_ID=alice@example.com
CODEX_KEY_MODELS=gpt-5.5
CODEX_KEY_MAX_BUDGET=50
CODEX_KEY_BUDGET_DURATION=30d
CODEX_KEY_TPM_LIMIT=100000
CODEX_KEY_RPM_LIMIT=1000

Provisione a chave:

CONFIRM_AWS_WRITE=1 make litellm-provision-key

O helper resolve a credencial mestra em um processo filho, chama a API /key/generate do LiteLLM com as políticas configuradas de modelo, orçamento e taxa, e grava a chave gerada diretamente em um segredo do Secrets Manager criptografado com KMS.

Configurando o Codex

Gere o bloco de provedor:

make litellm-codex-config

O helper lê o endpoint do gateway implantado a partir do CloudFormation e imprime a configuração de provedor do Codex. Adicione a saída ao arquivo de configuração em nível de usuário ~/.codex/config.toml. A configuração gerada tem este formato:

model = "gpt-5.5"
model_provider = "litellm-gateway"
web_search = "disabled"

[model_providers.litellm-gateway]
name = "LiteLLM Gateway"
base_url = "https://codex-gateway.example.com/v1"
wire_api = "responses"

[model_providers.litellm-gateway.auth]
command = "/absolute/path/to/python3"
args = [
  "/absolute/path/to/deployment/scripts/aws-secret-auth.py",
  "--aws-cli", "/absolute/path/to/aws",
  "--region", "us-east-1",
  "--secret-id", "codex-litellm-gateway/alice-key",
  "--field", "LITELLM_API_KEY",
  "--profile", "developer-profile",
  "print-token"
]
timeout_ms = 30000
refresh_interval_ms = 300000

Testando o Codex através do LiteLLM

Inicie uma sessão interativa do Codex e use /status para verificar que litellm-gateway é o provedor selecionado. Para um teste não interativo repetível, execute primeiro uma requisição mínima de verificação:

codex exec --sandbox read-only --ephemeral \
  "Reply with exactly LITELLM_GATEWAY_OK and no other text."

Em seguida, exercite o loop do agente com uma tarefa que exija tanto inferência de modelo quanto uma ferramenta local:

codex exec --sandbox read-only --ephemeral \
  "Read README.md with shell tools and summarize the deployment architecture. Do not modify files."

Validando o contrato da Responses API

Um prompt de texto bem-sucedido não prova que um fluxo de trabalho de agente é compatível. O Codex depende de mais do que uma resposta básica de chat. Execute a sonda estrita incluída:

make litellm-validate

A sonda verifica: campos obrigatórios do objeto Responses e formato de saída; continuação semântica com previous_response_id; streaming de eventos enviados pelo servidor com uma resposta terminal completa; e uma chamada de ferramenta forçada com ID de chamada.

O script de validação é um portão de compatibilidade, não um teste de carga. Antes da produção, também é importante testar sessões de agentes concorrentes, streams de longa duração, cancelamento de requisições, revogação de chaves, recuperação de falhas e pico de tráfego esperado.

Operacionalizando o LiteLLM para uso empresarial

A compatibilidade é apenas o ponto de partida. Antes de integrar desenvolvedores, é necessário definir como o gateway controlará o acesso ao modelo, atribuirá uso, aplicará política de consumo e fornecerá registro operacional para cada requisição.

Comece pela superfície de modelos que os desenvolvedores têm permissão de usar. Publique aliases de gateway estáveis apenas para modelos aprovados pela organização e fixe cada mapeamento upstream em deployment/litellm/litellm_config.yaml. Emita chaves com escopo separadas para usuários, equipes ou cargas de trabalho em vez de distribuir a chave mestra do LiteLLM.

A mesma identidade com escopo pode aplicar política de consumo. Defina CODEX_KEY_MAX_BUDGET, CODEX_KEY_BUDGET_DURATION, CODEX_KEY_TPM_LIMIT e CODEX_KEY_RPM_LIMIT ao provisionar uma chave.

Operar o gateway também requer uma visão do caminho completo de requisições. Monitore contagens de tarefas desejadas e em execução no ECS, rollback de implantação, saúde e latência do alvo do ALB, saúde do Amazon RDS, requisições e rejeições do LiteLLM, uso de tokens, gasto, acesso a segredos, mudanças de IAM e bloqueios do AWS WAF.

Implantações em produção devem habilitar o Amazon Bedrock Guardrails no caminho de acesso ao modelo para filtragem de conteúdo, detecção de tópicos negados e verificações de fundamentação. Os controles em nível de gateway (orçamentos, limites de taxa e roteamento) complementam, mas não substituem, as salvaguardas de IA responsável aplicadas na camada do modelo.

Caminhos alternativos de acesso

Acesso direto com IAM Identity Center

Use o provedor nativo amazon-bedrock do Codex quando identidade nativa da AWS e controles de auditoria forem suficientes:

model_provider = "amazon-bedrock"
model = "openai.gpt-5.5"

[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"
region = "us-east-1"

O desenvolvedor faz login com um perfil nomeado do IAM Identity Center:

aws sso login --profile codex-bedrock

Esse caminho remove o gateway, o banco de dados e as operações associadas. O guia de início rápido do IAM Identity Center do repositório inclui comandos CloudFormation e helpers para criar um grupo isolado e conjunto de permissões, atribuir o grupo a uma conta AWS, imprimir a configuração do cliente e validar o perfil autenticado contra o Amazon Bedrock.

Acesso gerenciado ou híbrido com Portkey

O Portkey pode ser útil quando o cliente deseja um plano de controle gerenciado, roteamento centralizado e política, ou um plano de dados híbrido suportado sem operar a pilha de referência do LiteLLM. Para uma avaliação do Codex, configure uma chave de workspace do Portkey, um provedor do Amazon Bedrock Model Catalog e o protocolo wire Responses:

model_provider = "portkey"
model = "@bedrock-validation/"

[model_providers.portkey]
name = "Portkey"
base_url = "https://api.portkey.ai/v1"
env_key = "PORTKEY_API_KEY"
wire_api = "responses"

Execute a mesma sonda estrita de Responses antes de promover para produção. Escolha o Portkey quando o modelo operacional gerenciado ou híbrido for mais importante do que executar o gateway inteiramente na sua conta AWS. Consulte o guia de início rápido de avaliação do Portkey para mais detalhes.

Limpeza dos recursos

Visualize o que o CloudFormation excluirá e reterá:

make litellm-cleanup-plan

Exclua o gateway somente após confirmar seu nome exato de pilha:

CONFIRM_STACK_DELETE=codex-litellm-gateway \
  make litellm-cleanup

A pilha de referência cria um snapshot final do Amazon RDS e retém chaves KMS, segredos do Secrets Manager, o grupo de logs do CloudWatch e o bucket de logs de acesso do ALB. Imagens do ECR e segredos de chaves com escopo provisionadas também ficam fora da exclusão da pilha. Revise e remova os recursos retidos de acordo com sua política de retenção de dados.

Conclusão

Rotear o Codex através do LiteLLM fornece um ponto de controle operado pelo cliente para seleção de modelos, identidade com escopo, orçamentos, limites de taxa e telemetria, preservando o modelo local de execução de tarefas e ferramentas do Codex. A porta de produção importante não é se um gateway pode retornar texto — é se o gateway preserva os comportamentos da Responses API que um fluxo de trabalho de agente precisa e se a equipe de sistema consegue operar a infraestrutura adicionada de forma confiável.

A recomendação é começar com acesso direto via IAM Identity Center quando os controles nativos da AWS atendem ao requisito. Adicionar o LiteLLM quando a política de gateway operada pelo cliente justificar o trabalho operacional. E avaliar o Portkey quando um modelo operacional gerenciado ou híbrido for o melhor encaixe organizacional — aplicando os mesmos testes de contrato a cada caminho.

Recursos adicionais

• Implementação do Guidance for Codex na AWS
• OpenAI no Amazon Bedrock
• Documentação do Amazon Bedrock
• Guia de início rápido do LiteLLM na AWS
• Guia de início rápido do IAM Identity Center
• Guia de implantação em produção
• Provedores de modelos personalizados do Codex
• Usando o Codex com o Amazon Bedrock
• Amazon ECS no AWS Fargate
• Documentação do AWS IAM Identity Center
• Documentação do proxy LiteLLM
• Integração do Portkey com Codex

Fonte

Set up OpenAI ChatGPT Codex with LiteLLM on Amazon ECS and Amazon Bedrock (https://aws.amazon.com/blogs/machine-learning/set-up-openai-chatgpt-codex-with-litellm-on-amazon-ecs-and-amazon-bedrock/)

Um agente que funciona no notebook não é um agente em produção

Essa é a premissa central de um guia técnico publicado pela AWS sobre como migrar workloads agênticos para o Amazon Bedrock AgentCore. O texto parte de um ponto muito honesto: a inferência do modelo raramente é o problema em produção. O que consome o time de engenharia são as responsabilidades operacionais que aparecem depois — isolamento de sessão, persistência de estado, autenticação de ferramentas, patching de infraestrutura, entre outras.

O guia mapeia dez dessas cargas operacionais e mostra como o AgentCore as absorve progressivamente, em estágios. O agente de exemplo é um bot de suporte ao cliente construído com LangGraph: ele classifica mensagens, escala clientes insatisfeitos e responde os demais usando três ferramentas. As chamadas de modelo já passam pelo Amazon Bedrock desde o início — mas isso, como o próprio guia destaca, não é a vantagem que parece.

O que o AgentCore cobre — e o que continua sendo seu

Antes de entrar nos estágios, o guia faz questão de ser claro sobre o escopo do AgentCore. Ele é descrito como uma plataforma para construir, conectar e otimizar agentes em escala, com qualquer framework ou modelo. Mas ele não elimina tudo:

• Runtime assume o compute: patching de sistema operacional, auto scaling e isolamento de sessão deixam de ser sua responsabilidade.
• Gateway assume a autenticação das ferramentas e as publica como ferramentas Protocolo de Contexto de Modelo (MCP — Model Context Protocol).
• Memory assume o estado da conversa, tornando-o durável entre turnos, processos e dias.

O que continua sendo responsabilidade da equipe: configuração de Rede Virtual Privada (VPC — Virtual Private Cloud), regras de Firewall de Aplicação Web (WAF — Web Application Firewall), políticas de Gerenciamento de Identidade e Acesso (IAM — Identity and Access Management), rotação de segredos e atualizações de dependências (estas últimas só saem do seu escopo no Estágio 3).

Estágio 0: o agente que você já tem

Antes de mover qualquer coisa, o guia recomenda registrar uma linha de base: quais ferramentas foram executadas e qual foi a mensagem final do estado do grafo. Isso transforma o próximo estágio em uma comparação objetiva, não em uma aposta.

O agente do exemplo usa ChatBedrockConverse como modelo, um MemorySaver com thread_id como checkpointer, e três ferramentas (lookup_order, process_return e search_faq) como funções @tool. O roteamento é feito por um nó classify_intent com uma função Python determinística.

O único problema real nesse estágio é o estado: um dicionário em memória morre com o processo, e duas réplicas não conseguem ver as conversas uma da outra. Tudo o mais funciona bem em escala de produção — mas esse ponto não.

Para quem chega de OpenAI ou Anthropic direto, a única mudança necessária neste estágio é trocar o construtor do modelo pelo ChatBedrockConverse, passando o ID do modelo e a região AWS. A lista de modelos disponíveis por região pode ser consultada na documentação de modelos suportados por região no Amazon Bedrock.

Estágio 1: o mesmo agente, migrado

O Estágio 1 move cinco das dez cargas operacionais sem alterar o comportamento do agente. Três coisas mudam: o Runtime assume o processo, duas das três ferramentas vão para o Gateway, e o estado da conversa passa para o Memory.

Runtime: hospedando o loop

O loop existente é envolvido por BedrockAgentCoreApp com um entrypoint decorado. O thread_id que antes era escolhido manualmente agora chega como context.session_id do RequestContext que o Runtime injeta. O guia faz um alerta importante: construa o grafo uma vez e mantenha-o, porque reconstruir por requisição pode derrubar a sessão MCP das ferramentas.

from bedrock_agentcore import BedrockAgentCoreApp
from langchain_core.messages import HumanMessage

app = BedrockAgentCoreApp()

@app.entrypoint
def agent_invocation(payload, context):
    state = support_graph().invoke(
        {"messages": [HumanMessage(payload.get("prompt", ""))]},
        config={"configurable": {"thread_id": context.session_id or "local-session"}},
    )
    return {"result": state["messages"][-1].text}

if __name__ == "__main__":
    app.run()

O mesmo wrapper funciona com loops CrewAI, LlamaIndex ou qualquer outro: aceite um dicionário de payload, invoque, retorne um dicionário.

Gateway: publicando ferramentas como MCP

O motivo de colocar uma ferramenta atrás de um gateway é o que vem junto: a autenticação sai do seu código e a ferramenta publicada passa a ser acessível por outros agentes futuros, não apenas pelo agente atual.

lookup_order e process_return são publicadas como ferramentas MCP pelo AgentCore Gateway a partir de uma função Lambda. A criação é feita com duas chamadas no cliente bedrock-agentcore-control: uma para criar o gateway (escolhendo o tipo de autorizador — AWS_IAM ou CUSTOM_JWT) e outra para registrar o target apontando para a função Lambda com o schema JSON das ferramentas.

client = boto3.client("bedrock-agentcore-control", region_name=region)
gateway = client.create_gateway(
    name="MigratedAgentGateway",
    roleArn=role_arn,
    protocolType="MCP",
    authorizerType="AWS_IAM",
)
gateway_id = gateway["gatewayId"]
gateway_url = gateway["gatewayUrl"]

As ferramentas descobertas chegam prefixadas com o nome do target e três underscores: lookup_order vira supportTools___lookup_order. search_faq permanece como função Python local em todos os estágios — e o guia deixa claro que esse é o caso normal, não um compromisso. Uma ferramenta que nenhum outro agente precisa e nenhuma política controla não tem nada a ganhar com a migração para o Gateway.

Memory: estado que sobrevive ao processo

O MemorySaver do Estágio 0 é substituído por um checkpointer respaldado pelo AgentCore Memory, identificado por actor_id e sessão. O checkpointer já vem como dependência instalada (langgraph-checkpoint-aws) e não precisa de código customizado:

from langgraph_checkpoint_aws import AgentCoreMemorySaver
graph = build_graph(
    llm=llm,
    tools=tools,
    checkpointer=AgentCoreMemorySaver(memory_id, region_name=region),
)
state = graph.invoke(
    {"messages": [HumanMessage(prompt)]},
    config={"configurable": {"thread_id": session_id, "actor_id": actor_id}},
)

O guia recomenda testar a durabilidade explicitamente: um segundo processo, compartilhando apenas os IDs de memória, actor e sessão, deve conseguir responder sobre uma conversa que nunca foi carregada localmente.

Deploy e armadilhas comuns

O deploy usa uma codeConfiguration: um zip do código-fonte no Amazon S3 com as dependências vendorizadas ao lado. Sem container, sem Amazon Elastic Container Registry (ECR — Elastic Container Registry), sem Docker. Mas há duas armadilhas que custam tempo real:

• Wheels de plataforma errada: o Runtime roda em ARM64 Linux. Instale as dependências para o target correto: --platform manylinux2014_aarch64 --python-version 3.12 --only-binary=:all:
• Dependência faltando no zip: um requirements.txt dentro do zip é inerte. O arquivo é o ambiente finalizado. Se uma dependência falta, o erro aparece como timeout de inicialização do Runtime, não como ModuleNotFoundError.

Estágio 2: reconstruindo o loop por escolha

O Estágio 2 não move cargas operacionais — ele muda quem decide o próximo passo. Faz sentido quando o roteamento escrito à mão (route_intent) se torna o gargalo: cada nova intenção exige um novo nó no grafo em vez de uma linha no prompt.

Com Strands Agents, o planejamento passa para o modelo. O add_conditional_edges não tem equivalente — e o guia é explícito sobre o trade-off: o branch determinístico e auditável é trocado por um planejamento que não é nem um nem outro.

O gerenciamento de memória colapsa em um objeto de configuração e um argumento de construtor, reutilizando o Gateway, o target e o Memory store do Estágio 1:

config = AgentCoreMemoryConfig(
    memory_id=memory_id,
    session_id=session_id,
    actor_id=actor_id
)
kwargs["session_manager"] = AgentCoreMemorySessionManager(
    config, region_name=region_name
)
return Agent(**kwargs)

Policy: decisão determinística de volta em cada chamada de ferramenta

Para compensar a perda do branch auditável, a Policy do Amazon Bedrock AgentCore coloca uma decisão determinística na frente de cada chamada de ferramenta via Gateway, usando regras Cedar avaliadas no plano de dados — em um caminho que a aplicação não consegue contornar. Um guardrail na saída do modelo não está nesse caminho; quando ele roda, a chamada já aconteceu.

O exemplo do guia usa duas regras: uma identidade somente-leitura pode chamar lookup_order; uma identidade privilegiada pode também chamar process_return. Cedar é default-deny — a recusa do caller somente-leitura é simplesmente a ausência de uma regra permit correspondente.

Estágio 3: entregando o loop

O Estágio 3 é documentado no guia, mas não construído no walkthrough. Um AgentCore harness executa o loop por você, alimentado por Strands Agents. O agente é declarado como configuração (modelo, prompt de sistema, ferramentas, memória e limites) e a AWS o executa — trocar de modelo vira uma mudança de configuração, não um redeploy.

O pré-requisito é que o agente já seja um loop orientado a modelo (não um grafo), o que significa que o Estágio 2 precede obrigatoriamente o Estágio 3. É o único ponto do guia onde a ordem recomendada é também a única ordem possível. Seis das dez cargas operacionais se movem aqui — e atualização de dependências é a única que só sai do seu escopo neste estágio.

Armadilhas comuns de migração

O guia fecha com três padrões que custam mais tempo às equipes após a migração:

1. Assumir paridade de comportamento

O agente não vai se comportar de forma idêntica após a migração, e sem critérios acordados antes da mudança, qualquer diferença de redação vira uma discussão sem fim. A recomendação é definir critérios de aceitação baseados em resultados, não em implementação — e usar o AgentCore Evaluations para testá-los.

2. Manter estado no processo

Uma sessão não é uma invocação: ela contém múltiplas invocações, e o Runtime encerra o ambiente de execução após 15 minutos de inatividade por padrão, provisionando um novo para a mesma sessão. Esse timeout é configurável via idleRuntimeSessionTimeout (de 60 segundos a 8 horas), mas ajustá-lo move o prazo — não o elimina. A sessão sobrevive; o estado em memória, não.

3. Subestimar a arquitetura de autenticação

Lacunas de autenticação custam retrabalho, não configuração. Mapeie primeiro todos os fluxos: como o agente se autentica em APIs externas, como usuários se autenticam no agente, como as permissões são escopadas. O AgentCore Identity responde à primeira questão, referenciado no target do gateway no lugar de GATEWAY_IAM_ROLE.

Pré-requisitos para seguir o walkthrough

Para reproduzir o guia, são necessários: uma conta AWS com acesso ao Amazon Bedrock habilitado, Python 3.12 e a Interface de Linha de Comando AWS (AWS CLI) configurada com credenciais para criar recursos de AgentCore, Lambda, Amazon S3 e IAM. Também é necessário habilitar o CloudWatch Transaction Search uma vez na conta — sem isso, os traces gerados não podem ser visualizados.

O repositório de exemplo está organizado por estágio, permitindo comparar cada um com o anterior. O setup cria um ambiente virtual e instala sete dependências com um único script.

Conclusão

O Estágio 1 é um ponto de parada válido: você mantém a orquestração em que confia, em compute gerenciado, com ferramentas gerenciadas e estado durável. O Estágio 2 é outro ponto de parada, para agentes onde o roteamento escrito à mão virou o gargalo. O Estágio 3 tira o loop do seu codebase.

O guia também destaca que nenhuma dessas migrações precisa ser feita duas vezes: as features do AgentCore se encaixam como um argumento de keyword para as ferramentas do gateway, uma dependência pinada para o checkpointer, um objeto de configuração para o session manager e um arquivo de regras Cedar para a Policy.

Para aprofundamento, a AWS recomenda clonar o repositório de exemplo, ler a comparação de arquitetura de segurança e consultar a documentação do Amazon Bedrock AgentCore.

Fonte

Migrate agentic workloads to Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/migrate-agentic-workloads-to-amazon-bedrock-agentcore/)