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

Sessões de agente gerenciadas

info

Beta

Esse recurso está em Beta.

Managed agent sessions give your agents a durable, framework-agnostic store for session state: the state an agent or framework keeps for one interaction. Most commonly this is the conversation history, the ordered transcript of messages, tool calls, and results that an agent reads at the start of a turn and appends to as it runs. It can also be any other state a framework persists for the interaction, such as a LangGraph gráfico. Databricks stores it in Lakebase and gerencia the storage for you, so you don't build or operate the database.

nota

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

Use sessões gerenciadas quando quiser:

  • Mantenha a história da conversa de um agente para que ela sobreviva a reinicializações e possa ser retomada posteriormente.
  • Reconstrua o contexto completo (incluindo chamadas de ferramentas e raciocínio) em uma mensagem de acompanhamento.
  • List, resume, and branch past conversations from your own UI.

As sessões gerenciadas mantêm o estado de uma única interação (estado de curto prazo, dentro da sessão). Para obter uma memória durável e de longo prazo que persista em conversas, use a memória de agente gerenciada.

Como funcionam as sessões gerenciadas​

Managed agent sessions recursos hierarchy: a session store contains many sessions, and each session contains many ordered session items.

As sessões gerenciadas têm três níveis:

  • A session store é o contêiner com escopo para workspace para as sessões de um agente. Creating a store provisions the backing Lakebase storage automatically. You choose a workspace-unique session_store_name.

  • Uma session é uma interação durável (tipicamente um histórico de conversa) dentro de um armazenamento. Uma session é identificada por:

    • actor_id (obrigatório): a quem a sessão pertence, como um usuário final ou outro agente. Ele agrupa todas as sessões de um assunto para que você possa listá-las e filtrá-las juntas. Ao criar um aplicativo por usuário, defina actor_id como o ID do usuário (por exemplo, a identidade verificada do usuário final proveniente da autenticação do seu aplicativo) para que as sessões de cada usuário permaneçam agrupadas. Defina-o a partir do contexto de aplicativo confiável, nunca de um valor fornecido pelo modelo ou pelo usuário.
    • session_id (opcional): um ID escolhido pelo chamador para a interação. O serviço gera um quando você o omite.
    • parent_session_id (opcional): vincula uma sessão àquela da qual ela foi bifurcada, para representar conversas ramificadas.

  • Um item de sessão é uma entrada na história ordenada de uma sessão. Cada item contém um valor data opaco e compatível com JSON, como uma mensagem, uma chamada de ferramenta, um resultado de ferramenta ou um bloco de raciocínio. O Databricks atribui a cada item um item_id e um create_time e não inspeciona nem valida seu conteúdo. Os itens são imutáveis após serem acrescentados.

O serviço mantém uma ordem determinística para os itens de uma sessão e autoriza cada operação no armazenamento da sessão.

Requisitos​

  • Python 3.10 ou acima , para usar o Mason (o cliente Python e a CLI do Databricks para APIs de agentes), que os exemplos abaixo usam. Você também pode chamar a REST API diretamente de qualquer linguagem, sem nenhum requisito de Python.

Começar​

Estes exemplos configuram sessões gerenciadas para um agente de suporte: eles criam um armazenamento de sessão, começam uma sessão para uma conversa, anexam os turnos da conversa e leem a história de volta em uma solicitação posterior. Escolha o cliente que se adapta ao seu projeto.

Mason é o cliente Python e a CLI do Databricks para APIs de agente. Ele se autentica com WorkspaceClient do SDK do Databricks.

  1. Instalar o Mason:

    Bash
    pip install databricks-mason

  2. Crie um armazenamento de sessão e, em seguida, inicie uma sessão para uma conversa. actor_id é o proprietário da conversa; o session_id opcional identifica exclusivamente esta conversa:

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_mason import MasonClient

    mason = MasonClient(WorkspaceClient())
    session_store = mason.session_stores.create("support-agent-sessions")
    session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Append the conversation's turns as the agent runs. Each item is any JSON-compatible value:

    Python
    session.append_items(
        [
            {"type": "message", "role": "user", "content": "I need help with my cluster."},
            {"type": "message", "role": "assistant", "content": "Let's take a look."},
        ]
    )

  4. Em uma solicitação de acompanhamento, recarregue a sessão e leia a história completa dela para reconstruir o contexto:

    Python
    session = session_store.get("case-456")
    # Request chronological order; list_items defaults to newest-first and auto-pages.
    history = [item.data for item in session.list_items(order_by="create_time asc")]

Os clientes também oferecem suporte à remoção do item mais recente, à limpeza dos itens de uma sessão e à bifurcação de uma conversa em uma cópia independente (opcionalmente até um item específico). A exclusão de uma sessão que possui sessões filhas requer uma opção de força para propagar a exclusão para elas (por exemplo, session.delete(force=True)).

Dê suporte à sessão de um agent framework com sessões gerenciadas​

Agent frameworks such as the OpenAI Agents SDK and the Claude Agent SDK read conversation história at the começo of a execução and append new items at the end. The session store maps directly onto that pattern:

Operação de framework

Chamada de armazenamento de sessão

Ler história

list_items em ordem cronológica (order_by="create_time asc")

Adicionar itens de turno

append os novos itens

Desfazer último item

pop o item mais recente

Limpar o thread

clear os itens da session

Operação de framework

Chamada de armazenamento de sessão

Ler história

list_items em ordem cronológica (order_by="create_time asc")

Adicionar itens de turno

append os novos itens

Desfazer último item

pop o item mais recente

Limpar o thread

clear os itens da session

Escopo e acesso​

As sessões gerenciadas armazenam os itens de uma sessão como valores opacos compatíveis com JSON: o serviço persiste e retorna tudo o que seu agente ou aplicativo de framework anexar, sem interpretá-lo. Ele não adiciona recursos de controle de execução, como execuções, pontos de verificação ou aprovações, como conceitos de primeira classe, embora um framework que serializa esse estado possa persistir isso como itens.

Os session stores têm escopo de workspace, e o acesso é autorizado no nível do store. Os campos actor_id e metadata oferecem suporte apenas a agrupamento e filtragem; eles não concedem nem restrigem o acesso. Defina o actor_id a partir do contexto do aplicativo confiável, em vez de um valor fornecido pelo modelo ou pelo usuário.

To let another principal, such as your agent's service principal, use a store, grant it access with the store's grant-permission operation (session_store.grant_permission(principal_id) in Mason).

Sessões gerenciadas e memória gerenciada são independentes. A exclusão de uma sessão ou de um armazenamento de sessão não exclui a memória retida em um armazenamento de memória.

Next steps​

Nesta página