Memória gerenciada do agente

info

Beta

Este recurso está em Beta. Os administradores de workspace podem controlar o acesso a este recurso na página **Pré-visualizações**. Consulte Gerenciar prévias do Databricks.

A memória gerenciada do agente fornece aos seus agentes memória de longo prazo em todas as conversas. O Databricks executa a infraestrutura e isola as memórias de cada escopo, para que você não precise gerenciar o armazenamento ou o particionamento por conta própria.

Com a memória gerenciada, seus agentes podem:

• Lembre-se das preferências do usuário, decisões passadas e contexto acumulado em todas as conversações.
• Proteja esse conhecimento com a governança do Unity Catalog.
• Compartilhe memória entre agentes e projetos.
• Melhore a precisão e a eficiência deles ao longo do tempo.

Requisitos

• Um workspace da Databricks com o Unity Catalog habilitado.
• O privilégio CREATE MEMORY STORE no esquema pai para criar armazenamentos de memória.

Como a memória gerenciada funciona

A memória gerenciada possui dois níveis:

• Um memory store é um ativo protegível do Unity Catalog que atua como um contêiner para entradas de memória. Um memory store herda a mesma governança, controle de acesso e linhagem que qualquer outro ativo do Unity Catalog.
• Uma entrada de memória é uma peça individual de conteúdo armazenada dentro de um armazenamento de memória. Cada entrada é identificada por um escopo e um caminho. O escopo determina a quais memórias uma entrada pertence, e o caminho organiza as entradas dentro de um escopo, semelhante a um caminho de arquivo (por exemplo, /memories/preferences.md).

Escopo

O escopo é a forma como você torna uma memória privada para um usuário ou compartilhada entre um grupo. Sua aplicação define um escopo em cada leitura e escrita, e uma pesquisa retorna apenas entradas com um escopo correspondente. Escolha a estratégia que corresponde ao que seu agente precisa lembrar:

• Memória privada para cada usuário: defina o escopo para a identidade verificada do usuário final. Cada usuário obtém sua própria partição e vê apenas suas próprias entradas. O valor user_client resolve o ID do usuário final para você.

  • Exemplo: Um agente de suporte lembra-se das preferências de comunicação e dos tíquetes anteriores de um usuário.

• Memória compartilhada para um grupo: Defina o escopo para uma key fixa de sua escolha, como um ID de organização, equipe ou projeto. Cada usuário lê e grava as mesmas memórias.

  • Exemplo: Um agente de equipe lembra de um glossário compartilhado de termos da empresa e políticas internas.

• Divisão de memória por outro critério: Crie o escopo a partir de seus próprios valores, como um ID de tenant ou um composto user_id:project.

  • Exemplo: Um aplicativo multi-tenant mantém a memória de cada cliente separada, ou a memória de um único usuário é isolada por projeto.

Um único agente pode combinar estratégias em uma conversa. Por exemplo, ele pode ler a memória privada de um usuário e a memória compartilhada de uma equipe na mesma solicitação.

Defina o escopo no código do seu aplicativo, a partir de um contexto de chamador confiável que a solicitação não possa adulterar: a identidade verificada do usuário final do token OBO para memória por usuário, ou uma chave de tenant, equipe ou projeto confiável para memória compartilhada. Nunca deixe o modelo escolhê-lo. Se sua estratégia de escopo depender de uma identidade de usuário final, rejeite solicitações que não a possuam em vez de recorrer a um escopo compartilhado. A managed-memory skill orienta você durante essa configuração.

O escopo separa memórias, mas não concede acesso ao armazenamento. Um chamador ainda precisa do privilégio READ MEMORY STORE ou WRITE MEMORY STORE para abri-lo. Consulte Controle de acesso à memória.

atenção

O escopo é o limite de isolamento entre usuários, mas não é um controle de acesso. O service principal do Databricks do aplicativo pode ler todos os escopos, portanto, proteja sua credencial adequadamente.

O que o agente salva e recupera

