Pular para o conteúdo
ClickHouse Loom
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Operações de conversation

Operações de conversation

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

Os campos exatos que cada operação conversation.* recebe e retorna.

Toda op é POST /v1/<op> via HTTP e a ferramenta MCP loom_<op>. Os campos de identidade (org, namespace, agent, user_id, session_id) são preenchidos a partir do token e da sessão MCP quando o transporte consegue fazer isso. Em uma chamada HTTP sem token em um servidor de usuário único, é usada a org da instalação em todas as ops, exceto code.* e tracker.* (que mantêm a org do próprio plano), e em algumas ops também o namespace e o agente. Veja identidades e namespaces. O índice de operações explica role, kind e a listagem all do MCP. Campos de entrada desconhecidos são atendidos e listados em ignored_args.

conversation.append

Registra um turno de chat (role + content) em uma thread.

POST /v1/conversation.append · MCP loom_conversation_append · role writer · idempotente

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permitir.
thread_id str obrigatório A thread à qual adicionar; ela não precisa ter sido criada antes.
msg_id str '' opcional; o servidor deriva um hash do conteúdo quando omitido
role Literal['user', 'assistant', 'system', 'tool'] obrigatório Quem falou: user, assistant, system ou tool.
content str obrigatório O texto da mensagem, armazenado literalmente; um turno de user ou assistant também recebe embedding para conversation.search, a menos que seu texto seja considerado high.
reasoning str '' O raciocínio do modelo neste turno, armazenado junto de content; vazio = nenhum.
user_id str '-' O usuário final ao qual a linha pertence; '-' para nenhum.
run_id str '-' A execução do agente (escopo da tarefa) à qual a chamada pertence; '-' para nenhuma.
metadata dict[str, Any] (calculado) JSON livre armazenado na mensagem; lido de volta por get e list.
tokens int 0 Contagem de tokens que o chamador informa para a mensagem, armazenada como recebida; 0 = não informada.
Campo de saída Tipo Significado
msg_id str O id da mensagem: o enviado ou o hash do conteúdo derivado pelo servidor.
ts datetime Horário do servidor desta chamada; o timestamp da mensagem quando ela foi gravada.
stored bool False quando o registro está desativado ou o turno foi removido enquanto o embedding era executado.
reason Literal['', 'duplicate', 'logging_disabled', 'deleted'] “” (gravada), “duplicate” (este msg_id já foi gravado; stored=True), “logging_disabled” ou “deleted” (stored=False).

conversation.compact

Resume turnos antigos em um único turno de sistema com embedding e marca os originais com tombstone.

POST /v1/conversation.compact · MCP loom_conversation_compact · role writer · idempotente · auditado · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permitir.
thread_id str obrigatório A thread a compactar.
keep_recent int 10 Esta quantidade das mensagens mais recentes permanece literal; as mais antigas são resumidas, quantas couberem no prompt do sumarizador.
min_to_compact int 4 Ignora quando há menos turnos novos que este valor antes das últimas keep_recent; um resumo anterior não conta.
Campo de saída Tipo Significado
compacted bool Verdadeiro quando um resumo foi gravado e os originais receberam tombstone; reason explica o motivo caso contrário.
messages_summarized int Quantas mensagens mais antigas o resumo substituiu, sem contar um resumo anterior; 0 quando não houve compactação.
summary_msg_id str Id da mensagem sintética de resumo system; vazio quando não houve compactação.
tokens_in int Tokens de prompt que a chamada de LLM do sumarizador usou; 0 quando nenhuma chamada foi feita.
tokens_out int Tokens de conclusão do resumo; 0 quando nenhuma chamada foi feita.
reason str Por que compacted=False: nothing-to-compact, below-min-to-compact, already-compacted, summarizer-empty, embed-failed (tente de novo quando o embedder responder), summary-high-sensitivity (não tente de novo: a mesma janela gera o mesmo resumo).

conversation.create

Abre um contêiner de thread.

POST /v1/conversation.create · MCP loom_conversation_create · role writer · idempotente · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permitir.
thread_id str obrigatório O id da thread definido pelo chamador; recriar o mesmo id substitui seu título, metadados e run_id.
title str '' Título de exibição mostrado nas listas de threads; vazio = sem título.
metadata dict[str, Any] (calculado) JSON livre armazenado na linha da thread; conversation.get o retorna.
run_id str '-' A execução do agente (escopo da tarefa) à qual a chamada pertence; '-' para nenhuma.
user_id str '-' O usuário final ao qual a linha pertence; '-' para nenhum.
Campo de saída Tipo Significado
thread_id str Eco do thread_id de entrada.
created_at datetime Quando esta chamada gravou a linha da thread.

