Pular para o conteúdo principal
Última atualização em

Memória do agente

info

Beta

Esse recurso está na versão Beta.

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

nota

Durante a visualização, você é cobrado pela instância do Lakebase subjacente que armazena suas entradas de memória. Não há cobranças adicionais pela memória do agente em si. Os preços estão sujeitos a alterações conforme o avanço da visualização.

Use a memória do agente quando você quiser que seus agentes:

  • Lembre-se de preferências, fatos e decisões do usuário em conversas separadas.
  • Personalize as respostas com base no que um 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 do agente funciona com agentes baseados em qualquer framework. Para uma história de conversa de curto prazo dentro de uma única interação, use sessões de agente.

Requisitos​

  • Instale o Python 3.10 ou acima para usar o AgentKit SDK. O AgentKit SDK é o cliente Python do Databricks para APIs de agentes usado pelos exemplos abaixo. Você também pode chamar a REST API diretamente de qualquer linguagem, sem a exigência do Python.
  • Para usar memory_store.put() ou memory_store.list(path=...), instale o databricks-agentbricks 0.6.0 e acima.

Como funciona a memória do agente​

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, e mantendo conteúdo e uma descrição.

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

  • Um armazenamento de memória é o contêiner no escopo do workspace para as memórias de um agente. Criar um armazenamento provisiona o armazenamento do Lakebase de suporte automaticamente. Você endereça um armazenamento pelo seu ID de armazenamento, que você escolhe ao criar o armazenamento.
  • Uma entrada de memória é um pedaço individual de conteúdo em um armazenamento. Cada entrada tem um content de texto de formato livre, um description curto usado para recuperação e um conjunto de campos que a organizam e particionam:
    • actor_id (obrigatório): quem é o proprietário da memória, como um usuário final ou outro agente.
    • session_id (opcional): a sessão à qual a memória pertence. Deixe-o não definido para uma memória que se aplica às sessões do ator.
    • path (obrigatório): um caminho semelhante a um filesystem que organiza entradas dentro de um ator, como /preferences/response-style.md.

Uma entrada é identificada exclusivamente 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, detém duas entradas separadas.

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

Recuperação​

Retrieve memory two ways:

  • Liste as entradas para um ator, opcionalmente filtradas por session_id, um prefixo path ou path exato. Use isto para navegar ou renderizar um índice do que um agente sabe.
  • Pesquise entradas de um ator com uma query em linguagem natural. A pesquisa retorna as entradas mais relevantes classificadas por pontuação de relevância.

Um filtro session_id em qualquer operação retorna apenas as entradas salvas com essa sessão. Não retorna entradas salvas sem uma sessão.

Começar​

Estes exemplos configuram a memória do agente para um agente de suporte: eles criam um armazenamento de memória, salvam a preferência de um usuário e a recuperam em uma conversa posterior. Escolha o cliente que se adequa ao seu projeto. O ID de um armazenamento de memória deve ter entre 3 e 56 caracteres, começar com uma letra minúscula, terminar com uma letra ou um número e conter apenas letras minúsculas, números e hifens.

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

  1. Instale o AgentKit SDK:

    Bash
    pip install databricks-agentbricks

  2. Crie um memory store para o seu agente. AgentKitClient se autentica com suas credenciais do WorkspaceClient:

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_agentkit import AgentKitClient

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

  3. Salve uma memória depois que o agente aprender algo duradouro sobre um usuário. actor_id é de quem é essa memória, path a organiza dentro desse ator e description melhora a recuperação:

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

  4. Recupere as memórias do usuário em uma conversa posterior com uma pesquisa em linguagem natural:

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

Forneça ferramentas de memória ao seu agente​

To let an agent decide when to save and recall memory, wrap the client operations as tools and instruct the agent on when to use them in its system prompt. Set the actor_id in trusted application code from the verified end-user identity. Never let the model choose whose memory to read or write.

O exemplo a seguir encapsula o SDK do AgentKit memory_store de Introdução como ferramentas para o OpenAI Agents SDK.

Python
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 já existente nesse caminho. Para adicionar o conteúdo como novas linhas, passe append=True. put() não é atômico, então gravações concorrentes no mesmo caminho podem se sobrescrever umas às outras. list(path=...) retorna as entradas naquele caminho exato em cada sessão, então forget_memory também exclui qualquer entrada salva no caminho em uma sessão.

O mesmo padrão funciona com o Claude Agent SDK e outros frameworks: envolva as operações de pesquisa, colocação, lista e exclusão do store como o tipo de ferramenta do framework.

Se você também execução um pipeline de memória no mesmo armazenamento de memória, o pipeline poderá reescrever, fazer merge, dividir ou excluir as entradas que seu agente salva para qualquer ator que processar.

Particionar e proteger a memória​

Dentro de um armazenamento, actor_id é a forma como você separa as memórias de cada um. Cada lista e pesquisa é escopada para um único actor_id, portanto, escolha a estratégia que corresponde ao que o seu agente precisa lembrar:

  • Private memory for each user: Set actor_id to the verified end-user identity. Each user gets their own partition, and the agent only recalls that user's entries.

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

  • Shared memory for a group: Set actor_id to a fixed key you choose, such as a team, project, or organization ID. Everyone reads and writes the same memories.

    • Exemplo: Um agente de equipe se lembra de um glossário compartilhado de termos da empresa e convenções internas.

  • Memória dividida por outro critério: crie actor_id a partir de seus próprios valores, como uma ID de tenant ou um composto de user:project.

    • Exemplo: Um aplicativo multi-tenant define actor_id como {tenant}:{user} para 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 de equipe ou de projeto confiável para memória compartilhada. Nunca permita que o modelo faça a escolha. Se a sua estratégia depender da identidade de um usuário final, rejeite solicitações que não possuam uma em vez de recorrer a um actor_id compartilhado.

atenção

actor_id separa memórias, mas não é um controle de acesso. Os armazenamentos de memória têm escopo de workspace, portanto, qualquer principal que possa acessar um armazenamento pode ler e gravar todas as entradas de todos os atores. O armazenamento, não o ator, é o limite de segurança. Para um isolamento estrito entre tenant ou usuários, crie um armazenamento de memória separado por limite.

Para permitir que outro principal, como o service principal do seu agente, use um store, conceda acesso a ele com a operação de permissão de concessão do store (memory_store.grant_permission(principal_id) no AgentKit SDK). Apenas o criador do store ou um administrador do workspace pode conceder acesso.

Limitações​

  • A memória do agente fornece apenas memória de longo prazo. Para obter a história de conversas de curto prazo, consulte sessões de agente.
  • A pesquisa classifica as entradas por relevância, combinando correspondência de texto completo (BM25) e correspondência semântica sobre o conteúdo e a descrição de cada entrada. Retorna até 100 entradas e não suporta paginação.
  • Access control is enforced at the store level. Per-entry and per-actor access control are not available.
  • O controle de acesso ao store abrange as entradas de um store. Qualquer usuário do workspace pode listar e obter memory stores, incluindo seus IDs e descrições.
  • Você não pode alterar o ID de um store depois de criá-lo. Apenas description podem ser atualizados.

Próximos os passos​

Nesta página