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.

Operação	Ponto final	Privilégio obrigatório
Create	`POST /api/2.1/unity-catalog/memory-stores`	`CREATE MEMORY STORE` no esquema pai
Obter	`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
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` Na loja
Delete	`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.

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:

Campo	Tipo	Necessário	Description
`name`	`string`	Yes	Nome abreviado para o armazenamento de memórias. Deve corresponder `[A-Za-z0-9_-]+`a 1-255 caracteres. Único dentro do esquema pai.
`catalog_name`	`string`	Yes	Nome do catálogo principal.
`schema_name`	`string`	Yes	Nome do esquema pai, relativo ao catálogo.
`description`	`string`	No	Descrição legível para humanos do armazenamento de memória.

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:

Parâmetro	Tipo	Necessário	Description
`catalog_name`	`string`	Yes	Nome do catálogo principal.
`schema_name`	`string`	Yes	Nome do esquema principal.
`page_token`	`string`	No	Token de paginação de uma resposta anterior.
`max_results`	`integer`	No	Armazenamento máximo por página. Por defeito é 100, máximo 1000.

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

Campo	Tipo	Description
`name`	`string`	Nome abreviado do armazenamento de memórias.
`catalog_name`	`string`	Nome do catálogo principal.
`schema_name`	`string`	Nome do esquema principal.
`description`	`string`	Descrição legível para humanos.
`owner`	`string`	Diretor da UC que é dono da loja. Decide-te a criar.
`full_name`	`string`	Nome totalmente qualificado em três partes: `catalog.schema.name`.
`memory_store_id`	`string`	UUID atribuído pelo servidor.
`securable_type`	`string`	Sempre `MEMORY_STORE`.
`created_at`	`integer`	Tempo de criação no Unix epoch milissegundos.
`updated_at`	`integer`	Última atualização no Unix epoch milissegundos.
`created_by`	`string`	Diretor que criou a loja.

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.

Operação	Ponto final	Privilégio obrigatório
Create	`POST /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` Na loja
Obter	`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
Update	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` Na loja
Delete	`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 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:

Campo	Em	Tipo	Necessário	Description
`scope`	consulta	`string`	Yes	Partição a que a entrada pertence, atribuída pelo chamador (por exemplo, um ID de utilizador final).
`path`	body	`string`	Yes	Caminho suave que identifica a entrada dentro do escopo. Deve começar com `/memories/`. Imutável.
`contents`	body	`string`	No	Conteúdo de texto de memória livre.
`description`	body	`string`	No	Resumo de uma linha da entrada de memória. Serve como gancho de índice nas respostas de listas.

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:

Parâmetro	Tipo	Necessário	Description
`scope`	`string`	Yes	Âmbito (partição) para listar as entradas de .
`path_prefix`	`string`	No	Devolva apenas entradas cujo caminho comece com este prefixo.
`page_size`	`integer`	No	Número máximo de inscrições por página. O servidor limita o tamanho da página.
`page_token`	`string`	No	Token de paginação de uma resposta anterior.

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

Operação	Fields	Comportamento
`replace_all`	`contents`	Sobrescreva o conteúdo completo da entrada.
`str_replace`	`old_str`, `new_str`	Substitua a ocorrência única de `old_str` por `new_str` (deve corresponder exatamente uma vez).
`insert`	`insert_line`, `insert_text`	Inserir `insert_text`; `insert_line` 0 = topo, omitido = acrescentar ao final.

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

Campo	Tipo	Description
`path`	`string`	Caminho suave da entrada dentro do seu âmbito.
`contents`	`string`	Texto de memória. Omitido nas respostas da lista.
`description`	`string`	Resumo de uma linha.
`scope`	`string`	Âmbito (partição) a que a entrada pertence.
`memory_store_name`	`string`	Nome em três partes do armazenamento de memória principal.
`has_contents`	`boolean`	Se a entrada tem não vazio `contents` (útil na Lista).
`create_time`	`string`	Carimbo temporal da criação (RFC 3339).
`update_time`	`string`	Carimbo temporal da última atualização (RFC 3339).

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.

Operação	Ponto final	Privilégio obrigatório
Create	`POST /api/2.1/unity-catalog/conversations`	`WRITE MEMORY STORE` Na loja
Obter	`GET /api/2.1/unity-catalog/conversations/{conversation_id}`	`READ MEMORY STORE` Na loja
Update	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` Na loja
Delete	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` Na loja

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:

Campo	Tipo	Necessário	Description
`memory_store`	`object`	Yes	Memória a sustentar a conversa.
`memory_store.name`	`string`	Yes	Nome totalmente qualificado do armazenamento de memória em três partes: `catalog.schema.memory_store`.
`scope`	`object`	Yes	O âmbito a que a conversa está fixada.
`scope.kind`	`string`	Yes	Tipo de escopo, por exemplo `user` ou `user_defined`.
`scope.value`	`string`	Yes	Valor de âmbito específico do tipo, por exemplo um ID de utilizador final.
`metadata`	`object`	No	Metadados chave-valor controlados pelo chamador. Até 16 teclas; Teclas até 64 caracteres, valores até 512 caracteres.
`items`	`array`	No	Itens iniciais da conversa OpenAI para semear a conversa (até 20). Os itens sem a `type` são armazenados como itens de mensagem.

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

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

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

Operação	Ponto final	Privilégio obrigatório
Criar itens	`POST /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`WRITE MEMORY STORE` Na loja
Obter artigo	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`READ MEMORY STORE` Na loja
Lista de itens	`GET /api/2.1/unity-catalog/conversations/{conversation_id}/items`	`READ MEMORY STORE` Na loja
Eliminar item	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}/items/{item_id}`	`WRITE MEMORY STORE` Na loja

Comentários

Esta página foi útil?

Last updated on 2026-07-01

Referência da API de memória

Pré-requisitos

APIs de armazenamento de memória

Criar um armazenamento de memória

Arranja um armazenamento de memórias

Listar Armazenamentos de Memória

Atualizar um armazenamento de memória

Eliminar um armazenamento de memória

Armazenamento de memória campos de resposta

APIs de entrada de memória

Criar uma entrada de memória

Faz uma entrada de memória

Entradas de memória de lista

Atualizar uma entrada de memória

Eliminar uma entrada de memória

Entradas de memória de pesquisa

Campos de resposta à entrada de memória

APIs de conversação

Cria uma conversa

Arranja uma conversa

Atualizar uma conversa

Apagar uma conversa

Campos de resposta à conversa

APIs de itens de conversação

Comentários

Recursos adicionais