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.
Procedimentos e aprendizados
Esta página trata do que um agente aprende ao executar tarefas, em oposição aos fatos que lhe são informados: procedimentos ("como fazer X", um grafo de etapas aprendido a partir de execuções reportadas), reflexões (lições escritas no fim de uma execução) e aprendizados (uma fila de revisão de fatos candidatos que um administrador promove). Os registros tipados estão em escrita de memória.
Procedimentos
Um procedimento é um grafo direcionado: os nós são etapas ou chamadas de ferramenta, as arestas são as transições permitidas, e cada aresta carrega um texto que o agente lê (condition, guidance, pitfalls). O Loom nunca executa um procedimento. O agente executa e reporta; o Loom armazena o grafo, serve a parte relevante, aprende com os resultados e promove o que funciona.
Ele é armazenado como uma memória procedural sob a chave procedure_<slug of name>, com seu registro de execuções em loom.procedure_runs.
Operações
| Operação | Papel | O que faz |
|---|---|---|
procedure.add |
writer | Registra name, situation (com embedding para correspondência), steps (2–64), e opcionalmente graph, tags, metadata. |
procedure.match |
viewer | Principais procedimentos para uma situation (e goal), com grafo, estatísticas de execução e status de confiança. |
procedure.locate |
viewer | O nó ativo e as transições até hops (padrão 2, no máximo 4) à frente. |
procedure.record_run |
writer | Reporta uma execução: ids dos nós visitados (path), ok, note opcional, custo. |
procedure.evolve |
writer | Incorpora as execuções registradas: caminho comprovado, becos sem saída, etapas propensas a falha, promoção a template, quarentena. |
procedure.revise |
writer | Propõe uma nova topologia; o registro de execuções a aceita ou a reverte. |
procedure.fork |
writer | Copia a forma de um procedimento de outro namespace legível, sem suas evidências. |
procedure.list |
viewer | Inventário por prefix de chave ou tags. |
Listas de campos: referência de operações.
O grafo
- Tipos de nó:
step,action(uma chamada de ferramenta;toola nomeia),memory,consolidation,decision,template_ref. - Tipos de aresta:
dep,dataflow,branch,converge. procedure.addrejeita ids de nó duplicados, arestas para nós desconhecidos, laços para o próprio nó e ciclos sem saída.- Limites: 256 nós, 1,024 arestas, 512 caracteres por atributo de aresta.
- Um procedimento registrado apenas com
stepsrecebe um grafo linear com idsn1,n2, ….
{
"nodes": [
{ "id": "cash", "kind": "action", "tool": "check_cash_in_bank" },
{ "id": "forecast", "kind": "action", "tool": "cash_flow_forecast" },
{ "id": "raise", "kind": "action", "tool": "fund_raising_request" },
{ "id": "close", "kind": "action", "tool": "book_closing" }
],
"edges": [
{ "src": "cash", "dst": "forecast", "kind": "dataflow" },
{
"src": "forecast",
"dst": "raise",
"kind": "branch",
"condition": "projected runway below the safety buffer",
"pitfalls": "do not stack a second request while one is pending"
},
{ "src": "forecast", "dst": "close", "kind": "branch", "condition": "runway healthy" },
{ "src": "raise", "dst": "close" }
]
}
Uma linha procedural escrita com memory.set que não seja um corpo de procedimento (uma situation não vazia e pelo menos dois steps) é armazenada como semantic, com a tag retyped_from:procedural.
Correspondência
procedure.match classifica pela similaridade entre a situation do chamador e cada uma das armazenadas, em todos os namespaces do próprio chamador, até o limite de fan-out (namespace_scope="all_mine"). Ela pode adicionar:
| Termo | Efeito |
|---|---|
| Sobreposição de ferramentas | recent_tools favorece procedimentos cujos nós de ação as cobrem (tool_boost, padrão 0.2). |
| Objetivo | Com goal, situação e objetivo são pontuados separadamente e combinados por média geométrica. |
| Utilidade | utility_weight (padrão 0 = desligado) soma a taxa de sucesso suavizada do registro de execuções. |
Toda correspondência carrega um status de confiança:
| Status | Significado |
|---|---|
template |
Promovido: pelo menos 5 execuções bem-sucedidas, taxa de sucesso de pelo menos 0.8 e uma topologia que evolve não altera mais. |
exercised |
Tem pelo menos uma execução registrada. |
authored |
Registrado e nunca executado. |
candidate |
Minerado por máquina e nunca executado: listado por último, rotulado (unproven) em context.pack, descartado por include_candidates=false. |
quarantined |
Suas últimas strike_limit execuções falharam; descartado a menos que include_quarantined=true. O próximo sucesso o libera. |
templates_only=true retorna apenas templates. for_agent mostra as execuções do próprio agente chamador; run_stats_by_agent as detalha por agente.
Orientação localizada
procedure.locate recebe memory_key e at (o id do nó ou a ferramenta recém-usada) ou recent_path. Ele retorna o nó ativo e as transições à frente, cada uma com sua condition, guidance, pitfalls e com que frequência execuções anteriores a seguiram e tiveram sucesso, além de um texto rendered pronto para prompt. Com recent_path, ele marca as transições visitadas, define looping com os exits não tomados em caso de revisita, e anexa os failure_notes de outras execuções. Quando at não corresponde a nada, matched=false e entry_nodes indicam por onde começar.
Aprendendo com as execuções
procedure.record_run acrescenta uma linha a loom.procedure_runs: o caminho, ok, note, a revision do grafo, steps_taken, duration_ms e tokens. run.complete também registra uma execução (com caminho vazio) para qualquer chave de procedimento em memories_used; um agente que chama record_run por conta própria deve deixar a chave fora de memories_used (execuções).
procedure.evolve incorpora as execuções mais novas que a marca d'água ledger_folded_through. Quando min_runs (padrão 3) é atingido, ele:
- segue as arestas com mais travessias bem-sucedidas como o caminho comprovado;
- marca como becos sem saída os nós de etapa e ação que nenhuma execução usou (reversível);
- marca como
fail_prone_steps/fail_prone_transitionsos nós e transições cuja taxa de falha excede claramente a taxa base do procedimento: leia-os como pitfalls; - promove um procedimento que atinge o critério de template;
- coloca em quarentena aquele cujas últimas
strike_limitexecuções falharam (LOOM_PROCEDURE_STRIKE_LIMIT, padrão 3; 0 = desligado).
Revisões passam por um portão
procedure.revise recebe um graph completo e um reason, mantém as estatísticas dos ids de nó que sobrevivem e guarda o grafo anterior como pending_revision. As execuções seguintes carregam a nova revisão, e procedure.evolve as compara com as da revisão anterior:
| Portão | Parâmetros (padrões) |
|---|---|
gate_mode="sprt" (padrão) |
Teste sequencial da razão de probabilidades: gate_min_drop 0.15, gate_alpha 0.05, gate_beta 0.20, gate_max_runs 50, gate_min_runs 3. |
gate_mode="margin" |
Uma gate_margin fixa sobre a diferença da taxa de sucesso. |
| Custo | Uma revisão cujas execuções bem-sucedidas custam mais que gate_cost_tolerance (0.25) acima das da anterior é revertida (gate_cost_min_samples). |
O teste sequencial decide assim que a evidência é forte o bastante. Uma revisão revertida vai para rejected_revisions, e procedure.revise se recusa a propô-la novamente, a menos que force=true.
Quais procedimentos um pack injeta
context.pack e memory.stack injetam um procedimento correspondente como etapas a seguir; por isso, com autenticação ativa, eles carregam apenas procedimentos escritos pelo principal chamador (o actor da linha). O procedimento de um colega em um namespace compartilhado ainda é retornado por um procedure.match explícito, cujas correspondências carregam actor. Com a autenticação desativada, toda correspondência é injetada.
Medindo se um procedimento ajuda
context.pack pode reter o procedimento mais bem correspondido com probabilidade procedure_explore_rate (padrão 0).
O pack lista os procedimentos exibidos em procedure_keys e os retidos em procedure_keys_withheld, de modo que os resultados das sessões possam ser comparados.
Exemplo
from loom import Agent
async with Agent(org="acme", namespace="support", agent="triage-bot") as bot:
added = await bot.procedure.add(
"refund request",
"a customer asks for a refund on a paid invoice",
["look up the invoice", "check the refund policy window", "issue or decline"],
tags=["billing"],
)
hits = await bot.procedure.match(
"customer wants money back for last month's invoice", goal="resolve a refund"
)
key = added["memory_key"] # procedure_refund_request
await bot.procedure.record_run(key, ["n1", "n2", "n3"], ok=True, duration_ms=42_000)
await bot.procedure.evolve(key)
O evolve do SDK envia gate_min_runs=5 e gate_margin=0.05, a menos que indicado de outra forma.
O add do SDK recebe apenas steps; registre um graph explícito via HTTP ou MCP.
memory.delete em uma chave de procedimento também exclui as linhas do seu registro de execuções.
Reflexões
Uma reflexão é uma lição sobre uma execução (what_worked, what_failed, lessons, com
chaves evidence), armazenada como uma memória reflection. Ela recebe embedding, mas fica de fora do
recall sem filtros, porque é uma hipótese sobre o processo, não um fato. Leia as reflexões
com memory.search(memory_type="reflection").
run.complete(reflection=...)grava a lição do próprio agente (execuções).- O worker
reflection_distill(desativado por padrão; faz chamadas ao modelo) combina sessões que falharam com alta confiança com as sessões bem-sucedidas mais próximas e destila a diferença.
Fila de revisão de learnings
Um learning é um fato candidato com seus apoiadores (supporter_count, supporters,
confidence_avg, rationale, source_kind), aguardando a decisão de uma pessoa. O Loom
registra a escolha do revisor e nunca a toma. Qualquer candidato que não seja uma regra de um bot
(veja abaixo) é gravado pelo seu próprio processo em loom.learnings_queue.
A extração registra por conta própria um tipo de candidato. Com os learnings de turnos do assistente ativados
(LOOM_MEMORY_EXTRACT_AGENT_LEARNINGS, desativado por padrão), uma regra que um bot declara sobre o próprio
comportamento em uma conversa se torna um candidato assistant_turn para aquele agente
(agent), nunca uma memória (extração). A linha do
candidato contém a regra e nenhuma fala de usuário. Cada sessão que declara a regra adiciona uma linha
a loom.learnings_supporters com as citações do próprio usuário. Quando o candidato é listado,
supporter_count é o número de usuários finais distintos, supporter_sessions o de
sessões distintas, supporter_writers o de principals distintos que gravaram essas linhas (um token
não fixado a um usuário pode enviar qualquer user_id, então muitos usuários vindos de um mesmo writer contam como uma única
fonte), e rationale são as citações do apoiador restante mais antigo. O apoio nunca
o promove; promovê-lo publica a regra no conhecimento do namespace, com a tag
agent:<agent>. context.pack com include_knowledge, memory.stack, loom_search
e memory.ask a entregam às leituras daquele agente para todos os usuários e a omitem das leituras de
outros agentes. Via HTTP, uma leitura de todo o namespace (agente *, o padrão de memory.ask)
recebe as regras de todos os bots, e uma leitura sem agente (-, o padrão de loom_search)
não recebe nenhuma regra promovida para um bot nomeado. Via MCP, um agent não informado é o
do cliente (claude-code, ...), então essas leituras entregam as regras desse agente. Uma regra para
todos os agentes é entregue a toda leitura. Um token fixado a um usuário final
(read_user_id) atua como o agente que ele nomeia, nunca como o agent do corpo; qualquer outro token,
inclusive um token own_user sem fixação, atua como o agent do corpo. Um token que o Loom gera com uma
fixação read_user_id não nomeia nenhum agente, então não registra regra de nenhum bot e não recebe nenhuma regra
promovida para um bot nomeado. knowledge.search não é filtrado por agente: qualquer agente que
possa ler o namespace a encontra ali.
A exclusão de um usuário apaga as linhas de apoiador dele, e as citações junto. Um candidato que fica sem apoiadores é excluído se estiver pendente. Se já tiver sido decidido, mantém sua linha de status com a regra apagada, de modo que uma regra rejeitada nunca volte como pendente.
learnings.quality conta por padrão o seeder de conversas, pois ele informa a qualidade
da extração; passe source_kind="assistant_turn" para as regras de bots.
| Op | Papel | O que faz |
|---|---|---|
learnings.list |
viewer | Candidatos por status (pending por padrão, promoted, rejected) e source_kind. |
learnings.review |
admin | decision promote ou reject, com reason. destination: memory (a zona compartilhada para um candidato de apoiadores, uma linha de namespace sob o user_id do aprovador para um fato originado de conversa, a linha de user_id '-' do agente para a regra de um bot), knowledge ou both; se não definido, knowledge para a regra de um bot e memory nos demais casos. Um candidato definition é recusado para memory e both: ele é promovido com memory.promote. |
learnings.quality |
viewer | Contagens de pendentes / promovidos / rejeitados por namespace e a taxa de aprovação. |
learnings.list e learnings.review existem apenas via HTTP e SDK (bot.learnings). Uma
promoção para memory carrega o id do candidato, então
memory.lineage a rastreia até o candidato.
Revisar um candidato novamente com a decisão que ele já tem não faz nada; rejeitar um
candidato promovido o marca como rejeitado e deixa o que a promoção gravou (exclua o documento
learning://<candidate_id> de uma promoção de conhecimento com knowledge.delete para
parar de entregá-lo). A regra de um bot cujo último apoiador foi apagado responde 404, como
um candidato inexistente. Listas de campos:
referência de operações.
Configurações
| Configuração | Efeito |
|---|---|
LOOM_PROCEDURE_STRIKE_LIMIT |
Execuções com falha consecutivas antes da quarentena (Processos em segundo plano). |
LOOM_REFLECTION_DISTILL_* |
O processo de destilação de reflexões (Consolidação). |
LOOM_MEMORY_EXTRACT_AGENT_LEARNINGS |
Desativado por padrão: a extração registra as regras do assistente sobre si mesmo como candidatos assistant_turn (Extração). |
Limites
- Evolve é explícito. Nada consolida o ledger com base em um temporizador; chame
procedure.evolvedepois que as execuções forem registradas. - Um caminho deve nomear ids de nós reais do grafo armazenado.
- O grafo mantém os últimos 50 traces; as estatísticas agregadas das execuções sobrevivem ao truncamento.
- Procedimentos bifurcados começam sem evidências.
Relacionados
- Execuções:
run.complete,memories_usede reflexões. - Memória de trabalho e perfis: como o
context.packexibe procedimentos. - Namespaces e compartilhamento: a zona compartilhada para a qual um candidato de supporters é promovido.
- Conhecimento: para onde a regra de um bot é promovida por padrão.
Os rascunhos de definição criados a partir de lacunas de conhecimento e do histórico de consultas ficam visíveis apenas para os administradores do namespace, incluindo as contagens da fila e a linhagem. Aprovar um rascunho publica seu valor completo, incluindo o SQL de apoio, para os leitores do namespace. Consulte rascunhos de definição para a configuração da fonte, os conflitos de revisão e a promoção interrompida.