Referência da API de memória

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

Um **armazenamento de memória** é um segurável do Unity Catalog que atua como um contêiner para entradas de memória. Use as APIs de armazenamento de memória para criar e gerenciar armazenamentos.
Uma entrada de memória é um item de conteúdo individual armazenado em um armazenamento de memória. Use as APIs de entrada de memória para ler e gravar entradas.
Uma **conversação** é um estado de conversação compatível com OpenAI — mensagens e chamadas de ferramenta — apoiado por um armazenamento de memória e pin a um escopo. Use as APIs de Conversação para criar e gerenciar conversações e seus itens.

Pré-requisitos

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

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

APIs do armazenamento de memória

Um armazenamento de memória é um recurso securable do Unity Catalog que atua como um contêiner para entradas de memória. Armazenamentos de memória usam nomenclatura de três níveis: catalog.schema.memory_store_name.

Operação	Endpoint	Privilégio necessário
Criar	`POST /api/2.1/unity-catalog/memory-stores`	`CREATE MEMORY STORE` no esquema pai
Get	`GET /api/2.1/unity-catalog/memory-stores/{full_name}`	`READ MEMORY STORE` na loja
Lista	`GET /api/2.1/unity-catalog/memory-stores`	`USE SCHEMA` no esquema pai
Atualizar	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` na loja
Deletar	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` na loja

Criar um armazenamento de memória

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

endpoint : POST /api/2.1/unity-catalog/memory-stores
Privilégio necessário : CREATE MEMORY STORE no esquema pai

Bash
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:

campo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome abreviado para o armazenamento de memória. Deve corresponder a `[A-Za-z0-9_-]+`, 1-255 caracteres. Exclusivo dentro do esquema pai.
`catalog_name`	`string`	Sim	Nome do catálogo pai.
`schema_name`	`string`	Sim	Nome do esquema pai, relativo ao catálogo.
`description`	`string`	Não	Descrição legível por humanos do armazenamento de memória.

Obter um armazenamento de memória

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

endpoint : GET /api/2.1/unity-catalog/memory-stores/{full_name}
Privilégio necessário : READ MEMORY STORE no armazenamento

Bash
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 em um esquema. Os resultados são filtrados para os armazenamentos que o chamador pode ler.

endpoint : GET /api/2.1/unity-catalog/memory-stores
Privilégio necessário : USE SCHEMA no esquema pai

Bash
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:

Parâmetro	Tipo	Obrigatório	Descrição
`catalog_name`	`string`	Sim	Nome do catálogo pai.
`schema_name`	`string`	Sim	Nome do esquema pai.
`page_token`	`string`	Não	Tokens de paginação de uma resposta anterior.
`max_results`	`integer`	Não	Máximo de armazenamentos por página. default é 100, máximo 1000.

Atualizar um armazenamento de memória

Atualiza campos mutáveis em um armazenamento de memória. Atualmente, apenas description é mutável.

endpoint : PATCH /api/2.1/unity-catalog/memory-stores/{full_name}
Privilégio necessário : MANAGE no armazenamento

Bash
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 armazenamento de memória

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

endpoint : DELETE /api/2.1/unity-catalog/memory-stores/{full_name}
Privilégio necessário : MANAGE no armazenamento

Bash
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 armazenamento de memória

campo	Tipo	Descrição
`name`	`string`	Nome curto do armazenamento de memória.
`catalog_name`	`string`	Nome do catálogo pai.
`schema_name`	`string`	Nome do esquema pai.
`description`	`string`	Descrição legível por humanos.
`owner`	`string`	Principal do UC que possui o armazenamento. Definido na criação.
`full_name`	`string`	Nome totalmente qualificado de três partes: `catalog.schema.name`.
`memory_store_id`	`string`	UUID atribuído pelo servidor.
`securable_type`	`string`	Sempre `MEMORY_STORE`.
`created_at`	`integer`	Hora de criação em milissegundos da época Unix.
`updated_at`	`integer`	Hora da última atualização em milissegundos de época Unix.
`created_by`	`string`	Principal que criou o armazenamento.

APIs de entrada de memória

