O problema de custo em aplicações agênticas

Imagine um assistente de compras construído sobre um modelo frontier. O usuário pede “uma pochete preta por menos de vinte dólares de uma loja com pelo menos 4,5 estrelas” e o agente busca no catálogo, examina candidatos, verifica restrições e faz uma recomendação. Parece simples, mas o que acontece por baixo dos panos é um loop de múltiplas chamadas: buscar, ler resultados, refinar, verificar, decidir. Cada etapa é uma chamada separada ao modelo frontier — e você paga por todas elas, para cada usuário.

Em escala de produção, esse custo por tarefa se acumula rapidamente, corrói o retorno sobre o investimento e pode inviabilizar o projeto. Uma alternativa natural é usar um modelo menor, que responde mais rápido e custa menos para hospedar. O problema é que modelos menores geralmente entregam qualidade inferior — é exatamente por isso que o modelo maior foi escolhido.

É aqui que entra a destilação de conhecimento: a técnica transfere o comportamento do modelo maior (“professor”) para um modelo menor (“aluno”), treinando o aluno para reproduzir as saídas do professor. O resultado é um modelo que mantém boa parte da qualidade do professor, mas com a velocidade e o custo do modelo menor.

A AWS publicou um guia completo mostrando como aplicar essa abordagem — especificamente a Destilação de Conhecimento em Nível de Sequência (SeqKD, do inglês Sequence-level Knowledge Distillation) — para treinar um agente de compras no Amazon SageMaker AI.

O que é SeqKD e quando usá-la

A SeqKD é a forma mais simples e portátil de destilação. O funcionamento é direto: o modelo professor gera respostas de alta qualidade, e o modelo aluno é treinado nessas respostas via Ajuste Fino Supervisionado (SFT, do inglês Supervised Fine-Tuning). Não é necessário acessar os pesos internos do professor, seus logits ou qualquer infraestrutura de aprendizado por reforço — apenas as saídas de texto já são suficientes.

Isso significa que a SeqKD funciona mesmo quando o professor é um modelo frontier fechado, acessível apenas por API. Como as respostas geradas persistem como um conjunto de dados, elas podem ser reutilizadas para treinar ou testar diferentes alunos sem precisar regenerar os dados.

Para agentes, a sequência que o professor produz não é um parágrafo de texto, mas uma trajetória: uma sequência ordenada de raciocínios, chamadas de ferramentas e observações retornadas, onde cada etapa depende de tudo que veio antes. Treinar o aluno nessa sequência completa ensina tanto o raciocínio que leva a cada ação quanto o curso de ação em múltiplas etapas.

A SeqKD é a escolha certa em três situações principais:

• Você tem as entradas, mas não tem saídas de alta qualidade: o professor gera os alvos de treinamento para você, mesmo para trajetórias agênticas complexas.
• Seu professor é um modelo frontier acessível apenas por API: como a SeqKD precisa apenas do texto gerado, é a única abordagem que funciona sem acesso aos pesos internos.
• Você quer um primeiro passo sólido e econômico: os modelos destilados DeepSeek-R1 são um exemplo conhecido dessa abordagem, onde o raciocínio de um modelo grande foi destilado em modelos Qwen e Llama menores.

Visão geral da solução

O pipeline descrito pela AWS funciona assim: um modelo frontier (GLM-5.3 no Amazon Bedrock) atua como agente no benchmark ShoppingBench para gerar trajetórias. O próprio scorer do benchmark filtra apenas as trajetórias que resolvem a tarefa, e essas trajetórias aprovadas são usadas para fazer o ajuste fino de um modelo Qwen3.5-4B (aluno) com SFT serverless via customização de modelos do SageMaker AI. O aluno destilado é então avaliado em um conjunto de teste separado e servido por um endpoint de inferência em tempo real.

Pré-requisitos

Para executar esse exemplo, são necessários:

• Uma conta AWS com uma função AWS Identity and Access Management (IAM) para o SageMaker AI com acesso de leitura e escrita a um bucket do Amazon S3 e permissão para invocar o modelo professor.
• Um modelo frontier para gerar as trajetórias (o guia usa um no Amazon Bedrock).
• Acesso à customização de modelos do SageMaker AI em uma região AWS suportada.
• O Amazon SageMaker Studio (ou uma IDE local com o AWS CLI configurado), com kernel Python 3.12 ou superior, SageMaker Python SDK v3 e boto3.
• Uma instância ml.m5.4xlarge no mínimo para o ambiente de notebook.
• O repositório de código do exemplo e uma tarefa com um scorer programático.

Preparando o conjunto de dados

O ShoppingBench publica 750 problemas de compras sintéticos (250 para cada intenção: produto, loja e voucher), cada um com uma resposta correta oculta e as restrições que definem o sucesso. Os dados são divididos em 426 problemas de treinamento e 324 para avaliação.

Para cada problema de treinamento, o modelo professor (GLM-5.3 no Bedrock, com raciocínio ativado e temperatura 1.0) age como agente do ShoppingBench: busca no catálogo de cerca de 2,7 milhões de produtos, examina candidatos e faz recomendações. O professor é amostrado duas vezes por problema, gerando 850 trajetórias no total. O scorer do ShoppingBench então filtra apenas as que resolvem a tarefa.

A temperatura 1.0 é intencional: a amostragem em vez da decodificação greedy faz com que as duas tentativas explorem consultas e caminhos de raciocínio diferentes, aumentando a chance de que pelo menos uma trajetória por problema seja bem-sucedida. Essa etapa de rejection sampling transforma um professor capaz-mas-imperfeito em um conjunto de treinamento limpo.

Codificando as trajetórias para treinamento

Cada trajetória aprovada é codificada como uma lista de mensagens de chat e renderizada com o template de chat do próprio modelo aluno — assim os tokens que o treinador vê são os mesmos que o agente produz na inferência.

Cada trajetória se torna uma linha de treinamento por etapa. O turno do usuário carrega o prompt de sistema e a conversa até aquele ponto. O turno do assistente carrega o raciocínio daquela etapa e a chamada de ferramenta correspondente. A perda é calculada apenas sobre o turno do assistente, para que o modelo aprenda a produzir o próximo raciocínio-e-ação, não a prever as observações retornadas pelo ambiente.

Um exemplo de linha de treinamento:

{
  "messages": [
    {"role": "user", "content": "You are a shopping assistant. ...\n# Task\nFind a black waist bag under $20 from a shop rated 4.5 or higher.\n# Observations so far\n(none yet)"},
    {"role": "assistant", "content": "Start with a broad search and let the price filter work before I narrow by shop rating.\n[{\"name\": \"find_product\", \"parameters\": {\"q\": \"black waist bag\", \"price\": \"0-20\"}}]"}
  ]
}

Cada etapa posterior vira sua própria linha, com a nova observação adicionada ao conteúdo do usuário e o próximo raciocínio-e-chamada-de-ferramenta como alvo do assistente.

Um ponto importante: divida os dados por problema, não por linha. Como o professor é amostrado duas vezes por problema e cada trajetória se expande em várias etapas, muitas linhas compartilham o mesmo problema — uma divisão por linha vazaria contextos quase idênticos entre treinamento e validação.

Para controlar o tamanho dos tokens, comprima as observações das ferramentas, que dominam a contagem. Para resultados de busca de produtos, mantenha apenas os campos que a próxima decisão depende (id, preço, avaliação e as restrições sendo verificadas). Após o JSONL de cada divisão estar no S3, registre cada um como um ativo de conjunto de dados de customização com DataSet.create do SageMaker Python SDK v3.

Ajuste fino do modelo aluno

O treinamento usa a customização de modelos do SageMaker AI com SFT serverless. Basta selecionar um modelo base do hub de modelos, apontar o job para os conjuntos de dados codificados, e o serviço gerenciado provisiona o compute, executa o job e retorna o modelo customizado — com métricas rastreadas no Amazon SageMaker com MLflow. Não há script de treinamento, imagem de container ou instância para gerenciar.

O job grava sua saída em um grupo de pacotes de modelo que versiona cada modelo produzido. A configuração do job de customização é feita assim:

from sagemaker.train.sft_trainer import SFTTrainer
from sagemaker.train.common import TrainingType

sft_trainer = SFTTrainer(
    model="huggingface-vlm-qwen3-5-4b", # Qwen3.5-4B from the JumpStart model hub
    training_type=TrainingType.LORA,    # TrainingType.FULL for full fine-tuning
    training_dataset=train_dataset.arn,
    validation_dataset=val_dataset.arn,
    model_package_group=model_package_group,
    mlflow_experiment_name="seqkd-shopping-exp",
    s3_output_path="s3:///seqkd/output/",
    accept_eula=True,
)

Os hiperparâmetros para este experimento:

sft_trainer.hyperparameters.dataset_max_len = 16384
sft_trainer.hyperparameters.max_epochs = 3
sft_trainer.hyperparameters.global_batch_size = 64
sft_trainer.hyperparameters.learning_rate = 0.0001
sft_trainer.hyperparameters.lora_rank = 64
sft_trainer.hyperparameters.lora_alpha = 256  # alpha / rank = 4
sft_trainer.hyperparameters.lr_warmup_steps_ratio = 0.1
sft_trainer.hyperparameters.train_val_split_ratio = 0.95

Para validar a configuração sem lançar o job, use dry_run=True. Para lançar e aguardar:

from sagemaker.core.resources import TrainingJob

sft_trainer.train(dry_run=True)           # verifica a config sem lançar
training_job = sft_trainer.train(wait=True) # lança e aguarda
model_package_arn = TrainingJob.get(
    training_job_name=training_job.training_job_name
).output_model_package_arn

Avaliando o modelo aluno

A avaliação acontece em dois estágios, do menor custo para o maior.

Primeiro, um pré-check gerenciado de baixo custo usando a avaliação de modelos do SageMaker AI, que pontua uma etapa gerada por vez contra a ação de referência do professor. O critério é a seleção de ferramentas: o modelo chamou as ferramentas certas, na ordem certa? A função de recompensa para o Custom Scorer é:

def reward_function(sample, index):
    pred = sample.get("model_response", "")
    ref  = sample.get("reference_answer", "") or sample.get("response", "")

    ref_names  = tool_names(ref)   # tool names from the teacher's [...]
    pred_names = tool_names(pred)  # tool names the student emitted, parsed leniently

    toolset = 1.0 if (pred_names and pred_names == ref_names) else 0.0
    return {
        "id": str(sample.get("id", f"sample-{index:03d}")),
        "aggregate_reward_score": toolset,
        "metrics_list": [
            {"name": "toolset_match", "value": toolset, "type": "Reward"},
        ],
    }

A regra de decisão é simples: o aluno deve superar o modelo base nesse pré-check. Se superar, a destilação funcionou e vale a pena rodar a avaliação completa ponta a ponta. Se não superar, o treinamento precisa ser corrigido primeiro.

Servindo o agente destilado

O modelo destilado não executa ferramentas por conta própria. O ajuste fino ensina-o a emitir a chamada de ferramenta certa no momento certo como texto, mas ainda é necessário um harness que prompta o modelo, analisa a chamada emitida, executa a ferramenta, adiciona a observação e prompta novamente — em loop até o modelo produzir uma resposta final.

