Author: Make.com Service User

O problema que essa arquitetura resolve

Grandes empresas acumulam petabytes de dados em data lakes e lakehouses, mas transformar esse volume em decisões rápidas ainda é um gargalo. O motivo é simples: acessar esses dados exige especialistas em SQL, modelagem de dados e ferramentas de Business Intelligence (BI). Quem está no negócio — analistas, gestores, times de operação — fica dependente da fila técnica para obter respostas.

A AWS publicou uma arquitetura de referência que endereça exatamente esse problema. A proposta combina Amazon SageMaker, Amazon Athena e Amazon Quick para criar um assistente de IA agêntica capaz de responder perguntas sobre dados complexos usando linguagem natural — sem que o usuário precise escrever uma linha de SQL.

Visão geral da arquitetura

A solução foi construída usando o dataset de benchmark TPC-H como base de dados. A escolha é estratégica: o TPC-H representa um modelo de negócio realista com pedidos, clientes e itens de linha, tornando os exemplos reproduzíveis e significativos.

Os principais componentes da arquitetura são:

• Amazon Simple Storage Service (S3) como camada de armazenamento principal
• Amazon SageMaker e AWS Glue para a estrutura do lakehouse e catálogo de metadados
• Amazon Athena para consultas SQL serverless em múltiplos formatos de armazenamento
• Amazon Quick para dashboards, agentes de IA conversacional e bases de conhecimento

O fluxo funciona da seguinte forma: os dados TPC-H são ingeridos e armazenados no S3 em três formatos distintos. O Athena executa consultas sobre esses dados usando o catálogo do AWS Glue como camada de metadados unificada. O Amazon Quick se conecta ao Athena para carregar os dados no SPICE (Motor de Cálculo Super-rápido, Paralelo e em Memória), onde alimenta dashboards interativos e agentes de chat com IA. Em paralelo, um Web Crawler indexa documentação não estruturada do TPC-H em uma Knowledge Base (Base de Conhecimento), que também é disponibilizada ao agente conversacional.

Três formatos de armazenamento no mesmo lakehouse

Um dos pontos mais instrutivos da arquitetura é a demonstração de três abordagens diferentes de armazenamento, todas consultáveis pelo mesmo Athena:

Tabela externa CSV

Utiliza o dataset de clientes do TPC-H diretamente de um bucket público do S3. Com tabelas externas, o Athena consulta os dados no local original sem movê-los — uma abordagem rápida e econômica para explorar dados brutos. O comando de criação no editor de queries do Athena é:

CREATE EXTERNAL TABLE IF NOT EXISTS blog_qs_athena_tpc_h_db_sql.customer_csv (
  C_CUSTKEY INT,
  C_NAME STRING,
  C_ADDRESS STRING,
  C_NATIONKEY INT,
  C_PHONE STRING,
  C_ACCTBAL DOUBLE,
  C_MKTSEGMENT STRING,
  C_COMMENT STRING
)
ROW FORMAT DELIMITED
FIELDS TERMINATED BY '|'
STORED AS TEXTFILE
LOCATION 's3://redshift-downloads/TPC-H/2.18/100GB/customer/'
TBLPROPERTIES ('classification' = 'csv');

Tabela Apache Iceberg (Parquet)

O Apache Iceberg é um formato de tabela aberto que traz transações ACID, time travel e evolução de partições para o data lake — ideal para cargas de trabalho em produção. A arquitetura cria uma tabela Iceberg a partir dos dados de pedidos usando o comando CREATE TABLE AS SELECT (CTAS), particionada por data de pedido:

CREATE TABLE blog_qs_athena_tpc_h_db_sql.orders_iceberg
WITH (
  table_type = 'ICEBERG',
  format = 'PARQUET',
  is_external = false,
  partitioning = ARRAY['o_orderdate'],
  location = 's3://amzn-s3-demo-bucket/tpch_iceberg/orders/')
AS SELECT *
FROM blog_qs_athena_tpc_h_db_sql.orders_csv
WHERE O_ORDERDATE BETWEEN '1998-06-01' AND '1998-12-31';

Amazon S3 Tables

As Amazon S3 Tables são tabelas totalmente gerenciadas com suporte nativo ao Apache Iceberg. Elas eliminam a necessidade de gerenciar operações de manutenção como compactação e remoção de arquivos não referenciados. A criação também usa CTAS, desta vez apontando para o catálogo s3tablescatalog:

CREATE TABLE lineitem_csv_s3_table
WITH (
  format = 'PARQUET')
AS SELECT *
FROM AwsDataCatalog.blog_qs_athena_tpc_h_db_sql.lineitem_csv
WHERE CAST(L_SHIPDATE AS DATE) BETWEEN DATE('1998-06-01') AND DATE('1998-12-31');

Preparação dos dados no Amazon Quick

Com as três tabelas registradas e consultáveis no Athena, o próximo passo é conectá-las ao Amazon Quick. A conexão é feita por meio de uma única fonte de dados Athena — as três tabelas ficam acessíveis porque todas estão catalogadas no AWS Glue Data Catalog e acessíveis pelo mesmo workgroup do Athena.

Cada tabela vira um dataset separado no Quick, importado para o SPICE para garantir performance sub-segundo em dashboards e fluxos agênticos. Um ponto de atenção importante: as S3 Tables ficam em um catálogo AWS Glue não padrão (s3tablescatalog), o que significa que elas não aparecem no navegador visual de tabelas do Quick. Para criar o dataset dessa tabela, é necessário usar SQL customizado:

SELECT * FROM "s3tablescatalog/blog-qs-athena-tpc-h-db-sql-s3-table-mar-3"."blog_qs_athena_tpc_h_namespace"."lineitem_csv_s3_table"

Join entre os três datasets

O esquema TPC-H é um esquema estrela por design. Para unir as três tabelas, a abordagem recomendada é fazer o join diretamente no Athena via SQL customizado e ingerir o resultado unificado no SPICE como um único dataset desnormalizado. Isso delega o processamento ao Athena e elimina restrições de tamanho de tabelas secundárias no Quick:

SELECT
  c.c_custkey, c.c_name, c.c_mktsegment, c.c_nationkey,
  o.o_orderkey, o.o_orderdate, o.o_orderstatus, o.o_totalprice, o.o_orderpriority,
  l.l_linenumber, l.l_partkey, l.l_suppkey, l.l_quantity,
  l.l_extendedprice, l.l_discount, l.l_shipmode, l.l_returnflag
FROM "s3tablescatalog/blog-qs-athena-tpc-h-db-sql-s3-table-mar-3"."blog_qs_athena_tpc_h_namespace"."lineitem_csv_s3_table" l
INNER JOIN "blog_qs_athena_tpc_h_db_sql"."orders_iceberg" o
  ON l.l_orderkey = o.o_orderkey
INNER JOIN "blog_qs_athena_tpc_h_db_sql"."customer_csv" c
  ON o.o_custkey = c.c_custkey;

Camada de BI e IA conversacional

Topic e Dashboard com Amazon Q

