AWS Builder Center

Builder Center

Primeiros Passos com o Amazon Bedrock AgentCore Memory

Primeiros Passos com o Amazon Bedrock AgentCore Memory

Um tutorial prático mostrando como criar um recurso de memória, gravar eventos de conversa e recuperar insights de longo prazo extraídos automaticamente com Python e o SDK do AgentCore.

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (7 articles)

  1. 1
    Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
  2. …
  3. 7
    Primeiros Passos com o Amazon Bedrock AgentCore Memory This article

Carlos Biagolini

AWS Solutions Architect

Introdução

Agentes de IA são stateless por padrão. Cada interação começa do zero, sem conhecimento de conversas anteriores. Isso cria uma experiência frustrante para os usuários, que precisam se repetir, enquanto o agente não consegue aprender preferências nem acompanhar questões em andamento entre sessões.
Amazon Bedrock AgentCore Memory  resolve esse problema fornecendo um serviço de memória totalmente gerenciado para agentes de IA. Ele lida tanto com short-term memory (turnos de conversa dentro de uma sessão) quanto com long-term memory (insights extraídos e persistidos entre sessões). Você não precisa construir ou gerenciar nenhuma infraestrutura para isso.
Este artigo faz parte de uma série que estou escrevendo sobre diferentes aspectos do Amazon Bedrock AgentCore. Aqui, focamos em como usar o Memory para dar aos agentes a capacidade de lembrar informações entre conversas. Para uma compreensão mais ampla do AgentCore e seus componentes, confira os outros artigos desta série:
Neste artigo, exploramos o Memory sob duas perspectivas:
  • Primeiro, usamos o Memory localmente via scripts Python, demonstrando como gravar eventos de conversa e recuperar insights extraídos programaticamente.
  • Depois, habilitamos o Memory no Harness da concessionária de carros introduzido no primeiro artigo  e mostramos o agente lembrando preferências do cliente entre sessões.

O que é AgentCore Memory?

AgentCore Memory é um dos serviços modulares do Amazon Bedrock AgentCore . Ele oferece dois tipos de memória:
Short-term memory armazena interações turno a turno dentro de uma única sessão. Isso permite que os agentes mantenham contexto imediato. Por exemplo, quando um cliente pergunta "Vocês têm carros vermelhos?" e em seguida diz "E na categoria SUV?", o agente usa a short-term memory para entender que o cliente ainda está perguntando sobre carros vermelhos.
Long-term memory extrai e armazena automaticamente insights importantes de conversas ao longo de múltiplas sessões. Por exemplo, se um cliente menciona que tem um orçamento de $25.000 e prefere SUVs, o agente armazena essas preferências e pode usá-las proativamente em interações futuras sem que o cliente precise se repetir.

Como Funciona

  1. Você cria um recurso de memória com uma ou mais estratégias
  2. Seu agente grava eventos (turnos de conversa) na memória
  3. O AgentCore analisa automaticamente esses eventos e extrai insights relevantes para a long-term memory
  4. Seu agente pode posteriormente recuperar esses insights via listagem ou busca semântica

Memory Strategies

As estratégias definem quais informações o AgentCore extrai das conversas:
  • Semantic — Extrai informações factuais e as armazena para recuperação via busca semântica
  • User Preferences — Identifica e armazena preferências, escolhas e estilos do usuário
  • Session Summaries — Cria resumos condensados das sessões de conversa

Pré-requisitos

  • Conta AWS com credenciais configuradas
  • Usuário ou role IAM com permissões para usar o Amazon Bedrock AgentCore Memory. Para detalhes, consulte o guia de início com Memory 
  • Python 3.12 instalado
  • Região AWS onde o AgentCore está disponível (us-east-1, us-west-2, ap-southeast-2 ou eu-central-1)

Step 1: Clonar o Repositório e Instalar Dependências

Clone o repositório complementar e configure o ambiente Python:
1
2
3
4
5
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreMemory.git
cd PythonAwsBedrockAgentCoreMemory
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
No Windows, substitua o comando de ativação por .venv\Scripts\activate.

