Memória do agente

Importante

Esse recurso está em Beta.

A memória do agente dá aos seus agentes memória de longo prazo que persiste entre as conversas. O Azure Databricks armazena a memória no Lakebase e gerencia o armazenamento, indexação e busca para você, para que seus agentes possam lembrar das preferências do usuário, decisões passadas e contexto acumulado sem que você opere um banco de dados.

Note

Durante a prévia, você é cobrado pela instância Lakebase subjacente que armazena suas entradas de memória. Não se aplicam cobranças adicionais pela memória do agente em si. Os preços podem variar conforme a prévia avança.

Use a memória dos agentes quando quiser que seus agentes:

Lembre-se das preferências dos usuários, fatos e decisões em conversas separadas.
Personalize as respostas com base no que o agente aprendeu em sessões anteriores.
Compartilhe o conhecimento acumulado entre agentes e projetos.
Melhorar a precisão e a eficiência ao longo do tempo.

A memória de agentes funciona com agentes construídos em qualquer framework. Para histórico de conversas de curto prazo dentro de uma única interação, use sessões de agente.

Requirements

Instale o Python 3.10 ou superior para usar o SDK AgentKit. AgentKit SDK é o cliente Python do Databricks para APIs de agentes, que os exemplos abaixo utilizam. Você também pode chamar a API REST diretamente de qualquer linguagem, sem necessidade de Python.
Para usar memory_store.put() ou memory_store.list(path=...), instale databricks-agentbricks versão 0.6.0 ou superior.

Como funciona a memória dos agentes

Hierarquia de recursos de memória do agente: um armazenamento de memória contém muitas entradas de memória, cada uma identificada por actor_id, session_id opcional e caminho, contendo conteúdo e uma descrição.

A memória do agente possui dois níveis:

Um armazenamento de memória é o contêiner com escopo de workspace para as memórias de um agente. Criar um repositório provisiona automaticamente o armazenamento subjacente do Lakebase. Você identifica uma loja pela ID da loja, que você escolhe ao criar a loja.
Uma entrada de memória é um item de conteúdo individual em uma loja. Cada entrada possui um texto livre content, uma description curta usada para recuperação e um conjunto de campos que a organizam e particionam:
- actor_id (obrigatório): a quem pertence a memória, como um usuário final ou outro agente.
- session_id (opcional): a sessão à qual a memória pertence. Deixe sem definir para memória que se aplica ao longo das sessões do ator.
- path (obrigatório): um caminho semelhante a um sistema de arquivos que organiza entradas dentro de um ator, como /preferences/response-style.md.

Uma entrada é identificada de forma única pela combinação de actor_id, session_id, e path. O mesmo caminho sob duas sessões diferentes, ou sob uma sessão e sem uma, comporta duas entradas separadas.

As entradas chegam a um armazenamento de duas formas: seu agente ou o aplicativo as escreve diretamente, ou um pipeline de memória as destila das conversas em um armazenamento de sessão.

Recuperação

Recuperar memória de duas formas:

Liste entradas para um ator, opcionalmente filtradas por session_id, um prefixo path ou um path exato. Use isso para navegar ou renderizar um índice do que um agente sabe.
Pesquise entradas sobre um ator usando uma consulta em linguagem natural. A busca retorna as entradas mais relevantes ordenadas por pontuação de relevância.

Um filtro session_id em uma das operações retorna apenas as entradas salvas nessa sessão. Ele não retorna entradas salvas sem uma sessão.

Introdução

Os exemplos do SDK AgentKit e da API REST configuram a memória do agente para um agente de suporte: eles criam um armazenamento de memória, salvam a preferência do usuário e a recuperam em uma conversa posterior. O exemplo da CLI Agent Bricks conecta um armazenamento de memória a um agente que você constrói e implanta com a CLI. Escolha o cliente que se encaixe no seu projeto. O ID de um armazenamento de memória deve ter de 3 a 56 caracteres, começar com uma letra minúscula, terminar com uma letra ou número, e conter apenas letras minúsculas, números e hífens.

AgentKit SDK