Com o dataset unificado no SPICE, a arquitetura configura um Topic no Amazon Quick — a camada semântica que traduz nomes de colunas em conceitos de negócio. Quando um usuário pergunta “Qual foi a receita total no último trimestre por segmento de cliente?”, o Topic mapeia “receita” para l_extendedprice, “último trimestre” para um filtro em o_orderdate e “segmento de cliente” para c_mktsegment. Sem esse mapeamento, as consultas em linguagem natural retornam resultados genéricos ou incorretos.

O dashboard é construído usando o Amazon Q dentro do Quick, que permite criar visualizações a partir de prompts em linguagem natural como “Mostre um KPI de receita total” ou “Crie um gráfico de barras de receita por status de pedido”. Após a publicação, o dashboard embute uma barra de perguntas em linguagem natural para que os usuários façam perguntas adicionais sem sair da tela.

Knowledge Base e agente de chat

Em paralelo ao fluxo estruturado, a arquitetura configura uma Knowledge Base alimentada pela especificação oficial do TPC-H (documento PDF público). Um Web Crawler indexa esse conteúdo não estruturado, tornando-o pesquisável pelo agente de chat.

O agente é configurado dentro de um Space (Espaço) do Amazon Quick — a camada organizacional que agrupa Topic, Knowledge Base e Dashboard em um único contexto governado. A instrução de persona do agente define claramente seu escopo: responder perguntas sobre receita de pedidos, performance de fornecedores, precificação de itens e disponibilidade de inventário, sempre fundamentando as respostas nos dados do lakehouse TPC-H.

Na prática, quando um analista de negócio pergunta “Qual segmento de clientes gerou mais receita no mês passado, e o que significa ‘segmento de mercado’ no esquema TPC-H?”, o agente:

• Consulta o Topic TPC-H Analytics para obter a receita por c_mktsegment filtrada ao último mês
• Simultaneamente recupera a definição de c_mktsegment da Knowledge Base
• Retorna uma resposta unificada: o ranking de receita com citação ao dataset SPICE, seguido da definição do campo com citação ao documento de especificação

Sem SQL. Sem navegação em dashboards. Sem ticket para o time de dados.

Permissões e governança

A arquitetura mantém governança corporativa em toda a cadeia. Se o AWS Lake Formation estiver habilitado, ele atua como a camada central de autorização, sobrescrevendo as permissões IAM padrão do S3. Nesse caso, as permissões precisam ser concedidas diretamente ao autor do Amazon Quick ou à role IAM no console do Lake Formation. Se o Lake Formation não estiver habilitado, as permissões são gerenciadas no nível da service role do Quick via controle de acesso IAM padrão.

Para S3 Tables especificamente, a service role do Quick requer uma política inline adicional glue:GetCatalog para acessar o catálogo não padrão s3tablescatalog. A referência completa está disponível na documentação Visualizando dados de S3 Tables com Amazon Quick.

Limpeza dos recursos

Após os testes, a AWS recomenda remover todos os artefatos criados para evitar custos desnecessários. O processo de limpeza envolve, na ordem:

• Dropar tabelas e banco de dados via console do Athena
• Remover o S3 Table bucket, namespace e tabela via AWS CLI, SDKs ou API REST do S3
• Excluir o bucket S3 via console
• No Amazon Quick: excluir o Chat Agent, o Space, o Dashboard, o Topic, a Knowledge Base, os Datasets e a fonte de dados, nessa ordem

Conclusão

A arquitetura demonstrada pela AWS mostra como é possível transformar um lakehouse complexo — com dados em múltiplos formatos e fontes — em uma interface conversacional acessível para usuários de negócio. A combinação de Amazon Athena para consulta serverless, AWS Glue para catálogo unificado, SPICE para performance em memória e os agentes de IA do Amazon Quick cria uma camada de self-service que mantém governança e escalabilidade corporativa.

Para equipes que buscam democratizar o acesso a dados sem abrir mão de segurança e controle, essa arquitetura de referência oferece um caminho concreto e reproduzível. A documentação de referência inclui tutoriais adicionais para casos de uso em B2B, receita, vendas, marketing e RH, além de guias aprofundados sobre permissões com Lake Formation.

Links úteis para aprofundamento:

• Tutorial de introdução ao Amazon Quick
• Usando AWS Lake Formation com Quick
• Analise seus dados com segurança usando AWS Lake Formation e Amazon QuickSight
• Modernize cargas de trabalho de Business Intelligence com Amazon Quick
• Boas práticas para SPICE e modo de consulta direta no Amazon QuickSight
• Acessando Amazon S3 Tables pelo Amazon Quick com permissões do AWS Lake Formation
• Segurança AWS no Quick

Fonte

