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

Memória gerenciada do agente

info

Beta

Esse recurso está na versão Beta.

Managed agent memory gives your agents durable, long-term memory that persists across conversations. Databricks stores the memory in Lakebase e gerencia o armazenamento, a indexação e a pesquisa semântica para você, para que seus agentes possam lembrar as preferências do usuário, decisões passadas e contexto acumulado sem que você opere um banco de dados.

nota

During the preview, you are billed for the underlying Lakebase instance that stores your memory entries. No additional charges apply for managed agent memory itself. Preços is subject to change as the preview progresses.

Use a memória gerenciada quando quiser que seus agentes possam:

  • 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 gerenciada funciona com agentes criados em qualquer framework. Para obter o histórico de conversas de curto prazo em uma única interação, use as sessões de agente gerenciadas.

Como a memória gerenciada funciona​

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

A memória gerenciada possui dois níveis:

  • Um armazenamento de memória é o contêiner com escopo de Workspace para as memórias de um agente. Creating a store provisions the backing Lakebase storage automatically. You address a store by its display_name.
  • 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): registra de qual sessão a memória foi capturada, para rastreamento e procedência. Deixe sem definição para memórias que não estão vinculadas a uma sessão específica.
    • 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.

Recuperação​

Retrieve memory two ways:

  • Listar entradas para um ator, opcionalmente filtradas por session_id ou um prefixo path. Use isto para navegar ou renderizar um índice do que um agente conhece.
  • Pesquise entradas para um ator com uma query em linguagem natural. A pesquisa retorna as entradas mais relevantes ordenadas por uma pontuação de relevância de texto completo (BM25).

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.

Começar​

Estes exemplos configuram a memória gerenciada 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 adapta ao seu projeto. O display_name 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",
    )

  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."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

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

O mesmo padrão funciona com o Claude Agent SDK e outras estruturas: encapsule as operações de pesquisa e adição do armazenamento como o tipo de ferramenta da estrutura.

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 gerenciados têm escopo de workspace, portanto, qualquer principal que possa acessar um armazenamento pode ler e gravar todas as entradas em todos os atores. O armazenamento, e não o ator, é o limite de segurança. Para um isolamento rigoroso entre tenants ou usuários, crie um armazenamento de memória separado por limite.

Para permitir que outra entidade principal, como o service principal do seu agente, use um armazenamento, conceda acesso a ele com a operação grant-permission do armazenamento (memory_store.grant_permission(principal_id) no AgentKit SDK).

Limitações​

  • Managed memory provides long-term memory only. For short-term conversation história, see managed agent sessions.
  • A pesquisa é uma operação de texto completo (BM25) classificada por relevância que retorna um conjunto de resultados top-N de até 100 entradas. Ele não oferece suporte à paginação ou à busca por similaridade de vetores.
  • Access control is enforced at the store level. Per-entry and per-actor access control are not available.
  • O armazenamento display_name é imutável após a criação. Apenas description pode ser atualizado.

Próximos os passos​

Nesta página