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.

Operation	Endpoint	Privilégio necessá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
Atualização	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` na loja
Delete (excluir)	`DELETE /api/2.1/unity-catalog/memory-stores/{full_name}`	`MANAGE` na loja

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:

Campo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome curto para o repositório de memória. Deve corresponder `[A-Za-z0-9_-]+`a 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, em relação ao catálogo.
`description`	`string`	No	Descrição legível por humanos do repositório de memória.

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:

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`	No	Token de paginação de uma resposta anterior.
`max_results`	`integer`	No	Máximo de repositórios por página. O padrão é 100, no máximo 1000.

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

Campo	Tipo	Descrição
`name`	`string`	Nome curto do repositório 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`	A entidade de segurança da UC é dona da loja. Definir na criação.
`full_name`	`string`	Nome totalmente qualificado de três partes: `catalog.schema.name`.
`memory_store_id`	`string`	UUID atribuída pelo servidor.
`securable_type`	`string`	Sempre `MEMORY_STORE`.
`created_at`	`integer`	Tempo de criação em milissegundos de época do Unix.
`updated_at`	`integer`	Hora da última atualização em milissegundos de época do Unix.
`created_by`	`string`	Entidade de segurança que criou o repositório.

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.

Operation	Endpoint	Privilégio necessá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
Atualização	`PATCH /api/2.1/unity-catalog/memory-stores/{full_name}/entries`	`WRITE MEMORY STORE` na loja
Delete (excluir)	`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 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:

Campo	In	Tipo	Obrigatório	Descrição
`scope`	consulta	`string`	Sim	A partição à qual a entrada pertence, atribuída pelo chamador (por exemplo, uma ID do usuário final).
`path`	body	`string`	Sim	Caminho suave identificando a entrada dentro do escopo. Deve começar com `/memories/`. Imutável.
`contents`	body	`string`	No	Conteúdo de texto de memória de forma livre.
`description`	body	`string`	No	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.

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:

Parâmetro	Tipo	Obrigatório	Descrição
`scope`	`string`	Sim	Escopo (partição) do qual listar entradas.
`path_prefix`	`string`	No	Retornar somente entradas cujo caminho começa com esse prefixo.
`page_size`	`integer`	No	Entradas máximas por página. O servidor limita o tamanho da página.
`page_token`	`string`	No	Token de paginação de uma resposta anterior.

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

Operation	Fields	Behavior
`replace_all`	`contents`	Substitua o conteúdo completo da entrada.
`str_replace`	`old_str`, `new_str`	Substitua a única ocorrência por `old_strnew_str` (deve corresponder exatamente uma vez).
`insert`	`insert_line`, `insert_text`	Inserir `insert_text`; `insert_line` 0 = superior, omitido = acrescentar ao final.

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

Campo	Tipo	Descrição
`path`	`string`	Caminho suave da entrada dentro de seu escopo.
`contents`	`string`	Texto de memória. Omitido em respostas de 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 repositório de memória pai.
`has_contents`	`boolean`	Se a entrada não está vazia `contents` (ú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 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.

Operation	Endpoint	Privilégio necessá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
Atualização	`POST /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` na loja
Delete (excluir)	`DELETE /api/2.1/unity-catalog/conversations/{conversation_id}`	`WRITE MEMORY STORE` na loja

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:

Campo	Tipo	Obrigatório	Descrição
`memory_store`	`object`	Sim	Repositório de memória apoiando a conversa.
`memory_store.name`	`string`	Sim	Nome totalmente qualificado de três partes do repositório de memória: `catalog.schema.memory_store`.
`scope`	`object`	Sim	Escopo ao qual a conversa está fixada.
`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, uma ID do usuário final.
`metadata`	`object`	No	Metadados chave-valor controlados pelo chamador. Até 16 chaves; teclas de até 64 caracteres, valores de até 512 caracteres.
`items`	`array`	No	Itens iniciais de conversa openai para propagar a conversa (até 20). Os itens sem um `type` são armazenados como itens de mensagem.

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

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

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

Operation	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

Comentários

Esta página foi útil?

Last updated on 2026-07-01

Referência da API de Memória

Pré-requisitos

APIs do repositório de memória

Criar um repositório de memória

Obter um repositório de memória

Listar repositórios de memória

Atualizar um repositório de memória

Excluir um repositório de memória

Campos de resposta do repositório 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

Obter uma conversa

Atualizar uma conversa

Excluir uma conversa

Campos de resposta de conversa

APIs de item de conversa

Comentários

Recursos adicionais