conversation.delete

Faz o soft-delete de uma thread: suas mensagens, a linha da thread e os embeddings que nenhum outro agente mantém.

POST /v1/conversation.delete · MCP loom_conversation_delete · papel admin · idempotente · auditado · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permitir.
thread_id str obrigatório A thread a ser removida com soft-delete.
confirm_thread_id str obrigatório Deve ser igual a thread_id, ou a chamada falha com 400 e nada é excluído.
Campo de saída Tipo Significado
tombstoned_at datetime O horário do tombstone registrado em cada linha afetada.
thread_id str Eco do thread_id de entrada.
rows_affected dict[str, int] {table_name: linhas marcadas com tombstone}; para loom.conversation_embeddings, turnos (um por turno, independentemente de quantos modelos de embedding o mantenham).
total int Soma de rows_affected em todas as tabelas.

conversation.get

Busca uma thread pelo id: metadados da thread + mensagens opcionais.

POST /v1/conversation.get · MCP loom_conversation_get · role viewer · leitura · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório “” ou “-” lê os turnos de todos os agentes na thread (um turno que dois agentes registraram uma vez), para um chamador que só tem o id, assim como conversation.search lê “” e “-”; qualquer outro valor lê apenas os turnos desse agente.
thread_id str obrigatório A thread a buscar.
include_messages bool False Desativado por padrão: mantém a consulta de metadados em duas leituras pontuais.
limit int 100 No máximo esta quantidade de mensagens quando include_messages está ativo (1-1000).
offset int 0 Mensagens a pular a partir da extremidade da qual order conta.
order Literal['asc', 'desc'] 'asc' A partir de qual extremidade da thread a página é contada.
Campo de saída Tipo Significado
found bool False quando a thread não tem nem linha de thread nem mensagem ativa.
thread_id str Eco do thread_id de entrada.
title str Título de conversation.create ou update; vazio quando nenhum foi definido.
metadata dict[str, Any] JSON de metadados da thread; {} quando nenhum foi definido, exceto pela marca title_refused do gerador de títulos.
run_id str A execução do agente (escopo de tarefa) à qual a chamada pertence; '-' para nenhuma.
user_id str O usuário final ao qual a linha pertence; '-' para nenhum.
agent str O dono da thread (o agente da linha da thread); para uma thread construída apenas por appends, o último autor entre as mensagens lidas, portanto vazio sem include_messages.
created_at datetime | None Quando a linha da thread foi escrita pela primeira vez; None para uma thread construída apenas por appends.
updated_at datetime | None Quando a linha da thread mudou pela última vez; None para uma thread construída apenas por appends.
msg_count int Mensagens ativas (não marcadas como removidas) na thread, retornado mesmo sem as mensagens.
messages list[_ConversationEntry] Preenchido apenas com include_messages=True; fatiamento simples por limit/offset (percursos paginados por cursor ficam em conversation.list).
next_cursor str | None Com order="asc", o cursor de conversation.list para os turnos após esta página; None quando a página chega ao fim ou a ordem é desc.

conversation.list

Enumera as threads de conversa armazenadas para um agente / namespace.

POST /v1/conversation.list · MCP loom_conversation_list · role viewer · leitura · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório “” ou “-” lê os turnos de todos os agentes na thread (um turno que dois agentes registraram uma vez), para um chamador que tem apenas o seu id, assim como conversation.search lê “” e “-”; qualquer outro valor lê apenas os turnos desse agente.
thread_id str obrigatório A thread a ser percorrida página por página, da mensagem mais antiga para a mais recente.
run_id str | None None filtro opcional; None ou “-” = todas as execuções
limit int 100 No máximo este número de mensagens por página (1-1000).
cursor str | None None (ts, msg_id) opaco
Campo de saída Tipo Significado
rows list[_ConversationEntry] A página de mensagens em ordem cronológica.
next_cursor str | None Passe como cursor para a próxima página; None quando esta for a última página.

conversation.list_saved_messages

Percorre as mensagens que um usuário salvou, da mais recente para a mais antiga, sem consulta: a primeira visualização de um painel “Salvas” antes de qualquer digitação.