Step 2: Criar um Recurso de Memory

Um recurso de memória precisa de pelo menos uma estratégia para extrair insights de longo prazo.

2.1 Navegar até Memory

2.1.1. Abra o console do Amazon Bedrock AgentCore 
2.1.2. No painel de navegação à esquerda, em Build, clique em Memory
2.1.3. Clique no botão Create memory
Console do Amazon Bedrock AgentCore mostrando a opção Memory em Build no painel de navegação esquerdo e o botão Create memory para iniciar um novo recurso de memória
Navegação até a seção Memory e início da criação de um novo recurso de memória

2.2 Configurar o Memory

2.2.1. No campo Memory name, digite car_memory. Os caracteres válidos são a-z, A-Z, 0-9 e _ (underscore). Máximo de 48 caracteres.
2.2.2. No campo Short-term memory (raw event) expiration, defina a duração em dias. Isso define por quanto tempo os eventos de short-term memory são retidos antes de expirar. Defina como 90 dias para este tutorial (intervalo válido: 3 a 365 dias).
2.2.3. Em Long-term memory extraction strategies, clique em Add strategy na seção Built-in strategies. As estratégias de extração disponíveis são:
  • Summarization — Condensa interações em insights-chave. Recomendada para reter pontos essenciais de conversas longas sem armazenar cada detalhe.
  • Semantic — Extrai conhecimento factual geral, conceitos e significados das conversas. Recomendada para construir uma base de conhecimento de fatos e relacionamentos mencionados pelos usuários.
  • User preferences — Extrai padrões de comportamento e escolhas pessoais do usuário. Recomendada para personalizar interações futuras com base em preferências declaradas (cores, orçamentos, estilos).
  • Episodic — Transforma eventos em episódios estruturados para ajudar agentes a aprender com ações passadas. Recomendada para agentes orientados a ação que precisam melhorar com base em experiência operacional.
Para mais detalhes, consulte Memory strategies .
Para este tutorial, selecione Semantic — ela extrairá fatos como orçamento do cliente, tipo de veículo preferido e outros detalhes da conversa.
2.2.4. No campo Strategy name, digite CustomerFacts
2.2.5. Para o Namespace template, mantenha o valor padrão /strategies/{memoryStrategyId}/actors/{actorId}/. O namespace define como as memórias de longo prazo são organizadas. As variáveis entre chaves são resolvidas automaticamente: {memoryStrategyId} identifica qual estratégia extraiu a memória, e {actorId} identifica a quem a memória pertence. Isso significa que os fatos extraídos de cada cliente são armazenados separadamente, evitando que dados se misturem entre diferentes usuários. Para mais detalhes sobre organização de namespaces, consulte Memory organization in AgentCore Memory .
2.2.6. Clique em Create memory
A página de criação também mostra duas seções adicionais de estratégias que deixamos vazias para este tutorial:
  • Built-in strategy with override — Permite substituir a lógica de extração padrão fornecendo seus próprios prompts e selecionando um modelo de fundação específico. A invocação do modelo é executada na sua conta. Útil quando você precisa de controle refinado sobre o que é extraído (por exemplo, extrair preferências de voo muito específicas para um agente de viagens). Para detalhes, consulte Configure a custom strategy .
  • Self-managed strategy — Oferece controle completo sobre o pipeline de processamento de memória. O AgentCore armazena eventos e entrega payloads em lote para seu bucket S3 com notificações SNS, e você define a lógica de extração no seu próprio ambiente. Útil para pipelines complexos que requerem modelos de ML customizados ou lógica de negócio além do que as estratégias built-in oferecem. Para detalhes, consulte Self-managed strategy .
Para a maioria dos casos de uso, as estratégias built-in (configuradas acima) são suficientes.
Formulário de criação de memória mostrando o campo de nome, a expiração dos eventos de curto prazo em dias e a estratégia de extração de longo prazo Semantic configurada
Configuração do nome da memória, da expiração de curto prazo e da estratégia de extração Semantic para a memória de longo prazo
Aguarde até que o status da memória mude para Active (isso normalmente leva 2-3 minutos).