Unleashing Agentic AI Analytics on Amazon SageMaker with Amazon Athena and Amazon Quick (https://aws.amazon.com/blogs/machine-learning/unleashing-agentic-ai-analytics-on-amazon-sagemaker-with-amazon-athena-and-amazon-quick/)

Por que migrar LLMs é mais difícil do que parece

Novos Modelos de Linguagem de Grande Escala (LLMs) surgem com frequência cada vez maior. Nenhum modelo mantém desempenho de pico para sempre em um determinado caso de uso — e, na prática, equipes de engenharia acabam precisando migrar de família de modelos ou simplesmente atualizar para uma versão mais recente dentro da mesma família. Sem um processo estruturado, essa transição vira uma fonte de instabilidade em produção.

Para endereçar esse problema, a AWS publicou o Generative AI Model Agility Solution: um framework de ponta a ponta para migração e atualização de LLMs em aplicações de IA generativa. A proposta é oferecer um processo padronizado, reutilizável e com métricas quantificáveis, cobrindo desde a preparação dos dados até os critérios de aprovação final da migração.

Visão geral da solução

O núcleo da abordagem é dividido em três etapas principais:

• Avaliação do modelo de origem (source model)
• Migração e otimização de prompts para o modelo de destino (target model), usando a Amazon Bedrock Prompt Optimization e a ferramenta Metaprompt da Anthropic
• Avaliação do modelo de destino

O tempo total estimado para uma migração seguindo esse framework varia de dois dias a duas semanas, dependendo da complexidade do caso de uso. Entre os destaques da solução estão: opções variadas de frameworks de avaliação, otimização automatizada de prompts, comparação de modelos por custo, latência e qualidade, além de exemplos prontos para aplicação imediata.

Preparação do conjunto de dados

Um conjunto de dados de avaliação com amostras de alta qualidade é peça fundamental no processo. Para a maioria dos casos de uso, as amostras precisam incluir respostas de referência (ground truths). Para outros cenários, é possível usar métricas que não dependem de ground truth — como relevância da resposta, fidelidade, toxicidade e viés.

Os campos sugeridos para cada amostra incluem: o prompt usado no modelo de origem, os inputs do prompt (perguntas e contexto, por exemplo, em casos de Geração Aumentada por Recuperação — RAG), configurações de invocação do modelo (temperatura, top_p, top_k), as respostas de referência, a saída do modelo de origem, latência, e tokens de entrada e saída (usados para cálculo de custo).

A qualidade dos ground truths é crítica: eles devem ser validados não apenas quanto à correção factual, mas também quanto ao alinhamento com os critérios e a orientação de especialistas no domínio (SMEs — Subject Matter Experts).

Seleção de frameworks e métricas de avaliação

Após coletar os dados, o próximo passo é escolher as métricas de avaliação adequadas ao caso de uso. Além da avaliação humana por especialistas, a AWS recomenda métricas automatizadas por serem mais escaláveis, objetivas e sustentáveis a longo prazo.

A solução trabalha com dois tipos de métricas automatizadas:

• Métricas predefinidas: disponíveis em frameworks como Ragas, DeepEval e Amazon Bedrock Evaluations, ou baseadas em algoritmos clássicos de Processamento de Linguagem Natural (PLN).
• Métricas customizadas: definidas pelo usuário para tarefas ou domínios específicos, geralmente usando o LLM como juiz imparcial com um prompt personalizado.

Seleção do modelo de destino

A escolha do LLM adequado exige considerar múltiplos fatores: modalidades de entrada e saída (texto, código, multimodal), tamanho da janela de contexto, custo por inferência ou token, métricas de desempenho (latência e throughput), qualidade das saídas, especialização em domínio, opções de hospedagem e requisitos de privacidade e segurança dos dados.

Após uma filtragem inicial com base nessas características, a recomendação é realizar benchmarks em tarefas específicas. O Amazon Bedrock oferece acesso a diversos LLMs por meio de uma API unificada, o que simplifica a experimentação e comparação de modelos — além de ajudar a evitar o aprisionamento a um único fornecedor (vendor lock-in).

Migração de prompts

A solução apresenta duas ferramentas automatizadas para migração e otimização de prompts:

Amazon Bedrock Prompt Optimization

A Amazon Bedrock Prompt Optimization é uma ferramenta disponível no Amazon Bedrock que otimiza automaticamente prompts escritos pelos usuários. Ela reduz o esforço de engenharia de prompts ao migrar workloads de outros provedores para o Amazon Bedrock.

É possível utilizá-la de duas formas:

• Opção A — Console do Amazon Bedrock: acesse o gerenciamento de prompts, crie um novo template, insira o prompt do modelo de origem, defina variáveis com duplas chaves ({{variavel}}), selecione o modelo de destino e clique em “Optimize” para gerar o prompt otimizado.
• Opção B — API do Bedrock: envie uma requisição OptimizePrompt para o endpoint de runtime do Agents for Amazon Bedrock. O stream de resposta retorna dois eventos: analyzePromptEvent (análise do prompt original) e optimizedPromptEvent (prompt otimizado gerado).

O código de exemplo para uso via API é o seguinte:

import boto3

# Set values here
TARGET_MODEL_ID = "anthropic.claude-3-sonnet-20240229-v1:0"  # Model to optimize for. For model IDs, see https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html
PROMPT = "Please summarize this text: "  # Prompt to optimize

def get_input(prompt):
    return {
        "textPrompt": {
            "text": prompt
        }
    }

def handle_response_stream(response):
    try:
        event_stream = response['optimizedPrompt']
        for event in event_stream:
            if 'optimizedPromptEvent' in event:
                print("========================== OPTIMIZED PROMPT ======================\n")
                optimized_prompt = event['optimizedPromptEvent']
                print(optimized_prompt)
            else:
                print("========================= ANALYZE PROMPT =======================\n")
                analyze_prompt = event['analyzePromptEvent']
                print(analyze_prompt)
    except Exception as e:
        raise e

if __name__ == '__main__':
    client = boto3.client('bedrock-agent-runtime')
    try:
        response = client.optimize_prompt(
            input=get_input(PROMPT),
            targetModelId=TARGET_MODEL_ID
        )
        print("Request ID:", response.get("ResponseMetadata").get("RequestId"))
        print("========================== INPUT PROMPT ======================\n")
        print(PROMPT)
        handle_response_stream(response)
    except Exception as e:
        raise e

Ferramenta Metaprompt da Anthropic

O Metaprompt é uma ferramenta de otimização de prompts da Anthropic em que o próprio Claude é instruído a escrever templates de prompts em nome do usuário, com base em uma tarefa ou objetivo. O processo consiste em especificar o template de prompt bruto, explicar a tarefa, definir as variáveis de entrada e o formato de saída esperado, e então executar o Metaprompt com um LLM Claude (como o Claude-3-Sonnet).

O resultado é um novo template com instruções otimizadas seguindo as boas práticas do Claude — incluindo uso de tags XML e reagrupamento de instruções para maior clareza. Para implementar esse processo, a AWS disponibiliza um Jupyter Notebook de migração de prompts no repositório de código.

Geração de resultados e avaliação

A geração de respostas durante a migração é um processo iterativo: diferentes versões de prompts, diferentes LLMs e diferentes configurações são comparados para identificar a melhor combinação. Como boa prática, a AWS recomenda usar o método padrão de invocação dos modelos do Amazon Bedrock (disponível no repositório de código de migração) para capturar metadados como latência, tempo até o primeiro token (TTFT — Time to First Token), tokens de entrada e de saída.

A avaliação foca em três categorias principais de métricas:

• Acurácia e qualidade: usando frameworks automatizados como Ragas (precisão, recall, correção e similaridade da resposta), DeepEval (relevância, fidelidade, toxicidade e viés) e Amazon Bedrock Evaluations (acurácia, fidelidade, utilidade, coerência lógica, nocividade, entre outros), além de avaliação humana por especialistas.
• Latência: latência total (do prompt à resposta final) e TTFT (tempo até o primeiro token gerado), especialmente relevante em aplicações conversacionais em tempo real.
• Custo: calculado com base no número de tokens de entrada e saída multiplicado pelo preço por token, conforme a tabela de preços do Amazon Bedrock.

O notebook de geração de relatório comparativo disponível no repositório permite gerar automaticamente uma visão consolidada do modelo de origem versus o modelo de destino, com tabelas lado a lado de tokens médios, custo médio e latência média.

Otimização contínua

Otimização de prompts

Para melhorar a qualidade das respostas, a AWS recomenda conduzir uma análise de erros estruturada. Após coletar os insights da análise e o feedback dos especialistas, inicia-se um ciclo iterativo de otimização de prompts. As técnicas disponíveis incluem: engenharia de prompts para incorporar critérios específicos nas instruções, aprendizado com poucos exemplos (few-shot learning) para definir formato e exemplos de resposta, incorporação de meta-informações de contexto, e pré ou pós-processamento para reforçar o formato de saída.

Otimização de latência

Duas abordagens principais são indicadas para reduzir a latência:

• Otimização de prompts para respostas mais curtas: adicionar instruções que evitem respostas longas, explicações desnecessárias ou palavras de preenchimento reduz diretamente o número de tokens de saída e, consequentemente, a latência.
• Throughput provisionado: adquirir throughput provisionado no Amazon Bedrock garante um nível mais alto de capacidade dedicada, o que pode reduzir a latência e previne requisições throttled.

Ciclo de vida da melhoria e uso em produção

A AWS destaca que dificilmente um LLM candidato atinge seu melhor desempenho sem nenhuma otimização. Por isso, o ciclo de melhoria — que inclui otimização de prompts, geração de respostas, avaliação de métricas, análise de erros, verificação de amostras e atualização do dataset — deve ser planejado como parte integrante do processo.

A solução pode ser aplicada em duas fases do ciclo de vida de uma aplicação de IA generativa em produção: na migração completa de LLM (quando um novo modelo é adotado) e no monitoramento e garantia de qualidade contínuos (usando o mesmo processo de avaliação e coleta de ground truth estabelecido durante a migração).

Dicas e lições aprendidas

• Critérios de aprovação: os dados, critérios de avaliação e critérios de sucesso devem ser definidos no início e não alterados durante o processo.
• Qualidade dos dados: as amostras devem ter quantidade e qualidade suficientes para uma avaliação confiável, com ground truths totalmente alinhados com os critérios dos especialistas.
• Seleção de modelos: antes de iniciar os experimentos, utilize recursos como o site de benchmarking Artificial Analysis para uma comparação holística de qualidade, desempenho e preço entre os candidatos.
• Trade-offs entre desempenho e custo: um modelo com desempenho ligeiramente inferior pode ser a escolha mais inteligente se a diferença de custo for substancial e a diferença de qualidade for mínima.
• Técnicas de otimização: engenharia de prompts e throughput provisionado podem fechar a diferença de desempenho entre modelos e devem ser considerados como parte do processo de avaliação.

O repositório completo da solução está disponível no AWS Generative AI Model Agility Code Repo no GitHub.

Fonte

AWS Generative AI Model Agility Solution: A comprehensive guide to migrating LLMs for generative AI production (https://aws.amazon.com/blogs/machine-learning/aws-generative-ai-model-agility-solution-a-comprehensive-guide-to-migrating-llms-for-generative-ai-production/)

O que foi anunciado

A AWS anunciou que o Amazon Elastic Container Service (Amazon ECS) agora oferece suporte a métricas de GPU NVIDIA para cargas de trabalho em contêineres executadas no Amazon ECS Managed Instances. Essas métricas chegam integradas ao Amazon CloudWatch Container Insights com observabilidade aprimorada, dando às equipes visibilidade real sobre a saúde e o desempenho das GPUs utilizadas em ambientes ECS.

O que é possível monitorar agora

Com esse novo suporte, quem utiliza o Amazon ECS Managed Instances pode acompanhar diretamente no CloudWatch as seguintes dimensões das GPUs:

• Capacidade de GPU — quanto do recurso está disponível no pool
• Utilização — percentual de uso em tempo real
• Memória — consumo de memória da GPU
• Saúde do hardware — estado operacional dos dispositivos físicos
• Condições térmicas — temperatura e alertas relacionados ao superaquecimento

O Container Insights com observabilidade aprimorada vai além do nível de cluster ou serviço: ele entrega visibilidade granular até o nível do dispositivo GPU individual, o que facilita muito a identificação de gargalos e falhas pontuais.

Por que isso importa para cargas de IA/ML

Workloads de treinamento e inferência de modelos de Inteligência Artificial e Aprendizado de Máquina (IA/ML) são altamente sensíveis ao desempenho da GPU. Um dispositivo operando abaixo do esperado — seja por limitação de memória, superaquecimento ou degradação de hardware — pode comprometer toda uma pipeline de treinamento sem que a equipe perceba rapidamente.

Com as novas métricas, as equipes conseguem identificar esses problemas de forma proativa, antes que eles impactem as cargas em produção. Além disso, a visibilidade sobre capacidade e utilização ajuda no right-sizing da frota de instâncias GPU, evitando tanto o desperdício de recursos quanto o subdimensionamento.

Como começar a usar

Para acessar as métricas de GPU NVIDIA no ECS, o processo envolve dois passos principais:

• Habilitar o Container Insights com observabilidade aprimorada no cluster do Amazon ECS
• Provisionar instâncias Amazon EC2 com aceleração por GPU por meio de um capacity provider do Amazon ECS Managed Instances

O recurso já está disponível em todas as regiões comerciais da AWS. Para entender os custos envolvidos, a AWS disponibiliza a página de preços do Amazon CloudWatch. Para aprofundar o conhecimento técnico, o ponto de partida recomendado é o guia de métricas do Amazon ECS Container Insights com observabilidade aprimorada.

Fonte

Amazon ECS Managed Instances now supports NVIDIA GPU metrics (https://aws.amazon.com/about-aws/whats-new/2026/04/amazon-ecs-mi-gpu-metrics/)

O problema de alinhamento dos modelos de linguagem

Grandes Modelos de Linguagem (LLMs) já estão no centro de agentes conversacionais, ferramentas criativas e sistemas de apoio a decisões. Mas o output bruto desses modelos frequentemente carrega imprecisões, desalinhamentos de política ou respostas pouco úteis — problemas que comprometem a confiança e limitam o uso real em produção.

Para resolver isso, o Ajuste Fino por Reforço (RFT) se consolidou como o método preferido de alinhamento eficiente. Em vez de depender de rotulagem manual cara e demorada, o RFT usa sinais de recompensa automatizados para guiar o comportamento do modelo.

No centro do RFT moderno estão as funções de recompensa, construídas de duas formas principais:

• Aprendizado por Reforço com Recompensas Verificáveis (RLVR): usa código para avaliar as respostas geradas pelo modelo com critérios verificáveis.
• Aprendizado por Reforço com Feedback de IA (RLAIF): usa um segundo modelo de linguagem como “juiz” para avaliar as respostas candidatas — a técnica conhecida como LLM-as-a-judge.

A AWS publicou um post técnico detalhando como o RLAIF funciona na prática com os modelos Amazon Nova, incluindo um caso de uso real no setor jurídico.

Por que usar LLM-as-a-judge em vez de recompensas genéricas?

Recompensas genéricas baseadas em regras simples — como correspondência de substrings — funcionam para casos bem definidos, mas falham quando os critérios de qualidade são subjetivos ou multidimensionais.

Um juiz baseado em LLM raciocina sobre múltiplas dimensões ao mesmo tempo: correção, tom, segurança, relevância. Ele captura nuances e especificidades de domínio sem precisar de retreinamento específico por tarefa. Além disso, oferece explicabilidade embutida por meio de justificativas — algo que funções de recompensa estáticas simplesmente não conseguem fornecer.

Seis passos para implementar o LLM-as-a-judge

1. Escolha a arquitetura do juiz

Existem dois modos principais de avaliação:

• Julgamento baseado em rubrica (pontuação absoluta): atribui uma nota numérica a uma única resposta com base em critérios predefinidos. Recomendado quando não há dados de preferência disponíveis e o RLVR não é adequado. Funciona melhor para dados fora da distribuição e evita viés de dados.
• Julgamento baseado em preferência (comparação relativa): compara duas respostas candidatas lado a lado e seleciona a superior. Recomendado quando há dados comparativos disponíveis e o modelo deve explorar livremente sem restrições de dados de referência.

2. Defina os critérios de avaliação

Critérios claros são a base de um treinamento RLAIF eficaz. Para juízes baseados em rubrica, a AWS recomenda usar pontuação booleana (aprovado/reprovado) em vez de escalas de 1 a 10 — isso reduz a variabilidade do juiz e torna a avaliação mais confiável.

3. Selecione e configure o modelo juiz

A escolha do modelo depende da complexidade do domínio e do equilíbrio entre custo e confiabilidade:

• Modelos grandes/pesados (Amazon Nova Pro, Claude Opus, Claude Sonnet): indicados para raciocínio complexo, avaliação com nuances e pontuação multidimensional. Alto custo, altíssima confiabilidade.
• Modelos médios/leves (Amazon Nova 2 Lite, Claude Haiku): adequados para domínios gerais como matemática ou programação. Custo baixo a médio, confiabilidade moderada a alta.

O juiz é configurado via Amazon Bedrock e chamado por uma função AWS Lambda de recompensa.

4. Refine o prompt do modelo juiz

O prompt do juiz é o alicerce da qualidade do alinhamento. Ele deve produzir saídas estruturadas e facilmente parseáveis, com regras de pontuação claras, tratamento de casos extremos e comportamentos desejados explicitamente definidos.

5. Alinhe os critérios do juiz com as métricas de produção

A função de recompensa deve espelhar as métricas que serão usadas para avaliar o modelo final em produção. O fluxo recomendado é: definir critérios de sucesso em produção, mapear cada critério para dimensões de pontuação do juiz, validar a correlação entre as notas do juiz e as métricas de avaliação, e testar em amostras representativas e casos extremos.

6. Construa uma função Lambda de recompensa robusta

Sistemas RFT em produção processam milhares de avaliações de recompensa por etapa de treinamento. A AWS recomenda combinar o juiz LLM com componentes de recompensa determinísticos rápidos para capturar falhas óbvias antes de acionar avaliações mais custosas:

• Validação de formato: verifica estrutura JSON, campos obrigatórios e conformidade com o schema — sempre, pois é barato e instantâneo.
• Penalidades de tamanho: desencoraja respostas excessivamente longas ou curtas, quando o comprimento importa.
• Consistência de idioma: verifica se as respostas correspondem ao idioma de entrada — crítico para aplicações multilíngues.
• Filtros de segurança: verificações baseadas em regras para conteúdo proibido — sempre, para evitar que conteúdo inseguro chegue à produção.

Do ponto de vista de infraestrutura, a AWS recomenda: implementar backoff exponencial para lidar com limites de taxa da API do Amazon Bedrock, usar ThreadPoolExecutor ou padrões assíncronos para paralelizar chamadas ao juiz, configurar o timeout da Lambda para 15 minutos e usar concorrência provisionada de aproximadamente 100 para configurações típicas. Erros devem retornar recompensas neutras (0.5) em vez de interromper toda a etapa de treinamento.

Fluxo de treinamento RFT com LLM-as-a-judge

O processo completo de ponta a ponta passa por três fases principais: configuração e validação, treinamento e implantação. O diagrama abaixo ilustra esse fluxo, mostrando como cada etapa se apoia na anterior para criar um pipeline resiliente que equilibra qualidade de alinhamento com eficiência computacional.

• Fase 1 — Configuração e Validação: avaliação do modelo juiz, avaliação de baseline e design do dataset e das funções de recompensa.
• Fase 2 — Treinamento: treinamento iterativo com monitoramento contínuo de distribuições de recompensa, scores de vantagem, taxa de concordância do juiz e detecção de reward hacking.
• Fase 3 — Implantação: verificação de diversidade de rollouts, calibração do juiz, alinhamento recompensa-avaliação e ausência de reward hacking antes do deploy.

Caso de uso real: revisão automatizada de contratos jurídicos

O post da AWS descreve uma aplicação prática com um parceiro do setor jurídico. O desafio era automatizar a revisão, avaliação e identificação de riscos em documentos de contratos, comparando-os com diretrizes internas, regulamentações, contratos anteriores e legislação aplicável.

O problema foi formulado da seguinte forma: dado um documento-alvo (o contrato a ser avaliado) e um documento de referência (as diretrizes e contexto), o LLM deve gerar um JSON com comentários, tipos de comentário e ações recomendadas baseadas na avaliação.

O dataset original era relativamente pequeno, contendo contratos completos com anotações e comentários de especialistas jurídicos. Foi utilizado um modelo GPT OSS 120b como juiz, com um system prompt personalizado durante o RFT.

Estrutura do prompt do juiz para revisão de contratos

O prompt do juiz foi construído em camadas bem definidas:

a) Objetivo de alto nível:

# Contract Review Evaluation - Unweighted Scoring
You are an expert contract reviewer evaluating AI-generated comments. Your PRIMARY objective is to assess how well each predicted comment identifies issues in the TargetDocument contract clauses and whether those issues are justified by the Reference guidelines.

b) Abordagem de avaliação: define o que o modelo recebe (TargetDocument, Reference, Prediction) e instrui o juiz a avaliar cada comentário de forma independente, verificando se o campo text_excerpt cita texto do contrato-alvo — não das diretrizes de referência.

c) Dimensões de pontuação: três dimensões avaliadas em sequência obrigatória — TargetDocument_Grounding, Reference_Consistency e Actionability — cada uma com escala de 1 a 5 e critérios explícitos para cada nota.

