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 oferece aos seus agentes de AI memória de longo prazo entre 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.

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-o entre agentes e projetos.
Melhorar a precisão e a eficiência 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 é 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 dentro do escopo que você consulta.

Memória pessoal: Use um ID de usuário final como escopo para que cada usuário obtenha sua própria memória privada, como suas preferências e decisões anteriores. Os usuários somente veem suas próprias entradas.
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 com memória gerenciada

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

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

Start from a template
Add the skill to an existing project

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/.

Clonar o repositório de padrões:

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

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.

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.

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

Crie o diretório de habilidades se ele não existir:
Bash
```
mkdir -p .claude/skills/managed-memory
```
Baixe o arquivo SKILL.md do diretório de habilidadesmanaged-memory e salve-o em .claude/skills/managed-memory/.
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 armazenamento de memória

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.

Gerar um token OAuth usando a CLI do Databricks para chamar as APIs:
Bash
```
databricks auth login --host ${DATABRICKS_HOST}
databricks auth token
```

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"
  }'

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"
  }'

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.

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={
     &quot;memory_store&quot;: {&quot;name&quot;: &quot;main.default.support_agent_memory&quot;},
     &quot;scope&quot;: {&quot;kind&quot;: &quot;user&quot;, &quot;value&quot;: user_id},
 },
)

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)

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.

Implementar memória de curto prazo

As APIs de entrada de memória fornecem memória de longo prazo apenas. Para conceder memória de curto prazo ao seu agente em uma sessão, use um dos seguintes:

Persista o estado da sessão no lado do servidor com uma conversação.
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.

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

Requisitos​

Como a memória gerenciada funciona​

Escopo​

Começar com memória gerenciada​

Criar e usar um armazenamento de memória​

Adicionar memória a um agente com conversas​

Controle de acesso à memória​

Implementar memória de curto prazo​

Limitações​

Próximos os passos​