As páginas sem tradução abrem em inglês e são identificadas como inglês.
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.
Operações de procedure
Os campos exatos que cada operação procedure.* 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 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.
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. |
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. |
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. |
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). |
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. |
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. |
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. |
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. |