O aluno é um adaptador LoRA (Adaptação de Baixo Rank, do inglês Low-Rank Adaptation) sobre uma base de pesos abertos. Em vez de mesclar o adaptador e servir uma segunda cópia completa dos pesos, a abordagem recomendada é servir o modelo base uma vez e anexar o aluno como adaptador, usando dois componentes de inferência em um único endpoint em tempo real. Nomear o componente de inferência na invocação seleciona qual responde, permitindo comparação lado a lado entre o modelo base e o aluno destilado.

from sagemaker.core import image_uris
import kd_serve

# DJL LMI container (vLLM engine bundled in); pin the version for reproducible redeploys
image_uri = image_uris.retrieve("djl-lmi", region=region, version="0.36.0")

# 1. Deploy the base model as an inference component, with LoRA serving enabled.
endpoint_name, base_ic = kd_serve.deploy_base_endpoint(
    endpoint_name="seqkd-shopping-agent",
    role=role,
    region=region,
    image_uri=image_uri,
    base_model_id="Qwen/Qwen3.5-4B",
    instance_types=["ml.g5.2xlarge", "ml.g6.2xlarge", "ml.g6e.2xlarge"],
    max_lora_rank=64,
    max_loras=4,
    max_model_len=131072,
)

# 2. Resolve the student's adapter artifacts from its Model Package and attach them
# as a second inference component on the same base.
adapter_uri = kd_serve.resolve_adapter_uri(model_package_arn, region)
student_ic = kd_serve.attach_adapter(
    endpoint_name=endpoint_name,
    base_ic_name=base_ic,
    adapter_component_name=f"{endpoint_name}-student",
    adapter_s3_uri=adapter_uri,
    region=region,
)

A lista instance_types é uma preferência ordenada: o SageMaker AI Inference implanta no primeiro tipo com capacidade disponível e recorre à lista conforme necessário. Os pesos base são carregados uma vez, e ambos os componentes de inferência os compartilham — adicionar o adaptador custa memória do tamanho do adaptador, não uma segunda cópia completa do modelo.

Resultados

A avaliação usa a Taxa de Sucesso Absoluta (ASR, do inglês Absolute Success Rate) — a proporção de problemas que o agente resolve — no conjunto de teste separado do ShoppingBench, com 324 problemas distribuídos entre três intenções (produto, loja e voucher).

Os pontos de referência comparados são: o Qwen3.5-4B base sem ajuste fino (piso), o aluno destilado via SeqKD (o resultado que importa), o professor GLM-5.3 (amostrado a temperatura 1.0 e greedy a temperatura 0) e um modelo frontier de médio porte como teto prático.

Os resultados de ASR médio por modelo:

• Base Qwen3.5-4B (sem ajuste fino): 0,297
• Aluno destilado (SeqKD): 0,541
• Professor GLM-5.3 (amostrado, temperatura 1.0): 0,511
• Professor GLM-5.3 (greedy, temperatura 0): 0,540
• Modelo frontier de médio porte: 0,546

O resultado principal: um modelo de 4 bilhões de parâmetros recuperou essencialmente toda a qualidade de tarefa do seu professor frontier, igualando-o dentro da variação entre execuções.

O raciocínio nas saídas importa muito

Treinar o aluno apenas nas chamadas de ferramentas (sem o raciocínio do professor) derruba a ASR média de 0,541 para 0,415. Ambos os alunos superam o modelo base, mas manter o raciocínio é o que leva o aluno até o nível do seu professor. O raciocínio entre as ações não é narração descartável — é parte do comportamento que resolve a tarefa.

Capacidade geral preservada

Para verificar se o aluno manteve sua capacidade geral de seguir instruções, o guia usa o IFEval, um benchmark de seguimento de instruções. A pontuação prompt-strict cai de 0,819 (modelo base) para 0,741, e a instruction-strict de 0,872 para 0,813 — uma queda de cerca de 6 a 8 pontos. Isso é o custo esperado da especialização: o aluno trocou alguma capacidade geral por um grande ganho na tarefa de compras.

Benefícios, limitações e boas práticas

A justificativa econômica é clara: um modelo frontier acessado via API é cobrado por token, em cada etapa de cada tarefa, e o custo cresce com o uso sem parar. O aluno destilado roda em um endpoint que você hospeda, cobrado por hora independente do volume — você troca uma cobrança variável por requisição por uma fixa por hora. Quanto menor o modelo que você consegue usar, menor esse custo fixo. A AWS recomenda medir o custo no seu próprio workload comparando a precificação do SageMaker AI com os preços de tokens do seu provedor frontier.

Há limitações importantes a considerar:

• O muro de capacidade: a destilação transfere uma distribuição que o aluno já consegue representar. Se a lacuna entre a tarefa e o aluno for grande demais, o aluno copia o formato do professor sem aprender a resolver. O sintoma: as trajetórias ficam mais longas enquanto a acurácia permanece estagnada. Quando isso acontece, aumente o aluno ou reduza a dificuldade da tarefa.
• Onde a SeqKD para de ajudar: a SeqKD melhora problemas fáceis e de dificuldade média, mas atinge um platô nos mais difíceis, onde o aluno precisa se recuperar dos próprios erros. Métodos on-policy são o próximo passo natural para fechar essa lacuna — a SeqKD é um forte ponto de partida, não o fim da linha.

Duas escolhas que fazem a diferença: primeiro, alinhe os alvos de treinamento ao comportamento desejado (mantenha o raciocínio do professor junto a cada chamada de ferramenta). Segundo, avalie honestamente — use dados que os modelos não viram, e compare contra mais do que apenas o modelo base não treinado.

Limpeza de recursos

Um endpoint de inferência em tempo real é cobrado enquanto estiver ativo. Para encerrar, os componentes devem ser removidos na ordem de dependência: o adaptador primeiro, depois o componente base, depois o endpoint e sua configuração. O helper kd_serve faz isso automaticamente:

import kd_serve

# Deletes the adapter IC, then the base IC, then the endpoint and its configuration
kd_serve.teardown_endpoint(endpoint_name, region=region)

O job de treinamento não precisa de limpeza — o treinamento serverless provisiona compute, executa e libera automaticamente. O grupo de pacotes de modelo também não gera custo de compute. O que continua gerando custo é o armazenamento no S3 (trajetórias codificadas e artefatos de saída), então delete o que não for mais necessário ou mova para uma classe de armazenamento mais econômica.

Conclusão

O guia publicado pela AWS demonstra como a SeqKD permite destilar um assistente de compras agêntico em um modelo menor e mais barato que mantém essencialmente toda a qualidade de tarefa do professor frontier. O pipeline completo cobre: geração de trajetórias de alta qualidade com rejeição das que falham, codificação por etapa preservando o raciocínio do professor, ajuste fino serverless com rastreamento via MLflow, verificação de qualidade com avaliação de modelos do SageMaker AI, e serviço do resultado em um endpoint de inferência.

Como a SeqKD precisa apenas das saídas de texto do professor, ela funciona mesmo quando o professor é um modelo frontier fechado acessível apenas por API — e após o aluno assumir, você para de pagar preços frontier em cada etapa. Para explorar o pipeline completo, consulte o repositório de código do exemplo e a documentação do SageMaker AI.

Fonte