POST /v1/conversation.list_saved_messages · MCP loom_conversation_list_saved_messages · role viewer · leitura · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou escreve.
agent str obrigatório O agente que escreve ou lê; '-' ou '*' significa qualquer agente, onde a op permite.
user_id str obrigatório Somente as mensagens salvas por este usuário são listadas.
conversation_id str | None None Opcional: somente as mensagens salvas de uma conversa.
limit int 50 No máximo esta quantidade de mensagens por página (1-200).
cursor str | None None Opaco; passe o next_cursor da página anterior.
fields list[str] | None None Os campos de saída que o chamador lê (uma lista de permissão resolvida com base no modelo de linha; um nome desconhecido resulta em 422); se não definido, todos os campos.
Campo de saída Tipo Significado
rows list[_SavedMessageHit] A página, da mais recentemente salva para a mais antiga.
next_cursor str | None Passe como cursor para obter a próxima página; None quando esta for a última página.

conversation.save_message

Salva uma mensagem de chat que um usuário escolheu para a busca, independentemente de o namespace registrar transcrições ou não.

POST /v1/conversation.save_message · MCP loom_conversation_save_message · role writer · idempotente · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a operação lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente onde a operação permitir.
conversation_id str obrigatório O id da conversa do cliente; ele continua sendo o id da thread no Loom.
message_id str obrigatório O id estável da mensagem do cliente.
role Literal['user', 'assistant'] obrigatório Somente mensagens selecionáveis de usuário e de assistente são incorporadas (embedded).
content str obrigatório O texto da mensagem; ignorado quando a transcrição já contém a mensagem.
user_id str obrigatório O proprietário é um filtro rígido na operação de busca pareada.
Campo de saída Tipo Significado
conversation_id str
message_id str
indexed bool True quando o turno está salvo e tem um vetor que a busca de salvos ranqueia: uma nova gravação, um novo salvamento (concluindo o que um salvamento interrompido deixou pendente) e um turno da transcrição que agora está marcado como salvo.
reason Literal['', 'duplicate', 'owner_mismatch', 'deleted', 'unsupported_role', 'embed_failed', 'high_sensitivity'] “duplicate”: já salvo, nada mudou. “owner_mismatch”: o turno armazenado pertence a outro usuário. “deleted”: o turno armazenado foi marcado com tombstone. “unsupported_role”: o turno armazenado é um turno de sistema ou de ferramenta, que não é incorporado.…
ts datetime O timestamp do turno armazenado; o momento da recusa quando ela ocorre.

conversation.saved_status

Quais mensagens de uma conversa um usuário salvou, em uma única chamada: um cliente de chat desenha o estado de salvamento de cada mensagem quando abre a conversa.

POST /v1/conversation.saved_status · MCP loom_conversation_saved_status · role viewer · leitura · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permitir.
user_id str obrigatório O usuário final a quem a linha pertence; '-' para nenhum.
conversation_id str obrigatório A conversa à qual as mensagens pertencem; os ids de mensagem são únicos dentro dela.
message_ids list[str] obrigatório As mensagens a verificar (1-500).
Campo de saída Tipo Significado
saved list[str] O subconjunto de message_ids que este usuário salvou, na ordem em que foram pedidos.

conversation.search

Classifica as mensagens de uma conversa por similaridade de embedding com query.

POST /v1/conversation.search · MCP loom_conversation_search · role viewer · leitura · não listada no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório “*” ou “-” busca nos turnos de todos os agentes; qualquer outro valor busca apenas nos turnos desse agente.
query str obrigatório Texto comparado ao conteúdo das mensagens, por similaridade de embedding, ou por substring quando o embedder não está disponível.
thread_id str | None None opcional: restringe a uma thread
run_id str | None None opcional: filtra por run_id; None ou “-” = todas as execuções
role Literal['user', 'assistant', 'system', 'tool'] | None None Filtra por autor da mensagem; turnos de system que não sejam resumos de compactação, e turnos de tool, não têm embedding, então só correspondem no fallback de substring.
user_id str | None None Filtro opcional por proprietário; None ou “-” = todos os usuários.
top_k int 20 No máximo esta quantidade de resultados (1-200).
namespace_scope Literal['this', 'all_mine'] 'all_mine' “all_mine” também lê os namespaces do próprio chamador, até memory_search_fanout_max_namespaces, como o knowledge.search faz.
Campo de saída Tipo Significado
hits list[_ConversationHit] Mensagens correspondentes, das mais similares para as menos similares, e vazio quando nenhuma atinge o piso de similaridade; no fallback de substring, das mais recentes para as mais antigas, sem piso.
namespaces_skipped list[str] Namespaces do chamador que uma busca all_mine não leu porque ela para em memory_search_fanout_max_namespaces; indique um deles pelo nome para pesquisá-lo.

