Referência da API de Memória

Esta página é a referência da API REST para memória do agente gerenciado. Ele abrange os pontos de extremidade, os campos de solicitação e os campos de resposta para memória gerenciada:

• Um repositório de memória é um catálogo do Unity protegível que atua como um contêiner para entradas de memória. Use as APIs do repositório de memória para criar e gerenciar repositórios.
• Uma entrada de memória é um conteúdo individual armazenado dentro de um repositório de memória. Use as APIs de entrada de memória para ler e gravar entradas.
• Uma conversa é o estado de conversa compatível com OpenAI — mensagens e chamadas de ferramenta — apoiado por um repositório de memória e fixado em um escopo. Use as APIs de Conversa para criar e gerenciar conversas e seus itens.

Pré-requisitos

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

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

APIs do repositório de memória

Um repositório de memória é um catálogo do Unity protegível que atua como um contêiner para entradas de memória. Os repositórios de memória usam nomenclatura de três níveis: catalog.schema.memory_store_name.

Criar um repositório de memória

Cria um novo repositório de memória em um esquema pai.

• Ponto de extremidade:POST /api/2.1/unity-catalog/memory-stores
• Privilégio necessá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 solicitação:

Obter um repositório de memória

Recupera um repositório de memória por seu nome totalmente qualificado de três partes.

• Ponto de extremidade:GET /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilégio necessá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 repositórios de memória

Lista repositórios de memória em um esquema. Os resultados são filtrados para armazenar que o chamador pode ler.

• Ponto de extremidade:GET /api/2.1/unity-catalog/memory-stores
• Privilégio necessá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 repositório de memória

Atualiza campos mutáveis em um repositório de memória. Atualmente, só description é mutável.

• Ponto de extremidade:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilégio necessá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"
  }'

Excluir um repositório de memória

Exclui um repositório de memória e todas as suas entradas de memória.

• Ponto de extremidade:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
• Privilégio necessá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}"

Campos de resposta do repositório de memória

APIs de entrada de memória

As entradas de memória são as partes individuais do conteúdo armazenadas dentro de um repositório de memória. Cada entrada é identificada por um escopo e um caminho: scope é uma chave de partição que o chamador atribui (por exemplo, uma ID de usuário final) e path é um caminho suave dentro desse escopo que deve começar com /memories/ (por exemplo, /memories/preferences.md). scope é necessário em cada solicitação de entrada de memória.

Criar uma entrada de memória

Cria uma nova entrada de memória em um repositório de memória.

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

scope é um parâmetro de consulta; o corpo da solicitação é a entrada em si.

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 solicitação:

Obter uma entrada de memória

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

• Ponto de extremidade:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
• Privilégio necessá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}"

Listar entradas de memória

Lista entradas de memória em um escopo.

• Ponto de extremidade:GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilégio necessá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:

Listar respostas omitir contents (somente metadados) e incluir um next_page_token quando mais páginas permanecerem.

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, insertou replace_all. description é editável: defina-o para substituir a descrição da entrada ou omita-a para deixar a descrição inalterada.

• Ponto de extremidade:PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilégio necessá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):

Excluir uma entrada de memória

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

• Ponto de extremidade:DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
• Privilégio necessá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}"

Pesquisar entradas de memória

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

• Ponto de extremidade:POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
• Privilégio necessá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 solicitação: scope (obrigatório), query (obrigatório), path_prefix (opcional), top_k (opcional; o padrão é 10, no máximo 50).

Campos de resposta de entrada de memória

APIs de conversa

Uma conversa armazena o estado de conversa compatível com OpenAI — mensagens, chamadas de ferramenta e outros itens — em um repositório de memória em um único escopo. Com uma conversa, um agente persiste e recarrega o lado do servidor de estado da sessão. Você cria cada conversa em um repositório de memória (nome de três partes) e uma scopee as operações de conversa exigem os mesmos privilégios que o repositório de memória subjacente.

Criar uma conversa

Cria uma conversa associada a um repositório de memória e ao escopo.

• Ponto de extremidade:POST /api/2.1/unity-catalog/conversations
• Privilégio necessá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 solicitação:

Obter uma conversa

Recupera uma conversa por sua ID.

• Ponto de extremidade:GET /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilégio necessá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 a de uma conversa metadata.

• Ponto de extremidade:POST /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilégio necessá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" } }'

Excluir uma conversa

Exclui uma conversa e seus itens.

• Ponto de extremidade:DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
• Privilégio necessá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 de conversa

APIs de item de conversa

Os itens são mensagens individuais e chamadas de ferramenta dentro de uma conversa. Eles seguem a forma de itens de conversa openai e usam paginação compatível com OpenAI (after, , limit). has_more