d) Formato de saída: JSON estruturado com pontuação por comentário, justificativas e score agregado.

e) Handler Lambda com multithreading:

def lambda_handler(event, context):
    scores: List[RewardOutput] = []
    samples = event
    max_workers = len(samples)
    print(f"Evaluating {len(samples)} items with {max_workers} threads...")
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = [executor.submit(judge_answer, sample) for sample in samples]
        scores = [future.result() for future in futures]
    print(f"Completed {len(scores)} evaluations")
    return [asdict(score) for score in scores]

Configuração de permissões e IAM

A função de execução do Amazon SageMaker AI precisa de permissão para invocar a Lambda de recompensa:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction"
      ],
      "Resource": "arn:aws:lambda:region:account-id:function:function-name"
    }
  ]
}

A AWS reforça que o nome da função Lambda deve conter “SageMaker” (por exemplo, arn:aws:lambda:us-east-1:123456789012:function:MyRewardFunctionSageMaker) e que o treinamento RFT pode falhar se as permissões estiverem ausentes. O princípio do menor privilégio deve ser aplicado, limitando as permissões a ARNs de recursos específicos. Para mais detalhes, consulte a documentação de Segurança no AWS Lambda e a Segurança no Amazon SageMaker AI.

Personalização do treinamento com o Nova Forge SDK