conversation.search_saved_messages

Busca híbrida apenas nas mensagens que um usuário salvou com conversation.save_message, não em toda a transcrição.

POST /v1/conversation.search_saved_messages · MCP loom_conversation_search_saved_messages · role viewer · leitura · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente quando a op permite.
user_id str obrigatório O usuário final a quem a linha pertence; '-' para nenhum.
query str obrigatório
conversation_id str | None None
role Literal['user', 'assistant'] | None None
top_k int 20
search_mode Literal['hybrid', 'semantic', 'lexical'] 'hybrid' hybrid: a perna vetorial e uma perna BM25 sobre o texto completo de cada mensagem, combinadas por reciprocal rank; semantic: somente vetorial; lexical: somente BM25.
lexical_weight float 1.0 Peso da perna BM25 na fusão (modo hybrid); 1.0 = peso igual.
Campo de saída Tipo Significado
hits list[_SavedMessageHit]

conversation.set_logging

Ativa ou desativa o registro de transcrições de conversas neste namespace.

POST /v1/conversation.set_logging · MCP loom_conversation_set_logging · role admin · idempotente · auditada · não listada no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
enabled bool obrigatório True registra transcrições neste namespace; False faz com que append não armazene nada.
Campo de saída Tipo Significado
namespace str O namespace que a op lê ou grava.
enabled bool O estado atual da chave de registro.

conversation.threads

Threads de conversa recentes de um namespace, das mais novas para as mais antigas.

POST /v1/conversation.threads · MCP loom_conversation_threads · role viewer · read

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str '*' “*” ou “-” lista as threads de todos os agentes
window_days int 30 Apenas threads com uma mensagem ativa nos últimos tantos dias (1-365).
limit int 30 No máximo este número de threads (1-200).
offset int 0 Threads a ignorar antes da página (0-100,000); o padrão é 0, a primeira página.
fields list[str] | None None Os campos de saída que o chamador lê (uma lista de permissão resolvida contra o modelo de linha; um nome desconhecido gera um 422); se não definido, todos os campos.
Campo de saída Tipo Significado
threads list[ConversationThreadSummary] Threads, da atividade mais recente para a mais antiga, cada uma com sua contagem e o trecho da última mensagem.

conversation.unsave_message

Remove uma mensagem da busca de mensagens salvas de um usuário.

POST /v1/conversation.unsave_message · MCP loom_conversation_unsave_message · role writer · idempotente · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente quando a op permite.
conversation_id str obrigatório O id da conversa do cliente, como informado em conversation.save_message.
message_id str obrigatório O id da mensagem do cliente, como informado em conversation.save_message.
user_id str obrigatório Somente a linha salva deste usuário é removida.
Campo de saída Tipo Significado
conversation_id str
message_id str
found bool False quando não existe nenhuma linha salva deste usuário: nunca foi salva, já foi removida ou foi salva por outro usuário (o que não é confirmado).
removed bool True quando o próprio turno foi removido: o namespace não registra transcrições, então a linha existia apenas por causa do salvamento.
ts datetime

conversation.update

Atualiza o título, os metadados ou o run_id de uma thread.

POST /v1/conversation.update · MCP loom_conversation_update · papel writer · idempotente · não listado no toolset all do MCP

Campo de entrada Tipo Padrão Significado
org str obrigatório O tenant (primeiro elemento da tupla de identidade).
namespace str obrigatório O namespace que a op lê ou grava.
agent str obrigatório O agente que grava ou lê; '-' ou '*' significa qualquer agente, onde a op permite.
thread_id str obrigatório A thread a atualizar; uma thread desconhecida retorna updated=False.
title str | None None O handler lança 400 se os três campos estiverem ausentes (uma chamada sem efeito indica um bug do chamador).
metadata dict[str, Any] | None None Novo JSON de metadados, que substitui o objeto antigo por inteiro; None mantém o valor atual.
run_id str | None None A nova execução da thread; None ou “-” mantém o valor atual, “” desvincula a thread da execução.
Campo de saída Tipo Significado
updated bool False quando a thread não tem linha de thread (nunca foi criada); nada é gravado nesse caso.
thread_id str Eco do thread_id de entrada.
updated_at datetime | None O novo updated_at da thread; None quando nada foi atualizado.

Esta página foi útil?