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

# Operações de `procedure`

<!-- i18n: source=docs/reference/operations/procedure.md blob=7ffae765f4965c91d0da72b0ded6b8bb9483dfb3 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/procedure.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/procedure.md), which is authoritative.


Os campos exatos que cada operação `procedure.*` 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, é usada a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a 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](/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="procedureadd"></a>

## `procedure.add`

Registra uma memória procedural — uma receita de "como fazer X" com campos estruturados (name, situation, steps).

`POST /v1/procedure.add` · MCP `loom_procedure_add` · role `writer` · escrita

| 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` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, quando a op permite. |
| `user_id` | `str` | `'-'` | O usuário final ao qual a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa à qual a linha pertence; `'-'` para nenhuma. |
| `name` | `str` | obrigatório | Nome do procedimento; a chave da memória é `procedure_<slug of name>`, então o mesmo nome a sobrescreve. |
| `situation` | `str` | obrigatório | Quando o procedimento se aplica (sua pré-condição); este texto orienta o `procedure.match`. |
| `steps` | `list[str]` | obrigatório | No mínimo dois: um único passo é uma lição, não um procedimento (o minerador segue a mesma regra). |
| `tags` | `list[str]` | *(calculado)* | Tags do chamador armazenadas no procedimento; a linha também recebe a tag `procedure`. |
| `metadata` | `dict[str, Any]` | *(calculado)* | Metadados estruturados opcionais (pré-condições como chave-valor, saídas esperadas, ...). |
| `graph` | `dict[str, Any] \| None` | `None` | Grafo executável opcional (nós = passos / memória / consolidação / decisão, arestas = dep / dataflow / branch). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Chave da linha do procedimento (`procedure_<slug>`). |
| `memory_id` | `str` | Id da versão da memória gravada. |
| `version` | `int` | Número da versão da linha gravada. |

<a id="procedureevolve"></a>

## `procedure.evolve`

Consolida os traces de execução acumulados de um procedimento em um grafo aprimorado: classifica o caminho comprovado por travessias BEM-SUCEDIDAS, marca como becos sem saída os passos que nenhuma execução usou e marca os passos e transições que ficam…

`POST /v1/procedure.evolve` · MCP `loom_procedure_evolve` · role `writer` · escrita · 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` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `memory_key` | `str` | obrigatório | Chave do procedimento a evoluir (`procedure_<slug>`). |
| `min_runs` | `int` | `3` | Mínimo de execuções incorporadas antes que a poda atue sobre as evidências. |
| `gate_mode` | `Literal['sprt', 'margin']` | `'sprt'` | Critério de aceitação para uma revisão pendente. |
| `gate_min_runs` | `int` | `3` | Execuções necessárias na revisão em teste antes de qualquer veredito. |
| `gate_margin` | `float` | `0.05` | modo margin: a queda na taxa de sucesso que provoca a reversão. |
| `gate_min_drop` | `float` | `0.15` | modo sprt: a queda que justifica reverter, as taxas de erro e a contagem de execuções a partir da qual a estimativa pontual decide. |
| `gate_alpha` | `float` | `0.05` | modo sprt: taxa de erro de falsa reversão; quanto menor, mais evidências são necessárias antes de reverter. |
| `gate_beta` | `float` | `0.2` | modo sprt: taxa de erro de queda não detectada; quanto menor, mais evidências são necessárias antes de aceitar. |
| `gate_max_runs` | `int` | `50` | modo sprt: execuções na revisão após as quais a estimativa pontual decide. |
| `strike_limit` | `int \| None` | `None` | Execuções consecutivas com falha que colocam o procedimento em quarentena; None = LOOM_PROCEDURE_STRIKE_LIMIT (3), 0 = nunca. |
| `gate_cost_tolerance` | `float` | `0.25` | Desempate por custo em uma revisão aceita: reverte quando suas execuções bem-sucedidas custam mais que esta fração acima das da revisão anterior (o primeiro entre duração, passos, tokens que ambos os lados informarem); ambos os lados precisam de `gate_cost_min_samples` sucessos com custo… |
| `gate_cost_min_samples` | `int \| None` | `None` | Execuções bem-sucedidas com custo de que cada lado precisa para a verificação de custo; `None` = `gate_min_runs`. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Chave do procedimento evoluído. |
| `version` | `int` | Versão da linha do procedimento gravada por esta chamada. |
| `revision` | `int` | A revisão de topologia do procedimento após esta chamada (uma reversão abre uma nova). |
| `changed` | `bool` | True quando esta chamada alterou os flags do grafo ou o estado de quarentena. |
| `template` | `bool` | True quando o procedimento passa a ser um template reutilizável (estável, quase sempre bem-sucedido, fora de quarentena). |
| `folded_runs` | `int` | Linhas do ledger incorporadas ao grafo por esta chamada. |
| `gate` | `Literal['none', 'undecided', 'accept', 'revert']` | Critério de aceitação de uma revisão pendente: none (nada pendente), undecided (ainda não há execuções suficientes), accept, revert. |
| `gate_mode` | `str` | O modo de critério usado (`sprt` ou `margin`); "" quando não havia revisão pendente. |
| `gate_llr` | `float` | sprt: razão de log-verossimilhança acumulada (positiva favorece "a revisão piorou as coisas"); o veredito é emitido quando ela cruza um limite. |
| `gate_before` | `dict[str, int]` | {total, ok} da revisão anterior |
| `gate_after` | `dict[str, int]` | {total, ok} da revisão em teste |
| `gate_cost_before` | `dict[str, float]` | Custo mediano das execuções bem-sucedidas de cada lado, e o motivo pelo qual uma revisão que passou no critério de sucesso ainda assim foi revertida ("cost"). |
| `gate_cost_after` | `dict[str, float]` | Custo mediano das execuções bem-sucedidas na revisão em teste. |
| `gate_reason` | `str` | `success` ou `cost` em uma reversão; "" caso contrário. |
| `dead_end_steps` | `list[str]` | Textos dos passos que nenhuma execução incorporada percorreu (rebaixados de `steps` linear). |
| `fail_prone_steps` | `list[str]` | Contraste de resultado: passos / transições desproporcionalmente presentes em execuções com falha (parcela de falhas >= taxa base de falhas do procedimento + margem, com execuções suficientes). |
| `fail_prone_transitions` | `list[str]` | Transições desproporcionalmente presentes em execuções com falha, como ids de nós `src -> dst`. |
| `run_stats` | `dict[str, int]` | O `{total, ok}` incorporado do procedimento após esta chamada. |
| `strikes` | `int` | Execuções consecutivas com falha no final do log de traces, e se o procedimento atingiu o limite de falhas. |
| `quarantined` | `bool` | True quando o procedimento atingiu o limite de falhas (veja `strike_limit`). |
| `retention` | `dict[str, float]` | Retenção de sucesso no log de traces: pares de execuções consecutivas cuja primeira foi bem-sucedida, quantas de suas segundas também foram, e a taxa. |

<a id="procedurefork"></a>

## `procedure.fork`

Copia um procedimento de um namespace que o chamador pode ler para o namespace da requisição, com a evidência zerada.

`POST /v1/procedure.fork` · MCP `loom_procedure_fork` · role `writer` · escrita · 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 | destino (o namespace da requisição; WRITER imposto pela op) |
| `agent` | `str` | `'-'` | O agente que escreve ou lê; `'-'` ou `'*'` significa qualquer agente onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `from_namespace` | `str` | obrigatório | Namespace de origem da cópia; o chamador precisa ter acesso de leitura a ele. |
| `from_org` | `str` | `''` | assume `org` por padrão |
| `memory_key` | `str` | obrigatório | Chave do procedimento a copiar em `from_namespace`. |
| `new_name` | `str` | `''` | Renomeia na entrada (a chave da memória deriva do nome). |
| `reason` | `str` | `''` | Motivo da adoção do procedimento; mantido em `forked_from`. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Chave do novo procedimento no namespace de destino. |
| `version` | `int` | Versão da linha escrita. |
| `name` | `str` | Nome do novo procedimento (`new_name` ou o da origem). |
| `steps` | `list[str]` | Os passos copiados. |
| `forked_from` | `dict[str, Any]` | Linhagem: org de origem, namespace, chave, revisão, digest, flag de template, estatísticas de execução, quem fez o fork, por quê e quando. |

<a id="procedurelist"></a>

## `procedure.list`

Enumera os procedimentos registrados no namespace (opcionalmente filtrados por prefixo de memory_key ou por tags).

`POST /v1/procedure.list` · MCP `loom_procedure_list` · papel `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` | `'*'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, quando a op permite. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `prefix` | `str` | `''` | Somente procedimentos cuja chave começa com `procedure_` + este valor; "" lista todos. |
| `tags` | `list[str]` | *(calculado)* | Somente procedimentos que tenham pelo menos uma destas tags; vazio = sem filtro de tags. |
| `limit` | `int` | `50` | No máximo este número de linhas de procedimentos é lido (o servidor limita a 500). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `procedures` | `list[_ProcedureSummary]` | Os procedimentos do namespace (nome, situação, tags, chave, data de criação). |

<a id="procedurelocate"></a>

## `procedure.locate`

Onde estou neste procedimento e o que vem a seguir?

`POST /v1/procedure.locate` · MCP `loom_procedure_locate` · função `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` | `'*'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, quando a op permite. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `memory_key` | `str` | obrigatório | Chave do procedimento que o agente está seguindo (`procedure_<slug>`). |
| `at` | `str` | `''` | Onde o agente está: um id de nó ou o nome da ferramenta da sua chamada mais recente. |
| `recent_path` | `list[str]` | *(calculado)* | Os ids de nó ou nomes de ferramenta recentes do agente nesta execução, do mais antigo para o mais recente; alimenta `revisits` e `looping`. |
| `hops` | `int` | `2` | Até onde olhar adiante. 2 basta para a próxima decisão; mais significa mais tokens. |
| `include_notes` | `bool` | `True` | Anexa notas de falha recentes do registro para as transições à frente. |
| `max_notes` | `int` | `5` | No máximo este número de notas de falha; 0 não anexa nenhuma. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Chave do procedimento lido. |
| `name` | `str` | O nome do procedimento. |
| `status` | `Literal['template', 'exercised', 'authored', 'candidate', 'quarantined']` | `template`, `exercised`, `authored`, `candidate` ou `quarantined`. |
| `matched` | `bool` | Verdadeiro quando `at` (ou o último item de `recent_path`) nomeia um nó do grafo. |
| `active` | `dict[str, Any] \| None` | O nó em que o agente está; `None` quando não há correspondência. |
| `hops` | `list[list[dict[str, Any]]]` | hops[0] = um passo à frente, hops[1] = dois à frente, ... (becos sem saída omitidos). |
| `entry_nodes` | `list[str]` | Quando não há correspondência: ids de nó sem aresta de entrada, onde o procedimento começa. |
| `dominant_next` | `list[str]` | Ids dos próximos nós ao longo do caminho comprovado a partir do nó ativo. |
| `revisits` | `dict[str, int]` | Janela da trajetória: visitas por nó nesta execução, se o nó ativo está sendo revisitado e as saídas não tomadas a partir dele. |
| `looping` | `bool` | Verdadeiro quando o nó ativo já aparece antes em `recent_path`. |
| `exits` | `list[str]` | Quando há loop: ids de nó alcançáveis a partir do nó ativo e ainda não visitados nesta execução; vazio caso contrário. |
| `failure_notes` | `list[dict[str, Any]]` | Notas que agentes deixaram em execuções que falharam e morreram em uma transição à frente. |
| `rendered` | `str` | Texto determinístico do conteúdo acima, pronto para colocar em um prompt. |
| `run_stats` | `dict[str, int]` | O `{total, ok}` consolidado do procedimento. |
| `for_agent` | `dict[str, int]` | `{total, ok}` do agente que chama; vazio para `*`, `-` ou sem execuções. |

<a id="procedurematch"></a>

## `procedure.match`

Encontra procedimentos cujo campo `situation` é semanticamente mais próximo da situação descrita pelo chamador.

`POST /v1/procedure.match` · MCP `loom_procedure_match` · 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 grava. |
| `agent` | `str` | `'*'` | fan-out padrão: procedimentos de qualquer agente no escopo |
| `user_id` | `str` | `'-'` | O usuário final ao qual a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa à qual a linha pertence; `'-'` para nenhuma. |
| `situation` | `str` | obrigatório | O estado em que o agente se encontra; é comparado com a situação armazenada de cada procedimento. |
| `top_k` | `int` | `5` | No máximo este número de candidatos é pesquisado (1–50); os filtros podem retornar menos. |
| `tags` | `list[str]` | *(calculado)* | Somente procedimentos com pelo menos uma destas tags; vazio = sem filtro de tag. |
| `namespace_scope` | `Literal['this', 'all_mine']` | `'all_mine'` | `all_mine` também pesquisa os namespaces do próprio chamador (até o limite de fan-out); `this` pesquisa apenas `namespace`. |
| `templates_only` | `bool` | `False` | Quando verdadeiro, retorna apenas procedimentos promovidos a templates reutilizáveis (topologias de workflow comprovadas e bem exercitadas). |
| `include_candidates` | `bool` | `True` | Candidatos são procedimentos que nada exercitou ainda E que nenhum humano escreveu. |
| `include_quarantined` | `bool` | `False` | Um procedimento em quarentena (suas últimas `strike_limit` execuções falharam) é descartado, a menos que seja solicitado; retornado por último, com rótulo. |
| `recent_tools` | `list[str]` | *(calculado)* | As ferramentas que o agente chamou recentemente nesta tarefa. |
| `tool_boost` | `float` | `0.2` | Peso de `tool_overlap` no `score` combinado; 0 ignora `recent_tools`. |
| `utility_weight` | `float \| None` | `None` | Peso do termo de utilidade derivado do ledger no score combinado: score = similarity + tool_boost*overlap + weight * ((ok+1)/(total+2) - 0.5). |
| `goal` | `str \| None` | `None` | O objetivo que o agente persegue, distinto do estado em que ele se encontra. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `matches` | `list[_ProcedureMatch]` | Procedimentos correspondentes, por camada de status (candidatos e em quarentena por último), depois por `score`. |
| `matched` | `int` | A taxa de acerto no ledger: quantos corresponderam, o procedimento principal e seu score (out_matched / out_procedure_key / out_score). |
| `procedure_key` | `str` | Chave de memória da melhor correspondência; "" quando nada correspondeu. |
| `score` | `float` | Score combinado da melhor correspondência; 0 quando nada correspondeu. |

<a id="procedurerecord_run"></a>

## `procedure.record_run`

Informa uma execução de um procedimento para que o loom possa aprender qual caminho realmente funciona.

`POST /v1/procedure.record_run` · MCP `loom_procedure_record_run` · role `writer` · escrita · 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` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final a quem a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa a que a linha pertence; `'-'` para nenhuma. |
| `memory_key` | `str` | obrigatório | Chave do procedimento que foi executado (`procedure_<slug>`). |
| `path` | `list[str]` | *(calculado)* | IDs dos nós, em ordem, que o agente realmente visitou nesta execução. |
| `ok` | `bool` | `True` | Se a execução foi bem-sucedida. |
| `note` | `str` | `''` | Nota livre sobre a execução (por que falhou, …); `procedure.locate` mostra as notas das execuções que falharam. |
| `ts` | `str` | `''` | Não é armazenado: o ledger registra cada execução com o horário do servidor. |
| `steps_taken` | `int \| None` | `None` | Quanto a execução custou. |
| `duration_ms` | `int` | `0` | Quanto tempo a execução levou, em milissegundos; 0 = desconhecido. |
| `tokens` | `int` | `0` | Tokens gastos pela execução; 0 = desconhecido. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Chave do procedimento no qual a execução foi registrada. |
| `version` | `int` | Sempre 0: a execução vai para o ledger, a linha do procedimento não é reescrita. |
| `run_stats` | `dict[str, int]` | `{total, ok, unfolded}` incluindo esta execução; `unfolded` conta as execuções do ledger que o `procedure.evolve` ainda não incorporou. |

<a id="procedurerevise"></a>

## `procedure.revise`

Propõe uma topologia editada para um procedimento — você é o refinador.

`POST /v1/procedure.revise` · MCP `loom_procedure_revise` · função `writer` · escrita · 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. |
| `agent` | `str` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `user_id` | `str` | `'-'` | O usuário final ao qual a linha pertence; `'-'` para nenhum. |
| `session_id` | `str` | `'-'` | A sessão ou conversa à qual a linha pertence; `'-'` para nenhuma. |
| `memory_key` | `str` | obrigatório | Chave do procedimento a revisar (`procedure_<slug>`). |
| `graph` | `dict[str, Any]` | obrigatório | A topologia proposta (grafo completo; os nós mantêm seus ids quando não mudam, para que suas estatísticas sejam preservadas). |
| `reason` | `str` | `''` | O motivo: o que as execuções que falharam mostraram e o que esta edição muda. |
| `force` | `bool` | `False` | Propõe mesmo assim uma topologia que o gate já rejeitou. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `memory_key` | `str` | Chave do procedimento revisado. |
| `version` | `int` | Versão da linha do procedimento gravada por esta chamada. |
| `revision` | `int` | O novo número de revisão; as execuções registradas a partir de agora contam para ele. |
| `prior_revision` | `int` | A revisão que ele substitui (restaurada se o gate reverter). |
| `digest` | `str` | Hash da topologia proposta; o gate o usa para reconhecer uma topologia rejeitada. |
| `steps` | `list[str]` | A lista linear de passos derivada do novo grafo. |

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