A AWS disponibilizou o Nova Forge SDK para gerenciar todo o ciclo de personalização de modelos — da preparação dos dados ao deploy e monitoramento. O SDK elimina a necessidade de buscar receitas ou URIs de container para técnicas específicas. No caso de uso jurídico, os parâmetros de treinamento foram ajustados via overrides:

# Launch training with recipe overrides
result = customizer.train(
    job_name="my-rft-run",
    rft_lambda_arn="",
    overrides={
        # Training config
        "max_length": 64000,
        "global_batch_size": 64,
        "reasoning_effort": None,
        # Data
        "shuffle": False,
        # Rollout
        "type": "off_policy_async",
        "age_tolerance": 2,
        "proc_num": 6,
        "number_generation": 8,
        "max_new_tokens": 16000,
        "set_random_seed": True,
        "temperature": 1,
        "top_k": 0,
        "lambda_concurrency_limit": 100,
        # Trainer
        "max_steps": 516,
        "save_steps": 32,
        "save_top_k": 17,
        "refit_freq": 4,
        "clip_ratio_high": 0.28,
        "ent_coeff": 0.0,
        "loss_scale": 1,
    },
)

Resultados: RFT supera modelos maiores

Os resultados foram avaliados em um cenário “best of k” com comentário único, onde cada modelo gerou múltiplos comentários por amostra e o de maior qualidade foi pontuado. Essa abordagem estabelece um limite superior de desempenho e permite comparação justa entre modelos.

