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

Operações `run`

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 run.* 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, a org da instalação é usada em todas as ops, exceto code.* e tracker.* (que mantêm a org do seu 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.

run.begin

Abre uma RUN (uma execução de uma tarefa) ANTES de você começar a trabalhar nela.

POST /v1/run.begin · MCP loom_run_begin · role writer · idempotente · auditado

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.
user_id str '-' O usuário final a quem a linha pertence; '-' para nenhum.
session_id str '-' A conversa à qual esta run pertence.
run_id str '' O id da run; vazio ou “-” = o servidor gera um.
goal str obrigatório O que a run se propõe a fazer, nas palavras do agente; armazenado na linha da run.
user_request str '' A solicitação original que iniciou a run, literal; vazio quando não informada.
expected_outcome str '' O que uma run bem-sucedida deve produzir; armazenado para revisão posterior, vazio quando não informado.
environment str '' Rótulo em texto livre de onde a run é executada (por exemplo, ci, local); armazenado como informado.
model str '' O modelo em que o agente roda; armazenado como informado, vazio quando não informado.
consumer str '' A tag da integração que fez a chamada, registrada na linha do ledger.
role str '' O papel do agente em uma run com vários agentes: planner, executor, critic ou a palavra da própria equipe.
metadata dict[str, Any] (calculado) Pares chave/valor livres armazenados na run; role, quando definido, é adicionado a ele.
budget_usd float 0.0 Gasto com modelo, em USD, que a run pode atingir; requer um session_id (0 = nenhum, mantido em um begin reenviado do mesmo run_id).
budget_seconds int 0 Segundos que a run pode levar (0 = nenhum, mantido em um begin reenviado do mesmo run_id).
Campo de saída Tipo Significado
run_id str A run do agente (escopo da tarefa) à qual a chamada pertence; '-' para nenhuma.
status Literal['active', 'completed', 'failed', 'cancelled'] Sempre active para uma run recém-aberta.
started_at str Quando a run começou, em UTC ISO com Z; um run_id reenviado mantém o primeiro início.
next str Sugestão do protocolo: o que fazer com o run_id.

run.complete

Fecha uma execução aberta com run.begin — chame EXATAMENTE UMA VEZ, quando a tarefa terminar.

POST /v1/run.complete · MCP loom_run_complete · role writer · escrita · auditada

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.
user_id str '-' O usuário e a conversa da execução, como run.begin os recebeu: um token restrito a uma sessão resolve seu escopo a partir deles e conclui apenas a própria execução.
session_id str '-' A sessão ou conversa à qual a linha pertence; '-' para nenhuma.
run_id str obrigatório A execução do agente (escopo da tarefa) à qual a chamada pertence; '-' para nenhuma.
status Literal['completed', 'failed', 'cancelled'] obrigatório Como a execução terminou: completed, failed ou cancelled; também define o outcome padrão.
final_response str '' A resposta final do agente; armazenada na linha da execução.
confidence float 0.0 A confiança do agente no resultado (0–1), armazenada na execução; 0 registra o rótulo de resultado da sessão com confiança total.
memories_used list[str] (calculado) memory_keys nas quais o agente de fato se apoiou (um subconjunto do que recuperou).
recalled_keys list[str] (calculado) As memory keys que as ferramentas Loom da sessão ENTREGARAM (o hook PostToolUse do plugin as guarda a partir dos resultados de loom_search / memory.get e as repassa no SessionEnd).
outcome Literal['', 'positive', 'negative', 'none'] '' Resultado aplicado a memories_used. “” é derivado de status: completed → positive, failed → negative, cancelled → none.
weight int 1 Contagem de eventos que cada evento de uso, evidência ou dano de memories_used carrega (1–100).
duration_ms int 0 Substituição do tempo real; 0 = calculado a partir de started_at.
metadata dict[str, Any] (calculado) Chaves/valores mesclados aos metadados armazenados da execução; as chaves informadas aqui prevalecem.
reflection RunReflection | None None Aprendizado de processo opcional, gravado como uma memória reflection (veja RunReflection).
retain Literal['', 'keep', 'demote', 'expire'] '' O que acontece com as linhas que esta execução gravou. ‘’ = o padrão do servidor (settings.memory_run_complete_retain, keep).
Campo de saída Tipo Significado
run_id str A execução do agente (escopo da tarefa) à qual a chamada pertence; '-' para nenhuma.
status Literal['active', 'completed', 'failed', 'cancelled'] O status com o qual a execução foi fechada.
duration_ms int Duração da execução em milissegundos: duration_ms da chamada; caso contrário, agora menos started_at.
used_applied int Chaves de memories_used que corresponderam a uma linha de memória ativa (cada uma recebeu used).
evidence_applied int Linhas que também receberam um evento de evidência de resultado positivo.
harm_applied int Linhas que receberam um evento de dano de resultado negativo.
memories_written list[str] memory_keys gravadas sob este run_id (derivadas de loom.memory).
recalled int memory_keys distintas que memory.search retornou sob este run_id — requer LOOM_SEARCH_TRACE_LOG_ENABLED; -1 quando o log de rastreamento está desligado.
observations int Observações episódicas (observe.record) marcadas com este run_id.
procedure_runs_recorded int Memórias procedurais em memories_used que receberam uma linha de procedure.record_run (path vazio, ok = o resultado da execução) — o registro que procedure.evolve lê. 0 em um resultado none.
reflection_key str memory_key da reflexão gravada a partir de reflection; “” quando não há.
retain str Contagens de retenção sobre as linhas que esta execução gravou.
retained int Linhas gravadas por esta execução que o modo demote/expire deixou intactas (fixadas, verificadas, …); 0 em keep.
demoted int Linhas cuja confiança foi reduzida por retain=demote.
expiring int Linhas que receberam uma expiração por retain=expire.

run.get

Reproduz uma execução: objetivo, status, resposta final, as memórias em que ela se apoiou, as memory_keys que escreveu, quantas memórias recuperou e observou, e quanto custaram os turnos do modelo.

POST /v1/run.get · MCP loom_run_get · role viewer · leitura

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.
run_id str obrigatório A execução do agente (escopo da tarefa) à qual a chamada pertence; '-' para nenhuma.
Campo de saída Tipo Significado
found bool Falso quando não existe nenhuma execução com este id no namespace; todos os outros campos ficam vazios.
run RunRow | None A linha da execução; None quando não encontrada.
recalled int Derivações em tempo real (não armazenadas na linha): o que a execução recuperou, escreveu, observou e custou.
recalled_keys list[str] Chaves que memory.search retornou durante a execução, mais as chaves que os hooks relataram como servidas; vazio quando nenhuma das duas é conhecida.
memories_written list[str] Chaves escritas sob o id desta execução, lidas em tempo real de loom.memory.
observations int Observações episódicas (observe.record) marcadas com o id desta execução.
turns int Os turnos da sessão em loom.agent_turn_usage (o hook Stop do plugin os escreve) feitos enquanto a execução estava aberta; 0 quando a execução não tem sessão ou o hook não está instalado.
unpriced_turns int Os turnos cujo modelo a tabela de preços não conhece: cada um custa 0, então cost_usd e um orçamento de custo os deixam de fora.
cost_usd float Custo total do modelo, em USD, desses turnos; 0 como em turns.
elapsed_seconds int Segundos de started_at até completed_at (até agora enquanto ativa), pelo relógio do servidor; não é duration_ms.
over_budget list[Literal['cost', 'time']] Os orçamentos que a execução ultrapassou: cost (cost_usd > budget_usd) e time (elapsed_seconds > budget_seconds).

run.grade

Um veredito sobre uma execução FECHADA, geralmente dias depois dela — um mantenedor confirmou a descoberta, o CI passou, um revisor a rejeitou.

POST /v1/run.grade · MCP loom_run_grade · 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.
run_id str '' A execução a avaliar; “” ou “-” = nenhuma.
session_id str '' Todas as execuções fechadas desta sessão; “” ou “-” = nenhuma.
grade Literal['pass', 'fail'] obrigatório O veredito: pass (o resultado se sustentou) ou fail.
source str 'caller' Quem avaliou: maintainer, ci, reviewer, judge… (texto livre, curto).
reason str '' Por que a nota foi dada; armazenada na execução como grade_reason.
ref str '' No que a nota se baseia: uma URL, uma chave de descoberta, um id de execução de verificação.
Campo de saída Tipo Significado
graded int Execuções cuja nota foi gravada (uma execução fechada cujo veredito mudou).
run_ids list[str] Ids das execuções cuja nota foi gravada.
skipped_active int Execuções do alvo deixadas de lado porque ainda estão ativas (não fechadas).
unchanged int Execuções fechadas que já tinham esta nota, fonte, motivo e referência.
memories_counted int Memórias distintas nas quais as execuções avaliadas se apoiaram (memories_used).
proposals_decided list[RunGradeProposal] Propostas sobre as quais a política definida pelo proprietário decidiu com esta nota (somente no modo auto).

run.list

Uma página das execuções de agente de um namespace e a contagem de correspondências (total), filtradas e ordenadas.

POST /v1/run.list · MCP loom_run_list · role viewer · leitura · não listada no toolset MCP all

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 '' Somente as execuções deste agente; “”, “*” ou “-” = todos os agentes.
session_id str '' Somente as execuções desta sessão; “”, “*” ou “-” = todas as sessões.
status Literal['', 'active', 'completed', 'failed', 'cancelled'] '' Somente as execuções neste status; “” lista todos os status.
limit int 50 No máximo este número de execuções, na ordem de order_by; o servidor limita a 200.
offset int 0 Execuções a ignorar antes da página (0-100,000); padrão 0, a primeira página.
order_by Literal['started_desc', 'started_asc', 'duration_desc', 'duration_asc', 'relied_on_desc', 'relied_on_asc'] 'started_desc' Ordena por hora de início, duração (0 enquanto ativa) ou memórias usadas como base; padrão: mais recentes primeiro.
q str '' Somente as execuções cujo objetivo, id da execução ou agente contenha este texto, sem diferenciar maiúsculas de minúsculas; “” significa sem filtro.
memory_activity Literal['', 'with', 'without'] '' A página Runs oculta as execuções que não usaram nem gravaram nenhuma memória.
grade Literal['', 'ungraded', 'graded', 'pass', 'fail'] '' ungraded / graded / um veredito (pass, fail); “” = todas as execuções.
fields list[str] | None None Os campos de saída que o chamador lê (uma lista de permissão resolvida contra o modelo da linha; um nome desconhecido gera um 422); se não definido, todos os campos.
Campo de saída Tipo Significado
runs list[RunRow] Execuções correspondentes na ordem de order_by (por padrão, started_at mais recente primeiro), projetadas para fields quando informado.
total int | None Quantas execuções correspondem aos filtros; nulo em uma página cheia após a primeira.

Esta página foi útil?