A memória gerenciada fornece o armazenamento de memória e as APIs para leitura e gravação de entradas. Sua aplicação controla o que o agente salva, quando ele recupera a memória e como ele usa os resultados.

Defina esse comportamento no prompt do sistema do agente: instrua o agente sobre quais informações duráveis salvar e quando recuperá-las. A skill e os padrões managed-memory mantêm este prompt do sistema em uma constante chamada MEMORY_INSTRUCTIONS. O escopo é configurado separadamente no código da aplicação confiável e nunca é escolhido pelo modelo.

Corresponda a redação à sua estratégia de escopo. O exemplo a seguir é para a estratégia por usuário:

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Começar a usar habilidades de memória gerenciada

A maneira mais fácil de adicionar memória gerenciada a um agente é a habilidade Claude Code managed-memory. A habilidade cuida de toda a configuração para você e funciona com o OpenAI Agents SDK e o LangGraph.

Obtenha a habilidade em seu projeto de uma das duas maneiras:

Start from a template

A habilidade é fornecida nos padrões de aplicativo Databricks. Estruture um novo agente a partir de um dos padrões de agente, encontre a habilidade em .claude/skills/managed-memory/.

1. Clonar o repositório de padrões:

   Bash

   git clone https://github.com/databricks/app-templates.git

2. Navegue em app-templates, selecione um padrão de agente para começar. Por exemplo, para usar o padrão OpenAI Agents SDK:

   Bash

   cd app-templates/agent-openai-agents-sdk

nota

Para padrões de aplicativo "avançados", depois de implantar, você deve conceder à entidade de serviço do aplicativo privilégios do Lakebase Postgres, caso contrário, a configuração da sessão retornará um erro 502.

3. Depois que a habilidade estiver no seu projeto, descreva o que você deseja e seu assistente de codificação cuida do resto:

prompt

Add Databricks managed long-term memory to my agent.

Add the skill to an existing project

Se você já tiver um projeto de agente, adicione a habilidade a ele.

1. Crie o diretório de habilidades se ele não existir:

   Bash

   mkdir -p .claude/skills/managed-memory

2. Baixe o arquivo SKILL.md do diretório de habilidadesmanaged-memory e salve-o em .claude/skills/managed-memory/.

3. Depois que a habilidade estiver no seu projeto, descreva o que você deseja e seu assistente de codificação cuida do resto:

prompt

Add Databricks managed long-term memory to my agent.

Criar e usar um repositório de memória manualmente

Esta seção mostra como criar e usar um armazenamento de memória sem a managed-memory habilidade Claude Code.

O exemplo a seguir configura memória gerenciada para um agente de suporte ao cliente que armazena as preferências de um usuário e as recupera em uma conversa posterior.

1. Gerar um token OAuth usando a CLI do Databricks para chamar as APIs:

   Bash

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token

2. Crie um armazenamento de memória para guardar as memórias do seu agente:

   Bash

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'

3. Escreva uma entrada de memória depois que o agente aprender algo sobre um usuário. O scope particiona a entrada para um único usuário. Use o campo contents para o texto de memória completo e o description como um breve resumo que melhora a recuperação:

   Bash

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'

4. Pesquise entradas de memória para esse usuário em uma conversa posterior para recuperar o que o agente aprendeu:

   Bash

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'

Para a API REST completa, incluindo endpoints, campos de solicitação e campos de resposta, consulte a referência da API de memória.

Adicionar memória a um agente com conversas

O fluxo de trabalho REST acima chama as APIs de armazenamento de memória e de entrada diretamente. Ao criar um agente em um endpoint de **servindo modelo** do Databricks, conecte um armazenamento de memória a uma *conversa* com o cliente compatível com OpenAI no SDK, em vez databricks-openai disso.

Uma conversa é um estado de conversa compatível com OpenAI — a história em execução de mensagens e chamadas de ferramenta — apoiada por um armazenamento de memória e com pin em um único escopo. Reutilize a mesma conversa em várias solicitações para dar memória ao agente de interações anteriores.