O Amazon Nova 2 Lite com RFT alcançou score agregado de 4.33 — o maior entre todos os modelos avaliados — além de validação perfeita do schema JSON. Isso representa uma melhoria significativa sobre o Nova 2 Lite base (3.05), o Nova 2 Lite com Ajuste Fino Supervisionado — SFT (3.16), o Claude Haiku 4.5 (3.54) e o Claude Sonnet 4.5 (3.89).

Outros destaques dos resultados:

• Eliminação de artefatos indesejados: durante iterações de SFT, foram observados comportamentos problemáticos como geração repetitiva de comentários e predições anômalas de caracteres Unicode. Esses problemas não apareceram nos checkpoints de RFT, pois o mecanismo de recompensa desencoraja naturalmente tais artefatos.
• Boa generalização para novos critérios de avaliação: quando os modelos RFT foram avaliados com um prompt de juiz modificado (alinhado, mas não idêntico ao usado no treinamento), o desempenho se manteve forte — evidência de que o RFT aprende padrões de qualidade generalizáveis, não apenas decora critérios específicos.
• Custo computacional maior: o RFT exigiu de 4 a 8 rollouts por amostra de treinamento, aumentando os custos em relação ao SFT. Para aplicações de missão crítica — como revisão jurídica, conformidade financeira ou documentação de saúde — os ganhos de desempenho justificam esse custo adicional.

Conclusão

O RFT com LLM-as-a-judge representa uma abordagem poderosa para alinhar LLMs a aplicações específicas de domínio. Como demonstrado no caso de revisão de contratos jurídicos, a metodologia entrega melhorias significativas sobre modelos base e sobre o ajuste fino supervisionado tradicional.

Para equipes que constroem sistemas de IA de missão crítica, a recomendação da AWS é começar pequeno: validar o design do juiz em benchmarks curados, verificar a resiliência da infraestrutura e escalar gradualmente monitorando sinais de reward hacking.

Para aprofundamento, a AWS disponibiliza o Guia do Desenvolvedor Amazon Nova 2, o Nova Forge SDK no GitHub e a documentação de Ajuste Fino por Reforço (RFT) com modelos Amazon Nova.

Fonte