Build efficient agents with knowledge distillation on Amazon SageMaker AI (https://aws.amazon.com/blogs/machine-learning/build-efficient-agents-with-knowledge-distillation-on-amazon-sagemaker-ai/)

Novidade para ambientes governamentais

A AWS anunciou a disponibilidade do modelo Claude Haiku 5.5, da Anthropic, no Kiro — tanto na Ambiente de Desenvolvimento Integrado (IDE) quanto na Interface de Linha de Comando (CLI) — para as regiões AWS GovCloud (US). Com essa adição, todos os três modelos da família Claude 5.5 passam a estar acessíveis no Kiro nessas regiões.

O que é o Claude Haiku 5.5?

O Claude Haiku 5.5 é o modelo mais rápido da família Claude 5.5. Ele representa uma evolução clara em relação ao Claude Haiku 4.5 e foi projetado especificamente para cenários que exigem alto volume de requisições com respostas ágeis.

Entre os casos de uso mais indicados estão:

• Sumarização e compactação de contextos longos
• Classificação e roteamento de requisições
• Processamento de texto em larga escala
• Edições pequenas e direcionadas em múltiplos arquivos

O modelo também se destaca como um subagente de revisão executado em paralelo, enquanto modelos mais robustos da família — como o Opus 5.5 e o Sonnet 5.5 — assumem tarefas mais complexas de planejamento e codificação.

Capacidades técnicas do modelo

O Haiku 5.5 utiliza adaptive thinking (pensamento adaptativo) com cinco níveis de esforço, que vão de baixo a máximo, sendo o nível médio o padrão. Outras especificações relevantes:

• Janela de contexto: 1 milhão de tokens
• Multiplicador de crédito padrão: 0,06x
• Requisições acima de 100 mil tokens: faturadas com multiplicador de 0,3x

Como acessar o Haiku 5.5 no Kiro

Para utilizar o novo modelo, basta garantir que o Kiro (IDE ou CLI) esteja atualizado para a versão mais recente e, em seguida, reiniciá-lo. O Haiku 5.5 estará disponível diretamente no seletor de modelos da ferramenta.

Para mais detalhes, a AWS disponibiliza a documentação da GovCloud, o guia de monitoramento e rastreamento, além do suporte via equipe de conta AWS. Para conhecer mais sobre o Kiro, acesse a página oficial do produto.

Fonte

Haiku 5.5 now available on Kiro in AWS GovCloud (US) (https://aws.amazon.com/about-aws/whats-new/2026/11/kiro-haiku-5-5-aws-govcloud-us/)

Introdução: a qualidade dos dados define a qualidade das respostas

Quando falamos de aplicações de Geração Aumentada por Recuperação (RAG), a qualidade das respostas depende diretamente dos dados que alimentam o sistema. O Amazon Bedrock Knowledge Bases é a capacidade totalmente gerenciada de RAG do Amazon Bedrock. Com o Amazon Bedrock Managed Knowledge Base, basta conectar as fontes de dados — a AWS cuida de toda a ingestão, armazenamento, indexação e recuperação. Não é preciso provisionar ou escalar um armazenamento vetorial, e os modelos de embedding e reranking já vêm configurados por padrão.

Para conteúdo web, o ponto de partida mais direto é o Amazon Bedrock Web Crawler, o conector de fonte de dados para knowledge bases gerenciadas. Basta informar as URLs semente ou sitemaps autorizados, e o crawler opera dentro do escopo e dos limites de taxa definidos. Sincronizações agendadas mantêm a base atualizada conforme as páginas mudam, e o conector consegue aguardar conteúdo carregado via JavaScript. Não há crawler para construir, hospedar ou operar — o que torna esse conector o ponto de partida para a maioria dos sites públicos.

Porém, algumas fontes exigem mais controle sobre o que chega à knowledge base. Pode ser necessário indexar apenas a região principal de conteúdo de cada página, remover navegação e outros elementos repetitivos, ou anexar metadados personalizados a cada documento. Para esse tipo de material, é possível estender o alcance da knowledge base com uma etapa de preparação usando o Crawl4AI, um crawler Python de código aberto. Essa etapa grava Markdown e um arquivo de metadados sidecar para cada página no Amazon S3, e a knowledge base ingere ambos por meio da fonte de dados S3.

O artigo original da AWS mostra como escolher o caminho de ingestão web adequado, implementar a preparação personalizada e validar a qualidade da recuperação. O repositório de exemplo aws-samples fornece o fluxo completo como implementação de referência. Vale destacar que se trata de ingestão em lote de propriedades web conhecidas, e não de acesso web em tempo real durante a inferência — para isso, existe o Web Grounding com Amazon Nova.

Visão geral da solução

A recomendação é começar pelo Amazon Bedrock Web Crawler quando ele consegue alcançar e indexar as páginas necessárias. Ele respeita o robots.txt e, após o primeiro crawl completo, cada sincronização captura apenas conteúdo adicionado, atualizado ou excluído.

O caminho via Crawl4AI entra em cena quando o material público precisa de um ou mais dos seguintes tratamentos antes da ingestão:

• Preparação estruturada em Markdown: Uso do DefaultMarkdownGenerator com filtro de conteúdo por poda para reduzir navegação e boilerplate, preservando cabeçalhos, listas e tabelas. Como a poda é heurística, é importante revisar a saída representativa dos seus sites.
• Extração direcionada e delimitada: Extração apenas da região da página que um seletor CSS opcional corresponde. Controle da travessia em largura por origem da semente, escopo de página/caminho/host, profundidade, limites de página e padrões de URL.
• Metadados personalizados: Anexar URLs de origem, timestamps de crawl, tipo de conteúdo e atributos próprios a cada documento, permitindo filtrar resultados de recuperação por eles.

Como tanto knowledge bases gerenciadas quanto gerenciadas pelo cliente suportam fontes de dados Amazon S3, o caminho via Crawl4AI funciona com ambos os tipos.

Como o fluxo de trabalho funciona

A aplicação AWS CDK empacota a implementação em uma imagem de contêiner durante o deploy. Quando o agendamento dispara, o contêiner executa scripts/container_entrypoint.py e realiza crawl, upload e ingestão em sequência. O fluxo segue estes passos:

• O Amazon EventBridge inicia a tarefa Amazon ECS no AWS Fargate conforme o agendamento configurado.
• A tarefa faz o crawl dos sites públicos configurados e prepara Markdown com um sidecar de metadados para cada página.
• A tarefa faz upload dos arquivos preparados para o bucket Amazon S3 que respalda a fonte de dados da knowledge base.
• A tarefa inicia um job de ingestão do Amazon Bedrock Knowledge Bases.
• O Amazon Bedrock Knowledge Bases lê os objetos novos e alterados, faz o parsing e aplica a estratégia de chunking selecionada. Cria embeddings e os indexa no armazenamento vetorial da knowledge base.
• A aplicação de IA generativa consulta a knowledge base para obter chunks relevantes ou uma resposta gerada com citações.

A tarefa lê sua configuração de pipeline (não secreta) do AWS Systems Manager Parameter Store na inicialização. O fluxo processa apenas páginas públicas e não implementa sessões autenticadas. Para sites que exigem login, a recomendação é avaliar primeiro as opções de autenticação do Amazon Bedrock Web Crawler, que incluem autenticação básica, baseada em formulário e SAML.

Etapa 1: Crawl e extração de conteúdo

A etapa de crawl realiza a varredura delimitada e grava um arquivo Markdown com um sidecar de metadados para cada página preparada com sucesso. Segue o trecho simplificado do código:

async def crawl_and_prepare(config: PipelineConfig, output_dir: str) -> list[str]:
    written, seen = [], set()
    pages_crawled = 0
    browser_config = BrowserConfig(headless=True, java_script_enabled=True)

    async with AsyncWebCrawler(config=browser_config) as crawler:
        for seed in config.seed_urls:
            remaining = config.crawl.max_pages - pages_crawled
            if remaining <= 0:
                break

            strategy = BFSDeepCrawlStrategy(
                max_depth=config.crawl.max_depth,
                max_pages=remaining,
                filter_chain=FilterChain([
                    SeedScopeFilter(seed, config.crawl.scope),
                ]),
            )

            run_config = CrawlerRunConfig(
                deep_crawl_strategy=strategy,
                markdown_generator=DefaultMarkdownGenerator(
                    content_filter=PruningContentFilter()
                ),
                css_selector=config.crawl.css_selector,
                check_robots_txt=config.crawl.check_robots_txt,
                mean_delay=config.crawl.request_delay_seconds,
                max_range=0,
                semaphore_count=1,
            )

            results = await crawler.arun(url=seed, config=run_config)
            for result in results:
                if pages_crawled >= config.crawl.max_pages:
                    break
                pages_crawled += 1

                requested_url = result.url
                source_url = getattr(result, "redirected_url", None) or requested_url
                if not SeedScopeFilter(seed, config.crawl.scope).apply(source_url):
                    continue

                canonical = _canonical_url(source_url)
                if canonical in seen:
                    continue
                seen.add(canonical)

                if not result.success or not result.markdown:
                    continue

                md_result = result.markdown
                markdown = (
                    getattr(md_result, "fit_markdown", None)
                    or getattr(md_result, "raw_markdown", None)
                    or (md_result if isinstance(md_result, str) else "")
                )
                if not markdown:
                    continue

                written.extend(
                    _write_document(
                        output_dir, _base_name(source_url),
                        markdown, {"source_url": source_url},
                    )
                )
    return written

O Amazon Bedrock Knowledge Bases suporta diversos formatos de documento para fontes de dados S3, incluindo texto puro, HTML, Markdown, PDF e DOCX. O fluxo grava em Markdown porque esse formato preserva cabeçalhos, listas e tabelas sem carregar todo o HTML bruto para a ingestão.

Etapa 2: Upload para o Amazon S3

A etapa de upload envia cada documento Markdown preparado e seu sidecar de metadados correspondente para o bucket S3 configurado, sob o prefixo s3Prefix do fluxo. Para page.md, o sidecar deve ser nomeado page.md.metadata.json — o nome completo do arquivo de origem com .metadata.json anexado.

O Amazon Bedrock limita cada sidecar de metadados a 10 KB. Se um sidecar exceder esse limite, a execução para com erro antes de gravar qualquer arquivo. Veja um exemplo abreviado de sidecar:

{
  "metadataAttributes": {
    "source_url": {
      "value": {"type": "STRING", "stringValue": "https://www.example.com/services/permits"}
    },
    "crawled_at_epoch": {
      "value": {"type": "NUMBER", "numberValue": 1790640000}
    },
    "content_category": {
      "value": {"type": "STRING", "stringValue": "web"}
    }
  }
}

Etapa 3: Chunking, embedding e indexação pelo Amazon Bedrock

Com o conteúdo no S3, um job de ingestão entrega cada documento ao pipeline de ingestão da fonte de dados. Por padrão, uma knowledge base gerenciada faz o parsing de cada arquivo com seu parser gerenciado, que seleciona automaticamente a abordagem de parsing para o conteúdo.

A estratégia de chunking é selecionada ao conectar a fonte de dados e não pode ser alterada depois — por isso é importante avaliar as opções antes de criar uma fonte de dados de produção. As estratégias disponíveis em uma knowledge base gerenciada são:

• Chunking padrão: chunks de tamanho fixo de 300 tokens com 20% de sobreposição.
• Chunking de tamanho fixo: divisão por contagem máxima de tokens e percentual de sobreposição configuráveis.
• Sem chunking: trata cada arquivo como um único chunk, para conteúdo já dividido previamente.

Para mais informações, consulte Personalizar ingestão para uma fonte de dados. Uma knowledge base gerenciada pelo cliente também oferece chunking semântico e hierárquico, além de opções adicionais de parsing — veja Como o chunking de conteúdo funciona para knowledge bases.

O fluxo então inicia o job de ingestão com o seguinte código simplificado:

def start_ingestion_job(config: PipelineConfig) -> str:
    client = boto3.client("bedrock-agent", region_name=config.region)
    response = client.start_ingestion_job(
        knowledgeBaseId=config.knowledge_base_id,
        dataSourceId=config.data_source_id,
    )
    return response["ingestionJob"]["ingestionJobId"]

Deploy da solução

Pré-requisitos

Antes de começar, é necessário ter:

• Uma conta AWS.
• Uma knowledge base gerenciada em uma região onde knowledge bases gerenciadas estão disponíveis, com o conector Amazon S3. Na fonte de dados, deixe o campo Metadata files prefix vazio, pois o fluxo grava cada sidecar de metadados junto ao seu documento. Ou uma knowledge base gerenciada pelo cliente existente — para adicionar uma fonte de dados S3, veja Conectar ao Amazon S3 para sua knowledge base.
• Uma fonte de dados Amazon S3 nessa knowledge base com status AVAILABLE.
• A knowledge base, o bucket S3 e a stack na mesma região.
• Autorização para fazer crawl dos sites públicos configurados.
• Uma estação de trabalho com Git, Python 3.10+, Node.js, AWS CLI v2, AWS CDK CLI v2 e um engine de contêiner compatível com Docker. O guia de deploy lista a versão mínima do CDK CLI.
• Credenciais AWS configuradas com permissão para bootstrap e deploy da stack CDK.

Deploy do fluxo agendado

Clone o repositório e instale as dependências de deploy:

git clone https://github.com/aws-samples/sample-crawl4ai-bedrock-knowledge-base.git
cd sample-crawl4ai-bedrock-knowledge-base/deploy
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Mantenha o Docker em execução. Defina AWS_DEFAULT_REGION para a região da sua knowledge base. Faça o bootstrap da conta e região alvo uma vez, se necessário, e depois faça o deploy da stack:

export AWS_DEFAULT_REGION=REGION
cdk bootstrap aws://ACCOUNT_ID/REGION
cdk deploy \
  -c knowledgeBaseId=ABCDEFGHIJ \
  -c dataSourceId=KLMNOPQRST \
  -c s3Bucket=amzn-s3-demo-bucket \
  -c 'seedUrls=["https://www.example.com/services"]' \
  -c maxDepth=1 \
  -c maxPages=25

Substitua todos os valores de exemplo pelos seus próprios. Os valores maxDepth e maxPages limitam o primeiro crawl a um nível de link e 25 páginas. Aumente-os após revisar a saída preparada. Para visualizar quais páginas um crawl prepara, é possível executar o pipeline localmente com --dry-run, conforme descrito no README.

Se o Docker na sua estação x86_64 não conseguir compilar imagens ARM64, adicione -c cpuArchitecture=X86_64 ao comando. Se a conta ativar VPC Block Public Access, a tarefa não consegue acessar a internet pela subnet pública padrão — nesse caso, faça o deploy com -c egressMode=nat, que adiciona um NAT gateway com cobranças por hora. O guia de deploy cobre as demais configurações.

Validação da qualidade de recuperação

Após a ingestão, a recomendação é testar perguntas representativas com a operação Retrieve antes de adicionar geração. Uma knowledge base gerenciada usa busca híbrida e, quando utiliza o modelo de embedding gerenciado padrão, também reordena resultados com seu reranker gerenciado. É possível filtrar resultados com os metadados dos sidecars.

O exemplo a seguir retorna até cinco chunks de páginas com content_category igual a web que foram indexadas nos últimos sete dias. Requer Boto3 1.43.32 ou posterior:

import time
import boto3

client = boto3.client("bedrock-agent-runtime", region_name="us-east-1")
week_ago = int(time.time()) - 7 * 24 * 60 * 60

response = client.retrieve(
    knowledgeBaseId="ABCDEFGHIJ",
    retrievalQuery={"text": "How do I apply for a building permit?"},
    retrievalConfiguration={
        "managedSearchConfiguration": {
            "numberOfResults": 5,
            "filter": {
                "andAll": [
                    {"equals": {"key": "content_category", "value": "web"}},
                    {"greaterThan": {"key": "crawled_at_epoch", "value": week_ago}},
                ]
            },
        }
    },
)

for result in response["retrievalResults"]:
    print(result.get("metadata", {}).get("source_url"), result["content"]["text"][:200])

Para uma knowledge base gerenciada pelo cliente, passe o mesmo filtro em vectorSearchConfiguration em vez de managedSearchConfiguration. A filtragem por metadados pode melhorar a precisão da recuperação, mas não é uma fronteira de autorização. Se diferentes usuários devem ver páginas diferentes, o conector Amazon S3 para knowledge bases gerenciadas suporta controle de acesso em nível de documento com arquivos de Lista de Controle de Acesso (ACL).

Para gerar respostas a partir de uma knowledge base gerenciada, use a recuperação agêntica. A operação AgenticRetrieveStream retorna os resultados recuperados e uma resposta gerada com citações. Para uma knowledge base gerenciada pelo cliente, use RetrieveAndGenerate. Avalie relevância de recuperação, cobertura de páginas-fonte e qualidade de citação sempre que alterar preparação de conteúdo, chunking ou configurações de recuperação — veja Configurar e personalizar consultas para knowledge bases gerenciadas.

Execuções recorrentes e custos

Cada evento agendado lança uma tarefa Fargate independente. A stack não impede execuções sobrepostas, então é importante escolher um intervalo maior que a duração esperada do crawl e ingestão. Uma execução com falha não é anunciada, pois o exemplo não adiciona política de retry, fila de mensagens mortas ou alarme.

Cada execução incorre em cobranças Fargate pelo tamanho configurado da tarefa (padrão: 2 vCPU e 4 GB). A tarefa continua em execução enquanto consulta o job de ingestão por até 30 minutos. A stack habilita Container Insights para o cluster e flow logs para a VPC, ambos adicionando cobranças do CloudWatch. Com egressMode=nat ou privateEndpoints=true, o NAT gateway e os endpoints de interface são cobrados por hora, mesmo sem tarefa em execução. Para detalhes, consulte preços do Amazon VPC e preços do Amazon Bedrock.

Os uploads são aditivos: remover uma URL ou perder uma página em um crawl posterior não exclui os objetos S3 existentes. Para remover conteúdo obsoleto, delete o documento e o sidecar correspondente sob o prefixo configurado e inicie a ingestão novamente. Para iniciar a ingestão automaticamente quando objetos no bucket mudam, veja Construir e implantar uma solução de sincronização automática para Amazon Bedrock Knowledge Bases.

Considerações de IA Responsável

As passagens recuperadas se tornam o contexto que um modelo foundation usa para gerar uma resposta. A AWS destaca os seguintes controles para aplicar antes de usar este fluxo em produção:

• Amazon Bedrock Guardrails: Anexe um guardrail às suas requisições de recuperação agêntica ou RetrieveAndGenerate para aplicar filtros de conteúdo, tópicos negados, filtros de palavras e filtros de informações sensíveis.
• Verificações de grounding contextual: Ative a verificação de grounding contextual do Guardrails para pontuar cada resposta quanto ao grounding contra as passagens recuperadas e à relevância para a consulta.
• Trate conteúdo rastreado como entrada não confiável: Páginas web preparadas se tornam contexto do modelo, então texto em uma página pública pode tentar injeção de prompt via recuperação. Restrinja as URLs semente a sites confiáveis.
• Citações e revisão humana: Retorne citações com cada resposta gerada para que os usuários possam verificar afirmações contra a página-fonte.

Considerações de segurança e conformidade

• Use alvos de crawl públicos confiáveis: Configure apenas sites públicos autorizados. Não use este exemplo para rastrear endpoints privados ou internos.
• Respeite diretivas de crawl: O fluxo ativa a verificação de robots.txt do Crawl4AI por padrão, consistente com a Política de Uso Aceitável da AWS.
• Limitação de taxa: Configure atrasos entre requisições para evitar sobrecarregar os sites de origem.
• Criptografia em repouso: A stack cria uma chave AWS KMS gerenciada pelo cliente com rotação automática e criptografa seus log groups do CloudWatch com ela.
• IAM de menor privilégio: A stack CDK concede à role da tarefa Fargate apenas s3:PutObject no prefixo do bucket configurado, bedrock:StartIngestionJob e bedrock:GetIngestionJob na knowledge base alvo, além de ssm:GetParameter para seu parâmetro de configuração.
• Segurança do pipeline de ingestão: Veja Protegendo o pipeline de ingestão RAG: Mecanismos de filtragem para padrões de filtragem e validação.

Limpeza de recursos

Para evitar cobranças contínuas, execute cdk destroy no diretório deploy/ do repositório, na mesma região e com os mesmos quatro valores -c obrigatórios usados no cdk deploy. Isso remove a regra do EventBridge, cluster ECS, task definition, log groups, roles IAM, parâmetro do Parameter Store e security groups. A chave AWS KMS é agendada para exclusão após 30 dias. Não são excluídos: a VPC importada, a knowledge base, o bucket S3 ou os objetos carregados pelo fluxo.

Para remover o conteúdo web ingerido, delete os objetos preparados sob s3://<bucket>/<prefix> e sincronize a fonte de dados novamente.

Conclusão

Este artigo da AWS demonstra como estender o Amazon Bedrock Knowledge Bases para conteúdo web público autorizado que precisa de preparação antes da ingestão. Uma tarefa Fargate agendada usa o Crawl4AI para crawl delimitado, prepara Markdown com sidecars page.md.metadata.json, faz upload para uma fonte de dados Amazon S3 e inicia a ingestão. A knowledge base então cuida de parsing, chunking, embeddings, indexação, recuperação e respostas fundamentadas com citações.

A recomendação é começar pelo Amazon Bedrock Web Crawler em uma knowledge base gerenciada para a maioria dos sites públicos. O caminho via Crawl4AI é indicado quando se precisa de controle sobre qual parte de cada página é indexada ou quais metadados acompanham o documento. Para começar, faça o deploy do fluxo Fargate agendado a partir do repositório sample-crawl4ai-bedrock-knowledge-base e valide a qualidade de recuperação e citações com conteúdo representativo antes de escalar.

Saiba mais

• Construir uma knowledge base gerenciada
• Amazon Bedrock Web Crawler para knowledge bases gerenciadas
• Conector Amazon S3 para knowledge bases gerenciadas
• Usar recuperação agêntica para consultar uma knowledge base
• Crawl4AI no GitHub
• Exemplos de Knowledge Bases no aws-samples/amazon-bedrock-samples

Fonte

Prepare web content for Amazon Bedrock Knowledge Bases with Crawl4AI (https://aws.amazon.com/blogs/machine-learning/prepare-web-content-for-amazon-bedrock-knowledge-bases-with-crawl4ai/)

O problema: substituição de peças críticas em engenharia aeroespacial

Quando uma peça aeroespacial qualificada fica obsoleta ou entra em situação de longo prazo de entrega, um engenheiro pode passar dias cruzando especificações entre fichas técnicas de fornecedores, Documentos de Controle de Interface (ICD, na sigla em inglês) e registros de qualificação — tudo isso antes de redigir uma justificativa formal para revisão. Uma substituição incorreta em um componente crítico de voo pode causar falha de missão, mas o rastro de evidências por trás de cada decisão costuma estar espalhado em e-mails e conhecimento institucional não documentado.

Um post anterior da AWS, Manufacturing intelligence with Amazon Nova Multimodal Embeddings, mostrou como o modelo recupera respostas “presas” dentro de diagramas de engenharia, gráficos térmicos e tabelas de fichas técnicas que pipelines puramente textuais não conseguem acessar. O novo post avança sobre esse trabalho e coloca essas capacidades dentro de um sistema multi-agente que monta a evidência de substituição — da recuperação até um rascunho de avaliação.

Visão geral da solução

A AWS demonstra como construir um assistente de engenharia multi-agente que reduz o cruzamento manual de informações na avaliação de substituição de peças, usando Amazon Bedrock AgentCore, Amazon Nova Multimodal Embeddings e o Strands Agents SDK de código aberto.

A solução é construída em torno de uma regra de design central: o engenheiro toma todas as decisões, e o sistema monta as evidências para ele. Essa regra determina onde se usam Modelos de Linguagem de Grande Escala (LLMs) e onde se usa código determinístico. Três pilares definem a arquitetura:

• Avaliação determinística de especificações — Código Python com regras de tolerância pontua cada peça candidata em relação à peça de referência e aos requisitos declarados pelo engenheiro. Como as mesmas entradas produzem consistentemente os mesmos veredictos, os resultados podem ser incluídos em uma revisão de engenharia formal.
• Orquestração multi-agente — Um planejador leve roteia cada consulta para um ou mais dos três agentes especialistas (Catálogo, Avaliação, Conhecimento), e um supervisor sintetiza os resultados apenas quando mais de um especialista contribuiu.
• Decisão humana no ciclo — O sistema elabora memorandos de justificativa e Avaliações de Impacto de Integração (IIA) para revisão de engenharia, mas não recomenda nem aprova uma substituição. Cada avaliação também gera uma entrada de trilha de auditoria alinhada com as seções 8.4 e 8.5.6 da norma AS9100.

As requisições de chat do engenheiro fluem para um grafo multi-agente hospedado no AgentCore Runtime: um planejador (Claude Haiku 5.5) produz um plano de roteamento, especialistas (Claude Sonnet 5.5) executam suas ferramentas, e um supervisor (Claude Opus 5.5) sintetiza os resultados quando mais de um especialista é acionado. Os especialistas recuperam informações de uma base de conhecimento gerenciada criada com Amazon Bedrock Managed Knowledge Bases usando Amazon Nova Multimodal Embeddings, roteada por um AgentCore Gateway.

Estrutura do corpus de peças

O conjunto de dados de exemplo é composto por sete rodas de reação de um fabricante fictício (AnyCompany), cobrindo de 0,003 a 5,0 Nms de armazenamento de momento. Cada peça é uma pasta que combina dados estruturados com os documentos de origem que um engenheiro realmente lê — e essa mistura é o que torna o corpus multimodal.

O arquivo specs.json contém os campos legíveis por máquina que alimentam a pontuação determinística, enquanto o ICD, a foto do produto e a página do datasheet carregam detalhes visuais e narrativos que os campos estruturados não capturam. O Amazon Nova Multimodal Embeddings incorpora ambos no mesmo espaço vetorial que o texto, permitindo que uma consulta corresponda a um valor de especificação, um parágrafo ou um gráfico.

data/synthetic-parts-data/rw_rl_0060/
├── specs.json # structured specs + lifecycle fields
├── description.txt # flat text for text retrieval
├── AC-ICD-00068-RW3-0.06-Interface-Control-Document-v2.2.pdf
├── datasheet_page.png # rendered datasheet page
├── datasheet_chart.png # cropped chart region (image-as-query index)
└── photo.png # product image (visual similarity + chart matching)

Agentes especialistas com ferramentas delimitadas

Cada especialista é um agente Strands com um prompt restrito e apenas as ferramentas de que precisa. Delimitar as ferramentas por especialista mantém o comportamento previsível: o especialista de Conhecimento não tem acesso às ferramentas de descoberta de catálogo, e o especialista de Catálogo não tem acesso às ferramentas de avaliação. Os três especialistas são:

• Catálogo — Descobre peças por busca na base de conhecimento e filtragem de especificações (kb_search, filter_parts_by_spec, get_part_specs, get_substitution_requirements).
• Avaliação — Pontua candidatos deterministicamente e compara peças visualmente (score_substitution_fit, compare_parts, visual_similarity_score, check_qualification_status, generate_substitution_memo).
• Conhecimento — Responde perguntas de fichas técnicas e ICDs, verifica status de fim de vida em tempo real e recupera conteúdo visual (get_part_specs, web_search_eol, retrieve_visual_content).

Modelo pequeno para roteamento, modelo grande para síntese

Roteamento é uma tarefa de classificação sem chamadas de ferramentas, então não precisa de um modelo de raciocínio pesado. Um planejador baseado em Haiku retorna um plano de roteamento numerado em alguns segundos. O supervisor Opus só é acionado quando dois ou mais especialistas contribuíram, porque sintetizar a resposta já completa de um único especialista adiciona cerca de 8 segundos de latência sem ganho de qualidade.

# Step 1: Planner (fast model) plans the routing (may be multi-step).
plan_response = planner(planning_prompt)
ordered_specialists = _parse_specialist_plan(str(plan_response))

# Step 2: Execute specialists in sequence, passing context forward
accumulated_context = ""
for spec_name in ordered_specialists:
    specialist = specialists[spec_name]
    specialist_response = specialist(spec_prompt)
    accumulated_context += f"\n[{spec_name.upper()}]: {specialist_response}\n"

# Step 3: Synthesize only when 2+ specialists ran.
if len(ordered_specialists) == 1:
    final_text = steps[0]["response"]
else:
    final_text = str(supervisor(synthesis_prompt))

Pontuação determinística de especificações

A avaliação de adequação de especificação roda como código Python comum contra um esquema de requisitos escrito à mão. O esquema define as especificações críticas e as regras de tolerância para cada categoria de componente, e a ferramenta score_substitution_fit compara cada especificação, conta aprovações e sinalizações, e expõe riscos de ciclo de vida. Como o veredicto precisa ser reproduzível para um pacote de revisão de engenharia, nenhum LLM está envolvido nessa etapa. A ferramenta retorna um veredicto estruturado com um aviso explícito de que os resultados são apenas evidências — a decisão é sempre do engenheiro.

Similaridade visual com Amazon Nova Multimodal Embeddings

O formato físico importa quando uma peça substituta precisa caber em um suporte existente. A ferramenta visual_similarity_score incorpora as fotos de ambas as peças com o Nova Multimodal Embeddings e calcula a similaridade por cosseno, depois pede ao Claude para descrever as diferenças físicas observáveis específicas.

def embed_image(image_bytes):
    """Embed one image with Nova MME (IMAGE_RETRIEVAL) -> 1024-d vector."""
    b64 = base64.b64encode(image_bytes).decode('utf-8')
    fmt = 'png' if image_bytes[:8] == b'\x89PNG\r\n\x1a\n' else 'jpeg'
    body = {
        'taskType': 'SINGLE_EMBEDDING',
        'singleEmbeddingParams': {
            'embeddingPurpose': 'IMAGE_RETRIEVAL',
            'embeddingDimension': 1024,
            'image': {'detailLevel': 'STANDARD_IMAGE', 'format': fmt, 'source': {'bytes': b64}},
        },
    }
    resp = bedrock.invoke_model(
        modelId='amazon.nova-2-multimodal-embeddings-v1:0',
        body=json.dumps(body),
        accept='application/json',
        contentType='application/json',
    )
    result = json.loads(resp['body'].read())
    return np.array(result['embeddings'][0]['embedding'])

# cosine similarity of the two photo embeddings
emb_a, emb_b = embed_image(photo_a_bytes), embed_image(photo_b_bytes)
similarity = float(np.dot(emb_a, emb_b) / (np.linalg.norm(emb_a) * np.linalg.norm(emb_b)))

A similaridade de embedding retorna cerca de 0,84 para duas rodas da mesma família de produtos e 0,40 para rodas de classes diferentes. A análise de visão do Claude então explica o que impulsiona a diferença — por exemplo, notando que um alojamento tem aproximadamente o dobro do diâmetro do outro e possui um padrão de montagem de seis furos onde o outro tem quatro.

Dois caminhos de recuperação: texto e imagem como consulta

Consultas de texto e documentos passam pela base de conhecimento gerenciada com suporte do Nova Multimodal Embeddings, roteada pelo AgentCore Gateway. Consultas por imagem (enviar um gráfico ou foto para encontrar conteúdo correspondente) usam um índice nativo do Amazon S3 Vectors chamado diretamente do agente, pois a API de recuperação da base de conhecimento gerenciada não aceita imagem como entrada.

A AWS destaca três lições práticas aprendidas durante a construção dos caminhos de recuperação:

• Recortar os gráficos antes de indexá-los — Páginas inteiras de datasheet são entradas ruins para o índice, pois cerca de 90% de uma página (cabeçalho, tabela de especificações, rodapé) é padrão repetido em todas as peças. Nos testes, a correspondência por upload de gráfico foi de 3 em 7 peças corretas com indexação de página inteira para 7 em 7 com recortes de faixas de gráfico.
• Filtrar resultados quando o engenheiro nomeia uma peça — A similaridade texto-para-imagem sozinha não retorna de forma confiável o gráfico da peça certa, pois uma imagem de curva de torque não contém nome de peça visível. Quando o engenheiro nomeia uma peça específica, a ferramenta mantém apenas resultados do conteúdo indexado daquela peça.
• Registrar cada fallback no caminho de imagem — O caminho de imagem retorna None em erros e recai para recuperação textual. Isso significa que uma permissão s3vectors:QueryVectors ausente na função de execução do runtime do AgentCore não gera um erro — a consulta por imagem simplesmente para de funcionar silenciosamente. A ferramenta agora registra um aviso explícito de falha sempre que esse caminho recai.

Documentos formais com cadeia fixa de especialistas

O chat usa roteamento dinâmico porque os especialistas certos para uma pergunta livre não podem ser conhecidos de antemão. A Avaliação de Impacto de Integração (IIA) funciona de forma diferente: quando um engenheiro solicita uma avaliação de impacto para um par de referência e candidato, a sequência necessária já é conhecida, então o serviço compõe as mesmas funções de fábrica de especialistas em uma ordem fixa com um prompt de síntese específico.

# 1. Knowledge Specialist --- ICD/datasheet interface detail for both parts
knowledge_text = str(knowledge(knowledge_prompt))

# 2. Evaluation Specialist --- structured field delta + qualification check
evaluation_text = str(evaluation(evaluation_prompt))

# Deterministic structured delta for exact summary stats
comparison = compare_parts(reference_id, candidate_id)

# 3. Supervisor --- synthesize into the six-section IIA document
markdown = str(supervisor(synthesis_prompt))

Dados de ciclo de vida em tempo real via AgentCore Gateway

Dados de catálogo ficam desatualizados, então a ferramenta web_search_eol do especialista de Conhecimento verifica avisos atuais de fim de vida, anúncios de fornecedores e prazos de entrega por meio de um AgentCore Gateway com o conector de Busca na Web. O Gateway expõe o conector como um endpoint governado pelo Protocolo de Contexto de Modelo (MCP). Como o Gateway também lida com recuperação da base de conhecimento gerenciada, é possível anexar políticas e observabilidade tanto ao acesso a dados externos quanto internos em um único lugar.

Deploy no AgentCore Runtime

Para produção, o agente é empacotado como um contêiner ARM64, enviado para o Registro de Contêiner Elástico da Amazon (Amazon ECR) e o AgentCore Runtime o hospeda de forma serverless com isolamento de sessão e escalonamento automático. O Notebook 03 no repositório GitHub detalha esse deploy como receita de referência.

export TAG=mei-$(date +%Y%m%d-%H%M%S)
export ACCOUNT=
export ECR=${ACCOUNT}.dkr.ecr.us-east-1.amazonaws.com/mfg-engineering-intelligence

# Build the container for ARM64 (required by AgentCore Runtime)
docker buildx build --platform linux/arm64 -f agentcore/Dockerfile \
  -t mfg-engineering-intelligence:${TAG} --load .

# Push the immutable tag to Amazon ECR
aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin ${ACCOUNT}.dkr.ecr.us-east-1.amazonaws.com
docker tag mfg-engineering-intelligence:${TAG} ${ECR}:${TAG}
docker push ${ECR}:${TAG}

Um ponto importante: sempre use tags imutáveis para as imagens. Um runtime que já resolveu o digest por trás de uma tag :latest em movimento continua servindo a imagem antiga depois que uma nova é enviada. Mudanças em prompts, roteador e ferramentas exigem uma nova imagem e uma nova versão do runtime para entrar em vigor.

O Amazon Nova Multimodal Embeddings agora está disponível no AWS GovCloud (EUA), o que é relevante para programas aeroespaciais e de defesa sujeitos a requisitos de residência de dados, ITAR e FedRAMP. Verifique a disponibilidade de serviços AWS por região antes de planejar um deploy.

Avaliando o assistente com AgentCore Evaluations

A AWS mede a qualidade de duas formas: pontuação online contínua pelo Amazon Bedrock AgentCore Evaluations, disponível de forma geral desde março de 2026, e validação offline contra conjuntos de consultas curados. O serviço lê os rastreamentos OpenTelemetry que os agentes Strands já emitem, então um agente instrumentado não precisa de alterações na aplicação para ser avaliado.

O conjunto de consultas curado tem 36 consultas em seis categorias: descoberta de catálogo (8), recuperação de Conhecimento e ICD (8), cadeias multi-especialistas (6), avaliação determinística (5), recuperação texto-para-visual (5) e recusas de segurança com humano no ciclo (4) — que verificam se o agente se recusa a recomendar ou aprovar.

Os resultados de um snapshot do conjunto de dados sintético mostram:

• Taxa de Sucesso de Objetivo (sessão): 0,892
• Correção (trace): 0,968
• Utilidade (trace): 0,956
• Fidelidade (trace): 0,981
• Relevância da Resposta (trace): 0,968
• Precisão de Seleção de Ferramenta (chamada de ferramenta): 0,861
• Precisão de Parâmetros de Ferramenta (chamada de ferramenta): 0,980

Todas as métricas de qualidade em nível de trace ficaram em 0,95 ou acima. A Taxa de Sucesso de Objetivo é menor (0,892) porque o conjunto de consultas inclui prompts de segurança que pedem ao agente para recomendar ou aprovar uma substituição — o agente corretamente se recusa, mas o avaliador pontua uma recusa correta como um objetivo não atingido. Esse é o comportamento esperado em um sistema com humano no ciclo.

Adaptando o padrão para outros catálogos

O código é um padrão reutilizável que funciona para outras categorias de peças além de rodas de reação. Trocar de domínio requer apenas três mudanças: substituir os dados das peças (um specs.json, descrição, ICD, página de datasheet e foto por peça), editar o esquema de requisitos para definir as especificações críticas e regras de tolerância da sua categoria, e apontar a base de conhecimento para o seu corpus no S3. Os agentes, ferramentas e motor de pontuação permanecem inalterados.

Limpeza de recursos

Para evitar cobranças contínuas, a AWS recomenda excluir os recursos criados:

• Exclua o agente de runtime do AgentCore e seu repositório Amazon ECR.
• Exclua o AgentCore Gateway e seus alvos de Busca na Web e base de conhecimento.
• Exclua a configuração de avaliação online e os alarmes do CloudWatch criados.
• Exclua a base de conhecimento gerenciada e o índice S3 Vectors.
• Exclua o bucket S3 que contém o corpus de peças.

Conclusão

A AWS demonstra com esse artigo como construir um assistente de engenharia multi-agente que substitui a pesquisa manual de substituição de peças por montagem automatizada de evidências. A arquitetura combina o Amazon Nova Multimodal Embeddings — que lida com pontuação de similaridade visual e recuperação de gráficos que sistemas puramente textuais não conseguem — com o Amazon Bedrock AgentCore, que fornece o andaime de produção: hospedagem de runtime, recuperação e busca na web governadas pelo Gateway, e avaliações de qualidade.

Três escolhas de design são fundamentais: código determinístico produz cada veredicto de aprovação/reprovação; cada tarefa roda no menor dos três níveis de modelo que a executa bem; e apenas o engenheiro pode aprovar uma substituição.

Para começar, clone o repositório GitHub, execute os notebooks com sua própria conta AWS e substitua pelo seu catálogo de peças e esquema de requisitos. Para se aprofundar nas bases de recuperação, leia Manufacturing intelligence with Amazon Nova Multimodal Embeddings e A practical guide to Amazon Nova Multimodal Embeddings. Para padrões de agentes em produção, consulte a documentação do Amazon Bedrock AgentCore e o Strands Agents SDK.

Fonte

Agentic engineering intelligence with Amazon Nova Multimodal Embeddings and Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/agentic-engineering-intelligence-with-amazon-nova-multimodal-embeddings-and-amazon-bedrock-agentcore/)

Por que controlar custos de IA generativa é diferente

Comparar preços por token entre modelos e pedir para os times encurtarem prompts são os primeiros passos que quase todo mundo dá. Mas essas ações não respondem às perguntas que realmente importam quando o uso escala: qual time gerou esse gasto, em qual workload, e esse valor estava dentro do orçamento aprovado?

Workloads agênticos tornam essa questão ainda mais urgente. Um assistente conversacional típico faz uma invocação de modelo por turno de usuário. Já um fluxo agêntico — como um assistente de codificação que planeja uma mudança, lê arquivos, chama ferramentas e itera — pode gerar dezenas de invocações por tarefa, cada uma carregando um contexto maior. O consumo de tokens cresce com o grau de autonomia do workflow, não com o número de interações do usuário.

Por isso, a AWS estruturou um modelo operacional em cinco estágios para gerenciar custos do Amazon Bedrock. Use a Calculadora de Preços da AWS e a página de preços do Amazon Bedrock para modelar as taxas — mas meça o que seus workloads realmente consomem antes de tomar qualquer decisão.

O modelo operacional em cinco estágios

Os cinco estágios formam um loop contínuo. Cada um depende dos anteriores — times que pulam direto para otimização sem ter atribuição e observabilidade estão apenas chutando.

• Atribuir: todo gasto no Amazon Bedrock é associado a uma identidade, time e aplicação no pipeline de faturamento. Responsabilidade do time de FinOps.
• Observar: toda requisição é registrada com metadados suficientes para explicar o que gerou o gasto. Responsabilidade da engenharia de plataforma.
• Enforçar: orçamentos têm dentes — alertas no mínimo, bloqueios onde o risco exige. Responsabilidade da engenharia de plataforma.
• Otimizar: os padrões da plataforma (roteamento de modelo, cache, limites de tokens) eliminam desperdício de forma centralizada. Responsabilidade da engenharia de plataforma.
• Operar: um scorecard e uma cadência de revisão transformam dados em decisões. Responsabilidade conjunta de FinOps e plataforma.

Estágio 1: Atribuir cada gasto a um responsável

Tudo o que vem depois — chargeback, orçamentos, enforcement, detecção de anomalias — depende deste estágio. A base é a atribuição granular de custos do Amazon Bedrock: o serviço atribui automaticamente os custos de inferência ao principal do Gerenciamento de Identidade e Acesso da AWS (IAM) que fez a chamada, sem nenhum recurso adicional para gerenciar. O ARN do chamador aparece na coluna line_item_iam_principal do Relatório de Custo e Uso da AWS (CUR) 2.0.

A configuração envolve quatro passos: ativar dados de principal IAM na exportação CUR 2.0; marcar os principais IAM com dimensões de negócio como time, aplicação e centro de custo; para acesso federado, configurar o provedor de identidade para passar session names e tags via claims OIDC ou SAML; e ativar essas tags como tags de alocação de custo no AWS Billing. As tags aparecem no AWS Cost Explorer dentro de 24 a 48 horas após a ativação.

O problema do role compartilhado

O padrão mais crítico de se resolver é o shared-role problem: um gateway de LLM que chama o Amazon Bedrock por meio de uma única role IAM atribui todos os gastos àquela role, eliminando completamente a visibilidade por usuário.

A solução é o gerenciamento de sessão por usuário. O gateway assume a role de invocação do Bedrock uma vez por usuário, passando a identidade do usuário como o nome da sessão e seus atributos como session tags, e armazena essas credenciais em cache por até uma hora (uma chamada ao Serviço de Token de Segurança da AWS (STS) por usuário por hora, não por requisição). O resultado são entradas line_item_iam_principal como assumed-role/BedrockRuntimeRole/gw-alex, cada uma carregando as tags do usuário correspondente.

import boto3

sts = boto3.client("sts")

# One call per user; cache the returned credentials up to 1 hour
response = sts.assume_role(
    RoleArn="arn:aws:iam::123456789012:role/BedrockRuntimeRole",
    RoleSessionName="gw-alex",  # the user, not the gateway
    Tags=[
        {"Key": "team",        "Value": "sales-ai"},
        {"Key": "application", "Value": "renewal-agent"},
        {"Key": "costCenter",  "Value": "CC-2041"}
    ]
)

Outros mecanismos de atribuição

O Amazon Bedrock oferece dois mecanismos adicionais. Perfis de inferência de aplicação são recursos pré-criados por aplicação no endpoint bedrock-runtime que carregam tags de alocação de custo — ideais para times com um conjunto pequeno e estável de aplicações e modelos. Projetos e workspaces atendem ao endpoint bedrock-mantle (Responses API, Chat Completions API) e são indicados para workloads OpenAI-compatíveis; saiba mais em como gerenciar custos de IA com Amazon Bedrock Projects.

Para workloads no bedrock-runtime, a recomendação principal é a atribuição via principal IAM com session tags: ela escala com o sistema de identidade existente, não exige recursos pré-criados e cobre todos os modelos e operações de API.

Estágio 2: Tornar cada requisição observável

O CUR diz quem gastou. Os logs de invocação dizem o que aconteceu. O Amazon Bedrock suporta logging de invocação de modelo de dados de requisição, resposta e metadados para o Amazon CloudWatch Logs, Amazon Simple Storage Service (S3) ou ambos. Use o CloudWatch para consultas operacionais rápidas e S3 com Amazon Athena para acesso de longo prazo em Inteligência de Negócios (BI).

Trate o logging como infraestrutura, não como um toggle manual: provisione o grupo de logs ou bucket via código, defina políticas de retenção e criptografia, e valide a entrega durante o setup do ambiente. O logging também fecha a lacuna de latência: a atribuição via CUR tem um atraso de cerca de 24 horas, mas CloudWatch com OpenTelemetry pode alimentar dashboards quase em tempo real mostrando gasto por desenvolvedor em minutos — o post Analisando uso do Claude Code com CloudWatch e OpenTelemetry demonstra isso de ponta a ponta.

Metadados de requisição para atribuição por workload

Logs brutos respondem perguntas de nível de identidade. Para responder perguntas de nível de workload (qual feature, workflow ou tenant gerou os tokens), é preciso carimbar metadados de requisição em cada chamada. O Amazon Bedrock captura esses metadados nos logs de invocação para análise posterior:

response = client.converse(
    modelId="us.anthropic.claude-sonnet-5-5",
    messages=[...],
    requestMetadata={
        "application": "renewal-copilot",
        "workflow":    "renewal-risk-summary",
        "tenant":      "enterprise-sales",
        "agent":       "renewal-agent"
    }
)

O Amazon Bedrock não impõe metadados de requisição, e os times tendem a usar schemas inconsistentes rapidamente quando cada aplicação faz do seu jeito. O time de plataforma deve injetar metadados obrigatórios de forma centralizada em um wrapper de SDK compartilhado ou gateway, normalizar o conjunto de chaves e tratar a cobertura de metadados como uma métrica de saúde da plataforma.

Com logs e metadados configurados, o CloudWatch Logs Insights responde às perguntas recorrentes. Para identificar quem consome mais tokens, a consulta abaixo agrupa por chamador e modelo:

fields @timestamp, identity.arn as caller, modelId,
       input.inputTokenCount as inTokens,
       output.outputTokenCount as outTokens
| stats sum(inTokens + outTokens) as totalTokens,
        count(*) as calls
  by caller, modelId
| sort totalTokens desc
| limit 25

A mesma consulta agrupada por requestMetadata.application e requestMetadata.workflow em vez de caller produz o leaderboard por workload — a visão que os times de produto e engenharia vão pedir ao FinOps assim que as conversas de chargeback começarem.

Estágio 3: Enforçar orçamentos

Com atribuição e observabilidade estabelecidas, o enforcement vira uma escolha arquitetural. Existem três tiers viáveis, e a escolha certa depende da velocidade de gasto, da tolerância a risco de overspend e de como as ferramentas se conectam ao Amazon Bedrock.

Tier 1: Monitorar e alertar (sem bloqueio)

O Amazon Bedrock escreve a identidade do principal automaticamente no pipeline de faturamento. O AWS Budgets fica por cima para alertas de threshold, com os dashboards do OpenTelemetry do Estágio 2 fechando a lacuna de 24 horas do CUR. Nada para implantar, sem latência adicional nas chamadas de inferência. Nada pode bloquear o gasto em tempo real — o problema é visto depois que acontece. Indicado para adoção inicial. Dois guias práticos cobrem essa abordagem: Limitando o uso do Bedrock e controlando custos e Deep dive sobre gerenciamento do Bedrock no Claude Code com AWS Budgets e Tags.

Tier 2: Enforcement via tag IAM (bloqueio por violação)

Uma função AWS Lambda agrega contadores de tokens e gastos por usuário no Amazon DynamoDB a partir dos dados do log de invocação. Quando um usuário ultrapassa o threshold, a função adiciona a identidade a uma política de negação IAM (negando bedrock:*) até um reset mensal ou override de administrador. O enforcement é assíncrono — um bloqueio entra em vigor segundos a minutos após a chamada violadora. O Guidance for Claude Code with Amazon Bedrock na AWS Solutions Library oferece uma variante implantável. Indicado para times que precisam de enforcement real, tolerando essa latência, e querem manter software de terceiros fora do caminho de dados.

Tier 3: Enforcement via gateway (bloqueio síncrono)

Um gateway no caminho de dados de inferência enforça orçamentos de forma síncrona, retornando HTTP 429 no momento em que um usuário ou time ultrapassa o limite. Oferece bloqueio em sub-segundo, allowlists de modelos por usuário, limites de taxa de tokens e regras de roteamento enforçadas centralmente. O trade-off: um componente no caminho de dados que precisa ser implantado, escalado e revisado do ponto de vista de segurança.

Para frotas de Claude Code e Claude Desktop, o Claude apps gateway for AWS é a recomendação oficial. Ele roda como um contêiner stateless único com PostgreSQL como backend, oferecendo identidade OIDC, política gerenciada centralmente, telemetria OpenTelemetry, roteamento multi-Region no Amazon Bedrock e limites de gasto por usuário, grupo e organização. Para workloads com múltiplos modelos e múltiplos provedores, gateways de propósito geral são a escolha certa: LiteLLM via arquitetura de referência no Amazon ECS com AWS Fargate, ou a alternativa serverless descrita em Build a proactive AI cost management system for Amazon Bedrock, Part 2.

A maioria das organizações deve adotar os tiers de forma progressiva: comece observando no Tier 1, depois avance. O Well-Architected Agentic AI Lens já codifica a governança de custos de agentes como uma preocupação arquitetural de primeira classe.

Estágio 4: Otimizar os padrões da plataforma

A maior parte do desperdício no Amazon Bedrock não é descuido individual — são padrões de plataforma que ninguém configurou. As duas alavancas de maior impacto são ambas controladas pela plataforma.

Roteamento de modelos

Nem toda tarefa precisa de um modelo frontier. Completions rotineiras (boilerplate, sugestões de linting, pequenos refactors) podem rodar em modelos menores e mais baratos, com qualidade reservada para raciocínio complexo — usando roteamento inteligente de prompts dentro de uma família de modelos ou regras de roteamento no gateway. Veja o walkthrough completo em Reduza custos e latência com Amazon Bedrock Intelligent Prompt Routing e prompt caching. Para frotas de codificação agêntica, onde boilerplate domina o volume de chamadas, mais da metade das chamadas indo para modelos mais baratos é uma meta alcançável.

Cache de prompts

O cache de prompts recompensa prefixos estáveis e repetidos. Conforme a precificação do Amazon Bedrock publicada em outubro de 2026 para modelos Anthropic Claude na região US East (N. Virginia): um cache write é cobrado a 1,25x a taxa base de entrada com o TTL de 5 minutos (2x com o TTL de 1 hora). Um cache read é cobrado a 0,1x a taxa base no Claude Sonnet 4.6 e Claude Haiku 4.5, e a 0,05x no Claude Sonnet 5.5 e Claude Opus 5.5. Verifique a página de preços para seu modelo e região, pois esses multiplicadores variam.

A matemática de break-even é mais favorável do que os times costumam imaginar. Com o TTL de 5 minutos, uma única reutilização já paga pelo write, e dez chamadas contra um prefixo estável custam cerca de um quinto do preço sem cache. O único caso perdedor é writes que nunca são relidos. Por isso, o dashboard da plataforma deve rastrear o volume de cache reads contra cache writes por workflow. Uma taxa de read baixa significa que o prefixo não é realmente estável — geralmente há um timestamp ou session ID embutido antes do ponto de cache.

Candidatos para cache surgem diretamente dos logs de invocação com uma consulta que filtra workflows com mais de 50 chamadas e média de tokens de entrada acima de 2.000:

fields requestMetadata.workflow as workflow, modelId,
       input.inputTokenCount as inTokens
| stats count(*) as calls,
        avg(inTokens) as avgInputTokens,
        sum(inTokens) as totalInputTokens
  by workflow, modelId
| filter calls > 50 and avgInputTokens > 2000
| sort totalInputTokens desc
| limit 25

Estágio 5: Operar o loop

Os quatro estágios anteriores produzem dados. Este os transforma em decisões. O time de plataforma mantém um dashboard de saúde com quatro sinais:

• Mix de modelos: quais modelos são chamados e com que frequência — medida direta da disciplina de roteamento.
• Taxa de requisições com falha: erros, throttles e timeouts. Cada retry adiciona latência, e um timeout no lado cliente de uma requisição que ainda completa no serviço pode ser cobrado duas vezes.
• Efetividade do cache: a proporção reads versus writes do Estágio 4.
• Cobertura de metadados: o percentual de chamadas em produção com metadados completos. Cada chamada sem cobertura é um ponto cego de atribuição que degrada silenciosamente todos os outros números.

Quando um sinal deriva, a remediação é uma mudança de política (regras de roteamento, limites de tokens, enforcement de metadados) — não um e-mail pedindo para os times serem mais cuidadosos.

O scorecard de FinOps

Os thresholds abaixo são pontos de partida, não prescrições. Calibre-os com os dados da sua frota antes de adotá-los como política:

• Custo unitário por resultado bem-sucedido: Verde = dentro do orçamento; Amarelo = 1–1,5x o orçamento; Vermelho = acima de 1,5x.
• Custo diário por desenvolvedor: Verde = abaixo de US$ 100; Amarelo = US$ 100–300; Vermelho = acima de US$ 300.
• % de chamadas em modelos de menor custo: Verde = acima de 50%; Amarelo = 30–50%; Vermelho = abaixo de 30%.
• Taxa de hit de cache read: Verde = acima de 60%; Amarelo = 30–60%; Vermelho = abaixo de 30%.

Revise esse scorecard em cadência regular — semanal para frotas de alta velocidade, quinzenal para as demais — e trate-o como a superfície de decisão conjunta entre FinOps e plataforma.

Conclusão

O modelo operacional em cinco estágios leva o gasto com Amazon Bedrock de descontrolado a totalmente governado: atribuir cada gasto a um responsável via tags de principal IAM e session tags no CUR 2.0; observar cada requisição via logging de invocação de modelo e metadados carimbados; enforçar orçamentos no tier que corresponde ao seu risco; otimizar os padrões da plataforma com roteamento inteligente de prompts e cache; e operar um scorecard e cadência de revisão que transformam telemetria em decisões de política.

Vale notar a primeira linha do scorecard: custo por resultado bem-sucedido, não custo por chamada. Tudo aqui torna o gasto com Amazon Bedrock visível, atribuível, limitado e eficiente — mas um workflow pode ser perfeitamente eficiente e ainda assim não valer a pena rodar. Decidir isso exige medir o agente contra o processo humano que ele substituiu, o que é uma disciplina de produto e analytics, não de FinOps.

Para começar, implante a arquitetura de referência Guidance for Claude Code with Amazon Bedrock para os Estágios 1 a 3, e depois use a documentação de melhores práticas de atribuição de custos para configurar sua estratégia de tagging.

Fonte

Managing Amazon Bedrock costs end to end: A playbook for FinOps and platform teams (https://aws.amazon.com/blogs/machine-learning/managing-amazon-bedrock-costs-end-to-end-a-playbook-for-finops-and-platform-teams/)

O que foi anunciado

A AWS expandiu as capacidades do Amazon Bedrock para o ambiente AWS GovCloud (EUA), trazendo duas novidades relevantes: suporte aos modelos OpenAI GPT-5.6 — nas variantes Terra e Luna — no endpoint bedrock-runtime, e a chegada da Inferência Entre Regiões (Cross-Region Inference) para esse ambiente regulado.

Suporte ampliado a APIs

Com essa atualização, os modelos GPT-5.6 da OpenAI passam a funcionar no bedrock-runtime com suporte a três interfaces de programação:

• Responses API
• Chat Completions API
• Converse API

Um ponto importante destacado pela AWS: por rodar sobre o bedrock-runtime, esses modelos herdam automaticamente os controles já existentes na conta do cliente para outros modelos do Bedrock. Isso significa que o uso aparece no registro de invocações de modelos do Bedrock — entregável ao Amazon S3 ou ao Amazon CloudWatch Logs — e nas métricas do Amazon CloudWatch, cobrindo contagens de invocações, contagens de tokens, latência, throttles e erros. O consumo também é detalhado no AWS Cost Explorer e no Relatório de Custo e Uso (Cost and Usage Report), permitindo atribuir gastos por modelo.

Inferência Entre Regiões no GovCloud

A Inferência Entre Regiões (Cross-Region Inference) é o recurso que distribui automaticamente as requisições de inferência entre as duas regiões do AWS GovCloud (EUA), sem que o cliente precise gerenciar capacidade manualmente em cada uma delas.

O objetivo é entregar maior throughput e redundância, especialmente durante picos de demanda. E tudo isso mantendo a soberania dos dados nos Estados Unidos — requisito crítico para cargas de trabalho governamentais e reguladas.

Disponibilidade

A Inferência Entre Regiões para modelos OpenAI está disponível em todas as regiões da AWS onde os modelos OpenAI no Amazon Bedrock já são oferecidos. Para começar, a AWS recomenda consultar os cartões de modelo (model cards) do GPT-5.6 (Terra e Luna) diretamente no Guia do Usuário do Amazon Bedrock.

Fonte

Amazon Bedrock expands API support and introduces Cross-Region Inferencing for OpenAI models in AWS GovCloud (US) (https://aws.amazon.com/about-aws/whats-new/2026/10/bedrock-openai-runtime-govcloud/)

O problema que os Session Endpoints resolvem

Agentes de código já são capazes de construir aplicações web funcionais — dashboards, páginas de produto, protótipos que times de produto querem testar rapidamente. O gargalo sempre foi o ciclo de revisão: para ver o resultado de uma alteração, era necessário copiar os arquivos gerados e implantá-los em algum ambiente, o que tornava cada iteração lenta e trabalhosa.

A solução ideal é manter a aplicação rodando no mesmo lugar onde o agente a edita, de forma que cada mudança apareça no navegador em segundos. É exatamente isso que os Session Endpoints do AgentCore Runtime entregam.

O que é o Amazon Bedrock AgentCore

O Amazon Bedrock AgentCore é uma plataforma da AWS para construir, conectar e otimizar agentes em escala, com liberdade de escolha de framework e modelo de fundação (FM — Foundation Model). O AgentCore Runtime, uma das capacidades da plataforma, executa cada sessão de agente em sua própria microVM isolada.

Com os Session Endpoints, é possível abrir uma aplicação que está rodando dentro dessa sessão diretamente no navegador. Cada sessão recebe uma URL autenticada que encaminha o método HTTP, o caminho, a query string, o corpo da requisição e conexões WebSocket para as portas que você autorizar.

Como os Session Endpoints funcionam

Seis detalhes definem o comportamento dos Session Endpoints:

• Você escolhe as portas acessíveis. O parâmetro allowedPorts é definido na chamada CreateAgentRuntime: de 1 a 5 entradas, cada uma sendo uma porta única ou um intervalo dentro de 8000–12000, excluindo as portas reservadas da plataforma. Liberar uma porta não inicia um servidor — a aplicação precisa estar ouvindo nela, vinculada a 0.0.0.0.
• A URL chega junto com a sessão. A resposta do InvokeAgentRuntime traz a URL no header X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url, exposto pelos SDKs como sessionEndpointUrl.
• Toda requisição é autenticada. Para runtimes que usam Gerenciamento de Identidade e Acesso da AWS (IAM), cada requisição HTTP, stream HTTP/2 e handshake WebSocket carrega uma assinatura Signature Version 4 (SigV4). O chamador também precisa da permissão bedrock-agentcore:InvokeAgentRuntimeProxy. Para runtimes com um autorizador JSON Web Token (JWT) de entrada, cada requisição carrega um bearer token. Conhecer a URL não garante acesso.
• O hostname seleciona a porta. O cliente sempre conecta na porta 443, e um prefixo no hostname escolhe a porta dentro da sessão. Por exemplo: https://8090--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/index.html
• Suporte a múltiplos protocolos. Requisições HTTP/1.1 e HTTP/2, incluindo server-sent events e gRPC, além de conexões WebSocket, são todas suportadas.
• Escopo de uma única sessão. A URL exige credenciais em cada requisição e dura apenas enquanto a sessão existir. Use-a para construir, testar e revisar o que o agente produz. Para servir uma aplicação aos seus usuários finais, implante-a em um serviço de hospedagem como o AWS Amplify Hosting.

Como um navegador não consegue adicionar uma assinatura SigV4 ou um bearer token por conta própria, o cliente de Session Endpoint do SDK bedrock-agentcore abre um endpoint local na sua máquina. O navegador acessa http://localhost:8088, e esse endpoint local adiciona suas credenciais a cada requisição e handshake WebSocket antes de encaminhá-los.

Session Endpoint vs. Runtime Endpoint

É importante não confundir os dois conceitos. O runtime endpoint já é fornecido pelo AgentCore Runtime e serve para alcançar o agente em si — ele controla qual versão do agente os chamadores vão atingir, permitindo manter desenvolvimento e produção em versões diferentes. Já o Session Endpoint serve para visualizar o que o agente executa dentro da sessão, como uma prévia web. Ele alcança apenas as portas que você autorizou, funciona com qualquer versão que a sessão esteja rodando e para de funcionar quando a sessão encerra.

Visão geral da solução de exemplo

A AWS publicou um exemplo completo com quatro componentes principais:

• Um agente de código rodando na sessão na porta 8080, que edita os arquivos do site com quatro ferramentas: listar, ler, escrever e editar.
• Um servidor de desenvolvimento Vite na porta 8090, que serve o site e envia cada alteração salva ao navegador via hot-reload WebSocket.
• O PreviewApp na sua máquina, que serve a página de preview, envia seus prompts ao InvokeAgentRuntime e abre um endpoint local para a porta 8090.
• A página de preview em si, com o chat à esquerda e o site ao vivo à direita.

O fluxo funciona assim: a página de preview carrega o site do servidor Vite na porta 8090 através do endpoint local e do Session Endpoint. Quando você envia um prompt pelo chat, o PreviewApp o encaminha ao agente via InvokeAgentRuntime. O agente consulta o Claude Haiku 5.5 no Amazon Bedrock para decidir o que alterar, lê e salva os arquivos necessários. O Vite detecta a mudança e envia a atualização pelo WebSocket, de volta pelo Session Endpoint e pelo endpoint local, e o site se atualiza no navegador sem precisar de um refresh.

O exemplo completo, incluindo o notebook que acompanha o walkthrough, está disponível no repositório agentcore-samples no GitHub.

Pré-requisitos para seguir o walkthrough

• Uma conta AWS em uma região onde os Session Endpoints do AgentCore Runtime estejam disponíveis, com credenciais configuradas.
• Permissões para criar uma role de IAM, fazer upload para o Amazon Simple Storage Service (Amazon S3) e criar um runtime, além de bedrock-agentcore:InvokeAgentRuntime e bedrock-agentcore:InvokeAgentRuntimeProxy. Consulte a documentação de permissões IAM para o AgentCore Runtime.
• Python 3.10 ou superior, com bedrock-agentcore 1.25.2 ou superior e boto3 1.43.122 ou superior.
• Git para clonar o repositório e um ambiente Jupyter (JupyterLab ou VS Code com a extensão Jupyter) para executar o notebook.
• Acesso ao Claude Haiku 5.5 no Amazon Bedrock. Consulte a disponibilidade regional dos modelos.
• Node.js 22 ou superior com npm.

O exemplo implanta o agente como um arquivo zip no Amazon S3 usando implantação direta de código para Node.js, sem necessidade de Docker ou de um repositório no Amazon Elastic Container Registry (Amazon ECR). Session Endpoints funcionam com runtimes de microVM, não com o tipo de computação Instances. As URLs são acessíveis via HTTPS público — AWS PrivateLink não é suportado para conexões de entrada.

Implantando o agente e o site

O script de implantação empacota o agente em um único arquivo, adiciona o site e suas dependências para o sistema Linux on Arm64 do runtime, faz upload do zip para o Amazon S3 e cria o runtime. O trecho abaixo de deploy.py mostra as duas configurações centrais: protocolConfiguration define onde o agente escuta o InvokeAgentRuntime, e allowedPorts lista as portas que o Session Endpoint pode alcançar — 8090 para o site e 8081 para a rota de status do agente. A porta 8080 não está na lista porque o InvokeAgentRuntime alcança o agente diretamente, sem passar pelo Session Endpoint.

agentRuntimeArtifact={"codeConfiguration": {
    "code": {"s3": {"bucket": code_bucket(), "prefix": S3_PREFIX}},
    "runtime": "NODE_22",
    "entryPoint": ["app.js"],
}},
protocolConfiguration={"serverProtocol": "HTTP", "port": 8080, "path": "/invocations"},
allowedPorts=[{"port": 8090}, {"port": 8081}],

A configuração do Vite faz o servidor de desenvolvimento ser acessível pelo Session Endpoint: ele escuta em 0.0.0.0 na porta 8090 e não restringe o header Host (server.allowedHosts é true), pois as requisições chegam com um hostname atribuído pelo runtime, não localhost. Como o Session Endpoint autentica cada requisição antes de encaminhá-la ao servidor, o servidor não precisa fazer sua própria verificação de host.

Para implantar o runtime:

git clone https://github.com/awslabs/agentcore-samples.git
cd agentcore-samples/01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints

Em seguida, abra o notebook session_endpoints_preview.ipynb, execute a célula de instalação das dependências Python e depois a célula %run deploy.py. A implantação leva alguns minutos, principalmente aguardando o runtime atingir o status READY.

Abrindo o preview e pedindo alterações

Com o runtime pronto, uma única chamada inicia o preview, abre um endpoint local para a porta 8090 e serve a página de preview em localhost:8087:

from preview_app import PreviewApp
app = PreviewApp().start()
print("Open", app.url)

Internamente, a primeira chamada ao InvokeAgentRuntime retorna a URL do Session Endpoint no header de resposta. O cliente então abre o endpoint local para a porta 8090:

answer = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn,
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": ""}).encode(),
    contentType="application/json",
)
endpoint = client.session_endpoint_client(session_endpoint_url(answer))
local = endpoint.open_local_endpoint(port=8090, local_port=8088).start()

Com a página aberta em http://localhost:8087, você verá o site à direita e um chat à esquerda. Ao pedir uma mudança — por exemplo, “Switch this website to a dark coffee-house color theme” — o agente lê os arquivos necessários, salva os alterados e o Vite empurra a mudança pelo WebSocket. O site atualiza no browser sem refresh.

Você também pode enviar prompts diretamente do Python:

for event in app.ask("Make the Order ahead button green"):
    if "step" in event:
        print(" ", event["step"])
    elif "done" in event:
        print(event["done"]["reply"])

Acessando uma segunda porta na mesma sessão

O site não é o único servidor acessível. O agente serve uma rota /status na porta 8081, que lista cada prompt recebido e os arquivos que ele alterou. O mesmo Session Endpoint alcança essa rota — a única diferença é o argumento de porta:

status = app.endpoint.request("GET", "/status", port=8081)
print("GET /status on port 8081: HTTP", status.status)
for edit in status.json()["edits"]:
    print(" ", edit["prompt"], "->", ", ".join(edit["files"]))

O que o Session Endpoint recusa

Quando o runtime recusa uma requisição, ele responde com um status HTTP, corpo vazio e um código de erro em um header de resposta. A tabela abaixo resume as recusas mais comuns:

• Porta fora do allowedPorts: 403 AccessDenied
• Requisição sem credenciais válidas: 403 AccessDenied ou 401 AuthenticationRequired
• Porta permitida sem servidor ouvindo: 502 PortNotReachable
• URL de sessão que não existe mais: 404 SessionNotFound

Como o acesso à sessão é protegido

O runtime remove seus próprios headers de autenticação antes de encaminhar uma requisição, de forma que o site nunca recebe a assinatura do chamador. As requisições são registradas no AWS CloudTrail como eventos InvokeAgentRuntimeProxy, com a fonte de evento bedrock-agentcore.amazonaws.com. Para mais detalhes, consulte a documentação sobre registro de requisições de Session Endpoint no CloudTrail.

O endpoint local age com suas credenciais, o que limita quem pode usá-lo: ele escuta apenas em 127.0.0.1, responde somente a requisições endereçadas ao seu próprio endereço local e recusa conexões WebSocket abertas por páginas de outras origens. Execute o endpoint local apenas enquanto estiver usando o preview.

Os controles de acesso não separam o site do agente — ambos rodam na mesma sessão. Por isso, conceda à execution role apenas as permissões que o agente realmente precisa. Se o runtime substituir o compute da sessão, conexões abertas se fecham e as edições do agente podem não sobreviver, a menos que a sessão use armazenamento persistente. Consulte a documentação sobre configurações de sistema de arquivos para o AgentCore Runtime se precisar que os arquivos persistam além do compute.

Se outras pessoas puderem enviar prompts ao seu agente de código, considere usar o Amazon Bedrock Guardrails para filtrar prompts e respostas prejudiciais, e revise as alterações do agente antes de publicá-las.

Limpeza dos recursos

Para evitar cobranças contínuas, pare o preview e delete os recursos criados pelo exemplo. O site editado pelo agente vive na sessão e é removido junto com ela. Execute a célula stop no notebook e pressione Enter quando solicitado — isso para a página de preview, o endpoint local e a sessão. Em seguida, execute %run cleanup.py, que deleta o runtime, o código enviado ao S3 e a role IAM.

Conclusão

Os Session Endpoints entregam acesso autenticado às aplicações dentro de uma sessão do AgentCore Runtime diretamente das suas ferramentas, via HTTP/1.1, HTTP/2 e WebSocket, nas portas que você autorizar. O resultado prático é um ciclo de desenvolvimento muito mais ágil: peça uma mudança ao agente de código e veja o resultado no browser em segundos, sem nenhum passo de implantação intermediário.

Para explorar mais, a AWS disponibiliza documentação completa sobre como conectar a sessões de runtime por um Session Endpoint, como configurar a porta e o caminho de invocação do agente, como executar comandos shell em sessões do AgentCore Runtime e como fazer implantação direta de código para Node.js. Para uma visão geral completa do serviço, consulte como hospedar agentes ou ferramentas com o Amazon Bedrock AgentCore Runtime e explore mais exemplos no repositório agentcore-samples no GitHub.

Fonte

Preview web apps live as your coding agent builds them with Amazon Bedrock AgentCore runtime (https://aws.amazon.com/blogs/machine-learning/preview-web-apps-live-as-your-coding-agent-builds-them-with-amazon-bedrock-agentcore-runtime/)