2.3 Copiar o Memory ID

Após a criação, o console exibe a página de detalhes da memória. Copie o valor do Memory ID. Você usará esse identificador nos próximos passos.
A página de detalhes também mostra trechos de código para integração (Python, TypeScript, JavaScript), estratégias de long-term memory e métricas de observabilidade.

Step 3: Gravar Eventos de Conversa

Agora vamos simular uma conversa entre um cliente e nosso agente da concessionária, e gravá-la na memória.

3.1 Configurar Variáveis de Ambiente

Copie o arquivo de exemplo de variáveis de ambiente e adicione seu Memory ID:
1
cp .env.example .env
Edite o .env:
1
2
AWS_REGION=us-east-1
MEMORY_ID=<your-memory-id>
Substitua <your-memory-id> pelo Memory ID que você copiou do console no Step 2.3.

3.2 Executar o Script

1
# code/write_events.py
Execute o script:
1
python write_events.py
Isso grava uma conversa onde um cliente pergunta sobre SUVs e menciona seu orçamento. O AgentCore armazena os turnos como short-term memory e começa a analisá-los para extrair insights para a long-term memory.
Saída esperada:
1
2
3
4
5
6
7
Writing conversation to memory...
Conversation written to memory.

--- Short-term Memory (last turns) ---
[ASSISTANT] Based on your budget and color preferences, I'd recommend looking at our Toyota RAV4 2022 in silver with 28,000 miles, or the Honda CR-V 2021 in white with 32,000 miles. Both are well within your budget.
[USER] I'm looking for a reliable SUV under $25,000. I prefer something with low mileage, ideally in white or silver.
[ASSISTANT] Welcome to our dealership! How can I help you find your next car?

Step 4: Recuperar a Long-term Memory

Após gravar os eventos, o AgentCore os processa e extrai fatos relevantes para a long-term memory. Isso acontece de forma assíncrona e normalmente leva de 20 a 40 segundos.
1
# code/retrieve_memory.py
Execute o script:
1
python retrieve_memory.py
Saída esperada:
1
2
3
4
5
6
7
8
9
10
11
12
13
Writing conversation to memory...
Conversation written to memory.

--- Short-term Memory (last turns) ---
[ASSISTANT] Based on your budget and color preferences, I'd recommend looking at our Toyota RAV4 2022 in silver with 28,000 miles, or the Honda CR-V 2021 in white with 32,000 miles. Both are well within your budget.
[USER] I'm looking for a reliable SUV under $25,000. I prefer something with low mileage, ideally in white or silver.
[ASSISTANT] Welcome to our dealership! How can I help you find your next car?
((.venv) ) biagolini@workstation code % python retrieve_memory.py
Waiting for long-term memory extraction (about 30 seconds)...

--- Long-term Memory Records ---

--- Semantic Search: 'budget' ---
Note que nunca dissemos explicitamente ao sistema o que memorizar. A estratégia semântica analisou a conversa e identificou os fatos importantes por conta própria. Em interações futuras, o agente pode recuperar esses fatos sem reproduzir todo o histórico da conversa.

Step 5: Integrar Memory com o Harness

Agora habilitamos o Memory no Harness da concessionária para que o agente automaticamente lembre informações do cliente entre sessões.

5.1 Editar o Harness

5.1.1. Navegue até Amazon Bedrock AgentCore > Harness
5.1.2. Clique no nome do seu Harness (car_agent) para abrir a página de detalhes
5.1.3. Clique em Edit na área superior direita
5.1.4. Na seção Memory, habilite o Memory e selecione seu recurso de memória (ex.: car_memory)
5.1.5. Clique em Save Harness e aguarde o status retornar para Ready
Interface de teste do Harness mostrando a primeira conversa em que o cliente descreve suas necessidades e o agente armazena o contexto na memória
Primeira sessão em que o cliente compartilha preferências que o agente armazena na memória de longo prazo sob o Actor ID informado