Reinforcement fine-tuning with LLM-as-a-judge (https://aws.amazon.com/blogs/machine-learning/reinforcement-fine-tuning-with-llm-as-a-judge/)

O que é o Neuron Agentic Development?

A AWS anunciou o Neuron Agentic Development, uma coleção open-source de agentes e habilidades projetada para equipar assistentes de codificação com IA e acelerar o desenvolvimento sobre o AWS Trainium e o AWS Inferentia. Em termos práticos, a novidade traz capacidades agênticas diretamente para o fluxo de trabalho do desenvolvedor, cobrindo desde a criação de kernels até a análise de desempenho.

O lançamento inicial foca no desenvolvimento de kernels pela Interface de Kernel Neuron (NKI) — a camada de programação de baixo nível que dá acesso direto ao hardware Trainium, permitindo escrever kernels de computação personalizados para extrair o máximo de desempenho da plataforma.

Como funciona na prática

O Neuron Agentic Development leva o conhecimento especializado de NKI para dentro da IDE agêntica do desenvolvedor — como Claude Code e Kiro — por meio de linguagem natural. Ou seja, em vez de consultar documentação extensa ou depurar manualmente, o desenvolvedor pode simplesmente descrever o que precisa e o agente executa a tarefa.

Alguns exemplos do que já é possível fazer com essa abordagem:

• Descrever uma operação PyTorch e receber um kernel NKI funcional como resposta;
• Pedir ao agente que corrija um erro de compilação — ele identifica o problema automaticamente e aplica a correção;
• Solicitar uma análise de desempenho e receber um relatório apontando quais linhas do código do kernel estão causando gargalos.

Capacidades cobertas

O conjunto de capacidades disponíveis nesta versão inicial abrange:

• Autoria de kernels — criação de kernels NKI a partir de descrições em linguagem natural;
• Depuração — identificação e correção automática de erros de compilação;
• Consulta à documentação — busca contextual na documentação do Neuron;
• Captura de perfil — coleta de dados de profiling durante a execução;
• Análise de perfil — interpretação dos dados coletados para identificar pontos de melhoria.

Visão de longo prazo

A AWS posiciona o Neuron Agentic Development como um framework amplo para capacidades agênticas em toda a pilha Neuron, sendo o desenvolvimento de kernels NKI apenas o ponto de partida. A expectativa é que novas capacidades sejam incorporadas ao longo do tempo, expandindo o escopo além do NKI.

O repositório já está disponível no GitHub. Para quem quiser explorar mais a fundo, a documentação oficial do AWS Neuron e o repositório do Neuron Agentic Development no GitHub são os pontos de partida recomendados.

Fonte

AWS Neuron SDK now available with Neuron Agentic Development for NKI kernel development on Trainium (https://aws.amazon.com/about-aws/whats-new/2026/04/announcing-neuron-agentic-development/)

Novos modelos de IA disponíveis no SageMaker JumpStart

A AWS anunciou a disponibilidade dos modelos Gemma 4 E4B, Gemma 4 26B-A4B e Gemma 4 31B no Amazon SageMaker JumpStart, ampliando o portfólio de modelos de fundação acessíveis aos clientes da plataforma. Os três modelos são desenvolvidos pelo Google DeepMind e chegam com ajuste de instrução (instruction-tuned), capacidades multimodais, raciocínio configurável, chamada nativa de funções e suporte multilíngue para mais de 140 idiomas.

O que esses modelos são capazes de fazer

Os três modelos compartilham um conjunto robusto de capacidades voltadas para casos de uso empresariais. Veja o que cada funcionalidade oferece:

• Thinking (Raciocínio): modo de raciocínio integrado que permite ao modelo pensar passo a passo antes de responder.
• Compreensão de imagens: detecção de objetos, análise de documentos e PDFs, entendimento de interfaces gráficas (UI), interpretação de gráficos, Reconhecimento Óptico de Caracteres (OCR) multilíngue e reconhecimento de escrita à mão.
• Compreensão de vídeo: análise de conteúdo em vídeo por meio do processamento de sequências de frames.
• Entrada multimodal intercalada: possibilidade de combinar texto e imagens em qualquer ordem dentro de um único prompt.
• Function Calling (Chamada de funções): suporte nativo para uso estruturado de ferramentas externas, viabilizando fluxos de trabalho agênticos.
• Programação: geração, complementação e correção de código.
• Multilíngue: suporte nativo a mais de 35 idiomas, com pré-treinamento em mais de 140 idiomas.

Diferencial do Gemma 4 E4B

Entre os três modelos disponibilizados, o Gemma 4 E4B se destaca por oferecer uma capacidade adicional: suporte a entrada de áudio para Reconhecimento Automático de Fala (ASR) e tradução de fala para texto em múltiplos idiomas. Esse diferencial o torna uma opção interessante para aplicações que envolvem processamento de voz.

Como começar a usar

Com o SageMaker JumpStart, a AWS permite que os clientes façam o deploy de qualquer um desses modelos com poucos cliques, sem a necessidade de configurações complexas. Para começar, basta acessar a seção Models do SageMaker Studio ou utilizar o SageMaker Python SDK para realizar o deploy direto na conta AWS. Mais detalhes sobre como implantar e utilizar modelos de fundação estão disponíveis na documentação oficial do Amazon SageMaker JumpStart.

Fonte

Gemma 4 models are now available in Amazon SageMaker JumpStart (https://aws.amazon.com/about-aws/whats-new/2026/04/gemma-4-models-on-sagemaker-jumpstart/)

O problema central: memória sem organização é memória inútil

Quem já trabalhou com agentes de IA sabe que persistir contexto entre sessões é um dos desafios mais práticos do desenvolvimento. Não basta armazenar informações — é preciso organizá-las de forma que possam ser recuperadas com precisão, no momento certo, pela entidade certa. Sem isso, o agente traz contexto irrelevante, mistura dados de usuários diferentes ou expõe informações que não deveriam ser acessíveis.

Para endereçar exatamente esse problema, a AWS publicou um guia técnico detalhado sobre o design de namespaces no Amazon Bedrock AgentCore Memory. Se você ainda não conhece o serviço, vale começar pela introdução ao AgentCore Memory antes de mergulhar nos padrões avançados.

O que são namespaces no AgentCore Memory?

Namespaces são caminhos hierárquicos que organizam os registros de memória de longo prazo dentro de um recurso de memória do AgentCore. A analogia mais direta é com estruturas de diretórios em um sistema de arquivos: cada registro fica armazenado em um caminho específico, e esse caminho determina como ele será recuperado e quem poderá acessá-lo.

Por exemplo, as preferências de um usuário podem ficar em /actor/customer-123/preferences/, enquanto o resumo de uma sessão específica fica em /actor/customer-123/session/session-789/summary/. Com essa estrutura, é possível recuperar memórias com exatamente o nível de granularidade necessário.

Se você já trabalhou com chaves de partição no Amazon DynamoDB ou com estruturas de prefixo no Amazon Simple Storage Service (Amazon S3), o raciocínio é o mesmo: antes de definir a estrutura, você precisa pensar nos padrões de acesso. As perguntas fundamentais são:

• Quem precisa acessar essas memórias — um único usuário ou todos os usuários de um agente?
• Qual granularidade de recuperação é necessária — resumos por sessão ou preferências acumuladas ao longo do tempo?
• Quais são os limites de isolamento — a memória de um usuário pode ser visível para outro?

A principal diferença em relação a uma chave de partição é que namespaces suportam recuperação hierárquica além do match exato. É possível consultar em qualquer nível da hierarquia, não apenas na folha.

Templates de namespace e resolução dinâmica

Ao criar um recurso de memória, o namespace é definido por meio do campo namespaceTemplate dentro de cada configuração de estratégia. Três variáveis pré-definidas estão disponíveis para composição dinâmica:

• {actorId} — resolve para o identificador do ator nos eventos processados
• {sessionId} — resolve para o identificador da sessão
• {memoryStrategyId} — resolve para o identificador da estratégia

Veja um exemplo de criação de recurso de memória com templates de namespace:

response = agentcore_client.create_memory(
    name="CustomerSupportMemory",
    description="Memory for customer support agents",
    eventExpiryDuration=30,
    memoryStrategies=[
        {
            "semanticMemoryStrategy": {
                "name": "customer-facts",
                "namespaceTemplate": "/actor/{actorId}/facts/"
            }
        },
        {
            "summaryMemoryStrategy": {
                "name": "session-summaries",
                "namespaceTemplate": "/actor/{actorId}/session/{sessionId}/summary/"
            }
        }
    ]
)

Quando eventos chegam com actorId=customer-456 e sessionId=session-789, os namespaces resolvidos ficam:

• /actor/customer-456/facts/
• /actor/customer-456/session/session-789/summary/

Padrões de design por estratégia de memória

Cada tipo de estratégia de memória tem necessidades de escopo diferentes. A AWS detalha os padrões recomendados para cada caso.

1. Memória semântica e preferências: escopo por ator

A memória semântica captura fatos e conhecimentos extraídos de conversas — por exemplo, “a empresa do cliente tem 500 funcionários”. A memória de preferências captura escolhas e estilos — por exemplo, “o usuário prefere Python para desenvolvimento”. Ambas acumulam valor ao longo do tempo e são relevantes em qualquer sessão futura.

Para esses casos, o namespace deve ser escopado ao ator:

• /actor/{actorId}/facts/
• /actor/{actorId}/preferences/

Com esse design, fatos e preferências de um usuário ficam consolidados em um único namespace, independentemente de qual sessão os originou. O motor de consolidação do AgentCore Memory mescla memórias relacionadas dentro do mesmo namespace.

Vale notar que quando o namespace inclui o sessionId no caminho dos fatos (como /actor/{actorId}/{sessionId}/facts/), o motor de consolidação não consegue enxergar registros de sessões diferentes — e os fatos nunca são mesclados. Por isso, para memórias que devem persistir entre sessões, o escopo por ator é o padrão correto.

Em alguns casos, um administrador pode precisar recuperar informações de múltiplos atores. Para isso, a AWS sugere inverter a estrutura, colocando o identificador do ator como filho do tipo de memória:

• /customer-issues/{actorId}/
• /sales/{actorId}/

Com essa estrutura invertida, uma consulta com namespacePath="/customer-issues/" retorna problemas reportados por todos os clientes, enquanto uma consulta com namespace="/customer-issues/customer-123/" retorna apenas os dados daquele ator específico.

2. Memória de resumo: escopo por sessão

A memória de resumo cria narrativas das conversas, capturando pontos principais e decisões. Em vez de alimentar todo o histórico de uma conversa na janela de contexto do modelo de linguagem (LLM), o agente pode recuperar um resumo compacto que preserva as informações essenciais com muito menos tokens.

Como resumos estão intrinsecamente ligados a uma conversa específica, o namespace deve incluir o identificador da sessão: /actor/{actorId}/session/{sessionId}/summary/. Assim, cada sessão tem seu próprio resumo, mas todos ficam organizados sob o ator para recuperação cruzada quando necessário.

3. Memória episódica: escopo por sessão com hierarquia de reflexão

A memória episódica captura rastros completos de raciocínio — o objetivo, os passos executados, os resultados e as reflexões. Como cada episódio representa o que aconteceu em uma interação específica, ele deve ser escopado à sessão, de forma similar aos resumos.

Reflexões são insights transversais, armazenados em um nível pai. Elas generalizam aprendizados entre sessões — por exemplo, “quando uma restrição de classe tarifária bloqueia uma modificação, busque voos alternativos imediatamente em vez de apenas explicar a política”. O namespace das reflexões deve ser um subcaminho do namespace dos episódios:

• Episódios: /actor/{actorId}/session/{sessionId}/episodes/
• Reflexões: /actor/{actorId}/

Padrões de recuperação de memória

O AgentCore Memory oferece três APIs principais para recuperação de memória de longo prazo.

Busca semântica com RetrieveMemoryRecords

Esse é o método primário durante interações do agente. Ele retorna as memórias semanticamente relevantes para uma consulta, com base em significado — não em correspondência exata de texto.

# Retrieve memories relevant to the current user query
memories = agentcore_client.retrieve_memory_records(
    memoryId="mem-12345abcdef",
    namespace="/actor/customer-123/facts/",
    searchCriteria={
        "searchQuery": "What cloud migration approach is the customer using?",
        "topK": 5
    }
)

A consulta de busca pode vir diretamente da pergunta do usuário ou ser gerada pelo próprio LLM do agente para cenários mais complexos. No segundo caso, há um custo adicional de latência.

Listagem direta com ListMemoryRecords

Usado quando é necessário enumerar memórias dentro de um namespace específico — por exemplo, exibir as preferências armazenadas de um usuário em uma interface, auditar o que existe ou executar operações em lote.

# List all memories in a specific namespace
records = agentcore_client.list_memory_records(
    memoryId="mem-12345abcdef",
    namespace="/actor/customer-123/preferences/"
)

Acesso e exclusão diretos com GetMemoryRecord e DeleteMemoryRecord

Quando o ID específico de um registro é conhecido (por exemplo, a partir de uma listagem anterior), é possível acessá-lo ou removê-lo diretamente. Esses métodos são úteis para fluxos de gerenciamento de memória que permitem aos usuários visualizar, corrigir ou excluir registros específicos pela interface da aplicação.

# Get a specific memory record
record = agentcore_client.get_memory_record(
    memoryId="mem-12345abcdef",
    memoryRecordId="rec-abc123"
)

# Delete a specific memory record
agentcore_client.delete_memory_record(
    memoryId="mem-12345abcdef",
    memoryRecordId="rec-abc123"
)

namespace vs. namespacePath: match exato versus recuperação hierárquica

O AgentCore Memory oferece dois campos distintos para escopar a recuperação, e entender a diferença é crítico para o comportamento correto do sistema.

O campo namespace realiza correspondência exata — retorna apenas os registros armazenados naquele caminho preciso. Já o campo namespacePath realiza correspondência hierárquica, retornando todos os registros cujo namespace esteja sob o caminho especificado.

A tabela abaixo, extraída do guia original, resume quando usar cada abordagem:

• Recuperar preferências semanticamente relevantes: RetrieveMemoryRecords com namespace → /actor/customer-123/preferences/
• Recuperar um resumo de sessão específica: ListMemoryRecords com namespace → /actor/customer-123/session/session-001/summary/
• Listar todas as preferências de um usuário: ListMemoryRecords com namespace → /actor/customer-123/preferences/
• Buscar em todas as memórias de um usuário: RetrieveMemoryRecords com namespacePath → /actor/customer-123/
• Listar resumos de todas as sessões de um usuário: ListMemoryRecords com namespacePath → /actor/customer-123/session/

É importante pensar bem nos padrões de isolamento ao usar namespacePath, pois a travessia em árvore pode expor dados não intencionais se a hierarquia não estiver bem planejada.

Controle de acesso via IAM

Os namespaces se integram ao Gerenciamento de Identidade e Acesso (IAM) da AWS por meio de condition keys que restringem quais namespaces uma entidade pode incluir nas requisições à API de memória.

Políticas de match exato

Para restringir o acesso a um namespace específico, usa-se StringEquals com a condition key bedrock-agentcore:namespace:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:RetrieveMemoryRecords",
        "bedrock-agentcore:ListMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/mem-12345abcdef",
      "Condition": {
        "StringEquals": {
          "bedrock-agentcore:namespace": "/actor/${aws:PrincipalTag/userId}/preferences/"
        }
      }
    }
  ]
}

