Pular para conteúdo

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.