---
title: "Operações `run`"
---

<!-- i18n: source=docs/reference/operations/run.md blob=4f9606262a494386856be2505b8e7fd3dbb703f0 model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/run.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/run.md), which is authoritative.

<a id="run-operations"></a>

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

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

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](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request) também o namespace e o agente. Veja [identidades e namespaces](/docs/pt-BR/concepts/identities-and-namespaces). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

<!-- prettier-ignore-start -->

<a id="runbegin"></a>

## `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. |

<a id="runcomplete"></a>

## `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`. |

<a id="runget"></a>

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

<a id="rungrade"></a>

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

<a id="runlist"></a>

## `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. |

<!-- prettier-ignore-end -->
