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 de agente gerenciada fornece aos seus agentes de AI memória de longo prazo em todas as conversas. A 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

Escopo é como a memória gerenciada mantém as memórias de um agente separadas para diferentes usuários ou grupos. Cada entrada de memória pertence a exatamente um escopo, e uma pesquisa retorna apenas entradas no escopo que você consulta.

• Memória pessoal: Use um ID de usuário final como escopo para que cada usuário tenha sua própria memória privada, como suas preferências e decisões passadas. Os usuários veem apenas suas próprias entradas. O valor de escopo user_client recupera automaticamente o ID do usuário final.
• Conhecimento organizacional: Use uma key compartilhada, como um ID de organização ou equipe, para armazenar conhecimento que qualquer usuário do agente possa utilizar, como fatos da empresa, glossários e melhores práticas.

Um único agente pode usar ambos ao mesmo tempo: ler de um escopo pessoal de usuário e de um escopo organizacional compartilhado na mesma conversa. scope é necessário em cada solicitação de entrada de memória.

atenção

O escopo é o limite de isolamento entre usuários. Configure o escopo em código confiável e nunca permita que o modelo o defina. A entidade de serviço Databricks do aplicativo pode ler todos os escopos.

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