O SDK AgentKit é o cliente Python do Databricks para APIs de agentes, distribuído no databricks-agentbricks pacote. Ele se autentica com o WorkspaceClient do SDK do Databricks.

Instale o SDK do AgentKit:
```
pip install databricks-agentbricks
```

Crie um armazenamento de memórias para seu agente. AgentKitClient Autentica com suas WorkspaceClient credenciais:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

Salve uma memória depois que o agente aprende algo duradouro sobre um usuário. actor_id é de quem é esta memória, path a organiza dentro desse ator e description melhora a recuperação:
```
memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)
```
add() falha com o erro ALREADY_EXISTS se uma entrada já existir nesse caminho. Para criar a entrada ou atualizar a existente, chame memory_store.put() com os mesmos argumentos.

Recupere as memórias do usuário em uma conversa futura usando uma busca em linguagem natural:

results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

API REST

Os clientes acessam a API REST em /api/2.0/agents/memory-stores. Chame-o diretamente em linguagens que não sejam Python.

Gerar um token OAuth com a CLI do Databricks:

databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

Crie um armazenamento de memórias para seu agente:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores?managed_memory_store_id=support-agent-memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"description": "Support agent memory"}'

Salve uma entrada de memória para um usuário. actor_id é de quem é esta memória, path a organiza e description melhora a recuperação:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

Se uma entrada já existir nesse caminho, a solicitação falha com ALREADY_EXISTS (HTTP 409). Para atualizar a entrada existente em vez disso, procure-a pelo caminho. A pesquisa retorna as entradas do caminho para cada sessão; então, escolha uma cujo session_id corresponda. O último segmento do seu name é o ID da entrada:

curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  --data-urlencode "actor_id=user-123" --data-urlencode "path=/preferences/communication.md"

Depois, atualize o conteúdo da entrada pelo seu ID:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries/<entry-id>?update_mask=content" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"content": "Prefers email over phone. Timezone: PST."}'

Lembre-se das memórias do usuário com uma busca em linguagem natural:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

Bricks do Agente

Se você criar seu agente com a CLI do Bricks do Agente, agentbricks init declara um armazenamento de memória em agent.toml. agentbricks deploy cria o armazenamento se ele ainda não existir e concede ao agente implantado acesso a ele.

Escolha um caminho:

Começar vazio (a maioria dos agentes): implante o agente. agentbricks deploy cria o armazenamento de memória que agentbricks init declarou. Para implantar um agente chamado my-agent, execute o seguinte:
```
agentbricks deploy my-agent
```
Comece com memórias já existentes no store: crie o store, adicione entradas, depois vincule o store ao agente e faça deploy.
1. Para criar uma loja chamada my-agent-memory, execute o seguinte. A saída inclui o ID da loja, um identificador gerado que é separado do nome da loja:
```
agentbricks memory stores create --name my-agent-memory
```
2. Para adicionar uma entrada, execute o seguinte, substituindo <store-id> pelo ID da loja da etapa anterior:
```
agentbricks memory entries create --store <store-id> --actor-id you@example.com \
  --path /preferences/style.md --content "Prefers Python and concise answers with code examples."
```
3. Para associar o armazenamento e implantar o agente, execute o seguinte. agentbricks memory bind substitui o nome da loja em agent.toml, e agentbricks deploy encontra a loja existente pelo nome e a usa em vez de criar uma nova:
```
agentbricks memory bind my-agent-memory
agentbricks deploy my-agent
```

--path é a chave da entrada dentro do armazenamento, não um arquivo na sua máquina. --actor-id é o usuário a quem a memória pertence. Um agente implantado usa o e-mail do usuário logado como ID do ator, então preencha cada entrada com o e-mail do usuário que conversa com o agente.

No Agent Bricks CLI, memory bind e agentbricks deploy referem-se a uma loja pelo nome. Comandos que atuam em uma única store, como memory entries create, recebem o ID da store gerada.

Dê ao seu agente ferramentas de memória

