Referência da API de memória

Esta página é a referência da API REST para memória de agente gerida. Abrange os endpoints, campos de pedido e campos de resposta para memória gerida:

• Um armazenamento de memória é um Unity Catalog securável que atua como um contentor para entradas de memória. Use as APIs de armazenamento de memória para criar e gerir armazenamentos.
• Uma entrada de memória é um conteúdo individual armazenado dentro de um armazenamento de memória. Use as APIs de entrada de memória para ler e escrever entradas.
• Uma conversa é um estado de conversa compatível com OpenAI — mensagens e chamadas de ferramenta — apoiadas por um armazenamento de memória e fixadas a um escopo. Use as APIs de Conversa para criar e gerir conversas e os seus itens.

Pré-requisitos

Gerar um token OAuth usando a CLI Databricks para chamar as APIs:

databricks auth login --host ${DATABRICKS_HOST}
databricks auth token

APIs de armazenamento de memória

Um armazenamento de memória é um Unity Catalog securável que atua como um contentor para entradas de memória. Os armazenamentos de memória usam nomeação de três níveis: catalog.schema.memory_store_name.

Criar um armazenamento de memória

Cria um novo armazenamento de memória sob um esquema pai.

• Ponto final:POST /api/2.1/unity-catalog/memory-stores
• Privilégio obrigatório: CREATE MEMORY STORE no esquema pai

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": "agent_memory",
    "catalog_name": "main",
    "schema_name": "default",
    "description": "Memory store for customer support agents"
  }'

Campos de pedido:

Arranja um armazenamento de memórias

Recupera um armazenamento de memória pelo seu nome totalmente qualificado em três partes.

• Ponto final:GET /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilégio obrigatório: READ MEMORY STORE na loja

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Listar Armazenamentos de Memória

Lista os armazenamentos de memória num esquema. Os resultados são filtrados para os arquivos que o chamador pode ler.

• Ponto final:GET /api/2.1/unity-catalog/memory-stores
• Privilégio obrigatório: USE SCHEMA no esquema pai

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores?catalog_name=main&schema_name=default" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Parâmetros de consulta:

Atualizar um armazenamento de memória

Atualiza campos mutáveis num armazenamento de memória. Atualmente, só description é mutável.

• Ponto final:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilégio obrigatório: MANAGE na loja

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": {
      "description": "Updated description for the memory store"
    },
    "update_mask": "description"
  }'

Eliminar um armazenamento de memória

Apaga um armazenamento de memória e todas as suas entradas de memória.

• Ponto final:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilégio obrigatório: MANAGE na loja

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Armazenamento de memória campos de resposta

APIs de entrada de memória

As entradas de memória são as partes individuais de conteúdo armazenadas dentro de um armazenamento de memória. Cada entrada é identificada por um âmbito e um caminho: scope é uma chave de partição que o chamador atribui (por exemplo, um ID de utilizador final), e path é um caminho suave dentro desse âmbito que deve começar com /memories/ (por exemplo, /memories/preferences.md). scope é exigido em todos os pedidos de entrada de memória.

Criar uma entrada de memória

Cria uma nova entrada de memória num armazenamento de memória.

• Ponto final:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
• Privilégio obrigatório: WRITE MEMORY STORE na loja

scope é um parâmetro de consulta; O corpo do pedido é a própria inscrição.

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/memories/preferences.md",
    "contents": "The user prefers responses in English and uses formal tone.",
    "description": "User language and tone preferences"
  }'

Campos de pedido:

Faz uma entrada de memória

Recupera uma única entrada de memória por scope e path.

• Ponto final:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• Privilégio obrigatório: READ MEMORY STORE na loja

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:get?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Entradas de memória de lista

Lista entradas de memória num telescópio.

• Ponto final:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilégio obrigatório: READ MEMORY STORE na loja

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Parâmetros de consulta:

As respostas da lista omitam contents (apenas metadados) e incluem quando next_page_token restam mais páginas.

Atualizar uma entrada de memória

Aplica uma única operação de edição a uma entrada contentsexistente , identificada por scope e path. Forneça exatamente um de str_replace, insert, ou replace_all. description é editável: defina para substituir a descrição da entrada, ou omita-a para deixar a descrição inalterada.

• Ponto final:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilégio obrigatório: WRITE MEMORY STORE na loja

curl -X PATCH \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "path": "/memories/preferences.md",
    "replace_all": { "contents": "The user prefers responses in Spanish and uses casual tone." }
  }'

Editar operações (definir exatamente uma):

Eliminar uma entrada de memória

Apaga uma entrada de memória, identificada por scope e path.

• Ponto final:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilégio obrigatório: WRITE MEMORY STORE na loja

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries?scope=user-42&path=/memories/preferences.md" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Entradas de memória de pesquisa

Pesquisa entradas de memória por palavra-chave nos campos de caminho, conteúdo e descrição.

• Ponto final:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• Privilégio obrigatório: READ MEMORY STORE na loja

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.agent_memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "user-42",
    "query": "language preferences"
  }'

Campos de pedido: scope (obrigatório), query (obrigatório), path_prefix (opcional), top_k (opcional; por defeito é 10, máximo 50).

Campos de resposta à entrada de memória

APIs de conversação

Uma conversa armazena o estado da conversa compatível com OpenAI — mensagens, chamadas de ferramenta e outros itens — num armazenamento de memória sob um único escopo. Numa conversa, um agente persiste e recarrega o estado da sessão do lado do servidor. Cria-se cada conversa contra um armazenamento de memória (nome em três partes) e um scope, e as operações de conversa requerem os mesmos privilégios que o armazenamento de memória subjacente.

Cria uma conversa

Cria uma conversa vinculada a um armazenamento e âmbito de memória.

• Ponto final:POST /api/2.1/unity-catalog/conversations
• Privilégio obrigatório: WRITE MEMORY STORE na loja

curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store": { "name": "main.default.support_agent_memory" },
    "scope": { "kind": "user", "value": "user-123" },
    "metadata": { "source": "support-chat" }
  }'

Campos de pedido:

Arranja uma conversa

Recupera uma conversa pelo seu ID.

• Ponto final:GET /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilégio obrigatório: READ MEMORY STORE na loja

curl -X GET \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Atualizar uma conversa

Atualiza o metadata.

• Ponto final:POST /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilégio obrigatório: WRITE MEMORY STORE na loja

curl -X POST \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "source": "support-chat", "resolved": "true" } }'

Apagar uma conversa

Apaga uma conversa e os seus itens.

• Ponto final:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilégio obrigatório: WRITE MEMORY STORE na loja

curl -X DELETE \
  "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/conversations/${CONVERSATION_ID}" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

Campos de resposta à conversa

APIs de itens de conversação

Os itens são as mensagens individuais e as chamadas de ferramentas dentro de uma conversa. Seguem a forma dos elementos de conversa do OpenAI e utilizam paginação compatível com OpenAI (after, limit, has_more).