Entradas de memória são os itens de conteúdo individuais armazenados em um armazenamento de memória. Cada entrada é identificada por um escopo e um caminho : scope é uma key de partição que o chamador atribui (por exemplo, um ID de usuário final), e path é um caminho flexível dentro desse escopo que deve começar com /memories/ (por exemplo, /memories/preferences.md). scope é necessário em toda solicitação de entrada de memória.

Operação	Endpoint	Privilégio necessário
Criar	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` na loja
Get	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get`	`READ MEMORY STORE` na loja
Lista	`GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`READ MEMORY STORE` na loja
Atualizar	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` na loja
Deletar	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` na loja
Pesquisar	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search`	`READ MEMORY STORE` na loja

Criar uma entrada de memória

Cria uma nova entrada de memória em um armazenamento de memória.

endpoint : POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries?scope=<scope>
Privilégio necessário : WRITE MEMORY STORE no armazenamento

scope é um parâmetro de query; o corpo da solicitação é a própria entrada.

Bash
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:

campo	Dentro de	Tipo	Obrigatório	Descrição
`scope`	query	`string`	Sim	Partição à qual a entrada pertence, atribuída pelo chamador (por exemplo, um ID de usuário final).
`path`	Corpo	`string`	Sim	Caminho flexível que identifica a entrada dentro do escopo. Deve começar com `/memories/`. Imutável.
`contents`	Corpo	`string`	Não	Conteúdo de texto de memória de formato livre.
`description`	Corpo	`string`	Não	Resumo de uma linha da entrada de memória. Serve como um gancho de índice em respostas de lista.

Obter uma entrada de memória

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

endpoint : GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries:get
Privilégio necessário : READ MEMORY STORE no armazenamento

Bash
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 as entradas de memória em um escopo.

endpoint : GET /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Privilégio necessário : READ MEMORY STORE no armazenamento

Bash
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:

Parâmetro	Tipo	Obrigatório	Descrição
`scope`	`string`	Sim	Escopo (partição) para listar entradas.
`path_prefix`	`string`	Não	Retorne apenas as entradas cujo caminho começa com este prefixo.
`page_size`	`integer`	Não	Máximo de entradas por página. O servidor limita o tamanho da página.
`page_token`	`string`	Não	Tokens de paginação de uma resposta anterior.

As respostas da lista omitem contents (somente metadados) e incluem um next_page_token quando mais páginas permanecem.

Atualizar uma entrada de memória

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

endpoint : PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Privilégio necessário : WRITE MEMORY STORE no armazenamento

Bash
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 (defina exatamente uma):

Operação	Campos	Comportamento
`replace_all`	`contents`	Sobrescrever o conteúdo completo da entrada.
`str_replace`	`old_str`, `new_str`	Substitua a única ocorrência de `old_str` por `new_str` (deve corresponder exatamente uma vez).
`insert`	`insert_line`, `insert_text`	Insira `insert_text`; `insert_line` 0 = início, omitido = anexar ao final.

Excluir uma entrada de memória

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

endpoint : DELETE /api/2.1/unity-catalog/memory-stores/{full_name}/entries
Privilégio necessário : WRITE MEMORY STORE no armazenamento

Bash
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 nos campos caminho, conteúdo e descrição.

endpoint : POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries:search
Privilégio necessário : READ MEMORY STORE no armazenamento

Bash
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 da solicitação: scope (obrigatório), query (obrigatório), path_prefix (opcional), top_k (opcional; o default é 10, máximo 50).

Campos de resposta de entrada de memória

campo	Tipo	Descrição
`path`	`string`	Caminho flexível da entrada dentro de seu escopo.
`contents`	`string`	Texto da memória. Omitido nas respostas da lista.
`description`	`string`	Resumo de uma linha.
`scope`	`string`	Escopo (partição) ao qual a entrada pertence.
`memory_store_name`	`string`	Nome de três partes do armazenamento de memória pai.
`has_contents`	`boolean`	Se a entrada tem `contents` não vazios (útil na Lista).
`create_time`	`string`	Carimbo de data/hora de criação (RFC 3339).
`update_time`	`string`	Carimbo de data/hora da última atualização (RFC 3339).

APIs de Conversa

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