1. Vincule um armazenamento de memória existente e um escopo a uma nova conversa. memory_store.name é o nome de três níveis do armazenamento, e scope particiona o estado da conversa, normalmente por usuário final:

   Python

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
        "memory_store": {"name": "main.default.support_agent_memory"},
        "scope": {"kind": "user", "value": user_id},
    },
   )

2. Passe o ID da conversação para responses.create. O agente lê e escreve o estado da conversação no armazenamento de memória vinculado sob esse escopo:

   Python

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)

3. Reutilize o mesmo ID de conversa em solicitações posteriores para que o agente se lembre de interações anteriores. Não crie uma nova conversa por interação:

   Python

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)

Para os endpoints de conversação e campos de solicitação, consulte APIs de Conversação.

Controle de acesso à memória

Os armazenamentos de memória são objetos protegíveis do Unity Catalog. Os privilégios a seguir controlam o acesso:

Privilégio	Aplica-se a	Descrição
CREATE MEMORY STORE	Esquema pai	Crie novos armazenamentos de memória sob um esquema.
READ MEMORY STORE	Armazenamento de memória	Leia os metadados de um armazenamento de memória e suas entradas.
WRITE MEMORY STORE	Armazenamento de memória	Crie, atualize e exclua entradas de memória em um armazenamento.
MANAGE	Armazenamento de memória	Atualize ou exclua o próprio memory store. Conceda permissões a outros usuários.
USE SCHEMA	Esquema pai	Listar armazenamentos de memória em um esquema.

Privilégio	Aplica-se a	Descrição
CREATE MEMORY STORE	Esquema pai	Crie novos armazenamentos de memória sob um esquema.
READ MEMORY STORE	Armazenamento de memória	Leia os metadados de um armazenamento de memória e suas entradas.
WRITE MEMORY STORE	Armazenamento de memória	Crie, atualize e exclua entradas de memória em um armazenamento.
MANAGE	Armazenamento de memória	Atualize ou exclua o próprio memory store. Conceda permissões a outros usuários.
USE SCHEMA	Esquema pai	Listar armazenamentos de memória em um esquema.

Implementar memória de curto prazo

As APIs de entrada de memória fornecem memória de longo prazo como ferramentas para o seu agente usar. Para fornecer ao seu agente memória de curto prazo gerenciada em uma sessão, o Databricks recomenda associar seu armazenamento de memória a uma conversação. Também é possível:

• Mantenha a memória de sessão da estrutura do seu agente, como o parâmetro session= do OpenAI ou um checkpointer LangGraph.
• Use memória de agente autogerenciada para o armazenamento do histórico da conversa.

Recomendações de segurança

A Databricks oferece o armazenamento governado, a criptografia, as primitivas de isolamento e a trilha de auditoria. Como desenvolvedor de aplicativos, a Databricks recomenda o seguinte:

• Use o default do escopo por usuário (user_client), a menos que você tenha um motivo deliberado para particionar de forma diferente (por exemplo, memória por projeto ou por account).
• Conceda o menor privilégio: apenas o service principal do Databricks do seu agente precisa de WRITE MEMORY STORE. Conceda READ MEMORY STORE de forma restrita e evite concessões amplas a usuários humanos ou grandes grupos.
• Proteja a credencial do Service Principal do aplicativo Databricks: é a chave para o plano de dados do armazenamento. Trate-a como qualquer credencial de serviço de alto valor — use tokens de curta duração, evite registrá-la e adicione defesas SSRF ao seu aplicativo.

Limitações

• As entradas de memória fornecem memória de longo prazo apenas. Para a diferença entre memória de curto e longo prazo, consulte Memória de curto e longo prazo.
• Armazenamentos e entradas de memória são criados e gerenciados apenas através da API REST do Unity Catalog; não há SDK Python para essas APIs. Para usar um armazenamento de memória de um agente, conecte-o a uma conversa com o cliente compatível com OpenAI. Consulte Adicionar memória a um agente com conversas.

Próximos os passos

• Referência da API de Memória