5.2 Testar Memory Entre Sessões

5.2.1. Quando o Harness estiver Ready, clique no botão Test Harness
5.2.2. Na interface de teste, observe o campo Actor ID abaixo da seção Memory. Este campo identifica a qual usuário a memória pertence. Cada actor recebe short-term e long-term memory isoladas, o que significa que clientes diferentes não verão os dados uns dos outros. Para este teste, digite customer-abc123 como Actor ID.
5.2.3. Na primeira sessão, peça orientação ao agente:
1
Hi, my name is Bob. I'm thinking about buying a used car but I'm not sure if I should go for an SUV or a Sedan. Can you explain the main differences between them and the strengths and weaknesses of each?
Interface de teste do Harness mostrando uma nova sessão com o mesmo Actor ID em que o agente recupera as preferências do cliente da conversa anterior
Segunda sessão com o mesmo Actor ID em que o agente recupera o contexto do cliente armazenado durante a conversa anterior
5.2.4. Feche esta sessão. Inicie uma nova sessão (clique em New session > Stop current session and create new session). Mantenha o mesmo Actor ID (customer-abc123) para que o agente possa recuperar as memórias da sessão anterior.
5.2.5. Na nova sessão, faça uma pergunta sem repetir suas preferências:
1
Do you have anything that might work for me?
5.2.6. Como não configuramos acesso a um banco de dados de inventário, o agente não conseguirá listar carros específicos. No entanto, nos blocos de raciocínio do agente, você pode observar que ele recuperou informações da conversa anterior (o interesse do Bob em SUVs e Sedans). O agente fará perguntas de acompanhamento para refinar a busca, demonstrando que ele lembra o contexto da sessão anterior. Para aprender como fornecer ao agente acesso a ferramentas externas como um banco de dados de inventário, consulte o artigo sobre Gateway .

Step 6: Limpeza

Se você não pretende continuar usando os recursos criados neste tutorial, é uma boa prática removê-los da sua conta. Se você planeja usar o AgentCore Memory em produção, verifique a página de preços do AgentCore  para detalhes de cobrança atualizados.
Para remover os recursos:
  • Remova o Memory do Harness (edite o Harness, desabilite o Memory e salve)
  • Navegue até Amazon Bedrock AgentCore > Memory, selecione seu recurso de memória e clique em Delete

Conclusão

Neste artigo, você aprendeu como usar o Amazon Bedrock AgentCore Memory para dar aos agentes a capacidade de lembrar:
  • Short-term memory armazena turnos de conversa dentro de uma sessão, mantendo o contexto imediato.
  • Long-term memory extrai automaticamente fatos e preferências das conversas e os persiste entre sessões.
  • Invocação local permite que desenvolvedores gravem eventos e recuperem insights programaticamente usando o MemorySessionManager.
  • Integração com Harness permite que o agente use o Memory automaticamente, lembrando preferências do cliente entre sessões sem código adicional.
O insight principal é que você apenas grava os turnos brutos da conversa. O AgentCore cuida da extração de fatos significativos, preferências e resumos para a long-term memory automaticamente com base nas estratégias que você configurar. Isso é particularmente poderoso para o cenário da concessionária: o agente pode lembrar o orçamento de cada cliente, tipo de veículo preferido, preferências de cor e interações passadas, proporcionando uma experiência personalizada em cada visita.

Referências

Fique Conectado

Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura cloud, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos futuros e tutoriais:
Fique ligado para mais walkthroughs práticos e soluções para desafios de infraestrutura cloud e DevOps.
Happy building on AWS! 🚀☁️
# ai# agentic-ai# ai-agents# amazon-bedrock# agents

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (7 articles)

  1. 1
    Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
  2. …
  3. 7
    Primeiros Passos com o Amazon Bedrock AgentCore Memory This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article