Operação	Endpoint	Privilégio necessário
Criar	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` na loja
Get	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` na loja
Atualizar	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` na loja
Deletar	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` na loja

Criar uma conversação

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

endpoint : POST /api/2.1/unity-catalog/conversations
Privilégio necessário : WRITE MEMORY STORE no armazenamento

Bash
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:

campo	Tipo	Obrigatório	Descrição
`memory_store`	`object`	Sim	Armazenamento de memória que suporta a conversa.
`memory_store.name`	`string`	Sim	Nome totalmente qualificado de três partes do armazenamento de memória: `catalog.schema.memory_store`.
`scope`	`object`	Sim	Escopo ao qual a conversa está pin.
`scope.kind`	`string`	Sim	Tipo de escopo, por exemplo `user` ou `user_defined`.
`scope.value`	`string`	Sim	Valor de escopo específico do tipo, por exemplo, um ID de usuário final.
`metadata`	`object`	Não	Metadados key-valor controlados pelo chamador. Até 16 key; key com até 64 caracteres, valores com até 512 caracteres.
`items`	`array`	Não	Itens iniciais de conversação OpenAI para iniciar a conversa (até 20). Itens sem um `type` são armazenados como itens de mensagem.

Obter uma conversa

Recupera uma conversa pelo seu ID.

endpoint : GET /api/2.1/unity-catalog/conversations/{conversation_id}
Privilégio necessário : READ MEMORY STORE no armazenamento

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

Atualizar uma conversação

Atualiza metadata de uma conversa.

endpoint : POST /api/2.1/unity-catalog/conversations/{conversation_id}
Privilégio necessário : WRITE MEMORY STORE no armazenamento

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

endpoint : DELETE /api/2.1/unity-catalog/conversations/{conversation_id}
Privilégio necessário : WRITE MEMORY STORE no armazenamento

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

Campos de resposta da conversa

campo	Tipo	Descrição
`id`	`string`	ID de conversação atribuído pelo servidor.
`object`	`string`	Sempre `conversation`.
`created_at`	`integer`	Tempo de criação em segundos de época Unix.
`metadata`	`object`	Metadados de key-valor fornecidos pelo chamador.

APIs de item de conversa

Os itens são as mensagens individuais e as chamadas de ferramenta em uma conversação. Elas seguem o formato de itens de conversação do OpenAI e usam paginação compatível com OpenAI (after, limit, has_more).

Operação	Endpoint	Privilégio necessário
Criar itens	`POST /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`WRITE MEMORY STORE` na loja
Obter item	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`READ MEMORY STORE` na loja
Listar itens	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`READ MEMORY STORE` na loja
Excluir item	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`WRITE MEMORY STORE` na loja

Pré-requisitos​

APIs do armazenamento de memória​

Criar um armazenamento de memória​

Obter um armazenamento de memória​

Listar armazenamentos de memória​

Atualizar um armazenamento de memória​

Excluir um armazenamento de memória​

Campos de resposta do armazenamento de memória​

APIs de entrada de memória​

Criar uma entrada de memória​

Obter uma entrada de memória​

Listar entradas de memória​

Atualizar uma entrada de memória​

Excluir uma entrada de memória​

Pesquisar entradas de memória​

Campos de resposta de entrada de memória​

APIs de Conversa​

Criar uma conversação​

Obter uma conversa​

Atualizar uma conversação​

Excluir uma conversa​

Campos de resposta da conversa​

APIs de item de conversa​

Pré-requisitos

APIs do armazenamento de memória

Criar um armazenamento de memória

Obter um armazenamento de memória

Listar armazenamentos de memória

Atualizar um armazenamento de memória

Excluir um armazenamento de memória

Campos de resposta do armazenamento de memória

APIs de entrada de memória

Criar uma entrada de memória

Obter uma entrada de memória

Listar entradas de memória

Atualizar uma entrada de memória

Excluir uma entrada de memória

Pesquisar entradas de memória

Campos de resposta de entrada de memória

APIs de Conversa

Criar uma conversação

Obter uma conversa

Atualizar uma conversação

Excluir uma conversa

Campos de resposta da conversa

APIs de item de conversa