Para permitir que um agente decida quando salvar e recuperar memória, envolva as operações do cliente como ferramentas e instrua o agente sobre quando usá-las no prompt do sistema. Defina o actor_id no código de aplicação confiável com base na identidade verificada do usuário final. Nunca deixe o modelo escolher de quem é a memória que deve ser lida ou escrita.

O exemplo a seguir encapsula o AgentKit SDK memory_store de Get started como ferramentas do SDK OpenAI Agents.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences, recall them when relevant, and forget them when the user asks.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

put() cria a entrada, ou substitui o conteúdo da entrada que já está naquele caminho. Para adicionar o conteúdo como novas linhas, passe append=True. put() não é atômica, então gravações concorrentes no mesmo caminho podem sobrescrever umas às outras. list(path=...) retorna as entradas nesse caminho exato em cada sessão; então, forget_memory também exclui uma entrada salva no caminho em uma sessão.

O mesmo padrão funciona com o Claude Agent SDK e outras estruturas: envolver as operações de busca, put, list e exclusão da loja como o tipo de ferramenta da estrutura.

Se você também rodar um pipeline de memória no mesmo armazenamento de memória, o pipeline pode reescrever, mesclar, dividir ou excluir as entradas que seu agente salva para qualquer ator que ele processa.

Partição e memória segura

Dentro de uma loja, actor_id é a forma de separar quais memórias pertencem a quem. Cada lista e pesquisa está vinculada a um único actor_id, então escolha a estratégia que corresponda ao que seu agente precisa lembrar:

Memória privada para cada usuário: Definido actor_id para a identidade do usuário final verificado. Cada usuário recebe sua própria partição, e o agente só recupera as entradas desse usuário.
- Exemplo: Um agente de suporte lembra das preferências de comunicação de um usuário e dos tickets anteriores.
Memória compartilhada para um grupo: Defina actor_id para uma chave fixa que você escolher, como um ID de equipe, projeto ou organização. Todo mundo lê e escreve as mesmas memórias.
- Exemplo: Um agente da equipe lembra de um glossário compartilhado de termos da empresa e convenções internas.
Memória dividida por outra coisa: Construa actor_id a partir de seus próprios valores, como um ID de locatário ou um composto user:project.
- Exemplo: Um aplicativo multi-inquilino configura actor_id para {tenant}:{user} que os usuários de cada cliente permaneçam isolados uns dos outros.

Defina actor_id no código do seu aplicativo a partir do contexto do chamador confiável: a identidade verificada do usuário final para memória por usuário ou uma chave confiável de equipe ou projeto para memória compartilhada. Nunca deixe a modelo escolhê-la. Se sua estratégia depende da identidade de um usuário final, rejeite solicitações que não incluam essa identidade, em vez de recorrer a um actor_id compartilhado.

Warning

actor_id Separa memórias, mas não é um controle de acesso. Os armazenamentos de memória têm escopo de espaço de trabalho, então qualquer principal que possa acessar um armazenamento pode ler e escrever todas as entradas em todos os atores. A loja, não o ator, é o limite de segurança. Para isolamento estrito entre inquilinos ou usuários, crie um armazenamento de memória separado por cada limite.

Para permitir que outro principal, como o principal de serviço do seu agente, use uma loja, conceda acesso a ela com a operação de concessão de permissão da loja (memory_store.grant_permission(principal_id) no SDK AgentKit). Apenas o criador da loja ou um administrador do espaço de trabalho pode conceder acesso.

Limitations

A memória de agente fornece apenas memória de longo prazo. Para histórico de conversas de curto prazo, veja as sessões com agentes.
A busca classifica as entradas por relevância, combinando texto completo (BM25) e correspondência semântica sobre o conteúdo e a descrição de cada entrada. Ele retorna até 100 entradas e não suporta paginação.
O controle de acesso é aplicado no nível da loja. O controle de acesso por entrada e por ator não está disponível.
O controle de acesso à loja cobre as entradas da loja. Qualquer usuário do workspace pode listar e obter os armazenamentos de memória, incluindo seus IDs e descrições.
Você não pode mudar o ID de uma loja depois de criá-la. Somente description pode ser atualizado.

Próximas Etapas

Comentários

Esta página foi útil?

Última atualização em 2026-10-26