Essa política garante que um usuário só consiga recuperar memórias do seu próprio namespace de preferências, usando a tag de principal userId para escopo dinâmico.

Políticas de recuperação hierárquica

Para acesso hierárquico, usa-se StringLike com a condition key bedrock-agentcore:namespacePath:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:RetrieveMemoryRecords",
        "bedrock-agentcore:ListMemoryRecords"
      ],
      "Resource": "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/mem-12345abcdef",
      "Condition": {
        "StringLike": {
          "bedrock-agentcore:namespacePath": "/actor/${aws:PrincipalTag/userId}/*"
        }
      }
    }
  ]
}

Com essa configuração, o usuário pode realizar recuperação hierárquica em seus próprios namespaces (fatos, preferências, resumos), enquanto o acesso aos dados de outros usuários é bloqueado.

Conclusão: design de namespace é fundação, não detalhe

O guia publicado pela AWS deixa claro que o design de namespaces é tão fundamental quanto o design de esquemas em um banco de dados. Pensar nos padrões de acesso e nos limites de isolamento antes de definir os templates de namespace é o que separa um sistema de memória eficaz de um que traz contexto errado ou expõe dados indevidamente.

Os pontos-chave do guia são:

• Pense nos padrões de acesso e isolamento antes de criar os templates de namespace
• Escope memórias semânticas e de preferências ao ator (/actor/{actorId}/) para consolidação entre sessões
• Escope resumos e episódios à sessão (/actor/{actorId}/session/{sessionId}/), pois são específicos de cada conversa
• Use namespace para match exato quando souber o caminho preciso, e namespacePath para recuperação hierárquica quando precisar buscar em uma subárvore
• Use barras no início e no fim dos caminhos para manter consistência e evitar colisões de prefixo
• Use as condition keys do IAM (bedrock-agentcore:namespace e bedrock-agentcore:namespacePath) para controlar quais namespaces podem ser acessados

Para aprofundar, a AWS disponibiliza a documentação de organização do AgentCore Memory, a documentação de organização de memória de longo prazo e o repositório de exemplos no GitHub.

Fonte

Organizing Agents’ memory at scale: Namespace design patterns in AgentCore Memory (https://aws.amazon.com/blogs/machine-learning/organizing-agents-memory-at-scale-namespace-design-patterns-in-agentcore-memory/)