Operações run
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. |