{ "generated": "2026-08-01T23:34:43.761Z", "count": 15, "license": "Content © Santiago Santa María Morales, licensed CC BY 4.0. Attribution required: credit the author and link the canonical URL.", "license_spdx": "CC-BY-4.0", "license_url": "https://creativecommons.org/licenses/by/4.0/", "entries": [ { "slug": "context-compression", "category": "cost", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/context-compression", "api": "https://santismm.com/api/patterns/context-compression", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Summarization", "Context pruning", "RAG", "Prompt compression (LLMLingua)" ], "references": [ { "title": "Jiang et al. — LLMLingua (2023)", "url": "https://arxiv.org/abs/2310.05736" }, { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "long-term-memory", "semantic-caching" ], "locales": { "en": { "name": "Context Compression", "summary": "Context compression reduces the tokens fed to a model on each call while preserving the information it actually needs to act. Use it on long-running agents and long conversations to cut cost and latency and to stay inside the context window. The three levers are summarizing history, pruning irrelevant context, and compressing prompts. The central risk is lossy: dropping the one detail that mattered. Measure information retained, not just tokens saved.", "problem": "Long-running agents and multi-turn conversations accumulate context: every tool result, prior message, and retrieved document is replayed on the next call. Token count grows roughly linearly with the interaction, so per-call cost and latency climb, and eventually the window overflows and the oldest (sometimes most important) content is silently truncated. Naive fixes — bigger windows, more aggressive truncation — either raise cost or destroy the information the model needs to stay coherent.", "context": "Applies when context grows unbounded relative to what any single step needs: conversational assistants with long histories, autonomous agents looping over many tool calls, RAG pipelines that over-retrieve, and batch jobs where prompt size dominates cost. It fits when much of the accumulated context is redundant or stale, when you control prompt assembly, and when you can tolerate some reconstruction error. It is a poor fit when every token is load-bearing (legal, audit, exact-recall tasks) or when interactions are short enough that the window is never pressured.", "solution": [ "Treat the live context as a budget you actively manage rather than an append-only log. Three complementary levers exist. Summarization replaces a span of history with a shorter synopsis — typically a rolling summary of older turns, refreshed periodically, while recent turns stay verbatim. Pruning removes context that is irrelevant to the current step: deduplicate, drop stale tool output, and select only the retrieved chunks that score above a relevance threshold. Prompt compression (for example LLMLingua) uses a smaller model to delete or rephrase low-information tokens before sending the prompt, trading a small accuracy cost for large token reductions.\n\nCompose these into a pipeline with explicit boundaries: keep a verbatim recent window, a rolling summary of older history, and a retrieval slot filled on demand. Protect a 'pinned' region for facts that must never be compressed — identifiers, constraints, the current goal. Crucially, instrument the result: run an evaluation set comparing answers with and without compression so you can see when quality degrades, and tune the aggressiveness per workload rather than globally. Compression is a quality-versus-cost dial, not a free win." ], "components": [ "Rolling summarizer", "Relevance pruner", "Prompt compressor", "Pinned region", "Context budget controller", "Retention evaluator" ], "benefits": [ "Sending fewer tokens directly reduces input cost on every call, which compounds across long agent loops and high-volume traffic.", "Smaller prompts mean less to encode and shorter time-to-first-token, improving responsiveness in interactive and agentic flows.", "Bounding live context lets long conversations and many-step agents continue without overflowing the window or silently truncating.", "Removing redundant and stale context can improve quality by reducing distraction, helping the model attend to what currently matters." ], "risks": [ "Summaries and pruning can discard the single detail that later turns out to be decisive, producing confidently wrong answers.", "Rolling summaries summarize prior summaries; small omissions compound over many cycles until the thread quietly drifts.", "Running a summarizer or compressor adds its own latency, cost, and failure surface, which can offset savings on short interactions.", "Aggressive eviction can silently remove constraints or instructions the model still depends on, with no obvious error signal." ], "whenNot": [ "When every token is load-bearing — legal, audit, compliance, or precise data extraction — lossy compression is unacceptable.", "If conversations rarely pressure the window, compression overhead costs more than it saves and adds needless complexity.", "Without a retention evaluation harness, deploy nothing: you cannot tell whether compression is silently degrading answers." ], "examples": [ "An agent iterating over a large codebase keeps a verbatim recent window plus a rolling summary of earlier steps, pinning the task spec and file paths so it does not lose the goal.", "A multi-session support bot summarizes prior turns into a compact case summary, pruning resolved sub-issues while pinning the customer's account constraints.", "A retrieval pipeline that fetches many chunks applies relevance pruning and prompt compression to send only high-signal passages, cutting tokens without losing the answer." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "Long autonomous transcripts are compacted preemptively and tool results truncated to stay within the prompt budget.", "technology": "Preemptive compaction with a safety margin, tool-result truncation, a context-pruning hook, and a midturn overflow precheck.", "load": "2,810 context-compiled events across 2,776 turns over 57 days.", "results": "Compaction ran inline throughout the window, keeping multi-step autonomous turns within budget (p95 87.6s per turn) without context-overflow failures surfacing. Single-operator local-first deployment." }, "kpis": [ { "metric": "Tokens per call (input)", "note": "The primary cost driver. Track the distribution before and after compression; a healthy result is a clear reduction with no rise in downstream errors." }, { "metric": "Information retention / task quality", "note": "Compare answers with and without compression on an eval set. Good looks like quality holding steady within your tolerance as tokens drop." }, { "metric": "End-to-end latency", "note": "Net of compression overhead. Good is lower total latency; watch that summarizer or compressor calls do not erase the savings." }, { "metric": "Context-overflow / truncation rate", "note": "How often interactions hit the window limit. Good is driving this toward zero without resorting to dropping pinned content." } ], "failureModes": [ "A summary omits a constraint mentioned early; many turns later the agent violates it because that fact is simply gone from context.", "Repeated re-summarization amplifies paraphrase errors and omissions until the running summary no longer reflects what actually happened.", "A misconfigured budget compresses identifiers or instructions that were meant to be protected, breaking correctness silently.", "An aggressive relevance threshold filters out context that mattered for an edge case, so quality looks fine in tests but fails in the field." ], "lessons": [ "Token reduction is trivial to maximize and meaningless alone; the real metric is whether the model still answers correctly.", "Explicitly protect identifiers, constraints, and the current goal so no compression stage can evict them.", "Compress old history, not the active context; the most recent exchanges carry the most decision-relevant signal.", "Tune aggressiveness per workload against an eval set; what is safe for chit-chat is reckless for an audit task." ], "faqs": [ { "q": "How is this different from long-term memory?", "a": "Long-term memory persists facts outside the prompt and retrieves them on demand; context compression shrinks the live context sent on each call. They are complementary: memory decides what to bring back, compression decides how compactly it sits in the window." }, { "q": "Summarize, prune, or compress — which should I use?", "a": "Prune first (free, lossless when removing true redundancy), summarize older history when it grows unbounded, and add prompt compression only when you still need more headroom and can validate the quality cost. Most systems combine all three." }, { "q": "How do I know compression is hurting quality?", "a": "Run an evaluation set with compression on and off and compare task outcomes, not just token counts. Watch for confidently wrong answers and dropped constraints — those are the signature of lossy compression that has gone too far." } ] }, "es": { "name": "Compresión de contexto", "summary": "La compresión de contexto reduce los tokens que se envían al modelo en cada llamada conservando la información que realmente necesita para actuar. Úsala en agentes de larga duración y conversaciones extensas para recortar coste y latencia y mantenerte dentro de la ventana de contexto. Las tres palancas son resumir el historial, podar contexto irrelevante y comprimir prompts. El riesgo central es la pérdida: descartar el único detalle que importaba. Mide la información retenida, no solo los tokens ahorrados.", "problem": "Los agentes de larga duración y las conversaciones de múltiples turnos acumulan contexto: cada resultado de herramienta, mensaje previo y documento recuperado se reenvía en la siguiente llamada. El número de tokens crece casi linealmente con la interacción, por lo que el coste y la latencia por llamada suben, y al final la ventana se desborda y el contenido más antiguo (a veces el más importante) se trunca en silencio. Los arreglos ingenuos —ventanas más grandes, truncado más agresivo— elevan el coste o destruyen la información que el modelo necesita para mantener la coherencia.", "context": "Aplica cuando el contexto crece sin límite respecto a lo que necesita cada paso: asistentes conversacionales con historiales largos, agentes autónomos que iteran sobre muchas llamadas a herramientas, pipelines RAG que recuperan de más y trabajos por lotes donde el tamaño del prompt domina el coste. Encaja cuando gran parte del contexto acumulado es redundante u obsoleto, cuando controlas el ensamblaje del prompt y cuando puedes tolerar cierto error de reconstrucción. Encaja mal cuando cada token es esencial (tareas legales, de auditoría, de recuperación exacta) o cuando las interacciones son tan cortas que la ventana nunca se presiona.", "solution": [ "Trata el contexto activo como un presupuesto que gestionas de forma activa, no como un registro de solo anexar. Existen tres palancas complementarias. El resumen reemplaza un tramo del historial por una sinopsis más corta —normalmente un resumen continuo de los turnos antiguos, actualizado de forma periódica, mientras los turnos recientes se mantienen literales. La poda elimina el contexto irrelevante para el paso actual: deduplica, descarta salida de herramientas obsoleta y selecciona solo los fragmentos recuperados que superan un umbral de relevancia. La compresión de prompts (por ejemplo LLMLingua) usa un modelo más pequeño para borrar o reformular tokens de baja información antes de enviar el prompt, cambiando un pequeño coste de exactitud por grandes reducciones de tokens.\n\nCompón estas palancas en un pipeline con límites explícitos: mantén una ventana reciente literal, un resumen continuo del historial antiguo y un espacio de recuperación que se llena bajo demanda. Protege una región 'fijada' para hechos que nunca deben comprimirse —identificadores, restricciones, el objetivo actual. Y, crucialmente, instrumenta el resultado: ejecuta un conjunto de evaluación que compare respuestas con y sin compresión para ver cuándo se degrada la calidad, y ajusta la agresividad por carga de trabajo en lugar de globalmente. La compresión es un dial de calidad frente a coste, no una ganancia gratuita." ], "components": [ "Resumidor continuo", "Podador por relevancia", "Compresor de prompts", "Región fijada", "Controlador del presupuesto de contexto", "Evaluador de retención" ], "benefits": [ "Enviar menos tokens reduce directamente el coste de entrada en cada llamada, lo que se acumula a lo largo de bucles de agente largos y tráfico de alto volumen.", "Prompts más pequeños implican menos que codificar y un menor tiempo hasta el primer token, mejorando la respuesta en flujos interactivos y de agentes.", "Acotar el contexto activo permite que conversaciones largas y agentes de muchos pasos continúen sin desbordar la ventana ni truncar en silencio.", "Eliminar contexto redundante y obsoleto puede mejorar la calidad al reducir la distracción, ayudando al modelo a atender a lo que importa ahora." ], "risks": [ "Los resúmenes y la poda pueden descartar el único detalle que luego resulta decisivo, produciendo respuestas erróneas con seguridad.", "Los resúmenes continuos resumen resúmenes previos; pequeñas omisiones se acumulan a lo largo de muchos ciclos hasta que el hilo se desvía sin avisar.", "Ejecutar un resumidor o compresor añade su propia latencia, coste y superficie de fallo, que puede anular el ahorro en interacciones cortas.", "La expulsión agresiva puede eliminar en silencio restricciones o instrucciones de las que el modelo aún depende, sin una señal de error evidente." ], "whenNot": [ "Cuando cada token es esencial —legal, auditoría, cumplimiento o extracción precisa de datos— la compresión con pérdida es inaceptable.", "Si las conversaciones rara vez presionan la ventana, la sobrecarga de compresión cuesta más de lo que ahorra y añade complejidad innecesaria.", "Sin un arnés de evaluación de retención, no despliegues nada: no puedes saber si la compresión degrada las respuestas en silencio." ], "examples": [ "Un agente que itera sobre una base de código grande mantiene una ventana reciente literal más un resumen continuo de los pasos anteriores, fijando la especificación de la tarea y las rutas de archivo para no perder el objetivo.", "Un bot de soporte multisesión resume los turnos previos en un resumen de caso compacto, podando subincidencias resueltas mientras fija las restricciones de la cuenta del cliente.", "Un pipeline de recuperación que trae muchos fragmentos aplica poda por relevancia y compresión de prompts para enviar solo los pasajes de alta señal, recortando tokens sin perder la respuesta." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "Las transcripciones autónomas largas se compactan de forma preventiva y los resultados de herramientas se truncan para no salirse del presupuesto de prompt.", "technology": "Compactación preventiva con margen de seguridad, truncado de resultados de herramientas, hook de poda de contexto y verificación de desbordamiento a mitad de turno.", "load": "2.810 eventos de context-compiled sobre 2.776 turnos en 57 días.", "results": "La compactación corrió en línea durante toda la ventana, manteniendo los turnos autónomos de varios pasos dentro de presupuesto (p95 87,6s por turno) sin que aparecieran fallos por desbordamiento de contexto. Despliegue local-first mono-operador." }, "kpis": [ { "metric": "Tokens por llamada (entrada)", "note": "El principal motor del coste. Sigue la distribución antes y después de la compresión; un resultado sano es una reducción clara sin aumento de errores aguas abajo." }, { "metric": "Retención de información / calidad de tarea", "note": "Compara respuestas con y sin compresión en un conjunto de evaluación. Lo bueno es que la calidad se mantenga estable dentro de tu tolerancia mientras bajan los tokens." }, { "metric": "Latencia de extremo a extremo", "note": "Neta de la sobrecarga de compresión. Lo bueno es menor latencia total; vigila que las llamadas del resumidor o compresor no borren el ahorro." }, { "metric": "Tasa de desbordamiento / truncado de contexto", "note": "Con qué frecuencia las interacciones alcanzan el límite de la ventana. Lo bueno es llevar esto hacia cero sin recurrir a descartar contenido fijado." } ], "failureModes": [ "Un resumen omite una restricción mencionada al principio; muchos turnos después el agente la viola porque ese hecho simplemente desapareció del contexto.", "Resumir repetidamente amplifica errores de paráfrasis y omisiones hasta que el resumen acumulado ya no refleja lo que de verdad ocurrió.", "Un presupuesto mal configurado comprime identificadores o instrucciones que debían estar protegidos, rompiendo la corrección en silencio.", "Un umbral de relevancia agresivo filtra contexto que importaba para un caso límite, así la calidad parece bien en pruebas pero falla en producción." ], "lessons": [ "La reducción de tokens es trivial de maximizar y carece de sentido por sí sola; la métrica real es si el modelo sigue respondiendo correctamente.", "Protege de forma explícita identificadores, restricciones y el objetivo actual para que ninguna etapa de compresión pueda expulsarlos.", "Comprime el historial antiguo, no el contexto activo; los intercambios más recientes llevan la señal más relevante para las decisiones.", "Ajusta la agresividad por carga de trabajo contra un conjunto de evaluación; lo que es seguro para una charla es temerario para una tarea de auditoría." ], "faqs": [ { "q": "¿En qué se diferencia de la memoria a largo plazo?", "a": "La memoria a largo plazo persiste hechos fuera del prompt y los recupera bajo demanda; la compresión de contexto reduce el contexto activo que se envía en cada llamada. Son complementarias: la memoria decide qué traer de vuelta, la compresión decide con qué tan poca extensión se aloja en la ventana." }, { "q": "Resumir, podar o comprimir, ¿cuál uso?", "a": "Poda primero (gratis, sin pérdida cuando eliminas redundancia real), resume el historial antiguo cuando crece sin límite y añade compresión de prompts solo cuando aún necesitas más margen y puedes validar el coste de calidad. La mayoría de los sistemas combinan las tres." }, { "q": "¿Cómo sé si la compresión perjudica la calidad?", "a": "Ejecuta un conjunto de evaluación con compresión activada y desactivada y compara los resultados de tarea, no solo los recuentos de tokens. Vigila las respuestas erróneas con seguridad y las restricciones descartadas: esa es la firma de una compresión con pérdida que ha ido demasiado lejos." } ] }, "pt": { "name": "Compressão de contexto", "summary": "A compressão de contexto reduz os tokens enviados ao modelo em cada chamada preservando a informação de que ele realmente precisa para agir. Use-a em agentes de longa duração e conversas extensas para cortar custo e latência e permanecer dentro da janela de contexto. As três alavancas são resumir o histórico, podar contexto irrelevante e comprimir prompts. O risco central é a perda: descartar o único detalhe que importava. Meça a informação retida, não apenas os tokens economizados.", "problem": "Agentes de longa duração e conversas de múltiplos turnos acumulam contexto: cada resultado de ferramenta, mensagem anterior e documento recuperado é reenviado na chamada seguinte. A contagem de tokens cresce de forma quase linear com a interação, então o custo e a latência por chamada sobem, e por fim a janela transborda e o conteúdo mais antigo (às vezes o mais importante) é truncado em silêncio. As correções ingênuas —janelas maiores, truncamento mais agressivo— ou elevam o custo ou destroem a informação de que o modelo precisa para manter a coerência.", "context": "Aplica-se quando o contexto cresce sem limite em relação ao que cada passo precisa: assistentes conversacionais com históricos longos, agentes autônomos iterando sobre muitas chamadas de ferramentas, pipelines RAG que recuperam em excesso e jobs em lote em que o tamanho do prompt domina o custo. Encaixa-se quando grande parte do contexto acumulado é redundante ou obsoleto, quando você controla a montagem do prompt e quando pode tolerar algum erro de reconstrução. Encaixa-se mal quando cada token é essencial (tarefas jurídicas, de auditoria, de recuperação exata) ou quando as interações são curtas o bastante para a janela nunca ser pressionada.", "solution": [ "Trate o contexto ativo como um orçamento que você gerencia ativamente, e não como um registro somente de anexação. Existem três alavancas complementares. O resumo substitui um trecho do histórico por uma sinopse mais curta —normalmente um resumo contínuo dos turnos antigos, atualizado periodicamente, enquanto os turnos recentes permanecem literais. A poda remove o contexto irrelevante para o passo atual: deduplica, descarta saída de ferramenta obsoleta e seleciona apenas os trechos recuperados que ultrapassam um limiar de relevância. A compressão de prompts (por exemplo LLMLingua) usa um modelo menor para apagar ou reformular tokens de baixa informação antes de enviar o prompt, trocando um pequeno custo de exatidão por grandes reduções de tokens.\n\nCombine essas alavancas em um pipeline com limites explícitos: mantenha uma janela recente literal, um resumo contínuo do histórico antigo e um espaço de recuperação preenchido sob demanda. Proteja uma região 'fixada' para fatos que nunca devem ser comprimidos —identificadores, restrições, o objetivo atual. E, fundamentalmente, instrumente o resultado: rode um conjunto de avaliação comparando respostas com e sem compressão para ver quando a qualidade se degrada, e ajuste a agressividade por carga de trabalho em vez de globalmente. A compressão é um dial de qualidade versus custo, não um ganho gratuito." ], "components": [ "Resumidor contínuo", "Podador por relevância", "Compressor de prompts", "Região fixada", "Controlador do orçamento de contexto", "Avaliador de retenção" ], "benefits": [ "Enviar menos tokens reduz diretamente o custo de entrada em cada chamada, o que se acumula ao longo de loops de agente longos e tráfego de alto volume.", "Prompts menores significam menos a codificar e menor tempo até o primeiro token, melhorando a resposta em fluxos interativos e de agentes.", "Limitar o contexto ativo permite que conversas longas e agentes de muitos passos continuem sem transbordar a janela nem truncar em silêncio.", "Remover contexto redundante e obsoleto pode melhorar a qualidade ao reduzir a distração, ajudando o modelo a atender ao que importa agora." ], "risks": [ "Resumos e poda podem descartar o único detalhe que depois se mostra decisivo, produzindo respostas erradas com confiança.", "Resumos contínuos resumem resumos anteriores; pequenas omissões se acumulam ao longo de muitos ciclos até o fio desviar sem aviso.", "Rodar um resumidor ou compressor adiciona sua própria latência, custo e superfície de falha, que pode anular a economia em interações curtas.", "A expulsão agressiva pode remover em silêncio restrições ou instruções de que o modelo ainda depende, sem um sinal de erro evidente." ], "whenNot": [ "Quando cada token é essencial —jurídico, auditoria, conformidade ou extração precisa de dados— a compressão com perda é inaceitável.", "Se as conversas raramente pressionam a janela, a sobrecarga de compressão custa mais do que economiza e adiciona complexidade desnecessária.", "Sem um arcabouço de avaliação de retenção, não implante nada: você não consegue saber se a compressão está degradando as respostas em silêncio." ], "examples": [ "Um agente que itera sobre uma base de código grande mantém uma janela recente literal mais um resumo contínuo dos passos anteriores, fixando a especificação da tarefa e os caminhos de arquivo para não perder o objetivo.", "Um bot de suporte multissessão resume os turnos anteriores em um resumo de caso compacto, podando subproblemas resolvidos enquanto fixa as restrições da conta do cliente.", "Um pipeline de recuperação que traz muitos trechos aplica poda por relevância e compressão de prompts para enviar apenas as passagens de alto sinal, cortando tokens sem perder a resposta." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "Transcrições autônomas longas são compactadas preventivamente e os resultados de ferramentas truncados para permanecer dentro do orçamento de prompt.", "technology": "Compactação preventiva com margem de segurança, truncamento de resultados de ferramentas, hook de poda de contexto e verificação de estouro no meio do turno.", "load": "2.810 eventos de context-compiled em 2.776 turnos ao longo de 57 dias.", "results": "A compactação rodou em linha durante toda a janela, mantendo os turnos autônomos de vários passos dentro do orçamento (p95 87,6s por turno) sem que falhas por estouro de contexto aparecessem. Implantação local-first de operador único." }, "kpis": [ { "metric": "Tokens por chamada (entrada)", "note": "O principal motor do custo. Acompanhe a distribuição antes e depois da compressão; um resultado saudável é uma redução clara sem aumento de erros a jusante." }, { "metric": "Retenção de informação / qualidade da tarefa", "note": "Compare respostas com e sem compressão em um conjunto de avaliação. O bom é a qualidade se manter estável dentro da sua tolerância enquanto os tokens caem." }, { "metric": "Latência de ponta a ponta", "note": "Líquida da sobrecarga de compressão. O bom é menor latência total; observe que as chamadas do resumidor ou compressor não apaguem a economia." }, { "metric": "Taxa de transbordo / truncamento de contexto", "note": "Com que frequência as interações atingem o limite da janela. O bom é levar isso a zero sem recorrer a descartar conteúdo fixado." } ], "failureModes": [ "Um resumo omite uma restrição mencionada no início; muitos turnos depois o agente a viola porque esse fato simplesmente desapareceu do contexto.", "Resumir repetidamente amplifica erros de paráfrase e omissões até o resumo acumulado não refletir mais o que de fato aconteceu.", "Um orçamento mal configurado comprime identificadores ou instruções que deveriam estar protegidos, quebrando a corretude em silêncio.", "Um limiar de relevância agressivo filtra contexto que importava para um caso limite, então a qualidade parece boa nos testes mas falha em produção." ], "lessons": [ "A redução de tokens é trivial de maximizar e sem sentido por si só; a métrica real é se o modelo ainda responde corretamente.", "Proteja explicitamente identificadores, restrições e o objetivo atual para que nenhuma etapa de compressão possa expulsá-los.", "Comprima o histórico antigo, não o contexto ativo; as trocas mais recentes carregam o sinal mais relevante para as decisões.", "Ajuste a agressividade por carga de trabalho contra um conjunto de avaliação; o que é seguro para um bate-papo é imprudente para uma tarefa de auditoria." ], "faqs": [ { "q": "Como isso difere da memória de longo prazo?", "a": "A memória de longo prazo persiste fatos fora do prompt e os recupera sob demanda; a compressão de contexto encolhe o contexto ativo enviado em cada chamada. São complementares: a memória decide o que trazer de volta, a compressão decide com quão pouca extensão isso ocupa a janela." }, { "q": "Resumir, podar ou comprimir — qual usar?", "a": "Pode primeiro (gratuito, sem perda ao remover redundância real), resuma o histórico antigo quando ele cresce sem limite e adicione compressão de prompts apenas quando ainda precisar de mais folga e puder validar o custo de qualidade. A maioria dos sistemas combina as três." }, { "q": "Como sei se a compressão está prejudicando a qualidade?", "a": "Rode um conjunto de avaliação com compressão ligada e desligada e compare os resultados de tarefa, não apenas as contagens de tokens. Observe respostas erradas com confiança e restrições descartadas: essa é a assinatura de uma compressão com perda que foi longe demais." } ] } } }, { "slug": "evaluator-optimizer", "category": "reliability", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/evaluator-optimizer", "api": "https://santismm.com/api/patterns/evaluator-optimizer", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "LangGraph", "LLM-as-judge", "OpenAI Agents SDK", "Evaluation suites" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "reflection", "prompt-chaining", "orchestrator-workers" ], "locales": { "en": { "name": "Evaluator-Optimizer", "summary": "One LLM generates a response while a second LLM evaluates it against criteria and returns feedback; the generator revises and the loop repeats until the evaluation passes. It raises quality on tasks with clear evaluation criteria, at the cost of extra calls.", "problem": "A single-pass output may miss requirements, and there is no built-in mechanism to check and improve it before it is used.", "context": "Use evaluator-optimizer when you can articulate clear evaluation criteria and iterative refinement measurably improves the result — for example translation quality, code that must pass tests, or writing against a rubric.", "solution": [ "A generator produces a candidate; an evaluator (a separate LLM call or a deterministic check) scores it against explicit criteria and returns actionable feedback. The generator revises, and the cycle repeats until criteria are met or a budget is reached.", "Separating generation from evaluation mirrors how a human writer benefits from an editor: the critic catches issues the author misses, and explicit criteria keep the loop converging." ], "components": [ "Generator", "Evaluator (LLM judge or rule check)", "Explicit criteria", "Revision loop", "Stop condition / budget" ], "benefits": [ "Higher quality on tasks with clear criteria.", "Catches errors a single pass would ship.", "Feedback is explicit and actionable." ], "risks": [ "Extra calls add latency and cost.", "A weak evaluator gives misleading feedback.", "Loops can fail to converge without a budget." ], "whenNot": [ "When criteria cannot be clearly defined.", "When a single pass is already good enough.", "When latency or cost budgets are very tight." ], "examples": [ "Generating code, running tests, and revising until they pass.", "Drafting a translation and refining it against the source.", "Writing to a rubric with a critic enforcing each criterion." ], "kpis": [ { "metric": "Acceptance rate", "note": "Share of candidate outputs the evaluator accepts on first pass — too high means the bar is too low, too low means the generator or rubric is off." }, { "metric": "Iterations to accept", "note": "Average evaluate→revise loops before acceptance; rising counts flag a weak generator or vague criteria." }, { "metric": "Cost & latency per accepted output", "note": "Total tokens and wall-clock across all loop iterations, not just the final call — the loop multiplies both." }, { "metric": "Eval–human agreement", "note": "How often the evaluator's verdict matches a human reviewer on a sampled set; the loop is only as good as the evaluator." } ], "failureModes": [ "Reward hacking: the generator learns to satisfy the evaluator's wording rather than the real goal.", "Weak or miscalibrated evaluator: it accepts bad outputs or rejects good ones, so the loop adds cost without quality.", "Infinite or oscillating loops when no candidate ever clears the bar — without an iteration cap the cost is unbounded.", "Criteria drift: vague or shifting rubrics make acceptance non-deterministic and hard to audit." ], "lessons": [ "Cap iterations and define a fallback (return best-so-far, or escalate) so the loop always terminates.", "Make acceptance criteria explicit and stable; an evaluator is only as good as its rubric.", "Validate the evaluator against human judgement before trusting it as a gate.", "Use the loop only where quality justifies the multiplied cost — not for cheap, low-stakes outputs." ], "faqs": [ { "q": "How is this different from reflection?", "a": "Reflection has the same model self-critique. Evaluator-optimizer separates the roles: a distinct evaluator judges the generator, which often gives sharper, less biased feedback." }, { "q": "Can the evaluator be deterministic?", "a": "Yes. For code, a test runner is an ideal evaluator; for structured output, a schema check works. Use a model judge for nuanced criteria." }, { "q": "How many iterations?", "a": "Set a budget (e.g. 2–3) and stop when criteria pass. Unbounded loops waste cost and may not converge." } ] }, "es": { "name": "Evaluador-Optimizador (Evaluator-Optimizer)", "summary": "Un LLM genera una respuesta mientras un segundo LLM la evalúa contra criterios y devuelve feedback; el generador revisa y el bucle se repite hasta que la evaluación pasa. Eleva la calidad en tareas con criterios de evaluación claros, a costa de llamadas extra.", "problem": "Una salida de una sola pasada puede incumplir requisitos, y no hay un mecanismo incorporado para comprobarla y mejorarla antes de usarla.", "context": "Usa evaluador-optimizador cuando puedas articular criterios de evaluación claros y el refinamiento iterativo mejore el resultado de forma medible —por ejemplo calidad de traducción, código que debe pasar tests, o escritura contra una rúbrica.", "solution": [ "Un generador produce un candidato; un evaluador (otra llamada al LLM o una comprobación determinista) lo puntúa contra criterios explícitos y devuelve feedback accionable. El generador revisa y el ciclo se repite hasta cumplir los criterios o alcanzar un presupuesto.", "Separar generación de evaluación imita cómo un escritor humano se beneficia de un editor: el crítico atrapa problemas que el autor pasa por alto, y los criterios explícitos mantienen el bucle convergiendo." ], "components": [ "Generador", "Evaluador (juez LLM o comprobación de reglas)", "Criterios explícitos", "Bucle de revisión", "Condición de parada / presupuesto" ], "benefits": [ "Mayor calidad en tareas con criterios claros.", "Atrapa errores que una sola pasada publicaría.", "El feedback es explícito y accionable." ], "risks": [ "Las llamadas extra añaden latencia y coste.", "Un evaluador débil da feedback engañoso.", "Los bucles pueden no converger sin un presupuesto." ], "whenNot": [ "Cuando los criterios no se pueden definir con claridad.", "Cuando una sola pasada ya es suficientemente buena.", "Cuando los presupuestos de latencia o coste son muy ajustados." ], "examples": [ "Generar código, ejecutar tests y revisar hasta que pasen.", "Redactar una traducción y refinarla contra el original.", "Escribir contra una rúbrica con un crítico que exige cada criterio." ], "kpis": [ { "metric": "Tasa de aceptación", "note": "Proporción de salidas que el evaluador acepta a la primera; demasiado alta indica un listón bajo, demasiado baja, un generador o rúbrica deficientes." }, { "metric": "Iteraciones hasta aceptar", "note": "Bucles evaluar→revisar promedio antes de aceptar; si suben, el generador es débil o los criterios, vagos." }, { "metric": "Coste y latencia por salida aceptada", "note": "Tokens y tiempo total de todas las iteraciones, no solo la llamada final: el bucle multiplica ambos." }, { "metric": "Concordancia evaluador–humano", "note": "Con qué frecuencia el veredicto del evaluador coincide con un revisor humano en una muestra; el bucle vale lo que su evaluador." } ], "failureModes": [ "Reward hacking: el generador aprende a satisfacer la redacción del evaluador en vez del objetivo real.", "Evaluador débil o mal calibrado: acepta salidas malas o rechaza buenas, sumando coste sin calidad.", "Bucles infinitos u oscilantes cuando ningún candidato supera el listón; sin un tope de iteraciones el coste es ilimitado.", "Deriva de criterios: rúbricas vagas o cambiantes hacen la aceptación no determinista y difícil de auditar." ], "lessons": [ "Limita las iteraciones y define un respaldo (devolver el mejor hasta ahora o escalar) para que el bucle siempre termine.", "Haz los criterios de aceptación explícitos y estables; un evaluador vale lo que su rúbrica.", "Valida el evaluador frente al juicio humano antes de confiar en él como puerta.", "Usa el bucle solo donde la calidad justifique el coste multiplicado, no para salidas baratas y de bajo riesgo." ], "faqs": [ { "q": "¿En qué se diferencia de la reflexión?", "a": "La reflexión hace que el mismo modelo se autocritique. El evaluador-optimizador separa los roles: un evaluador distinto juzga al generador, lo que suele dar feedback más afilado y menos sesgado." }, { "q": "¿El evaluador puede ser determinista?", "a": "Sí. Para código, un runner de tests es un evaluador ideal; para salida estructurada, sirve una comprobación de esquema. Usa un juez modelo para criterios con matices." }, { "q": "¿Cuántas iteraciones?", "a": "Fija un presupuesto (p. ej. 2-3) y para cuando se cumplan los criterios. Los bucles sin límite malgastan coste y pueden no converger." } ] }, "pt": { "name": "Avaliador-Otimizador (Evaluator-Optimizer)", "summary": "Um LLM gera uma resposta enquanto um segundo LLM a avalia contra critérios e devolve feedback; o gerador revisa e o laço se repete até a avaliação passar. Eleva a qualidade em tarefas com critérios de avaliação claros, ao custo de chamadas extras.", "problem": "Uma saída de uma única passagem pode descumprir requisitos, e não há um mecanismo embutido para verificá-la e melhorá-la antes de usá-la.", "context": "Use avaliador-otimizador quando puder articular critérios de avaliação claros e o refinamento iterativo melhorar o resultado de forma mensurável — por exemplo qualidade de tradução, código que deve passar em testes, ou escrita contra uma rubrica.", "solution": [ "Um gerador produz um candidato; um avaliador (outra chamada ao LLM ou uma verificação determinística) o pontua contra critérios explícitos e devolve feedback acionável. O gerador revisa e o ciclo se repete até cumprir os critérios ou alcançar um orçamento.", "Separar geração de avaliação imita como um escritor humano se beneficia de um editor: o crítico captura problemas que o autor deixa passar, e os critérios explícitos mantêm o laço convergindo." ], "components": [ "Gerador", "Avaliador (juiz LLM ou verificação de regras)", "Critérios explícitos", "Laço de revisão", "Condição de parada / orçamento" ], "benefits": [ "Maior qualidade em tarefas com critérios claros.", "Captura erros que uma única passagem publicaria.", "O feedback é explícito e acionável." ], "risks": [ "As chamadas extras adicionam latência e custo.", "Um avaliador fraco dá feedback enganoso.", "Os laços podem não convergir sem um orçamento." ], "whenNot": [ "Quando os critérios não podem ser definidos com clareza.", "Quando uma única passagem já é boa o bastante.", "Quando os orçamentos de latência ou custo são muito apertados." ], "examples": [ "Gerar código, executar testes e revisar até passarem.", "Redigir uma tradução e refiná-la contra o original.", "Escrever contra uma rubrica com um crítico que exige cada critério." ], "kpis": [ { "metric": "Taxa de aceitação", "note": "Proporção de saídas que o avaliador aceita de primeira; alta demais indica régua baixa, baixa demais, gerador ou rubrica ruins." }, { "metric": "Iterações até aceitar", "note": "Loops avaliar→revisar médios antes de aceitar; se sobem, o gerador é fraco ou os critérios, vagos." }, { "metric": "Custo e latência por saída aceita", "note": "Tokens e tempo total de todas as iterações, não só a chamada final: o loop multiplica ambos." }, { "metric": "Concordância avaliador–humano", "note": "Com que frequência o veredito do avaliador coincide com um revisor humano numa amostra; o loop vale o que seu avaliador." } ], "failureModes": [ "Reward hacking: o gerador aprende a satisfazer a redação do avaliador em vez do objetivo real.", "Avaliador fraco ou mal calibrado: aceita saídas ruins ou rejeita boas, somando custo sem qualidade.", "Loops infinitos ou oscilantes quando nenhum candidato supera a régua; sem um teto de iterações o custo é ilimitado.", "Deriva de critérios: rubricas vagas ou mutáveis tornam a aceitação não determinística e difícil de auditar." ], "lessons": [ "Limite as iterações e defina um fallback (devolver o melhor até agora ou escalar) para o loop sempre terminar.", "Torne os critérios de aceitação explícitos e estáveis; um avaliador vale o que sua rubrica.", "Valide o avaliador contra o julgamento humano antes de confiar nele como portão.", "Use o loop só onde a qualidade justifique o custo multiplicado, não para saídas baratas e de baixo risco." ], "faqs": [ { "q": "Como difere da reflexão?", "a": "A reflexão faz o mesmo modelo se autocriticar. O avaliador-otimizador separa os papéis: um avaliador distinto julga o gerador, o que costuma dar feedback mais afiado e menos enviesado." }, { "q": "O avaliador pode ser determinístico?", "a": "Sim. Para código, um runner de testes é um avaliador ideal; para saída estruturada, serve uma verificação de esquema. Use um juiz modelo para critérios com nuances." }, { "q": "Quantas iterações?", "a": "Defina um orçamento (ex.: 2-3) e pare quando os critérios passarem. Laços sem limite desperdiçam custo e podem não convergir." } ] } } }, { "slug": "goal-decomposition", "category": "orchestration", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/goal-decomposition", "api": "https://santismm.com/api/patterns/goal-decomposition", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "Planner/executor frameworks", "LangGraph", "ReAct / Plan-and-Solve", "Task graphs" ], "references": [ { "title": "Yao et al. — ReAct (2022)", "url": "https://arxiv.org/abs/2210.03629" }, { "title": "Wang et al. — Plan-and-Solve Prompting (2023)", "url": "https://arxiv.org/abs/2305.04091" } ], "related": [ "supervisor-agent", "orchestrator-workers", "task-prioritization" ], "locales": { "en": { "name": "Goal Decomposition", "summary": "Goal decomposition has an agent break a high-level goal into an ordered set of smaller, tractable sub-tasks — a plan — before acting, then execute and monitor that plan, re-planning when steps fail. The explicit plan becomes an inspectable artifact you can review, gate, and debug. Use it when a goal needs several dependent steps and reactive, step-at-a-time agents drift or stall; skip it for simple, single-shot tasks.", "problem": "A single LLM call handed a broad, multi-step goal tends to improvise. Reactive agents that choose one action at a time can lose the thread on long horizons: they repeat work, skip prerequisites, or chase a dead end without realizing the overall objective is now unreachable. Because no plan exists as an artifact, you cannot review intended steps before they run, cannot tell whether a failure came from a bad strategy or a bad execution, and cannot easily resume after an interruption. The agent's reasoning is implicit, transient, and hard to audit.", "context": "This pattern fits goals that decompose into multiple interdependent steps with a meaningful ordering — research-then-synthesize, migrate-then-verify, gather-then-reconcile-then-report. It assumes the model can produce a reasonable plan from the goal and available tools, and that steps are observable enough to detect failure. It is most valuable where steps are costly, side-effecting, or hard to undo, so reviewing the plan before execution pays off. It is a poor fit when the next action is obvious from the current state, or when the environment changes so fast that any upfront plan is stale before the second step.", "solution": [ "Split the agent into a planning phase and an execution phase. The planner reads the goal, the available tools, and the current state, and emits an explicit, ordered plan: a list (or graph) of sub-tasks with their dependencies and expected outputs. Treating the plan as a first-class artifact is the core idea — it can be logged, shown to a human for approval, scored against policy, and diffed across runs. Encode dependencies explicitly so independent sub-tasks can run in parallel and dependent ones wait for their inputs, rather than forcing a brittle linear sequence the model invented.", "An executor then runs the plan step by step, feeding each step's result forward and checking it against the step's expected output. When a step fails, returns something unusable, or invalidates a downstream assumption, hand control back to the planner to re-plan from the current state instead of blindly continuing — this closed loop is what separates robust decomposition from one-shot planning. Keep plans as shallow as the goal allows: prefer a few well-chosen steps over a deep tree, gate re-planning with a budget so the agent cannot loop forever, and let trivial goals bypass planning entirely." ], "components": [ "Planner that emits an ordered, dependency-aware plan", "Plan representation (task list or task graph) as an inspectable artifact", "Executor that runs steps and forwards results", "Per-step verification against expected outputs", "Re-planning trigger and loop with a step/iteration budget", "Optional human approval gate before execution" ], "benefits": [ "Long-horizon goals stay coherent because intended steps are decided up front, not improvised one at a time.", "The explicit plan is inspectable: it can be reviewed, approved, audited, and diffed before any side effect runs.", "Failures are easier to localize — a bad plan is distinguishable from a bad step execution.", "Independent sub-tasks expose parallelism and let work resume from the last completed step after an interruption." ], "risks": [ "A flawed initial decomposition propagates: every downstream step inherits a wrong assumption or missing prerequisite.", "Over-planning adds latency and cost on simple goals that a reactive agent would finish in one step.", "Plans go stale in fast-changing environments, so executing a step still based on an outdated world state.", "Unbounded re-planning loops where the agent repeatedly rewrites the plan without making real progress." ], "whenNot": [ "The next action is obvious from the current state and a single reactive step solves the goal.", "The environment changes faster than a plan stays valid, making any upfront sequence stale.", "Steps are cheap, reversible, and independent, so the overhead of planning outweighs its benefit." ], "examples": [ "A research assistant plans gather-sources, extract-claims, cross-check, then synthesize, running the source gathering in parallel before the dependent synthesis step.", "A code-migration agent plans inventory-usages, transform-files, run-tests, then re-plans the transform step when the test step surfaces a missed edge case.", "A data-reconciliation agent decomposes a 'close the books' goal into pull-ledgers, normalize, match-entries, and flag-exceptions, with matching gated behind successful normalization." ], "kpis": [ { "metric": "Goal completion rate", "note": "Share of goals fully achieved end-to-end; good looks like decomposition beating a reactive baseline on the same multi-step tasks." }, { "metric": "Re-plan frequency", "note": "How often a run triggers re-planning; a healthy band means the loop catches real failures without thrashing on every step." }, { "metric": "Steps per goal vs. minimum", "note": "Plan length relative to a sensible minimum; watch for over-planning that inflates steps on simple goals." }, { "metric": "Plan-approval pass rate", "note": "Fraction of plans accepted by reviewers or policy checks before execution; low rates signal systematically weak decomposition." } ], "failureModes": [ "Bad decomposition propagates: a wrong early assumption corrupts every dependent step downstream.", "Re-planning loop: the agent rewrites the plan repeatedly without converging or making progress.", "Stale plan execution: a step runs against a world state that changed since the plan was made.", "Over-decomposition: a trivial goal is split into needless steps, adding latency, cost, and failure surface." ], "lessons": [ "Make the plan a real artifact — log it, show it, diff it — so failures are debuggable rather than mysterious.", "Always close the loop: detect step failure and re-plan from current state instead of continuing blindly.", "Bound both plan depth and re-planning with explicit budgets to prevent shallow goals from spiraling.", "Let trivial goals skip the planner; reserve decomposition for genuinely multi-step, dependent work." ], "faqs": [ { "q": "How is this different from a reactive ReAct-style agent?", "a": "A reactive agent decides one action at a time from the current state, with no plan as an artifact. Goal decomposition commits to an ordered plan up front, making intended steps inspectable and dependency ordering explicit. In practice the two are often combined: plan first, then execute reactively within each step and re-plan when a step fails." }, { "q": "What happens when a step fails mid-plan?", "a": "Hand control back to the planner to re-plan from the current state rather than continuing blindly. The closed re-planning loop is what makes decomposition robust. Bound it with a budget so a persistently failing step cannot trigger endless rewrites without progress." }, { "q": "When does planning hurt more than it helps?", "a": "On simple, single-step goals where the next action is obvious, or in environments that change faster than a plan stays valid. There, upfront planning adds latency and a stale-plan risk. Detect trivial goals and let them bypass the planner, reserving decomposition for genuinely multi-step, dependent work." } ] }, "es": { "name": "Descomposición de objetivos", "summary": "La descomposición de objetivos hace que un agente divida una meta de alto nivel en un conjunto ordenado de subtareas más pequeñas y abordables — un plan — antes de actuar, para luego ejecutar y supervisar ese plan, replanificando cuando algún paso falla. El plan explícito se vuelve un artefacto inspeccionable que puedes revisar, controlar y depurar. Úsalo cuando una meta requiera varios pasos dependientes y los agentes reactivos paso a paso se desvían o se estancan; omítelo en tareas simples de un solo paso.", "problem": "Una sola llamada a un LLM con una meta amplia y de múltiples pasos tiende a improvisar. Los agentes reactivos que eligen una acción a la vez pueden perder el hilo en horizontes largos: repiten trabajo, omiten prerrequisitos o persiguen un callejón sin salida sin advertir que el objetivo general ya es inalcanzable. Como no existe un plan como artefacto, no puedes revisar los pasos previstos antes de ejecutarlos, no distingues si un fallo vino de una mala estrategia o de una mala ejecución, y no puedes reanudar fácilmente tras una interrupción. El razonamiento del agente es implícito, transitorio y difícil de auditar.", "context": "Este patrón encaja con metas que se descomponen en múltiples pasos interdependientes con un orden significativo — investigar-luego-sintetizar, migrar-luego-verificar, recopilar-conciliar-luego-reportar. Supone que el modelo puede producir un plan razonable a partir de la meta y las herramientas disponibles, y que los pasos son lo bastante observables para detectar fallos. Es más valioso cuando los pasos son costosos, con efectos secundarios o difíciles de deshacer, de modo que revisar el plan antes de ejecutarlo compensa. Encaja mal cuando la siguiente acción es obvia desde el estado actual, o cuando el entorno cambia tan rápido que cualquier plan inicial queda obsoleto antes del segundo paso.", "solution": [ "Divide el agente en una fase de planificación y una de ejecución. El planificador lee la meta, las herramientas disponibles y el estado actual, y emite un plan explícito y ordenado: una lista (o grafo) de subtareas con sus dependencias y salidas esperadas. Tratar el plan como un artefacto de primera clase es la idea central — puede registrarse, mostrarse a una persona para su aprobación, evaluarse frente a una política y compararse entre ejecuciones. Codifica las dependencias de forma explícita para que las subtareas independientes corran en paralelo y las dependientes esperen sus entradas, en lugar de forzar una secuencia lineal frágil inventada por el modelo.", "Un ejecutor recorre el plan paso a paso, propagando el resultado de cada paso y contrastándolo con su salida esperada. Cuando un paso falla, devuelve algo inutilizable o invalida una suposición posterior, devuelve el control al planificador para replanificar desde el estado actual en lugar de continuar a ciegas — este bucle cerrado es lo que separa la descomposición robusta de la planificación de un solo intento. Mantén los planes tan superficiales como la meta lo permita: prefiere unos pocos pasos bien elegidos antes que un árbol profundo, limita la replanificación con un presupuesto para que el agente no entre en bucle infinito, y deja que las metas triviales eviten por completo la planificación." ], "components": [ "Planificador que emite un plan ordenado y consciente de dependencias", "Representación del plan (lista o grafo de tareas) como artefacto inspeccionable", "Ejecutor que corre los pasos y propaga resultados", "Verificación por paso frente a las salidas esperadas", "Disparador y bucle de replanificación con presupuesto de pasos/iteraciones", "Compuerta opcional de aprobación humana antes de ejecutar" ], "benefits": [ "Las metas de horizonte largo se mantienen coherentes porque los pasos previstos se deciden por adelantado, no se improvisan uno a uno.", "El plan explícito es inspeccionable: puede revisarse, aprobarse, auditarse y compararse antes de cualquier efecto secundario.", "Los fallos son más fáciles de localizar — un mal plan se distingue de una mala ejecución de un paso.", "Las subtareas independientes exponen paralelismo y permiten reanudar el trabajo desde el último paso completado tras una interrupción." ], "risks": [ "Una descomposición inicial defectuosa se propaga: cada paso posterior hereda una suposición errónea o un prerrequisito ausente.", "Planificar de más añade latencia y coste en metas simples que un agente reactivo terminaría en un solo paso.", "Los planes quedan obsoletos en entornos cambiantes, ejecutando un paso aún basado en un estado del mundo desactualizado.", "Bucles de replanificación sin límite en los que el agente reescribe el plan una y otra vez sin avanzar de verdad." ], "whenNot": [ "La siguiente acción es obvia desde el estado actual y un solo paso reactivo resuelve la meta.", "El entorno cambia más rápido de lo que un plan se mantiene válido, dejando obsoleta cualquier secuencia inicial.", "Los pasos son baratos, reversibles e independientes, de modo que la sobrecarga de planificar supera su beneficio." ], "examples": [ "Un asistente de investigación planifica recopilar-fuentes, extraer-afirmaciones, contrastar y luego sintetizar, corriendo la recopilación de fuentes en paralelo antes del paso dependiente de síntesis.", "Un agente de migración de código planifica inventariar-usos, transformar-archivos, ejecutar-pruebas, y luego replanifica el paso de transformación cuando las pruebas revelan un caso límite omitido.", "Un agente de conciliación de datos descompone la meta de 'cerrar los libros' en extraer-libros-mayores, normalizar, emparejar-asientos y marcar-excepciones, con el emparejamiento condicionado a una normalización exitosa." ], "kpis": [ { "metric": "Tasa de cumplimiento de objetivos", "note": "Proporción de metas logradas de extremo a extremo; lo bueno se ve como una descomposición que supera a una línea base reactiva en las mismas tareas de múltiples pasos." }, { "metric": "Frecuencia de replanificación", "note": "Con qué frecuencia una ejecución dispara replanificación; una banda sana significa que el bucle captura fallos reales sin oscilar en cada paso." }, { "metric": "Pasos por meta frente al mínimo", "note": "Longitud del plan respecto a un mínimo sensato; vigila la planificación excesiva que infla los pasos en metas simples." }, { "metric": "Tasa de aprobación de planes", "note": "Fracción de planes aceptados por revisores o controles de política antes de ejecutar; tasas bajas indican una descomposición sistemáticamente débil." } ], "failureModes": [ "La mala descomposición se propaga: una suposición temprana errónea corrompe cada paso dependiente posterior.", "Bucle de replanificación: el agente reescribe el plan repetidamente sin converger ni avanzar.", "Ejecución de plan obsoleto: un paso corre contra un estado del mundo que cambió desde que se hizo el plan.", "Sobredescomposición: una meta trivial se divide en pasos innecesarios, añadiendo latencia, coste y superficie de fallo." ], "lessons": [ "Haz del plan un artefacto real — regístralo, muéstralo, compáralo — para que los fallos sean depurables y no misteriosos.", "Cierra siempre el bucle: detecta el fallo de un paso y replanifica desde el estado actual en vez de continuar a ciegas.", "Limita tanto la profundidad del plan como la replanificación con presupuestos explícitos para evitar que las metas superficiales se descontrolen.", "Deja que las metas triviales salten el planificador; reserva la descomposición para trabajo realmente de múltiples pasos y dependiente." ], "faqs": [ { "q": "¿En qué se diferencia esto de un agente reactivo estilo ReAct?", "a": "Un agente reactivo decide una acción a la vez desde el estado actual, sin un plan como artefacto. La descomposición de objetivos se compromete con un plan ordenado por adelantado, haciendo inspeccionables los pasos previstos y explícito el orden de dependencias. En la práctica suelen combinarse: planificar primero, luego ejecutar de forma reactiva dentro de cada paso y replanificar cuando un paso falla." }, { "q": "¿Qué ocurre cuando un paso falla a mitad del plan?", "a": "Devuelve el control al planificador para replanificar desde el estado actual en lugar de continuar a ciegas. El bucle cerrado de replanificación es lo que hace robusta a la descomposición. Limítalo con un presupuesto para que un paso que falla de forma persistente no dispare reescrituras interminables sin avanzar." }, { "q": "¿Cuándo planificar perjudica más de lo que ayuda?", "a": "En metas simples de un solo paso donde la siguiente acción es obvia, o en entornos que cambian más rápido de lo que un plan se mantiene válido. Ahí, planificar por adelantado añade latencia y riesgo de plan obsoleto. Detecta las metas triviales y deja que eviten el planificador, reservando la descomposición para trabajo realmente de múltiples pasos y dependiente." } ] }, "pt": { "name": "Decomposição de objetivos", "summary": "A decomposição de objetivos faz um agente dividir uma meta de alto nível em um conjunto ordenado de subtarefas menores e tratáveis — um plano — antes de agir, e então executar e monitorar esse plano, replanejando quando passos falham. O plano explícito vira um artefato inspecionável que você pode revisar, controlar e depurar. Use quando uma meta exigir vários passos dependentes e agentes reativos passo a passo se desviarem ou travarem; dispense em tarefas simples de um único passo.", "problem": "Uma única chamada a um LLM com uma meta ampla e de múltiplos passos tende a improvisar. Agentes reativos que escolhem uma ação por vez podem perder o fio em horizontes longos: repetem trabalho, pulam pré-requisitos ou perseguem um beco sem saída sem perceber que o objetivo geral já é inalcançável. Como não existe um plano como artefato, você não consegue revisar os passos pretendidos antes de executá-los, não distingue se uma falha veio de uma estratégia ruim ou de uma execução ruim, e não consegue retomar facilmente após uma interrupção. O raciocínio do agente é implícito, transitório e difícil de auditar.", "context": "Este padrão encaixa em metas que se decompõem em múltiplos passos interdependentes com uma ordenação significativa — pesquisar-depois-sintetizar, migrar-depois-verificar, coletar-conciliar-depois-reportar. Pressupõe que o modelo consegue produzir um plano razoável a partir da meta e das ferramentas disponíveis, e que os passos são observáveis o suficiente para detectar falhas. É mais valioso quando os passos são caros, com efeitos colaterais ou difíceis de desfazer, de modo que revisar o plano antes de executar compensa. Encaixa mal quando a próxima ação é óbvia a partir do estado atual, ou quando o ambiente muda tão rápido que qualquer plano inicial fica desatualizado antes do segundo passo.", "solution": [ "Divida o agente em uma fase de planejamento e uma de execução. O planejador lê a meta, as ferramentas disponíveis e o estado atual, e emite um plano explícito e ordenado: uma lista (ou grafo) de subtarefas com suas dependências e saídas esperadas. Tratar o plano como um artefato de primeira classe é a ideia central — ele pode ser registrado, mostrado a uma pessoa para aprovação, avaliado contra uma política e comparado entre execuções. Codifique as dependências de forma explícita para que subtarefas independentes rodem em paralelo e as dependentes aguardem suas entradas, em vez de forçar uma sequência linear frágil inventada pelo modelo.", "Um executor então percorre o plano passo a passo, propagando o resultado de cada passo e conferindo-o contra a saída esperada. Quando um passo falha, retorna algo inutilizável ou invalida uma suposição posterior, devolva o controle ao planejador para replanejar a partir do estado atual em vez de continuar às cegas — esse laço fechado é o que separa a decomposição robusta do planejamento de tentativa única. Mantenha os planos tão rasos quanto a meta permitir: prefira poucos passos bem escolhidos a uma árvore profunda, limite o replanejamento com um orçamento para que o agente não entre em laço infinito, e deixe que metas triviais ignorem completamente o planejamento." ], "components": [ "Planejador que emite um plano ordenado e ciente de dependências", "Representação do plano (lista ou grafo de tarefas) como artefato inspecionável", "Executor que roda os passos e propaga resultados", "Verificação por passo contra as saídas esperadas", "Gatilho e laço de replanejamento com orçamento de passos/iterações", "Portão opcional de aprovação humana antes da execução" ], "benefits": [ "Metas de horizonte longo permanecem coerentes porque os passos pretendidos são decididos com antecedência, não improvisados um a um.", "O plano explícito é inspecionável: pode ser revisado, aprovado, auditado e comparado antes de qualquer efeito colateral.", "Falhas são mais fáceis de localizar — um plano ruim se distingue de uma execução de passo ruim.", "Subtarefas independentes expõem paralelismo e permitem retomar o trabalho a partir do último passo concluído após uma interrupção." ], "risks": [ "Uma decomposição inicial falha se propaga: cada passo posterior herda uma suposição errada ou um pré-requisito ausente.", "Planejar demais adiciona latência e custo em metas simples que um agente reativo terminaria em um único passo.", "Os planos ficam desatualizados em ambientes que mudam rápido, executando um passo ainda baseado em um estado de mundo defasado.", "Laços de replanejamento sem limite em que o agente reescreve o plano repetidamente sem progredir de fato." ], "whenNot": [ "A próxima ação é óbvia a partir do estado atual e um único passo reativo resolve a meta.", "O ambiente muda mais rápido do que um plano se mantém válido, deixando qualquer sequência inicial desatualizada.", "Os passos são baratos, reversíveis e independentes, de modo que o custo de planejar supera seu benefício." ], "examples": [ "Um assistente de pesquisa planeja coletar-fontes, extrair-afirmações, conferir e então sintetizar, rodando a coleta de fontes em paralelo antes do passo dependente de síntese.", "Um agente de migração de código planeja inventariar-usos, transformar-arquivos, rodar-testes, e então replaneja o passo de transformação quando os testes revelam um caso de borda omitido.", "Um agente de conciliação de dados decompõe a meta de 'fechar os livros' em puxar-razões, normalizar, casar-lançamentos e sinalizar-exceções, com o casamento condicionado a uma normalização bem-sucedida." ], "kpis": [ { "metric": "Taxa de conclusão de objetivos", "note": "Parcela de metas alcançadas de ponta a ponta; o bom se parece com uma decomposição superando uma linha de base reativa nas mesmas tarefas de múltiplos passos." }, { "metric": "Frequência de replanejamento", "note": "Com que frequência uma execução dispara replanejamento; uma faixa saudável significa que o laço captura falhas reais sem oscilar a cada passo." }, { "metric": "Passos por meta frente ao mínimo", "note": "Comprimento do plano em relação a um mínimo sensato; observe o planejamento excessivo que infla os passos em metas simples." }, { "metric": "Taxa de aprovação de planos", "note": "Fração de planos aceitos por revisores ou verificações de política antes da execução; taxas baixas sinalizam decomposição sistematicamente fraca." } ], "failureModes": [ "Decomposição ruim se propaga: uma suposição inicial errada corrompe cada passo dependente posterior.", "Laço de replanejamento: o agente reescreve o plano repetidamente sem convergir nem progredir.", "Execução de plano desatualizado: um passo roda contra um estado de mundo que mudou desde que o plano foi feito.", "Sobredecomposição: uma meta trivial é dividida em passos desnecessários, adicionando latência, custo e superfície de falha." ], "lessons": [ "Faça do plano um artefato real — registre, mostre, compare — para que falhas sejam depuráveis e não misteriosas.", "Feche sempre o laço: detecte a falha de um passo e replaneje a partir do estado atual em vez de continuar às cegas.", "Limite tanto a profundidade do plano quanto o replanejamento com orçamentos explícitos para evitar que metas rasas saiam de controle.", "Deixe metas triviais pularem o planejador; reserve a decomposição para trabalho realmente de múltiplos passos e dependente." ], "faqs": [ { "q": "Como isso difere de um agente reativo no estilo ReAct?", "a": "Um agente reativo decide uma ação por vez a partir do estado atual, sem um plano como artefato. A decomposição de objetivos se compromete com um plano ordenado de antemão, tornando os passos pretendidos inspecionáveis e explícita a ordenação de dependências. Na prática os dois costumam ser combinados: planejar primeiro, depois executar de forma reativa dentro de cada passo e replanejar quando um passo falha." }, { "q": "O que acontece quando um passo falha no meio do plano?", "a": "Devolva o controle ao planejador para replanejar a partir do estado atual em vez de continuar às cegas. O laço fechado de replanejamento é o que torna a decomposição robusta. Limite-o com um orçamento para que um passo que falha persistentemente não dispare reescritas intermináveis sem progresso." }, { "q": "Quando planejar atrapalha mais do que ajuda?", "a": "Em metas simples de um único passo onde a próxima ação é óbvia, ou em ambientes que mudam mais rápido do que um plano se mantém válido. Ali, planejar com antecedência adiciona latência e risco de plano desatualizado. Detecte as metas triviais e deixe que pulem o planejador, reservando a decomposição para trabalho realmente de múltiplos passos e dependente." } ] } } }, { "slug": "human-approval-gate", "category": "safety", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/human-approval-gate", "api": "https://santismm.com/api/patterns/human-approval-gate", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "LangGraph (interrupts)", "Workflow / approval systems", "Audit logging" ], "references": [ { "title": "European Union — AI Act, Article 14 (Human oversight)", "url": "https://artificialintelligenceact.eu/article/14/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "reflection", "evaluator-optimizer", "prompt-chaining" ], "locales": { "en": { "name": "Human Approval Gate", "summary": "A human approval gate pauses an automated workflow at a defined checkpoint so a person can review, edit or reject a proposed action before it executes — especially for high-impact, irreversible or regulated operations. It is the operational form of human-in-the-loop oversight.", "definition": "A human approval gate is a control checkpoint inserted before a high-impact automated action, where a person reviews and approves, edits or rejects the proposed action before it executes.", "problem": "Letting an AI system execute high-impact actions autonomously risks costly, irreversible or non-compliant mistakes with no chance for human judgment.", "context": "Use an approval gate for actions whose cost of error outweighs the latency of review: payments, deletions, external communications, production changes, or anything regulated.", "solution": [ "Insert a checkpoint before the sensitive action: the system prepares the proposed action with enough context, then suspends and routes it to a human who approves, edits or rejects. On approval it proceeds; on timeout it falls back safely. Every decision is logged for audit.", "Gate only the high-impact steps, not everything — over-gating destroys the value of automation and causes approval fatigue. Choose checkpoints by risk." ], "components": [ "Risk-based checkpoint", "Proposed-action preview", "Approve / edit / reject", "Timeout & safe fallback", "Audit log" ], "benefits": [ "Prevents costly or irreversible mistakes.", "Keeps accountability with a human.", "Satisfies compliance and oversight requirements.", "Builds trust, enabling gradual autonomy." ], "risks": [ "Adds latency and limits throughput.", "Rubber-stamping if reviewers lack context or time.", "Approval fatigue from too many gates.", "Bottlenecks if reviewers are unavailable." ], "whenNot": [ "For low-impact, easily reversible actions.", "When throughput must be high and risk is low.", "When a deterministic guardrail can safely auto-approve." ], "examples": [ "An agent drafting a refund a human approves before it is issued.", "A production change that pauses for sign-off before deploying.", "An outbound email queued for review before sending." ], "productionEvidence": { "context": "Enterprise workflows where an agent can trigger irreversible or regulated actions — refunds, account changes, outbound communications, production deployments.", "scenario": "The agent prepares the action with full context and pauses; a reviewer approves, edits or rejects it; on approval it executes, on timeout it falls back safely. Every decision is logged.", "technology": "A workflow engine with interrupts (e.g. LangGraph), an approval queue/UI, and an audit log.", "load": "Only a minority of high-impact steps are gated; the bulk of low-impact steps run automatically, so reviewer volume stays bounded.", "results": "Observed pattern: irreversible errors are caught before execution and accountability stays with a human, at the cost of added latency on gated steps. Gate by risk and measure approval latency and rubber-stamp rate on your own workflow — these are reference observations, not guaranteed numbers." }, "kpis": [ { "metric": "Approval latency", "note": "Time an action waits at the gate; the core cost of the pattern and the first thing to watch for bottlenecks." }, { "metric": "Rejection / edit rate", "note": "Share of proposals a human rejects or edits — near-zero often means rubber-stamping, very high means the agent isn't trusted yet." }, { "metric": "Throughput vs. gated steps", "note": "Tasks completed per hour against how many steps are gated; over-gating collapses throughput." }, { "metric": "Timeout / fallback rate", "note": "How often actions hit the timeout and take the safe fallback; a rising rate signals reviewer overload." } ], "failureModes": [ "Rubber-stamping: reviewers approve without real scrutiny when they lack context or time, defeating the gate.", "Approval fatigue and bottlenecks from over-gating low-impact steps.", "Silent auto-execution on timeout when no safe fallback is defined.", "Insufficient context in the proposal, so the human can't make an informed decision." ], "lessons": [ "Gate by risk, not by default — automate low-impact steps and reserve gates for irreversible or regulated actions.", "Give reviewers enough context and a clear approve/edit/reject choice to prevent rubber-stamping.", "Always define a safe fallback on timeout; never silently execute a gated action.", "Log every decision for audit — the gate is also your compliance evidence." ], "faqs": [ { "q": "How is this different from human-in-the-loop?", "a": "It is the concrete implementation of the human-in-the-loop principle: a specific approval checkpoint in a workflow before a sensitive action." }, { "q": "Won't approvals slow everything down?", "a": "Only if you over-gate. Apply gates by risk — automate low-impact steps and reserve approval for high-impact, irreversible or regulated actions." }, { "q": "What happens on timeout?", "a": "Define a safe fallback: hold the action, escalate, or cancel. Never silently auto-execute a gated action just because no one responded." } ] }, "es": { "name": "Puerta de Aprobación Humana (Human Approval Gate)", "summary": "Una puerta de aprobación humana pausa un flujo automatizado en un punto de control definido para que una persona revise, edite o rechace una acción propuesta antes de ejecutarse, sobre todo en operaciones de alto impacto, irreversibles o reguladas. Es la forma operativa de la supervisión humana en el bucle.", "definition": "Una puerta de aprobación humana es un punto de control que se inserta antes de una acción automatizada de alto impacto, donde una persona revisa y aprueba, edita o rechaza la acción propuesta antes de que se ejecute.", "problem": "Dejar que un sistema de IA ejecute acciones de alto impacto de forma autónoma arriesga errores costosos, irreversibles o no conformes sin posibilidad de juicio humano.", "context": "Usa una puerta de aprobación para acciones cuyo coste de error supera la latencia de la revisión: pagos, borrados, comunicaciones externas, cambios en producción o cualquier cosa regulada.", "solution": [ "Inserta un punto de control antes de la acción sensible: el sistema prepara la acción propuesta con suficiente contexto, luego se suspende y la enruta a un humano que aprueba, edita o rechaza. Con la aprobación, procede; ante un timeout, recurre a un respaldo seguro. Cada decisión se registra para auditoría.", "Pon puertas solo en los pasos de alto impacto, no en todo: el exceso de puertas destruye el valor de la automatización y causa fatiga de aprobación. Elige los puntos de control por riesgo." ], "components": [ "Punto de control basado en riesgo", "Vista previa de la acción propuesta", "Aprobar / editar / rechazar", "Timeout y respaldo seguro", "Registro de auditoría" ], "benefits": [ "Previene errores costosos o irreversibles.", "Mantiene la responsabilidad en un humano.", "Satisface requisitos de cumplimiento y supervisión.", "Genera confianza, habilitando una autonomía gradual." ], "risks": [ "Añade latencia y limita el rendimiento.", "Aprobación automática si los revisores carecen de contexto o tiempo.", "Fatiga de aprobación por demasiadas puertas.", "Cuellos de botella si los revisores no están disponibles." ], "whenNot": [ "Para acciones de bajo impacto y fácilmente reversibles.", "Cuando el rendimiento debe ser alto y el riesgo es bajo.", "Cuando un guardarraíl determinista puede autoaprobar con seguridad." ], "examples": [ "Un agente que redacta un reembolso que un humano aprueba antes de emitirse.", "Un cambio en producción que se pausa para una firma antes de desplegar.", "Un correo saliente en cola para revisión antes de enviarse." ], "productionEvidence": { "context": "Flujos empresariales donde un agente puede desencadenar acciones irreversibles o reguladas: reembolsos, cambios de cuenta, comunicaciones externas, despliegues en producción.", "scenario": "El agente prepara la acción con todo el contexto y se pausa; un revisor la aprueba, edita o rechaza; con la aprobación se ejecuta, ante un timeout recurre a un respaldo seguro. Cada decisión se registra.", "technology": "Un motor de flujos con interrupciones (p. ej. LangGraph), una cola/UI de aprobación y un registro de auditoría.", "load": "Solo se ponen puertas a una minoría de pasos de alto impacto; la mayoría de pasos de bajo impacto se ejecutan automáticamente, así que el volumen para los revisores se mantiene acotado.", "results": "Patrón observado: los errores irreversibles se detectan antes de ejecutarse y la responsabilidad queda en un humano, a costa de más latencia en los pasos con puerta. Pon puertas por riesgo y mide la latencia de aprobación y la tasa de aprobación automática en tu propio flujo: son observaciones de referencia, no cifras garantizadas." }, "kpis": [ { "metric": "Latencia de aprobación", "note": "Tiempo que una acción espera en la puerta; el coste central del patrón y lo primero a vigilar por cuellos de botella." }, { "metric": "Tasa de rechazo / edición", "note": "Proporción de propuestas que un humano rechaza o edita; casi cero suele indicar aprobación automática, muy alta, falta de confianza en el agente." }, { "metric": "Rendimiento vs. pasos con puerta", "note": "Tareas completadas por hora frente a cuántos pasos tienen puerta; el exceso de puertas hunde el rendimiento." }, { "metric": "Tasa de timeout / respaldo", "note": "Con qué frecuencia las acciones llegan al timeout y toman el respaldo seguro; si sube, los revisores están saturados." } ], "failureModes": [ "Aprobación automática: los revisores aprueban sin escrutinio real cuando faltan contexto o tiempo, anulando la puerta.", "Fatiga de aprobación y cuellos de botella por poner puertas en pasos de bajo impacto.", "Autoejecución silenciosa en el timeout cuando no se define un respaldo seguro.", "Contexto insuficiente en la propuesta, de modo que el humano no puede decidir con criterio." ], "lessons": [ "Pon puertas por riesgo, no por defecto: automatiza lo de bajo impacto y reserva las puertas para acciones irreversibles o reguladas.", "Da a los revisores contexto suficiente y una elección clara aprobar/editar/rechazar para evitar la aprobación automática.", "Define siempre un respaldo seguro en el timeout; nunca ejecutes en silencio una acción con puerta.", "Registra cada decisión para auditoría: la puerta es también tu evidencia de cumplimiento." ], "faqs": [ { "q": "¿En qué se diferencia del human-in-the-loop?", "a": "Es la implementación concreta del principio human-in-the-loop: un punto de aprobación específico en un flujo antes de una acción sensible." }, { "q": "¿Las aprobaciones no lo ralentizan todo?", "a": "Solo si pones demasiadas puertas. Aplica puertas por riesgo: automatiza los pasos de bajo impacto y reserva la aprobación para acciones de alto impacto, irreversibles o reguladas." }, { "q": "¿Qué pasa en un timeout?", "a": "Define un respaldo seguro: retener la acción, escalar o cancelar. Nunca autoejecutes en silencio una acción con puerta solo porque nadie respondió." } ] }, "pt": { "name": "Portão de Aprovação Humana (Human Approval Gate)", "summary": "Um portão de aprovação humana pausa um fluxo automatizado num ponto de controle definido para que uma pessoa revise, edite ou rejeite uma ação proposta antes de executar, sobretudo em operações de alto impacto, irreversíveis ou reguladas. É a forma operacional da supervisão humana no laço.", "definition": "Um portão de aprovação humana é um ponto de controle inserido antes de uma ação automatizada de alto impacto, onde uma pessoa revisa e aprova, edita ou rejeita a ação proposta antes que ela seja executada.", "problem": "Deixar um sistema de IA executar ações de alto impacto de forma autônoma arrisca erros custosos, irreversíveis ou não conformes sem possibilidade de julgamento humano.", "context": "Use um portão de aprovação para ações cujo custo de erro supera a latência da revisão: pagamentos, exclusões, comunicações externas, mudanças em produção ou qualquer coisa regulada.", "solution": [ "Insira um ponto de controle antes da ação sensível: o sistema prepara a ação proposta com contexto suficiente, depois se suspende e a roteia a um humano que aprova, edita ou rejeita. Com a aprovação, prossegue; em um timeout, recorre a um fallback seguro. Cada decisão é registrada para auditoria.", "Coloque portões só nos passos de alto impacto, não em tudo: o excesso de portões destrói o valor da automação e causa fadiga de aprovação. Escolha os pontos de controle por risco." ], "components": [ "Ponto de controle baseado em risco", "Pré-visualização da ação proposta", "Aprovar / editar / rejeitar", "Timeout e fallback seguro", "Registro de auditoria" ], "benefits": [ "Previne erros custosos ou irreversíveis.", "Mantém a responsabilidade com um humano.", "Satisfaz requisitos de conformidade e supervisão.", "Gera confiança, habilitando uma autonomia gradual." ], "risks": [ "Adiciona latência e limita a vazão.", "Aprovação automática se os revisores carecem de contexto ou tempo.", "Fadiga de aprovação por portões demais.", "Gargalos se os revisores não estiverem disponíveis." ], "whenNot": [ "Para ações de baixo impacto e facilmente reversíveis.", "Quando a vazão deve ser alta e o risco é baixo.", "Quando um guard-rail determinístico pode autoaprovar com segurança." ], "examples": [ "Um agente que redige um reembolso que um humano aprova antes de ser emitido.", "Uma mudança em produção que pausa para uma assinatura antes de implantar.", "Um e-mail de saída em fila para revisão antes de enviar." ], "productionEvidence": { "context": "Fluxos empresariais onde um agente pode desencadear ações irreversíveis ou reguladas: reembolsos, mudanças de conta, comunicações externas, implantações em produção.", "scenario": "O agente prepara a ação com todo o contexto e pausa; um revisor a aprova, edita ou rejeita; com a aprovação ela executa, em um timeout recorre a um fallback seguro. Cada decisão é registrada.", "technology": "Um motor de fluxos com interrupções (ex.: LangGraph), uma fila/UI de aprovação e um registro de auditoria.", "load": "Apenas uma minoria de passos de alto impacto tem portão; a maioria dos passos de baixo impacto roda automaticamente, então o volume para os revisores fica limitado.", "results": "Padrão observado: erros irreversíveis são detectados antes de executar e a responsabilidade fica com um humano, ao custo de mais latência nos passos com portão. Coloque portões por risco e meça a latência de aprovação e a taxa de aprovação automática no seu próprio fluxo — são observações de referência, não números garantidos." }, "kpis": [ { "metric": "Latência de aprovação", "note": "Tempo que uma ação espera no portão; o custo central do padrão e o primeiro a vigiar por gargalos." }, { "metric": "Taxa de rejeição / edição", "note": "Proporção de propostas que um humano rejeita ou edita; quase zero costuma indicar aprovação automática, muito alta, falta de confiança no agente." }, { "metric": "Vazão vs. passos com portão", "note": "Tarefas concluídas por hora frente a quantos passos têm portão; o excesso de portões afunda a vazão." }, { "metric": "Taxa de timeout / fallback", "note": "Com que frequência as ações atingem o timeout e tomam o fallback seguro; se sobe, os revisores estão sobrecarregados." } ], "failureModes": [ "Aprovação automática: os revisores aprovam sem escrutínio real quando faltam contexto ou tempo, anulando o portão.", "Fadiga de aprovação e gargalos por colocar portões em passos de baixo impacto.", "Autoexecução silenciosa no timeout quando não se define um fallback seguro.", "Contexto insuficiente na proposta, de modo que o humano não consegue decidir com critério." ], "lessons": [ "Coloque portões por risco, não por padrão: automatize o de baixo impacto e reserve os portões para ações irreversíveis ou reguladas.", "Dê aos revisores contexto suficiente e uma escolha clara aprovar/editar/rejeitar para evitar a aprovação automática.", "Defina sempre um fallback seguro no timeout; nunca execute em silêncio uma ação com portão.", "Registre cada decisão para auditoria: o portão é também sua evidência de conformidade." ], "faqs": [ { "q": "Como difere do human-in-the-loop?", "a": "É a implementação concreta do princípio human-in-the-loop: um ponto de aprovação específico num fluxo antes de uma ação sensível." }, { "q": "As aprovações não atrasam tudo?", "a": "Só se você colocar portões demais. Aplique portões por risco: automatize os passos de baixo impacto e reserve a aprovação para ações de alto impacto, irreversíveis ou reguladas." }, { "q": "O que acontece num timeout?", "a": "Defina um fallback seguro: reter a ação, escalar ou cancelar. Nunca autoexecute em silêncio uma ação com portão só porque ninguém respondeu." } ] } } }, { "slug": "human-escalation", "category": "safety", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/human-escalation", "api": "https://santismm.com/api/patterns/human-escalation", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "Confidence scoring", "Routing", "Ticketing / handoff systems", "Audit logging" ], "references": [ { "title": "EU AI Act — Article 14 (Human oversight)", "url": "https://artificialintelligenceact.eu/article/14/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "human-approval-gate", "recovery-strategy", "routing" ], "locales": { "en": { "name": "Human Escalation", "summary": "Hand the whole task to a human when the agent detects it is out of its depth — low confidence, repeated failure, ambiguity, or sensitive situations — and pass full context so the person can take over without re-investigating. Unlike an approval gate, which pauses one action for sign-off, escalation transfers ownership so the agent stops driving. The hard part is calibrating triggers to avoid both over- and under-escalation.", "problem": "An autonomous agent will inevitably encounter cases it cannot handle well: inputs outside its training distribution, requests it keeps failing to satisfy, genuinely ambiguous goals, or emotionally and legally sensitive moments. If it presses on anyway, it produces confidently wrong answers, loops, or harmful actions — and the user discovers the failure too late. Yet routing everything to humans defeats the point of automation and overwhelms staff. The system needs a disciplined way to recognize the edge of its competence and transfer the task before damage is done.", "context": "Use this pattern wherever an agent acts with meaningful autonomy and the cost of a wrong outcome exceeds the cost of a human glancing at it: customer support, claims and case handling, financial or medical triage, content moderation, and operational copilots. It assumes a human queue or on-call function exists to receive escalations and that the agent can observe signals about its own performance. It is most valuable when failures are silent — when a confidently wrong answer is worse than no answer — and when a subset of cases is known to be hard, rare, or regulated.", "solution": [ "Define explicit escalation triggers and wire them into the agent's main loop as first-class exit conditions, not afterthoughts. Common triggers are confidence below a threshold (from model scores, self-critique, or a verifier), loop or repeated-failure detection (the agent retries the same step without progress), structural ambiguity (multiple valid interpretations of the goal), and sensitivity signals (negative sentiment, safety keywords, high-value accounts, or regulated topics). Each trigger should map to a routing decision: which human or team, with what priority. Treat thresholds as tunable parameters owned by the team, reviewed against real outcomes, because they encode the trade-off between automation rate and error rate.\n\nWhen a trigger fires, the agent must perform a clean handoff: stop acting, package the full context — original request, what it attempted, intermediate results, its current best guess, and why it escalated — and route it to the right queue via a ticket or live handoff. The receiving human should be able to take over without re-investigating from scratch; context quality is what makes escalation feel like help rather than a dropped ball. Always provide a graceful fallback message to the end user (\"I'm bringing in a specialist\") so the experience degrades smoothly. Finally, log every escalation with its trigger and resolution so appropriateness can be measured and triggers retuned." ], "components": [ "Trigger evaluator", "Context packager", "Router", "Handoff channel", "Fallback responder", "Audit log" ], "benefits": [ "Hard cases reach a human before the agent produces a confidently wrong outcome, capping the blast radius of mistakes.", "Only genuinely difficult cases are handed off, so routine volume stays automated and staff focus on what needs judgment.", "A clean handoff with context means users are helped rather than bounced, and humans resume without starting over.", "Logged triggers and resolutions provide the evidence trail regulators and risk owners expect for meaningful human oversight." ], "risks": [ "Thresholds set too conservatively push easy cases to humans, erasing automation gains and burying staff in noise.", "Thresholds set too loosely let the agent power through cases it should have handed off, causing silent bad outcomes.", "If the payload is thin, the human re-investigates from scratch and escalation feels like a dropped task, not assistance.", "Model self-confidence often does not track real accuracy, so naive score thresholds escalate the wrong cases in both directions." ], "whenNot": [ "If there is no staffed queue or on-call function to take over, escalation has nowhere to go; invest in a safe-stop or recovery path instead.", "When you only need approval for one specific high-impact step while the agent keeps the task, use a human-approval gate, not full ownership transfer.", "For cheap, easily reversible tasks where a wrong answer costs nothing, the overhead and latency of escalation outweigh the benefit." ], "examples": [ "A support agent resolves routine questions but escalates to a human queue on detected frustration, repeated unhelpful answers, or account-sensitive requests, passing the full conversation.", "An insurance agent auto-processes clear claims and escalates ambiguous, high-value, or fraud-flagged ones to an adjuster with its findings and the reason attached.", "An autonomous coding agent that fails the same test repeatedly stops, summarizes what it tried and where it is blocked, and hands the task to an engineer instead of churning." ], "kpis": [ { "metric": "Escalation rate", "note": "Share of tasks handed to humans. Watch the trend and the distribution, not a target number — a sudden spike or drop signals a miscalibrated trigger or a shift in input mix." }, { "metric": "Escalation appropriateness", "note": "Of escalated cases, how many genuinely needed a human (true positives) versus could have been handled. Sampled human review of escalations is the most reliable read." }, { "metric": "Missed-escalation rate", "note": "Of automated resolutions, how many later turned out to be wrong and should have been escalated. The hardest and most important signal; mine complaints, reopens, and audits to find them." }, { "metric": "Handoff context sufficiency", "note": "How often the receiving human can take over without re-contacting the user or re-investigating. Track via agent feedback on whether the package was complete." } ], "failureModes": [ "Triggers tuned once and never revisited fall out of step as inputs and models change, silently shifting the automation/error balance.", "Cases route into a queue that no one owns or that is overwhelmed, so escalated users wait indefinitely — worse than a wrong answer.", "An agent optimized to avoid escalation learns to express false confidence, suppressing the very signal the pattern depends on.", "Handoff strips formatting, intermediate reasoning, or attachments, forcing the human to rebuild the situation and erasing the speed benefit." ], "lessons": [ "Validate that your confidence signal correlates with actual accuracy before thresholding on it; pair model scores with a verifier or self-critique.", "The difference between a good and bad escalation is almost entirely the handoff payload; invest there before tuning thresholds.", "Treat thresholds as living parameters reviewed against sampled escalations and missed escalations, owned by the team, not frozen at launch.", "Even a perfect trigger fails sometimes; a graceful holding message and an owned queue prevent failures from becoming abandonments." ], "faqs": [ { "q": "How is this different from a human-approval gate?", "a": "An approval gate pauses one specific high-impact action and asks a human to sign off, then the agent continues. Escalation transfers ownership of the whole task — the agent stops driving because it shouldn't proceed at all. Use a gate for 'should I do this one thing?' and escalation for 'I'm out of my depth, please take over.'" }, { "q": "What's the right escalation rate?", "a": "There is no universal number; it depends on task difficulty mix and the cost of errors. Optimize for appropriateness, not a target rate: escalate cases that genuinely need a human and minimize both unnecessary handoffs and missed escalations. Review the rate as a signal of miscalibration, not as a goal in itself." }, { "q": "Can I just escalate whenever model confidence is low?", "a": "It's a useful trigger but rarely sufficient alone, because model self-confidence often does not track real accuracy. Combine it with loop detection, ambiguity checks, and sensitivity signals, and validate that your confidence measure actually correlates with correct outcomes before trusting a threshold." } ] }, "es": { "name": "Escalado a humano", "summary": "Entrega toda la tarea a una persona cuando el agente detecta que supera su competencia — baja confianza, fallos repetidos, ambigüedad o situaciones delicadas — y traspasa el contexto completo para que el humano retome sin volver a investigar. A diferencia de una puerta de aprobación, que pausa una acción para su visto bueno, el escalado transfiere la propiedad y el agente deja de conducir. Lo difícil es calibrar los disparadores para evitar tanto el exceso como la falta de escalado.", "problem": "Un agente autónomo encontrará inevitablemente casos que no puede resolver bien: entradas fuera de su distribución de entrenamiento, solicitudes que falla una y otra vez, objetivos genuinamente ambiguos o momentos emocional y legalmente delicados. Si insiste de todos modos, produce respuestas erróneas con seguridad, bucles o acciones dañinas — y el usuario descubre el fallo demasiado tarde. Pero derivar todo a humanos anula el sentido de la automatización y satura al personal. El sistema necesita una forma disciplinada de reconocer el límite de su competencia y transferir la tarea antes de causar daño.", "context": "Usa este patrón donde un agente actúe con autonomía relevante y el coste de un mal resultado supere el de que un humano lo revise: atención al cliente, gestión de casos y reclamaciones, triaje financiero o médico, moderación de contenido y copilotos operativos. Supone que existe una cola humana o función de guardia que recibe los escalados y que el agente puede observar señales sobre su propio desempeño. Es más valioso cuando los fallos son silenciosos — cuando una respuesta erróneamente segura es peor que ninguna respuesta — y cuando se sabe que un subconjunto de casos es difícil, raro o regulado.", "solution": [ "Define disparadores de escalado explícitos e intégralos en el bucle principal del agente como condiciones de salida de primer nivel, no como añadidos. Los disparadores habituales son la confianza por debajo de un umbral (de puntuaciones del modelo, autocrítica o un verificador), la detección de bucles o fallos repetidos (el agente reintenta el mismo paso sin avanzar), la ambigüedad estructural (varias interpretaciones válidas del objetivo) y las señales de sensibilidad (sentimiento negativo, palabras de seguridad, cuentas de alto valor o temas regulados). Cada disparador debe mapear a una decisión de enrutamiento: qué humano o equipo, con qué prioridad. Trata los umbrales como parámetros ajustables propiedad del equipo, revisados frente a resultados reales, porque codifican el equilibrio entre tasa de automatización y tasa de error.\n\nCuando se dispara un trigger, el agente debe hacer un traspaso limpio: dejar de actuar, empaquetar el contexto completo — solicitud original, lo que intentó, resultados intermedios, su mejor estimación actual y por qué escaló — y enrutarlo a la cola adecuada mediante un ticket o un traspaso en vivo. El humano receptor debería poder retomar sin investigar de cero; la calidad del contexto es lo que hace que el escalado se sienta como ayuda y no como un balón soltado. Ofrece siempre un mensaje de respaldo elegante al usuario final (\"Voy a involucrar a un especialista\") para que la experiencia se degrade con suavidad. Por último, registra cada escalado con su disparador y su resolución para poder medir la idoneidad y reajustar los disparadores." ], "components": [ "Evaluador de disparadores", "Empaquetador de contexto", "Enrutador", "Canal de traspaso", "Respondedor de respaldo", "Registro de auditoría" ], "benefits": [ "Los casos difíciles llegan a un humano antes de que el agente produzca un resultado erróneamente seguro, limitando el radio de impacto de los errores.", "Solo se derivan los casos genuinamente difíciles, así el volumen rutinario sigue automatizado y el personal se centra en lo que requiere criterio.", "Un traspaso limpio con contexto significa que se ayuda a los usuarios en lugar de rebotarlos, y los humanos retoman sin empezar de cero.", "Los disparadores y resoluciones registrados aportan el rastro de evidencia que reguladores y responsables de riesgo esperan de una supervisión humana real." ], "risks": [ "Umbrales demasiado conservadores empujan casos fáciles a humanos, eliminando las ganancias de automatización y sepultando al personal en ruido.", "Umbrales demasiado laxos dejan que el agente fuerce casos que debió traspasar, provocando malos resultados silenciosos.", "Si la carga es escasa, el humano investiga de cero y el escalado se siente como una tarea abandonada, no como ayuda.", "La autoconfianza del modelo a menudo no refleja la precisión real, así que umbrales ingenuos escalan los casos equivocados en ambas direcciones." ], "whenNot": [ "Si no hay cola con personal ni función de guardia que retome, el escalado no tiene a dónde ir; invierte en una parada segura o ruta de recuperación.", "Cuando solo necesitas aprobación de un paso concreto de alto impacto mientras el agente conserva la tarea, usa una puerta de aprobación humana, no la transferencia de propiedad.", "Para tareas baratas y fácilmente reversibles donde una respuesta errónea no cuesta nada, la latencia y el coste del escalado superan el beneficio." ], "examples": [ "Un agente de soporte resuelve dudas rutinarias pero escala a una cola humana ante frustración detectada, respuestas inútiles repetidas o solicitudes sensibles de cuenta, pasando toda la conversación.", "Un agente de seguros procesa automáticamente reclamaciones claras y escala las ambiguas, de alto valor o marcadas como fraude a un perito, con sus hallazgos y el motivo adjuntos.", "Un agente de programación autónomo que falla la misma prueba repetidamente se detiene, resume lo que intentó y dónde está bloqueado, y entrega la tarea a un ingeniero en lugar de seguir girando." ], "kpis": [ { "metric": "Tasa de escalado", "note": "Proporción de tareas entregadas a humanos. Observa la tendencia y la distribución, no una cifra objetivo — un pico o caída repentina señala un disparador mal calibrado o un cambio en la mezcla de entradas." }, { "metric": "Idoneidad del escalado", "note": "De los casos escalados, cuántos necesitaban realmente un humano (verdaderos positivos) frente a los que podrían haberse resuelto. La revisión humana muestreada de los escalados es la lectura más fiable." }, { "metric": "Tasa de escalados omitidos", "note": "De las resoluciones automáticas, cuántas resultaron luego erróneas y debieron escalarse. La señal más difícil e importante; explora quejas, reaperturas y auditorías para encontrarlas." }, { "metric": "Suficiencia del contexto de traspaso", "note": "Con qué frecuencia el humano receptor puede retomar sin recontactar al usuario ni investigar de nuevo. Mídelo con la valoración del agente sobre si el paquete estaba completo." } ], "failureModes": [ "Disparadores ajustados una vez y nunca revisados se desfasan al cambiar las entradas y los modelos, alterando en silencio el equilibrio automatización/error.", "Los casos se enrutan a una cola sin dueño o saturada, así que los usuarios escalados esperan indefinidamente — peor que una respuesta errónea.", "Un agente optimizado para evitar el escalado aprende a expresar falsa confianza, suprimiendo la misma señal de la que depende el patrón.", "El traspaso elimina formato, razonamiento intermedio o adjuntos, obligando al humano a reconstruir la situación y borrando el beneficio de velocidad." ], "lessons": [ "Valida que tu señal de confianza correlaciona con la precisión real antes de poner umbrales; combina las puntuaciones del modelo con un verificador o autocrítica.", "La diferencia entre un buen y un mal escalado está casi por completo en la carga del traspaso; invierte ahí antes de ajustar umbrales.", "Trata los umbrales como parámetros vivos revisados frente a escalados muestreados y escalados omitidos, propiedad del equipo, no congelados en el lanzamiento.", "Incluso un disparador perfecto falla a veces; un mensaje de espera elegante y una cola con dueño evitan que los fallos se vuelvan abandonos." ], "faqs": [ { "q": "¿En qué se diferencia de una puerta de aprobación humana?", "a": "Una puerta de aprobación pausa una acción concreta de alto impacto y pide a un humano que dé el visto bueno, y luego el agente continúa. El escalado transfiere la propiedad de toda la tarea — el agente deja de conducir porque no debería proceder en absoluto. Usa una puerta para '¿debo hacer esta cosa concreta?' y el escalado para 'esto me supera, por favor toma el control.'" }, { "q": "¿Cuál es la tasa de escalado correcta?", "a": "No hay un número universal; depende de la mezcla de dificultad de las tareas y del coste de los errores. Optimiza por idoneidad, no por una tasa objetivo: escala los casos que realmente necesitan un humano y minimiza tanto los traspasos innecesarios como los escalados omitidos. Revisa la tasa como señal de descalibración, no como meta en sí misma." }, { "q": "¿Puedo escalar simplemente cuando la confianza del modelo es baja?", "a": "Es un disparador útil pero rara vez suficiente por sí solo, porque la autoconfianza del modelo a menudo no refleja la precisión real. Combínalo con detección de bucles, comprobaciones de ambigüedad y señales de sensibilidad, y valida que tu medida de confianza correlaciona de verdad con resultados correctos antes de confiar en un umbral." } ] }, "pt": { "name": "Escalonamento para humano", "summary": "Entrega a tarefa inteira a uma pessoa quando o agente detecta que está além de sua competência — baixa confiança, falhas repetidas, ambiguidade ou situações sensíveis — e repassa o contexto completo para que o humano assuma sem reinvestigar. Diferente de um portão de aprovação, que pausa uma ação para liberação, o escalonamento transfere a propriedade e o agente para de conduzir. O difícil é calibrar os gatilhos para evitar tanto o excesso quanto a falta de escalonamento.", "problem": "Um agente autônomo inevitavelmente encontrará casos que não consegue resolver bem: entradas fora de sua distribuição de treinamento, solicitações que ele falha repetidamente, objetivos genuinamente ambíguos ou momentos emocional e juridicamente sensíveis. Se insistir mesmo assim, produz respostas confiantemente erradas, laços ou ações nocivas — e o usuário descobre a falha tarde demais. Mas encaminhar tudo para humanos anula o propósito da automação e sobrecarrega a equipe. O sistema precisa de uma forma disciplinada de reconhecer o limite de sua competência e transferir a tarefa antes que o dano ocorra.", "context": "Use este padrão onde um agente age com autonomia relevante e o custo de um mau resultado supera o de um humano dar uma olhada: atendimento ao cliente, gestão de casos e sinistros, triagem financeira ou médica, moderação de conteúdo e copilotos operacionais. Pressupõe que existe uma fila humana ou função de plantão para receber os escalonamentos e que o agente consegue observar sinais sobre o próprio desempenho. É mais valioso quando as falhas são silenciosas — quando uma resposta confiantemente errada é pior que nenhuma resposta — e quando se sabe que um subconjunto de casos é difícil, raro ou regulado.", "solution": [ "Defina gatilhos de escalonamento explícitos e integre-os ao laço principal do agente como condições de saída de primeira classe, não como remendos. Os gatilhos comuns são confiança abaixo de um limiar (de pontuações do modelo, autocrítica ou um verificador), detecção de laço ou falha repetida (o agente repete o mesmo passo sem avançar), ambiguidade estrutural (várias interpretações válidas do objetivo) e sinais de sensibilidade (sentimento negativo, palavras de segurança, contas de alto valor ou temas regulados). Cada gatilho deve mapear para uma decisão de roteamento: qual humano ou equipe, com qual prioridade. Trate os limiares como parâmetros ajustáveis de propriedade da equipe, revisados contra resultados reais, pois codificam o equilíbrio entre taxa de automação e taxa de erro.\n\nQuando um gatilho dispara, o agente deve fazer um repasse limpo: parar de agir, empacotar o contexto completo — solicitação original, o que tentou, resultados intermediários, sua melhor estimativa atual e por que escalou — e roteá-lo para a fila certa via ticket ou repasse ao vivo. O humano receptor deve conseguir assumir sem investigar do zero; a qualidade do contexto é o que faz o escalonamento parecer ajuda e não uma bola fora. Forneça sempre uma mensagem de fallback elegante ao usuário final (\"Vou trazer um especialista\") para que a experiência se degrade suavemente. Por fim, registre cada escalonamento com seu gatilho e resolução para que a adequação possa ser medida e os gatilhos reajustados." ], "components": [ "Avaliador de gatilhos", "Empacotador de contexto", "Roteador", "Canal de repasse", "Respondedor de fallback", "Registro de auditoria" ], "benefits": [ "Casos difíceis chegam a um humano antes de o agente produzir um resultado confiantemente errado, limitando o raio de impacto dos erros.", "Apenas os casos genuinamente difíceis são repassados, então o volume rotineiro segue automatizado e a equipe foca no que exige julgamento.", "Um repasse limpo com contexto significa que os usuários são ajudados em vez de rejeitados, e os humanos retomam sem começar do zero.", "Gatilhos e resoluções registrados fornecem a trilha de evidência que reguladores e responsáveis por risco esperam de uma supervisão humana real." ], "risks": [ "Limiares conservadores demais empurram casos fáceis para humanos, apagando os ganhos de automação e enterrando a equipe em ruído.", "Limiares frouxos demais deixam o agente forçar casos que deveria ter repassado, causando maus resultados silenciosos.", "Se a carga é rasa, o humano reinvestiga do zero e o escalonamento parece uma tarefa abandonada, não ajuda.", "A autoconfiança do modelo muitas vezes não acompanha a precisão real, então limiares ingênuos escalam os casos errados em ambas as direções." ], "whenNot": [ "Se não há fila com equipe nem função de plantão para assumir, o escalonamento não tem para onde ir; invista em uma parada segura ou caminho de recuperação.", "Quando você só precisa de aprovação de um passo específico de alto impacto enquanto o agente mantém a tarefa, use um portão de aprovação humana, não a transferência de propriedade.", "Para tarefas baratas e facilmente reversíveis onde uma resposta errada não custa nada, a latência e o custo do escalonamento superam o benefício." ], "examples": [ "Um agente de suporte resolve dúvidas rotineiras mas escala para uma fila humana ao detectar frustração, respostas inúteis repetidas ou solicitações sensíveis de conta, passando toda a conversa.", "Um agente de seguros processa automaticamente sinistros claros e escala os ambíguos, de alto valor ou marcados como fraude a um analista, com suas constatações e o motivo anexados.", "Um agente de programação autônomo que falha o mesmo teste repetidamente para, resume o que tentou e onde está travado, e entrega a tarefa a um engenheiro em vez de continuar girando." ], "kpis": [ { "metric": "Taxa de escalonamento", "note": "Proporção de tarefas entregues a humanos. Observe a tendência e a distribuição, não um número-alvo — um pico ou queda repentina sinaliza um gatilho mal calibrado ou uma mudança na mistura de entradas." }, { "metric": "Adequação do escalonamento", "note": "Dos casos escalados, quantos realmente precisavam de um humano (verdadeiros positivos) versus os que poderiam ter sido resolvidos. A revisão humana amostrada dos escalonamentos é a leitura mais confiável." }, { "metric": "Taxa de escalonamentos omitidos", "note": "Das resoluções automáticas, quantas depois se mostraram erradas e deveriam ter sido escaladas. O sinal mais difícil e importante; explore reclamações, reaberturas e auditorias para encontrá-las." }, { "metric": "Suficiência do contexto de repasse", "note": "Com que frequência o humano receptor consegue assumir sem recontatar o usuário nem reinvestigar. Acompanhe pela avaliação do agente sobre se o pacote estava completo." } ], "failureModes": [ "Gatilhos ajustados uma vez e nunca revisados se descompassam à medida que entradas e modelos mudam, alterando em silêncio o equilíbrio automação/erro.", "Casos são roteados para uma fila sem dono ou sobrecarregada, então os usuários escalados esperam indefinidamente — pior que uma resposta errada.", "Um agente otimizado para evitar escalonamento aprende a expressar falsa confiança, suprimindo o próprio sinal do qual o padrão depende.", "O repasse remove formatação, raciocínio intermediário ou anexos, forçando o humano a reconstruir a situação e apagando o benefício de velocidade." ], "lessons": [ "Valide que seu sinal de confiança correlaciona com a precisão real antes de aplicar limiares; combine pontuações do modelo com um verificador ou autocrítica.", "A diferença entre um bom e um mau escalonamento está quase inteiramente na carga do repasse; invista aí antes de ajustar limiares.", "Trate os limiares como parâmetros vivos revisados contra escalonamentos amostrados e escalonamentos omitidos, de propriedade da equipe, não congelados no lançamento.", "Mesmo um gatilho perfeito falha às vezes; uma mensagem de espera elegante e uma fila com dono evitam que falhas virem abandonos." ], "faqs": [ { "q": "Como isso difere de um portão de aprovação humana?", "a": "Um portão de aprovação pausa uma ação específica de alto impacto e pede a um humano que libere, e então o agente continua. O escalonamento transfere a propriedade da tarefa inteira — o agente para de conduzir porque não deveria prosseguir de jeito nenhum. Use um portão para 'devo fazer esta coisa específica?' e o escalonamento para 'isto está além de mim, por favor assuma.'" }, { "q": "Qual é a taxa de escalonamento certa?", "a": "Não há número universal; depende da mistura de dificuldade das tarefas e do custo dos erros. Otimize pela adequação, não por uma taxa-alvo: escale os casos que realmente precisam de um humano e minimize tanto os repasses desnecessários quanto os escalonamentos omitidos. Revise a taxa como sinal de descalibração, não como meta em si." }, { "q": "Posso simplesmente escalar sempre que a confiança do modelo for baixa?", "a": "É um gatilho útil mas raramente suficiente sozinho, porque a autoconfiança do modelo muitas vezes não acompanha a precisão real. Combine-o com detecção de laço, verificações de ambiguidade e sinais de sensibilidade, e valide que sua medida de confiança realmente correlaciona com resultados corretos antes de confiar em um limiar." } ] } } }, { "slug": "long-term-memory", "category": "retrieval", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/long-term-memory", "api": "https://santismm.com/api/patterns/long-term-memory", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Vector store", "Memory frameworks (Mem0 / LangMem)", "RAG", "Summarization" ], "references": [ { "title": "Packer et al. — MemGPT (2023)", "url": "https://arxiv.org/abs/2310.08560" }, { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "semantic-caching", "context-compression" ], "locales": { "en": { "name": "Long-Term Memory", "summary": "Give an agent persistent memory across sessions so it remembers facts, user preferences, and prior outcomes beyond a single context window. A write path decides what to store, summarizes it, and deduplicates it; a read path retrieves only the relevant memories into context when needed. Unlike semantic caching, which caches whole answers to skip recomputation, long-term memory stores durable facts and state and recomposes them into fresh reasoning each time.", "problem": "The context window is finite and resets between sessions. An agent that only sees the current conversation forgets a user's stated preferences, decisions made last week, and the outcome of prior tasks. Stuffing all history into every prompt is impossible past a certain scale and degrades reasoning as the window fills with low-value tokens. Teams need a way to persist the small set of facts that matter and surface them precisely when they are relevant.", "context": "Use this when an agent serves the same users or works on the same long-running tasks repeatedly: assistants that learn preferences, support agents that track a customer's history, coding agents that remember project conventions, or multi-step workflows spanning days. It assumes you can store data outside the model (a vector store, database, or memory framework) and that you control both when memories are written and how they are retrieved into the prompt.", "solution": [ "Separate the write path from the read path. On the write path, after a turn or task completes, an extraction step decides what is worth remembering: stable facts, preferences, commitments, and outcomes — not transient chatter. Candidate memories are summarized into compact, self-contained statements, checked against existing memories to deduplicate and to detect contradictions, then written to a store with metadata: a memory type, a timestamp, a source, and the user or scope it belongs to. Writing less but writing well is the goal; noisy memories poison later retrieval.\n\nOn the read path, before the agent reasons, you retrieve candidate memories relevant to the current task — typically by semantic similarity plus filters on scope and recency — rank them, and inject only the top few into context. Treat retrieval as a precision problem: a handful of correct memories beats a large, loosely related set. Distinguish memory types so retrieval can be targeted: episodic (what happened), semantic (durable facts and preferences), and procedural (how to do a recurring task). Periodically consolidate and expire memories so the store stays small, current, and free of contradictions." ], "components": [ "Memory extractor (write path)", "Deduplication and contradiction check", "Memory store", "Retriever (read path)", "Context assembler", "Consolidation and expiry job" ], "benefits": [ "The agent recalls preferences, decisions, and outcomes from prior sessions, so users do not have to repeat context and the agent behaves consistently over time.", "Retrieving a few relevant memories keeps the window focused on high-value tokens instead of dumping full history, which preserves reasoning quality and reduces cost.", "As stable facts and preferences accumulate, the agent tailors responses more accurately with each interaction without retraining the model.", "Because memories live in an external store with metadata, you can inspect, correct, export, and delete what the agent knows — important for trust and compliance." ], "risks": [ "Without consolidation and expiry, the store accumulates outdated facts and conflicting statements, and the agent confidently acts on the wrong one.", "Persisting user data raises retention, consent, and access-control obligations; memories can leak sensitive information across sessions or users if scope is not enforced.", "Low precision injects irrelevant or wrong memories that mislead reasoning; low recall silently drops the memory that mattered, making failures hard to diagnose.", "Over-eager writing inflates the store, slows retrieval, raises storage and embedding costs, and dilutes the signal that good retrieval depends on." ], "whenNot": [ "If sessions are independent and nothing needs to carry over, persistent memory adds complexity, cost, and privacy surface for no benefit.", "When the goal is to reuse a previous answer for a repeated query, semantic caching is the right tool; long-term memory is for remembering facts and state, not caching outputs.", "Where regulation or policy forbids retaining user data, do not persist memories; rely on in-session context or explicit, scoped storage the user controls." ], "examples": [ "Across sessions it remembers tone, formats, recurring contacts, and standing instructions, retrieving the few that apply to the current request instead of re-asking.", "On each contact it retrieves the customer's prior issues, entitlements, and resolutions scoped to that account, so it continues rather than restarts the conversation.", "It stores procedural memories — build commands, naming rules, review preferences — and recalls them when working in the same repository over many sessions." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "The agent persists workspace memory files and per-session traces for cross-turn and cross-session continuity, with a semantic-recall plugin available on demand.", "technology": "Workspace memory files (MEMORY.md, IDENTITY.md, SOUL.md, USER.md, HEARTBEAT.md), persistent session ids and lifecycle events, and an active-memory plugin (memory_search/get/recall).", "load": "134 persisted session files across the 57-day window; semantic recall invoked once.", "results": "Continuity held across 134 persisted sessions over 57 days through structural workspace memory; explicit semantic recall was rarely needed (one call) in this autonomous workload. Single-operator local-first deployment." }, "kpis": [ { "metric": "Retrieval precision of injected memories", "note": "Of the memories placed in context, the share that were actually relevant. This is the metric that most directly governs answer quality; good looks like the injected set being almost entirely on-topic, with irrelevant memories rare." }, { "metric": "Retrieval recall on memory-dependent tasks", "note": "On tasks that require a known stored fact, how often that fact is actually retrieved. Good looks like the right memory surfacing reliably; persistent misses point to extraction or indexing gaps." }, { "metric": "Memory store size and growth rate", "note": "Total memories and how fast they accumulate per active user. Good looks like growth tracking genuinely new durable facts, not unbounded climb — a runaway curve signals over-eager writing." }, { "metric": "Staleness and contradiction rate", "note": "Share of retrieved memories that are outdated or conflict with a newer truth. Good looks like a low and stable rate, evidence that consolidation and expiry are keeping pace with change." } ], "failureModes": [ "Writing everything turns the store into noise; retrieval then surfaces low-value or wrong memories. Fix by raising the bar for what gets written and reviewing extraction quality.", "An old fact is retrieved and acted on after the truth changed, with no signal that it is outdated. Mitigate with timestamps, recency-weighted ranking, and explicit supersession on write.", "A memory from one user, tenant, or project is retrieved into another's context because scope filters were missing or wrong — a privacy and correctness failure at once.", "To compensate for poor ranking, teams inject many memories, refilling the window with marginal tokens and degrading the very reasoning memory was meant to support." ], "lessons": [ "Quality is decided when you choose what to remember. A small, clean, deduplicated store retrieves far better than a large noisy one.", "A few correct memories outperform many loosely related ones. Tune for relevance and rank tightly rather than maximizing how much you inject.", "Store metadata and provide ways to view, edit, expire, and delete memories. This is essential for debugging, trust, and meeting privacy obligations.", "Facts go stale and contradict each other. Build consolidation, supersession, and expiry early; retrofitting them onto a large polluted store is painful." ], "faqs": [ { "q": "How is this different from semantic caching?", "a": "Semantic caching stores and replays whole answers to avoid recomputing similar requests. Long-term memory stores durable facts, preferences, and outcomes, then recomposes them into fresh reasoning for each new task. One reuses outputs; the other remembers state." }, { "q": "What should the agent actually remember?", "a": "Stable, reusable signal: user preferences, decisions and commitments, outcomes of prior tasks, and recurring procedures. Avoid transient chatter and anything you cannot justify retaining. Writing less but writing well is what makes later retrieval precise." }, { "q": "How do you handle PII and privacy?", "a": "Treat the store as governed data: enforce scope so memories never cross users or tenants, minimize what you persist, support consent and deletion, and set retention and access controls. Inspectability and an expiry policy are part of meeting these obligations." } ] }, "es": { "name": "Memoria a largo plazo", "summary": "Dota a un agente de memoria persistente entre sesiones para que recuerde hechos, preferencias del usuario y resultados previos más allá de una única ventana de contexto. Una vía de escritura decide qué almacenar, lo resume y lo deduplica; una vía de lectura recupera solo las memorias relevantes hacia el contexto cuando hacen falta. A diferencia del almacenamiento en caché semántico, que cachea respuestas completas para evitar recomputar, la memoria a largo plazo guarda hechos y estado duraderos y los recompone en razonamiento nuevo cada vez.", "problem": "La ventana de contexto es finita y se reinicia entre sesiones. Un agente que solo ve la conversación actual olvida las preferencias declaradas por el usuario, las decisiones tomadas la semana pasada y el resultado de tareas previas. Meter todo el historial en cada prompt es imposible a cierta escala y degrada el razonamiento a medida que la ventana se llena de tokens de bajo valor. Los equipos necesitan una forma de persistir el pequeño conjunto de hechos que importan y de mostrarlos con precisión cuando son relevantes.", "context": "Úsalo cuando un agente atiende a los mismos usuarios o trabaja repetidamente en las mismas tareas de larga duración: asistentes que aprenden preferencias, agentes de soporte que siguen el historial de un cliente, agentes de programación que recuerdan las convenciones de un proyecto o flujos de varios pasos que abarcan días. Supone que puedes almacenar datos fuera del modelo (un almacén vectorial, una base de datos o un framework de memoria) y que controlas tanto cuándo se escriben las memorias como cómo se recuperan hacia el prompt.", "solution": [ "Separa la vía de escritura de la vía de lectura. En la vía de escritura, tras completar un turno o una tarea, un paso de extracción decide qué vale la pena recordar: hechos estables, preferencias, compromisos y resultados, no charla transitoria. Las memorias candidatas se resumen en enunciados compactos y autocontenidos, se contrastan con las memorias existentes para deduplicar y detectar contradicciones, y se escriben en un almacén con metadatos: un tipo de memoria, una marca de tiempo, una fuente y el usuario o ámbito al que pertenecen. El objetivo es escribir menos pero escribir bien; las memorias ruidosas envenenan la recuperación posterior.\n\nEn la vía de lectura, antes de que el agente razone, recuperas las memorias candidatas relevantes para la tarea actual — normalmente por similitud semántica más filtros de ámbito y recencia —, las clasificas e inyectas solo las pocas mejores en el contexto. Trata la recuperación como un problema de precisión: un puñado de memorias correctas vale más que un conjunto grande y poco relacionado. Distingue los tipos de memoria para que la recuperación sea dirigida: episódica (qué ocurrió), semántica (hechos y preferencias duraderos) y procedimental (cómo realizar una tarea recurrente). Consolida y expira las memorias periódicamente para que el almacén siga siendo pequeño, actual y libre de contradicciones." ], "components": [ "Extractor de memorias (vía de escritura)", "Verificación de duplicados y contradicciones", "Almacén de memorias", "Recuperador (vía de lectura)", "Ensamblador de contexto", "Tarea de consolidación y expiración" ], "benefits": [ "El agente recuerda preferencias, decisiones y resultados de sesiones previas, así los usuarios no tienen que repetir el contexto y el agente se comporta de forma consistente en el tiempo.", "Recuperar unas pocas memorias relevantes mantiene la ventana centrada en tokens de alto valor en lugar de volcar todo el historial, lo que preserva la calidad del razonamiento y reduce el coste.", "A medida que se acumulan hechos y preferencias estables, el agente adapta sus respuestas con más precisión en cada interacción sin reentrenar el modelo.", "Como las memorias viven en un almacén externo con metadatos, puedes inspeccionar, corregir, exportar y borrar lo que el agente sabe, algo importante para la confianza y el cumplimiento normativo." ], "risks": [ "Sin consolidación ni expiración, el almacén acumula hechos desactualizados y enunciados en conflicto, y el agente actúa con confianza sobre el equivocado.", "Persistir datos de usuario genera obligaciones de retención, consentimiento y control de acceso; las memorias pueden filtrar información sensible entre sesiones o usuarios si no se aplica el ámbito.", "Una precisión baja inyecta memorias irrelevantes o erróneas que desorientan el razonamiento; una cobertura baja descarta en silencio la memoria que importaba, lo que dificulta diagnosticar los fallos.", "Escribir en exceso infla el almacén, ralentiza la recuperación, eleva los costes de almacenamiento y de embeddings y diluye la señal de la que depende una buena recuperación." ], "whenNot": [ "Si las sesiones son independientes y nada necesita trasladarse, la memoria persistente añade complejidad, coste y superficie de privacidad sin beneficio.", "Cuando el objetivo es reutilizar una respuesta previa para una consulta repetida, el almacenamiento en caché semántico es la herramienta adecuada; la memoria a largo plazo es para recordar hechos y estado, no para cachear salidas.", "Donde la normativa o la política prohíbe retener datos de usuario, no persistas memorias; apóyate en el contexto de la sesión o en un almacenamiento explícito y acotado que controle el usuario." ], "examples": [ "Entre sesiones recuerda el tono, los formatos, los contactos recurrentes y las instrucciones permanentes, recuperando las pocas que aplican a la solicitud actual en lugar de volver a preguntar.", "En cada contacto recupera los problemas previos del cliente, sus derechos y las resoluciones acotadas a esa cuenta, de modo que continúa en vez de reiniciar la conversación.", "Almacena memorias procedimentales — comandos de compilación, reglas de nombres, preferencias de revisión — y las recuerda al trabajar en el mismo repositorio durante muchas sesiones." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "El agente persiste archivos de memoria de workspace y trazas por sesión para continuidad entre turnos y entre sesiones, con un plugin de recuerdo semántico disponible bajo demanda.", "technology": "Archivos de memoria de workspace (MEMORY.md, IDENTITY.md, SOUL.md, USER.md, HEARTBEAT.md), ids de sesión persistentes y eventos de ciclo de vida, y un plugin de memoria activa (memory_search/get/recall).", "load": "134 archivos de sesión persistidos en la ventana de 57 días; recuerdo semántico invocado una vez.", "results": "La continuidad se mantuvo en 134 sesiones persistidas durante 57 días mediante memoria estructural de workspace; el recuerdo semántico explícito apenas se necesitó (una llamada) en esta carga autónoma. Despliegue local-first mono-operador." }, "kpis": [ { "metric": "Precisión de recuperación de las memorias inyectadas", "note": "De las memorias colocadas en el contexto, la proporción que era realmente relevante. Es la métrica que más directamente gobierna la calidad de la respuesta; lo bueno se ve cuando el conjunto inyectado está casi todo a propósito, con memorias irrelevantes poco frecuentes." }, { "metric": "Cobertura de recuperación en tareas dependientes de memoria", "note": "En tareas que requieren un hecho almacenado conocido, con qué frecuencia ese hecho se recupera realmente. Lo bueno se ve cuando la memoria correcta aparece de forma fiable; los fallos persistentes apuntan a lagunas de extracción o de indexación." }, { "metric": "Tamaño del almacén de memorias y ritmo de crecimiento", "note": "Total de memorias y a qué velocidad se acumulan por usuario activo. Lo bueno se ve cuando el crecimiento sigue hechos duraderos genuinamente nuevos, no una subida sin límite — una curva descontrolada señala escritura excesiva." }, { "metric": "Tasa de obsolescencia y contradicción", "note": "Proporción de memorias recuperadas que están desactualizadas o entran en conflicto con una verdad más nueva. Lo bueno se ve como una tasa baja y estable, evidencia de que la consolidación y la expiración van al ritmo del cambio." } ], "failureModes": [ "Escribir todo convierte el almacén en ruido; entonces la recuperación expone memorias de bajo valor o erróneas. Se corrige elevando el umbral de lo que se escribe y revisando la calidad de la extracción.", "Un hecho antiguo se recupera y se actúa sobre él después de que la verdad cambió, sin señal de que esté desactualizado. Se mitiga con marcas de tiempo, clasificación ponderada por recencia y reemplazo explícito al escribir.", "Una memoria de un usuario, inquilino o proyecto se recupera hacia el contexto de otro porque faltaban o eran incorrectos los filtros de ámbito — un fallo de privacidad y de corrección a la vez.", "Para compensar una mala clasificación, los equipos inyectan muchas memorias, rellenando la ventana con tokens marginales y degradando el mismo razonamiento que la memoria debía sostener." ], "lessons": [ "La calidad se decide cuando eliges qué recordar. Un almacén pequeño, limpio y deduplicado recupera mucho mejor que uno grande y ruidoso.", "Unas pocas memorias correctas superan a muchas poco relacionadas. Ajusta por relevancia y clasifica con rigor en lugar de maximizar cuánto inyectas.", "Almacena metadatos y ofrece formas de ver, editar, expirar y borrar memorias. Es esencial para depurar, generar confianza y cumplir las obligaciones de privacidad.", "Los hechos se vuelven obsoletos y se contradicen. Construye consolidación, reemplazo y expiración pronto; adaptarlos sobre un almacén grande y contaminado es doloroso." ], "faqs": [ { "q": "¿En qué se diferencia del almacenamiento en caché semántico?", "a": "El caché semántico almacena y reproduce respuestas completas para evitar recomputar solicitudes similares. La memoria a largo plazo almacena hechos, preferencias y resultados duraderos, y luego los recompone en razonamiento nuevo para cada tarea. Uno reutiliza salidas; la otra recuerda estado." }, { "q": "¿Qué debe recordar realmente el agente?", "a": "Señal estable y reutilizable: preferencias del usuario, decisiones y compromisos, resultados de tareas previas y procedimientos recurrentes. Evita la charla transitoria y cualquier cosa que no puedas justificar retener. Escribir menos pero escribir bien es lo que hace precisa la recuperación posterior." }, { "q": "¿Cómo se manejan la PII y la privacidad?", "a": "Trata el almacén como datos gobernados: aplica el ámbito para que las memorias nunca crucen entre usuarios o inquilinos, minimiza lo que persistes, admite consentimiento y borrado, y define controles de retención y de acceso. La inspeccionabilidad y una política de expiración son parte del cumplimiento de estas obligaciones." } ] }, "pt": { "name": "Memória de longo prazo", "summary": "Dá a um agente memória persistente entre sessões para que ele lembre fatos, preferências do usuário e resultados anteriores além de uma única janela de contexto. Um caminho de escrita decide o que armazenar, resume e remove duplicatas; um caminho de leitura recupera apenas as memórias relevantes para o contexto quando preciso. Diferente do cache semântico, que armazena respostas inteiras para evitar recomputar, a memória de longo prazo guarda fatos e estado duradouros e os recompõe em raciocínio novo a cada vez.", "problem": "A janela de contexto é finita e reinicia entre sessões. Um agente que só enxerga a conversa atual esquece as preferências declaradas pelo usuário, as decisões tomadas na semana passada e o resultado de tarefas anteriores. Colocar todo o histórico em cada prompt é inviável a partir de certa escala e degrada o raciocínio à medida que a janela se enche de tokens de baixo valor. As equipes precisam de uma forma de persistir o pequeno conjunto de fatos que importam e de trazê-los com precisão quando são relevantes.", "context": "Use isto quando um agente atende os mesmos usuários ou trabalha repetidamente nas mesmas tarefas de longa duração: assistentes que aprendem preferências, agentes de suporte que acompanham o histórico de um cliente, agentes de programação que lembram as convenções de um projeto ou fluxos de várias etapas que se estendem por dias. Pressupõe que você consegue armazenar dados fora do modelo (um armazenamento vetorial, um banco de dados ou um framework de memória) e que controla tanto quando as memórias são escritas quanto como são recuperadas para o prompt.", "solution": [ "Separe o caminho de escrita do caminho de leitura. No caminho de escrita, após concluir um turno ou tarefa, uma etapa de extração decide o que vale a pena lembrar: fatos estáveis, preferências, compromissos e resultados — não conversa passageira. As memórias candidatas são resumidas em afirmações compactas e autocontidas, comparadas com as memórias existentes para remover duplicatas e detectar contradições, e gravadas em um armazenamento com metadados: um tipo de memória, um carimbo de tempo, uma fonte e o usuário ou escopo a que pertencem. O objetivo é escrever menos, mas escrever bem; memórias ruidosas envenenam a recuperação posterior.\n\nNo caminho de leitura, antes de o agente raciocinar, você recupera as memórias candidatas relevantes para a tarefa atual — geralmente por similaridade semântica mais filtros de escopo e recência —, as classifica e injeta apenas as poucas melhores no contexto. Trate a recuperação como um problema de precisão: um punhado de memórias corretas vale mais que um conjunto grande e pouco relacionado. Distinga os tipos de memória para que a recuperação seja direcionada: episódica (o que aconteceu), semântica (fatos e preferências duradouros) e procedimental (como executar uma tarefa recorrente). Consolide e expire as memórias periodicamente para que o armazenamento permaneça pequeno, atual e livre de contradições." ], "components": [ "Extrator de memórias (caminho de escrita)", "Verificação de duplicatas e contradições", "Armazenamento de memórias", "Recuperador (caminho de leitura)", "Montador de contexto", "Tarefa de consolidação e expiração" ], "benefits": [ "O agente lembra preferências, decisões e resultados de sessões anteriores, então os usuários não precisam repetir o contexto e o agente se comporta de forma consistente ao longo do tempo.", "Recuperar algumas memórias relevantes mantém a janela focada em tokens de alto valor em vez de despejar todo o histórico, o que preserva a qualidade do raciocínio e reduz o custo.", "À medida que fatos e preferências estáveis se acumulam, o agente adapta as respostas com mais precisão a cada interação sem retreinar o modelo.", "Como as memórias ficam em um armazenamento externo com metadados, você pode inspecionar, corrigir, exportar e excluir o que o agente sabe — importante para confiança e conformidade." ], "risks": [ "Sem consolidação e expiração, o armazenamento acumula fatos desatualizados e afirmações conflitantes, e o agente age com confiança sobre o errado.", "Persistir dados do usuário gera obrigações de retenção, consentimento e controle de acesso; as memórias podem vazar informações sensíveis entre sessões ou usuários se o escopo não for aplicado.", "Baixa precisão injeta memórias irrelevantes ou erradas que desorientam o raciocínio; baixa cobertura descarta em silêncio a memória que importava, dificultando o diagnóstico das falhas.", "Escrever em excesso infla o armazenamento, torna a recuperação mais lenta, eleva custos de armazenamento e de embeddings e dilui o sinal do qual uma boa recuperação depende." ], "whenNot": [ "Se as sessões são independentes e nada precisa ser carregado adiante, a memória persistente adiciona complexidade, custo e superfície de privacidade sem benefício.", "Quando o objetivo é reutilizar uma resposta anterior para uma consulta repetida, o cache semântico é a ferramenta certa; a memória de longo prazo serve para lembrar fatos e estado, não para armazenar saídas em cache.", "Onde a regulação ou a política proíbe reter dados do usuário, não persista memórias; apoie-se no contexto da sessão ou em um armazenamento explícito e delimitado que o usuário controle." ], "examples": [ "Entre sessões ele lembra o tom, os formatos, os contatos recorrentes e as instruções permanentes, recuperando as poucas que se aplicam ao pedido atual em vez de perguntar de novo.", "A cada contato ele recupera os problemas anteriores do cliente, seus direitos e as resoluções delimitadas àquela conta, de modo que continua em vez de reiniciar a conversa.", "Armazena memórias procedimentais — comandos de build, regras de nomenclatura, preferências de revisão — e as recupera ao trabalhar no mesmo repositório ao longo de muitas sessões." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "O agente persiste arquivos de memória de workspace e rastros por sessão para continuidade entre turnos e entre sessões, com um plugin de recall semântico disponível sob demanda.", "technology": "Arquivos de memória de workspace (MEMORY.md, IDENTITY.md, SOUL.md, USER.md, HEARTBEAT.md), ids de sessão persistentes e eventos de ciclo de vida, e um plugin de memória ativa (memory_search/get/recall).", "load": "134 arquivos de sessão persistidos na janela de 57 dias; recall semântico invocado uma vez.", "results": "A continuidade se manteve em 134 sessões persistidas por 57 dias por meio de memória estrutural de workspace; o recall semântico explícito quase não foi necessário (uma chamada) nesta carga autônoma. Implantação local-first de operador único." }, "kpis": [ { "metric": "Precisão de recuperação das memórias injetadas", "note": "Das memórias colocadas no contexto, a parcela que era de fato relevante. É a métrica que mais diretamente governa a qualidade da resposta; o bom é quando o conjunto injetado está quase todo no tema, com memórias irrelevantes raras." }, { "metric": "Cobertura de recuperação em tarefas dependentes de memória", "note": "Em tarefas que exigem um fato armazenado conhecido, com que frequência esse fato é de fato recuperado. O bom é quando a memória certa aparece de forma confiável; falhas persistentes apontam lacunas de extração ou de indexação." }, { "metric": "Tamanho do armazenamento de memórias e taxa de crescimento", "note": "Total de memórias e a que velocidade se acumulam por usuário ativo. O bom é quando o crescimento acompanha fatos duradouros genuinamente novos, não uma subida sem limite — uma curva descontrolada sinaliza escrita excessiva." }, { "metric": "Taxa de obsolescência e contradição", "note": "Parcela das memórias recuperadas que estão desatualizadas ou conflitam com uma verdade mais nova. O bom é uma taxa baixa e estável, evidência de que a consolidação e a expiração acompanham o ritmo da mudança." } ], "failureModes": [ "Escrever tudo transforma o armazenamento em ruído; a recuperação então expõe memórias de baixo valor ou erradas. Corrija elevando o critério do que é escrito e revisando a qualidade da extração.", "Um fato antigo é recuperado e usado depois que a verdade mudou, sem sinal de que está desatualizado. Mitigue com carimbos de tempo, classificação ponderada por recência e substituição explícita na escrita.", "Uma memória de um usuário, inquilino ou projeto é recuperada para o contexto de outro porque os filtros de escopo faltavam ou estavam errados — uma falha de privacidade e de correção ao mesmo tempo.", "Para compensar uma classificação ruim, as equipes injetam muitas memórias, reenchendo a janela com tokens marginais e degradando justamente o raciocínio que a memória deveria sustentar." ], "lessons": [ "A qualidade é decidida quando você escolhe o que lembrar. Um armazenamento pequeno, limpo e sem duplicatas recupera muito melhor que um grande e ruidoso.", "Algumas memórias corretas superam muitas pouco relacionadas. Ajuste por relevância e classifique com rigor em vez de maximizar quanto você injeta.", "Armazene metadados e ofereça formas de ver, editar, expirar e excluir memórias. Isso é essencial para depurar, gerar confiança e cumprir obrigações de privacidade.", "Fatos ficam obsoletos e se contradizem. Construa consolidação, substituição e expiração cedo; adaptá-las a um armazenamento grande e poluído é doloroso." ], "faqs": [ { "q": "Como isso difere do cache semântico?", "a": "O cache semântico armazena e reproduz respostas inteiras para evitar recomputar solicitações semelhantes. A memória de longo prazo armazena fatos, preferências e resultados duradouros e depois os recompõe em raciocínio novo para cada tarefa. Um reutiliza saídas; a outra lembra estado." }, { "q": "O que o agente deve de fato lembrar?", "a": "Sinal estável e reutilizável: preferências do usuário, decisões e compromissos, resultados de tarefas anteriores e procedimentos recorrentes. Evite conversa passageira e qualquer coisa que você não consiga justificar reter. Escrever menos, mas escrever bem, é o que torna a recuperação posterior precisa." }, { "q": "Como lidar com PII e privacidade?", "a": "Trate o armazenamento como dados governados: aplique o escopo para que as memórias nunca cruzem entre usuários ou inquilinos, minimize o que você persiste, dê suporte a consentimento e exclusão, e defina controles de retenção e de acesso. A inspecionabilidade e uma política de expiração fazem parte do cumprimento dessas obrigações." } ] } } }, { "slug": "orchestrator-workers", "category": "orchestration", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/orchestrator-workers", "api": "https://santismm.com/api/patterns/orchestrator-workers", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "LangGraph", "CrewAI", "OpenAI Agents SDK", "Model Context Protocol (MCP)" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "routing", "parallelization", "evaluator-optimizer" ], "locales": { "en": { "name": "Orchestrator-Workers", "summary": "An orchestrator LLM dynamically breaks a task into subtasks, delegates each to a worker LLM, and synthesizes the results. Unlike fixed parallelization, the orchestrator decides the subtasks at runtime — making it suited to complex tasks whose decomposition is not known in advance.", "problem": "Some tasks are too complex for a single call and cannot be decomposed up front, because the needed subtasks depend on the input.", "context": "Use orchestrator-workers when a task needs dynamic decomposition — the number and nature of subtasks vary by input — and a coordinating model can plan and integrate the work.", "solution": [ "A lead (orchestrator) model analyzes the task, decides which subtasks are needed, and delegates each to a worker model (often specialized). It then collects and synthesizes the workers' outputs into a final result.", "It is the agentic generalization of parallelization: the decomposition is decided at runtime rather than hard-coded, which adds flexibility at the cost of more coordination and unpredictability." ], "components": [ "Orchestrator (lead) model", "Worker models", "Delegation logic", "Synthesizer", "Shared state / tools" ], "benefits": [ "Handles complex tasks with dynamic decomposition.", "Workers can be specialized per subtask.", "Scales to varied inputs without hard-coded steps." ], "risks": [ "Coordination overhead, latency and token cost.", "Harder to predict and debug than fixed workflows.", "The orchestrator can mis-plan or loop without limits." ], "whenNot": [ "When the decomposition is known in advance — use chaining or fixed parallelization.", "For simple tasks a single call handles.", "When predictability and tight cost control are paramount." ], "examples": [ "A coding task where the lead decides which files to change and delegates edits.", "A research task split into sub-questions, each researched then synthesized.", "A complex report assembled from dynamically chosen sections." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "Scheduled work runs in isolated, one-shot worker sessions forked from the parent, with capability scoping and child/depth limits.", "technology": "Cron isolated-agent runtime, session forking (forkSessionFromParent), a subagent lane and registry, and per-agent child/depth limits.", "load": "57 cron-isolated worker sessions over the window (the explicit sessions.spawn tool was not exercised).", "results": "57 isolated worker sessions ran without cross-session interference; forked-session isolation was the dominant worker pattern, while the explicit spawn tool stayed unused in this window. Single-operator local-first deployment." }, "kpis": [ { "metric": "End-to-end task completion rate", "note": "Share of orchestrated jobs that finish correctly across all sub-tasks; the orchestrator owns the whole outcome." }, { "metric": "Worker fan-out & cost", "note": "Number of worker calls per job and their combined token cost; orchestration can explode spend if decomposition is sloppy." }, { "metric": "Critical-path latency", "note": "Wall-clock of the longest dependent chain, not the sum of workers — this bounds responsiveness." }, { "metric": "Sub-task error rate", "note": "How often individual workers fail or return unusable results, driving retries and recovery." } ], "failureModes": [ "Bad decomposition: the orchestrator splits the task wrongly, so correct workers still produce a wrong whole.", "Context loss between orchestrator and workers, causing inconsistent or contradictory partial results.", "Cost blow-up from spawning too many workers or deep nesting without budget limits.", "Single point of failure: if the orchestrator misjudges, the entire job fails despite healthy workers." ], "lessons": [ "Invest in the decomposition logic — most failures trace back to how the work was split, not the workers.", "Pass workers the minimum context they need, explicitly, to avoid drift and contradictions.", "Set a budget and depth cap; orchestration without limits is where agent cost spirals.", "Make the orchestrator's plan inspectable so failures can be traced to a specific sub-task." ], "faqs": [ { "q": "How is this different from parallelization?", "a": "Parallelization uses a fixed, predefined split. Orchestrator-workers decides the subtasks dynamically at runtime, so it handles tasks whose shape varies by input." }, { "q": "Is this a multi-agent system?", "a": "Yes — it is a common multi-agent pattern. Use it only when a task genuinely benefits from dynamic, separable subtasks." }, { "q": "How do I keep it from running away?", "a": "Set budgets, step limits and stop conditions, and add observability so you can see and bound the orchestrator's planning." } ] }, "es": { "name": "Orquestador-Trabajadores (Orchestrator-Workers)", "summary": "Un LLM orquestador descompone dinámicamente una tarea en subtareas, delega cada una a un LLM trabajador y sintetiza los resultados. A diferencia de la paralelización fija, el orquestador decide las subtareas en tiempo de ejecución, lo que lo hace adecuado para tareas complejas cuya descomposición no se conoce de antemano.", "problem": "Algunas tareas son demasiado complejas para una sola llamada y no se pueden descomponer de antemano, porque las subtareas necesarias dependen de la entrada.", "context": "Usa orquestador-trabajadores cuando una tarea necesita descomposición dinámica —el número y la naturaleza de las subtareas varían según la entrada— y un modelo coordinador puede planificar e integrar el trabajo.", "solution": [ "Un modelo líder (orquestador) analiza la tarea, decide qué subtareas hacen falta y delega cada una a un modelo trabajador (a menudo especializado). Luego recoge y sintetiza las salidas de los trabajadores en un resultado final.", "Es la generalización agéntica de la paralelización: la descomposición se decide en tiempo de ejecución en vez de estar fijada, lo que añade flexibilidad a costa de más coordinación e imprevisibilidad." ], "components": [ "Modelo orquestador (líder)", "Modelos trabajadores", "Lógica de delegación", "Sintetizador", "Estado / herramientas compartidos" ], "benefits": [ "Maneja tareas complejas con descomposición dinámica.", "Los trabajadores pueden especializarse por subtarea.", "Escala a entradas variadas sin pasos fijados." ], "risks": [ "Sobrecarga de coordinación, latencia y coste de tokens.", "Más difícil de predecir y depurar que los flujos fijos.", "El orquestador puede planificar mal o entrar en bucle sin límites." ], "whenNot": [ "Cuando la descomposición se conoce de antemano: usa encadenamiento o paralelización fija.", "Para tareas simples que resuelve una sola llamada.", "Cuando la previsibilidad y el control estricto de coste son prioritarios." ], "examples": [ "Una tarea de programación donde el líder decide qué ficheros cambiar y delega las ediciones.", "Una investigación dividida en sub-preguntas, cada una investigada y luego sintetizada.", "Un informe complejo ensamblado a partir de secciones elegidas dinámicamente." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "El trabajo programado corre en sesiones worker aisladas y de un solo uso, bifurcadas del padre, con acotado de capacidades y límites de hijos/profundidad.", "technology": "Runtime de agente aislado por cron, bifurcación de sesión (forkSessionFromParent), un carril y registro de subagentes y límites de hijos/profundidad por agente.", "load": "57 sesiones worker aisladas por cron en la ventana (la herramienta explícita sessions.spawn no se ejerció).", "results": "57 sesiones worker aisladas corrieron sin interferencia entre sesiones; el aislamiento por sesión bifurcada fue el patrón worker dominante, mientras la herramienta de spawn explícito quedó sin uso en esta ventana. Despliegue local-first mono-operador." }, "kpis": [ { "metric": "Tasa de finalización de extremo a extremo", "note": "Proporción de trabajos orquestados que terminan correctamente en todas las subtareas; el orquestador es dueño del resultado completo." }, { "metric": "Fan-out de workers y coste", "note": "Número de llamadas a workers por trabajo y su coste combinado en tokens; la orquestación puede disparar el gasto si la descomposición es descuidada." }, { "metric": "Latencia de ruta crítica", "note": "Tiempo de la cadena dependiente más larga, no la suma de workers; esto acota la capacidad de respuesta." }, { "metric": "Tasa de error de subtareas", "note": "Con qué frecuencia los workers individuales fallan o devuelven resultados inservibles, provocando reintentos y recuperación." } ], "failureModes": [ "Mala descomposición: el orquestador divide mal la tarea, así que workers correctos producen un todo incorrecto.", "Pérdida de contexto entre orquestador y workers, causando resultados parciales inconsistentes o contradictorios.", "Explosión de coste por generar demasiados workers o anidamiento profundo sin límites de presupuesto.", "Punto único de fallo: si el orquestador se equivoca, todo el trabajo falla pese a workers sanos." ], "lessons": [ "Invierte en la lógica de descomposición: la mayoría de fallos se remontan a cómo se dividió el trabajo, no a los workers.", "Pasa a los workers el mínimo contexto necesario, de forma explícita, para evitar deriva y contradicciones.", "Fija un presupuesto y un tope de profundidad; la orquestación sin límites es donde se dispara el coste.", "Haz inspeccionable el plan del orquestador para rastrear fallos hasta una subtarea concreta." ], "faqs": [ { "q": "¿En qué se diferencia de la paralelización?", "a": "La paralelización usa una división fija predefinida. Orquestador-trabajadores decide las subtareas dinámicamente en ejecución, así maneja tareas cuya forma varía según la entrada." }, { "q": "¿Es un sistema multiagente?", "a": "Sí, es un patrón multiagente común. Úsalo solo cuando una tarea se beneficie realmente de subtareas dinámicas y separables." }, { "q": "¿Cómo evito que se descontrole?", "a": "Fija presupuestos, límites de pasos y condiciones de parada, y añade observabilidad para ver y acotar la planificación del orquestador." } ] }, "pt": { "name": "Orquestrador-Trabalhadores (Orchestrator-Workers)", "summary": "Um LLM orquestrador decompõe dinamicamente uma tarefa em subtarefas, delega cada uma a um LLM trabalhador e sintetiza os resultados. Diferentemente da paralelização fixa, o orquestrador decide as subtarefas em tempo de execução, o que o torna adequado para tarefas complexas cuja decomposição não é conhecida de antemão.", "problem": "Algumas tarefas são complexas demais para uma única chamada e não podem ser decompostas de antemão, porque as subtarefas necessárias dependem da entrada.", "context": "Use orquestrador-trabalhadores quando uma tarefa precisa de decomposição dinâmica — o número e a natureza das subtarefas variam conforme a entrada — e um modelo coordenador pode planejar e integrar o trabalho.", "solution": [ "Um modelo líder (orquestrador) analisa a tarefa, decide quais subtarefas são necessárias e delega cada uma a um modelo trabalhador (muitas vezes especializado). Depois coleta e sintetiza as saídas dos trabalhadores num resultado final.", "É a generalização agêntica da paralelização: a decomposição é decidida em tempo de execução em vez de fixada, o que adiciona flexibilidade ao custo de mais coordenação e imprevisibilidade." ], "components": [ "Modelo orquestrador (líder)", "Modelos trabalhadores", "Lógica de delegação", "Sintetizador", "Estado / ferramentas compartilhados" ], "benefits": [ "Lida com tarefas complexas com decomposição dinâmica.", "Os trabalhadores podem se especializar por subtarefa.", "Escala para entradas variadas sem passos fixados." ], "risks": [ "Sobrecarga de coordenação, latência e custo de tokens.", "Mais difícil de prever e depurar que os fluxos fixos.", "O orquestrador pode planejar mal ou entrar em laço sem limites." ], "whenNot": [ "Quando a decomposição é conhecida de antemão: use encadeamento ou paralelização fixa.", "Para tarefas simples que uma única chamada resolve.", "Quando a previsibilidade e o controle estrito de custo são prioritários." ], "examples": [ "Uma tarefa de programação em que o líder decide quais arquivos mudar e delega as edições.", "Uma pesquisa dividida em subperguntas, cada uma pesquisada e depois sintetizada.", "Um relatório complexo montado a partir de seções escolhidas dinamicamente." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "O trabalho agendado roda em sessões worker isoladas e de uso único, bifurcadas do pai, com escopo de capacidades e limites de filhos/profundidade.", "technology": "Runtime de agente isolado por cron, bifurcação de sessão (forkSessionFromParent), uma faixa e registro de subagentes e limites de filhos/profundidade por agente.", "load": "57 sessões worker isoladas por cron na janela (a ferramenta explícita sessions.spawn não foi exercida).", "results": "57 sessões worker isoladas rodaram sem interferência entre sessões; o isolamento por sessão bifurcada foi o padrão worker dominante, enquanto a ferramenta de spawn explícito ficou sem uso nesta janela. Implantação local-first de operador único." }, "kpis": [ { "metric": "Taxa de conclusão ponta a ponta", "note": "Proporção de trabalhos orquestrados que terminam corretamente em todas as subtarefas; o orquestrador é dono do resultado completo." }, { "metric": "Fan-out de workers e custo", "note": "Número de chamadas a workers por trabalho e seu custo combinado em tokens; a orquestração pode disparar o gasto se a decomposição for descuidada." }, { "metric": "Latência do caminho crítico", "note": "Tempo da cadeia dependente mais longa, não a soma dos workers; isso limita a capacidade de resposta." }, { "metric": "Taxa de erro de subtarefas", "note": "Com que frequência os workers individuais falham ou devolvem resultados inúteis, provocando retentativas e recuperação." } ], "failureModes": [ "Má decomposição: o orquestrador divide a tarefa errado, então workers corretos produzem um todo incorreto.", "Perda de contexto entre orquestrador e workers, causando resultados parciais inconsistentes ou contraditórios.", "Explosão de custo por gerar workers demais ou aninhamento profundo sem limites de orçamento.", "Ponto único de falha: se o orquestrador erra, todo o trabalho falha apesar de workers saudáveis." ], "lessons": [ "Invista na lógica de decomposição: a maioria das falhas remonta a como o trabalho foi dividido, não aos workers.", "Passe aos workers o mínimo de contexto necessário, de forma explícita, para evitar deriva e contradições.", "Defina um orçamento e um teto de profundidade; a orquestração sem limites é onde o custo dispara.", "Torne o plano do orquestrador inspecionável para rastrear falhas até uma subtarefa concreta." ], "faqs": [ { "q": "Como difere da paralelização?", "a": "A paralelização usa uma divisão fixa predefinida. Orquestrador-trabalhadores decide as subtarefas dinamicamente em execução, então lida com tarefas cuja forma varia conforme a entrada." }, { "q": "É um sistema multiagente?", "a": "Sim, é um padrão multiagente comum. Use-o só quando uma tarefa realmente se beneficiar de subtarefas dinâmicas e separáveis." }, { "q": "Como evito que descontrole?", "a": "Defina orçamentos, limites de passos e condições de parada, e adicione observabilidade para ver e limitar o planejamento do orquestrador." } ] } } }, { "slug": "parallelization", "category": "orchestration", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/parallelization", "api": "https://santismm.com/api/patterns/parallelization", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation" ] }, "technologies": [ "LangGraph", "Async runtimes", "OpenAI Agents SDK", "Map-reduce frameworks" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "prompt-chaining", "orchestrator-workers", "evaluator-optimizer" ], "locales": { "en": { "name": "Parallelization", "summary": "Parallelization runs multiple LLM calls at the same time and aggregates the results. Two flavors: sectioning (split a task into independent subtasks run in parallel) and voting (run the same task several times to improve reliability or coverage). It cuts latency and can raise quality.", "problem": "Running independent subtasks one after another wastes time, and a single sample of a hard task can be unreliable.", "context": "Use parallelization when subtasks are independent (sectioning), or when multiple attempts at the same task improve confidence or coverage (voting).", "solution": [ "Sectioning: split the work into independent pieces, run them concurrently, and combine the outputs. Voting: run the same prompt multiple times (or with variations) and aggregate by majority, union or a judge.", "Both reduce wall-clock time versus sequential execution; voting additionally trades extra cost for higher reliability on tasks where a single sample is risky." ], "components": [ "Task splitter", "Concurrent workers", "Aggregator (merge / vote / judge)" ], "benefits": [ "Lower latency by running calls concurrently.", "Voting improves reliability and coverage.", "Each parallel call stays simple and focused." ], "risks": [ "Voting multiplies token cost.", "Aggregation logic can be tricky to get right.", "Subtasks assumed independent may actually interact." ], "whenNot": [ "When subtasks depend on each other's output — chain them.", "When cost is tight and a single call suffices.", "When results cannot be aggregated meaningfully." ], "examples": [ "Summarizing many documents at once, then merging the summaries.", "Running a safety check in parallel with the main response.", "Sampling an answer several times and taking the majority." ], "kpis": [ { "metric": "Latency reduction vs. sequential", "note": "Wall-clock saved by running calls concurrently; the whole point of the pattern." }, { "metric": "Aggregation quality", "note": "Whether merging the parallel outputs preserves correctness — the hard part is the join, not the fan-out." }, { "metric": "Concurrency cost", "note": "Total tokens across all parallel branches; you trade money for speed, so watch the multiplier." }, { "metric": "Rate-limit / throttle rate", "note": "How often parallel calls hit provider rate limits, which silently serializes or fails them." } ], "failureModes": [ "Aggregation errors: parallel results are correct individually but combined wrongly (double-counting, contradictions).", "Rate limiting turns intended parallelism back into slow, serialized calls.", "Cost surprise: N parallel branches cost N× even when only one result is used.", "Partial failure handling: one branch fails and the aggregator either blocks or silently drops it." ], "lessons": [ "Design the aggregation step first — combining results well is harder than splitting the work.", "Respect provider rate limits with batching or backoff, or parallelism evaporates.", "Only parallelize independent sub-tasks; dependencies force a sequence anyway.", "Decide explicitly how partial failures are handled before they happen in production." ], "faqs": [ { "q": "What is the difference between sectioning and voting?", "a": "Sectioning splits one task into different independent subtasks; voting runs the same task multiple times to aggregate for reliability." }, { "q": "Does voting always improve quality?", "a": "Often, on tasks where samples vary, but it multiplies cost. Reserve it for high-stakes steps where a single sample is risky." }, { "q": "How do I combine parallel results?", "a": "Depending on the case: concatenate sections, take a majority vote, union the findings, or use a judge model to synthesize." } ] }, "es": { "name": "Paralelización (Parallelization)", "summary": "La paralelización ejecuta varias llamadas al LLM a la vez y agrega los resultados. Dos variantes: seccionado (dividir una tarea en subtareas independientes en paralelo) y votación (ejecutar la misma tarea varias veces para mejorar fiabilidad o cobertura). Reduce la latencia y puede subir la calidad.", "problem": "Ejecutar subtareas independientes una tras otra desperdicia tiempo, y una sola muestra de una tarea difícil puede ser poco fiable.", "context": "Usa la paralelización cuando las subtareas son independientes (seccionado), o cuando varios intentos de la misma tarea mejoran la confianza o cobertura (votación).", "solution": [ "Seccionado: divide el trabajo en piezas independientes, ejecútalas en paralelo y combina las salidas. Votación: ejecuta el mismo prompt varias veces (o con variaciones) y agrega por mayoría, unión o un juez.", "Ambas reducen el tiempo real frente a la ejecución secuencial; la votación además cambia coste extra por mayor fiabilidad en tareas donde una sola muestra es arriesgada." ], "components": [ "Divisor de tareas", "Trabajadores concurrentes", "Agregador (fusión / voto / juez)" ], "benefits": [ "Menor latencia al ejecutar llamadas en concurrencia.", "La votación mejora la fiabilidad y la cobertura.", "Cada llamada paralela se mantiene simple y enfocada." ], "risks": [ "La votación multiplica el coste de tokens.", "La lógica de agregación puede ser difícil de acertar.", "Subtareas asumidas independientes pueden interactuar en realidad." ], "whenNot": [ "Cuando las subtareas dependen de la salida de otra: encadénalas.", "Cuando el coste es ajustado y basta una sola llamada.", "Cuando los resultados no se pueden agregar de forma significativa." ], "examples": [ "Resumir muchos documentos a la vez y luego fusionar los resúmenes.", "Ejecutar una comprobación de seguridad en paralelo con la respuesta principal.", "Muestrear una respuesta varias veces y tomar la mayoría." ], "kpis": [ { "metric": "Reducción de latencia vs. secuencial", "note": "Tiempo ahorrado al ejecutar llamadas en paralelo; la razón de ser del patrón." }, { "metric": "Calidad de la agregación", "note": "Si combinar las salidas paralelas preserva la corrección; lo difícil es la unión, no el fan-out." }, { "metric": "Coste de concurrencia", "note": "Tokens totales de todas las ramas paralelas; cambias dinero por velocidad, vigila el multiplicador." }, { "metric": "Tasa de límite de tasa / throttle", "note": "Con qué frecuencia las llamadas paralelas chocan con los límites del proveedor, que las serializa o falla en silencio." } ], "failureModes": [ "Errores de agregación: resultados paralelos correctos por separado pero mal combinados (doble conteo, contradicciones).", "El límite de tasa convierte el paralelismo previsto en llamadas lentas y serializadas.", "Sorpresa de coste: N ramas paralelas cuestan N× aunque solo se use un resultado.", "Manejo de fallo parcial: una rama falla y el agregador o se bloquea o la descarta en silencio." ], "lessons": [ "Diseña primero el paso de agregación: combinar bien los resultados es más difícil que dividir el trabajo.", "Respeta los límites de tasa del proveedor con batching o backoff, o el paralelismo se evapora.", "Paraleliza solo subtareas independientes; las dependencias fuerzan una secuencia de todos modos.", "Decide explícitamente cómo se manejan los fallos parciales antes de que ocurran en producción." ], "faqs": [ { "q": "¿Diferencia entre seccionado y votación?", "a": "El seccionado divide una tarea en subtareas independientes distintas; la votación ejecuta la misma tarea varias veces para agregar por fiabilidad." }, { "q": "¿La votación siempre mejora la calidad?", "a": "A menudo, en tareas donde las muestras varían, pero multiplica el coste. Resérvala para pasos críticos donde una sola muestra es arriesgada." }, { "q": "¿Cómo combino resultados paralelos?", "a": "Según el caso: concatenar secciones, tomar voto mayoritario, unir los hallazgos o usar un modelo juez para sintetizar." } ] }, "pt": { "name": "Paralelização (Parallelization)", "summary": "A paralelização executa várias chamadas ao LLM ao mesmo tempo e agrega os resultados. Duas variantes: seccionamento (dividir uma tarefa em subtarefas independentes em paralelo) e votação (executar a mesma tarefa várias vezes para melhorar confiabilidade ou cobertura). Reduz a latência e pode aumentar a qualidade.", "problem": "Executar subtarefas independentes uma após a outra desperdiça tempo, e uma única amostra de uma tarefa difícil pode ser pouco confiável.", "context": "Use a paralelização quando as subtarefas são independentes (seccionamento), ou quando várias tentativas da mesma tarefa melhoram a confiança ou cobertura (votação).", "solution": [ "Seccionamento: divida o trabalho em peças independentes, execute-as em paralelo e combine as saídas. Votação: execute o mesmo prompt várias vezes (ou com variações) e agregue por maioria, união ou um juiz.", "Ambas reduzem o tempo real frente à execução sequencial; a votação além disso troca custo extra por maior confiabilidade em tarefas em que uma única amostra é arriscada." ], "components": [ "Divisor de tarefas", "Trabalhadores concorrentes", "Agregador (fusão / voto / juiz)" ], "benefits": [ "Menor latência ao executar chamadas em concorrência.", "A votação melhora a confiabilidade e a cobertura.", "Cada chamada paralela se mantém simples e focada." ], "risks": [ "A votação multiplica o custo de tokens.", "A lógica de agregação pode ser difícil de acertar.", "Subtarefas assumidas independentes podem interagir na realidade." ], "whenNot": [ "Quando as subtarefas dependem da saída de outra: encadeie-as.", "Quando o custo é apertado e basta uma única chamada.", "Quando os resultados não podem ser agregados de forma significativa." ], "examples": [ "Resumir muitos documentos ao mesmo tempo e depois fundir os resumos.", "Executar uma verificação de segurança em paralelo com a resposta principal.", "Amostrar uma resposta várias vezes e tomar a maioria." ], "kpis": [ { "metric": "Redução de latência vs. sequencial", "note": "Tempo economizado ao executar chamadas em paralelo; a razão de ser do padrão." }, { "metric": "Qualidade da agregação", "note": "Se combinar as saídas paralelas preserva a correção; o difícil é a junção, não o fan-out." }, { "metric": "Custo de concorrência", "note": "Tokens totais de todas as ramificações paralelas; você troca dinheiro por velocidade, vigie o multiplicador." }, { "metric": "Taxa de rate limit / throttle", "note": "Com que frequência as chamadas paralelas batem nos limites do provedor, que as serializa ou falha em silêncio." } ], "failureModes": [ "Erros de agregação: resultados paralelos corretos isoladamente mas mal combinados (dupla contagem, contradições).", "O rate limit transforma o paralelismo pretendido em chamadas lentas e serializadas.", "Surpresa de custo: N ramificações paralelas custam N× mesmo quando só um resultado é usado.", "Tratamento de falha parcial: uma ramificação falha e o agregador ou bloqueia ou a descarta em silêncio." ], "lessons": [ "Projete primeiro o passo de agregação: combinar bem os resultados é mais difícil que dividir o trabalho.", "Respeite os limites de taxa do provedor com batching ou backoff, ou o paralelismo evapora.", "Paralelize só subtarefas independentes; dependências forçam uma sequência de qualquer forma.", "Decida explicitamente como as falhas parciais são tratadas antes que ocorram em produção." ], "faqs": [ { "q": "Diferença entre seccionamento e votação?", "a": "O seccionamento divide uma tarefa em subtarefas independentes distintas; a votação executa a mesma tarefa várias vezes para agregar por confiabilidade." }, { "q": "A votação sempre melhora a qualidade?", "a": "Muitas vezes, em tarefas em que as amostras variam, mas multiplica o custo. Reserve-a para passos críticos em que uma única amostra é arriscada." }, { "q": "Como combino resultados paralelos?", "a": "Conforme o caso: concatenar seções, tomar voto majoritário, unir os achados ou usar um modelo juiz para sintetizar." } ] } } }, { "slug": "prompt-chaining", "category": "orchestration", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/prompt-chaining", "api": "https://santismm.com/api/patterns/prompt-chaining", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Workflow engines" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "routing", "orchestrator-workers", "evaluator-optimizer" ], "locales": { "en": { "name": "Prompt Chaining", "summary": "Prompt chaining decomposes a task into a fixed sequence of LLM calls, where each step works on the output of the previous one. It trades a little latency for much higher accuracy and control, and is the simplest workflow pattern: use it whenever a task cleanly splits into ordered subtasks.", "problem": "A single prompt asked to do several things at once produces lower-quality, harder-to-control output, and is difficult to debug when it goes wrong.", "context": "Use prompt chaining when a task decomposes into a clear, ordered sequence of subtasks — for example outline, then draft, then edit — and each step benefits from the previous step's result.", "solution": [ "Break the task into discrete steps and run one LLM call per step, passing each output to the next. Optionally add programmatic checks (gates) between steps to validate intermediate results before continuing.", "Because each call has one focused job, prompts are simpler, outputs are more reliable, and failures are localized to a specific step that you can inspect and fix." ], "components": [ "Ordered steps", "Per-step prompt", "Inter-step gates / validation", "State passed between steps" ], "benefits": [ "Higher accuracy by giving each call one focused job.", "Easier to debug — failures localize to a step.", "Validation gates can catch errors between steps." ], "risks": [ "Higher total latency from sequential calls.", "Errors can compound down the chain if not checked.", "Too many steps add cost and brittleness." ], "whenNot": [ "When the task is simple enough for a single call.", "When subtasks are independent — parallelize instead.", "When the path is unknown up front — use an agent loop." ], "examples": [ "Generate an outline, then write each section, then revise for tone.", "Extract structured fields, then validate them, then summarize.", "Translate a document, then check the translation against the source." ], "kpis": [ { "metric": "End-to-end success rate", "note": "Share of chains that produce a correct final result; errors compound across steps." }, { "metric": "Per-step error rate", "note": "Failure rate at each link — a 95%-reliable step chained five times yields ~77% end to end." }, { "metric": "Total latency & cost", "note": "Sum across every call in the chain; more steps mean more of both." }, { "metric": "Recovery rate", "note": "How often a failed intermediate step is caught and corrected rather than silently propagated." } ], "failureModes": [ "Error propagation: a mistake early in the chain corrupts every downstream step.", "Latency and cost accumulation as the chain grows longer.", "Brittle hand-offs when one step's output format doesn't match the next step's expected input.", "Lost context across steps, so later links forget constraints set earlier." ], "lessons": [ "Validate or gate-check between steps so errors are caught before they propagate.", "Keep chains as short as the task allows; every extra step multiplies failure probability.", "Pin the output contract of each step so hand-offs don't break silently.", "Use chaining for genuinely sequential work; parallelize independent steps instead." ], "faqs": [ { "q": "How is prompt chaining different from an agent?", "a": "Prompt chaining follows a fixed, predefined sequence. An agent decides its own steps dynamically. Prefer chaining when the path is known in advance." }, { "q": "When should I add gates between steps?", "a": "Whenever an intermediate result must meet a condition before proceeding — it stops errors from propagating down the chain." }, { "q": "Does chaining increase cost?", "a": "Yes, modestly — more calls mean more tokens and latency — but the gain in reliability usually outweighs it for multi-part tasks." } ] }, "es": { "name": "Encadenamiento de Prompts (Prompt Chaining)", "summary": "El encadenamiento de prompts descompone una tarea en una secuencia fija de llamadas al LLM, donde cada paso trabaja sobre la salida del anterior. Cambia algo de latencia por mucha más precisión y control, y es el patrón de flujo más simple: úsalo cuando una tarea se divide limpiamente en subtareas ordenadas.", "problem": "Un solo prompt al que se le pide hacer varias cosas a la vez produce salidas de menor calidad, más difíciles de controlar y de depurar cuando fallan.", "context": "Usa el encadenamiento cuando una tarea se descompone en una secuencia clara y ordenada de subtareas —por ejemplo esquema, luego borrador, luego edición— y cada paso se beneficia del resultado del anterior.", "solution": [ "Divide la tarea en pasos discretos y ejecuta una llamada al LLM por paso, pasando cada salida a la siguiente. Opcionalmente añade comprobaciones programáticas (gates) entre pasos para validar resultados intermedios antes de continuar.", "Como cada llamada tiene un único trabajo enfocado, los prompts son más simples, las salidas más fiables y los fallos quedan localizados en un paso concreto que puedes inspeccionar y corregir." ], "components": [ "Pasos ordenados", "Prompt por paso", "Gates / validación entre pasos", "Estado pasado entre pasos" ], "benefits": [ "Mayor precisión al dar a cada llamada un único trabajo enfocado.", "Más fácil de depurar: los fallos se localizan en un paso.", "Los gates de validación pueden atrapar errores entre pasos." ], "risks": [ "Mayor latencia total por las llamadas secuenciales.", "Los errores pueden acumularse en la cadena si no se comprueban.", "Demasiados pasos añaden coste y fragilidad." ], "whenNot": [ "Cuando la tarea es lo bastante simple para una sola llamada.", "Cuando las subtareas son independientes: paraleliza en su lugar.", "Cuando el camino no se conoce de antemano: usa un bucle de agente." ], "examples": [ "Generar un esquema, luego escribir cada sección, luego revisar el tono.", "Extraer campos estructurados, luego validarlos, luego resumir.", "Traducir un documento, luego comprobar la traducción contra el original." ], "kpis": [ { "metric": "Tasa de éxito de extremo a extremo", "note": "Proporción de cadenas que producen un resultado final correcto; los errores se acumulan entre pasos." }, { "metric": "Tasa de error por paso", "note": "Fallo en cada eslabón: un paso fiable al 95% encadenado cinco veces da ~77% de extremo a extremo." }, { "metric": "Latencia y coste totales", "note": "Suma de todas las llamadas de la cadena; más pasos significan más de ambos." }, { "metric": "Tasa de recuperación", "note": "Con qué frecuencia un paso intermedio fallido se detecta y corrige en vez de propagarse en silencio." } ], "failureModes": [ "Propagación de errores: un fallo temprano en la cadena corrompe todos los pasos posteriores.", "Acumulación de latencia y coste a medida que la cadena se alarga.", "Transferencias frágiles cuando el formato de salida de un paso no coincide con la entrada esperada del siguiente.", "Pérdida de contexto entre pasos, de modo que eslabones posteriores olvidan restricciones fijadas antes." ], "lessons": [ "Valida o verifica entre pasos para detectar errores antes de que se propaguen.", "Mantén las cadenas tan cortas como permita la tarea; cada paso extra multiplica la probabilidad de fallo.", "Fija el contrato de salida de cada paso para que las transferencias no se rompan en silencio.", "Usa el encadenamiento para trabajo genuinamente secuencial; paraleliza los pasos independientes." ], "faqs": [ { "q": "¿En qué se diferencia del agente?", "a": "El encadenamiento sigue una secuencia fija predefinida. Un agente decide sus propios pasos de forma dinámica. Prefiere el encadenamiento cuando el camino se conoce de antemano." }, { "q": "¿Cuándo debo añadir gates entre pasos?", "a": "Siempre que un resultado intermedio deba cumplir una condición antes de seguir: evita que los errores se propaguen por la cadena." }, { "q": "¿El encadenamiento aumenta el coste?", "a": "Sí, moderadamente —más llamadas significan más tokens y latencia— pero la ganancia en fiabilidad suele compensarlo en tareas de varias partes." } ] }, "pt": { "name": "Encadeamento de Prompts (Prompt Chaining)", "summary": "O encadeamento de prompts decompõe uma tarefa numa sequência fixa de chamadas ao LLM, em que cada passo trabalha sobre a saída do anterior. Troca um pouco de latência por muito mais precisão e controle, e é o padrão de fluxo mais simples: use-o quando uma tarefa se divide limpamente em subtarefas ordenadas.", "problem": "Um único prompt ao qual se pede fazer várias coisas ao mesmo tempo produz saídas de menor qualidade, mais difíceis de controlar e de depurar quando falham.", "context": "Use o encadeamento quando uma tarefa se decompõe numa sequência clara e ordenada de subtarefas — por exemplo esboço, depois rascunho, depois edição — e cada passo se beneficia do resultado do anterior.", "solution": [ "Divida a tarefa em passos discretos e execute uma chamada ao LLM por passo, passando cada saída à seguinte. Opcionalmente adicione verificações programáticas (gates) entre passos para validar resultados intermediários antes de continuar.", "Como cada chamada tem um único trabalho focado, os prompts são mais simples, as saídas mais confiáveis e as falhas ficam localizadas num passo concreto que você pode inspecionar e corrigir." ], "components": [ "Passos ordenados", "Prompt por passo", "Gates / validação entre passos", "Estado passado entre passos" ], "benefits": [ "Maior precisão ao dar a cada chamada um único trabalho focado.", "Mais fácil de depurar: as falhas se localizam num passo.", "Os gates de validação podem capturar erros entre passos." ], "risks": [ "Maior latência total pelas chamadas sequenciais.", "Os erros podem se acumular na cadeia se não forem verificados.", "Passos demais adicionam custo e fragilidade." ], "whenNot": [ "Quando a tarefa é simples o bastante para uma única chamada.", "Quando as subtarefas são independentes: paralelize em vez disso.", "Quando o caminho não é conhecido de antemão: use um laço de agente." ], "examples": [ "Gerar um esboço, depois escrever cada seção, depois revisar o tom.", "Extrair campos estruturados, depois validá-los, depois resumir.", "Traduzir um documento, depois verificar a tradução contra o original." ], "kpis": [ { "metric": "Taxa de sucesso ponta a ponta", "note": "Proporção de cadeias que produzem um resultado final correto; os erros se acumulam entre passos." }, { "metric": "Taxa de erro por passo", "note": "Falha em cada elo: um passo confiável a 95% encadeado cinco vezes dá ~77% ponta a ponta." }, { "metric": "Latência e custo totais", "note": "Soma de todas as chamadas da cadeia; mais passos significam mais de ambos." }, { "metric": "Taxa de recuperação", "note": "Com que frequência um passo intermediário falho é detectado e corrigido em vez de propagado em silêncio." } ], "failureModes": [ "Propagação de erros: uma falha cedo na cadeia corrompe todos os passos seguintes.", "Acúmulo de latência e custo à medida que a cadeia se alonga.", "Transferências frágeis quando o formato de saída de um passo não coincide com a entrada esperada do seguinte.", "Perda de contexto entre passos, de modo que elos posteriores esquecem restrições fixadas antes." ], "lessons": [ "Valide ou verifique entre passos para detectar erros antes que se propaguem.", "Mantenha as cadeias tão curtas quanto a tarefa permitir; cada passo extra multiplica a probabilidade de falha.", "Fixe o contrato de saída de cada passo para que as transferências não quebrem em silêncio.", "Use o encadeamento para trabalho genuinamente sequencial; paralelize os passos independentes." ], "faqs": [ { "q": "Como difere de um agente?", "a": "O encadeamento segue uma sequência fixa predefinida. Um agente decide seus próprios passos de forma dinâmica. Prefira o encadeamento quando o caminho é conhecido de antemão." }, { "q": "Quando devo adicionar gates entre passos?", "a": "Sempre que um resultado intermediário precise cumprir uma condição antes de prosseguir: evita que os erros se propaguem pela cadeia." }, { "q": "O encadeamento aumenta o custo?", "a": "Sim, moderadamente — mais chamadas significam mais tokens e latência — mas o ganho em confiabilidade costuma compensar em tarefas de várias partes." } ] } } }, { "slug": "recovery-strategy", "category": "reliability", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/recovery-strategy", "api": "https://santismm.com/api/patterns/recovery-strategy", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Retries with backoff", "Circuit breakers", "Checkpointing", "Compensating actions" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" }, { "title": "Google SRE Book — Handling Overload & Cascading Failures", "url": "https://sre.google/sre-book/handling-overload/" } ], "related": [ "reflection", "human-escalation", "evaluator-optimizer" ], "locales": { "en": { "name": "Recovery Strategy", "summary": "Give the agent an explicit plan for when things break. Detect failures by validating outputs and catching tool errors; then retry with adjustment, fall back to an alternative path, roll back partial actions, or escalate. Bound retries to avoid runaway loops and cost, make actions idempotent, and distinguish transient from permanent failures. The goal is graceful degradation instead of crashes or silently wrong results.", "problem": "Agents fail constantly: tools time out, APIs return errors, models emit malformed output, plans hit dead-ends, and multi-step workflows leave partial side effects behind. Without an explicit recovery path, an agent either crashes on the first error or — worse — plows ahead on bad data and silently produces confidently wrong results. Naive retry loops make it worse, hammering a failing dependency, burning tokens, and spinning forever. The hard part is not catching one error; it is deciding what kind of failure it is and what response is safe.", "context": "Use this pattern in any agent that calls external tools, runs multi-step plans, or takes consequential actions where partial completion is possible. It matters most for long-running or autonomous workflows that no human watches in real time, and for actions with side effects (payments, writes, emails) where a blind retry could duplicate work. It assumes you can validate outputs against some contract and that at least some operations can be made idempotent or compensated. It is less relevant for single-shot, read-only, low-stakes prompts.", "solution": [ "Treat recovery as a first-class control loop layered around the agent's normal execution. Every tool call and model output passes through a validation gate: catch exceptions and timeouts, and check outputs against a schema or contract before trusting them. On failure, classify it. Transient failures (timeouts, rate limits, 5xx) get a bounded retry with exponential backoff and jitter, ideally against an idempotent operation so a duplicate request is harmless. Permanent failures (invalid arguments, auth errors, contract violations) skip retries and move straight to an alternative: a different tool, a simpler plan, or a fallback answer.\n\nWhen progress matters, checkpoint state so the agent can resume from the last good step rather than restarting. When a step has already produced side effects and cannot proceed, run compensating actions to roll back — cancel the order, delete the draft, reverse the charge. Wrap the whole loop in hard budgets: maximum attempts, maximum wall-clock time, and a cost ceiling, plus a circuit breaker that stops calling a dependency that keeps failing. When all recovery options are exhausted, escalate cleanly — surface the failure to a human or a supervising agent with enough context to act, rather than guessing." ], "components": [ "Validation gate", "Failure classifier", "Bounded retry with backoff", "Fallback router", "Checkpoint store", "Compensation handler" ], "benefits": [ "The agent produces a partial or fallback result and a clear status instead of crashing or returning confident garbage.", "Hard attempt, time, and cost limits stop runaway retry loops from burning budget on a failing dependency.", "Compensating actions and checkpoints keep external systems and task state coherent when a workflow stops midway.", "When recovery fails, the agent hands off with enough context for a human or supervisor to act, rather than guessing." ], "risks": [ "Aggressive retries against a struggling dependency add load and can turn a brief blip into a cascading outage.", "Retrying a non-idempotent action can double-charge, double-send, or double-write if request keys are not used.", "Over-eager fallbacks can hide systematic failures, so a broken tool looks healthy while quietly degrading every result.", "Rollback logic is often incomplete or itself fails, leaving systems in an inconsistent state that is hard to detect." ], "whenNot": [ "For low-stakes prompts with no side effects and no multi-step plan, a simple retry-or-fail is enough; full recovery machinery is overhead.", "When a failure means the task is genuinely impossible (missing permission, deprecated API), retry and fallback only waste time — fail fast and escalate.", "If a side effect is irreversible and cannot be made idempotent, do not auto-retry across it; require confirmation or human approval instead." ], "examples": [ "A research agent's search tool returns a 503; the agent retries with backoff, succeeds on the third attempt, and continues without crashing the run.", "A code agent generates JSON that fails schema validation; the validation gate rejects it and re-prompts with the error, instead of passing malformed data downstream.", "A booking agent reserves a flight but the hotel step fails permanently; the compensation handler cancels the reservation and escalates rather than leaving a half-booked trip." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "Errors, aborts and timeouts during autonomous turns are absorbed by retry/backoff and a model-fallback chain so the agent keeps running.", "technology": "retryAsync with exponential backoff and jitter, runWithModelFallback, abort propagation, and cron self-protection against refire loops.", "load": "2,942 terminal turns; 52 errors, 126 aborts, 120 timeouts and 31 prompt-errors observed.", "results": "A 1.77% terminal-error rate across 2,942 turns; recovery primitives absorbed transient failures and the deployment held 98.8% session success. Single-operator local-first deployment." }, "kpis": [ { "metric": "Recovery success rate", "note": "Share of failures resolved automatically by retry or fallback without human help; a healthy value is high and stable, with no quiet downward drift." }, { "metric": "Mean attempts per successful task", "note": "How many tries it takes to succeed; watch for creep, which signals a degrading dependency rather than genuine recovery." }, { "metric": "Unbounded-loop / budget-breach rate", "note": "How often runs hit retry, time, or cost ceilings; this should be rare, and spikes mean limits or classification need tuning." }, { "metric": "Compensation completeness", "note": "Fraction of failed multi-step workflows that end in a consistent state; the target is full rollback with no orphaned side effects." } ], "failureModes": [ "Missing or too-high attempt caps let the agent retry a permanent failure forever, burning cost and never making progress.", "Treating a permanent error as transient wastes retries; treating a transient error as permanent gives up too early and triggers needless fallbacks.", "A fallback path returns a plausible but wrong answer with no signal that recovery occurred, so downstream consumers trust bad output.", "The agent fails after a write or external action but before compensation runs, leaving duplicate or dangling records." ], "lessons": [ "The retry/fallback/escalate decision hinges on transient versus permanent; invest in clear classification before tuning backoff curves.", "Idempotency keys turn a risky retry into a safe one; design for it up front rather than bolting on dedup later.", "Hard caps on attempts, time, and cost are non-negotiable; an agent without them will eventually find a way to run forever.", "Log every retry, fallback, and compensation so silent degradation surfaces as a metric instead of a surprise incident." ], "faqs": [ { "q": "How is this different from just adding try/except and a retry loop?", "a": "Try/except handles one error; a recovery strategy decides what kind of failure it is and chooses among retry, fallback, rollback, and escalation under hard budgets. The control logic and idempotency, not the exception handling, are the substance." }, { "q": "How many retries should I allow?", "a": "Few — typically a small fixed cap with exponential backoff and jitter, plus separate time and cost ceilings. The exact number depends on the dependency, but the loop must always terminate, and permanent failures should not be retried at all." }, { "q": "What if an action cannot be undone or made idempotent?", "a": "Do not auto-retry across it. Checkpoint before the irreversible step, and on failure escalate to a human or supervising agent rather than guessing. Irreversibility is a signal to slow down, not to retry harder." } ] }, "es": { "name": "Estrategia de recuperación", "summary": "Da al agente un plan explícito para cuando algo falla. Detecta fallos validando salidas y capturando errores de herramientas; luego reintenta con ajuste, recurre a una ruta alternativa, revierte acciones parciales o escala. Acota los reintentos para evitar bucles y costes descontrolados, haz las acciones idempotentes y distingue fallos transitorios de permanentes. El objetivo es una degradación elegante en lugar de caídas o resultados silenciosamente erróneos.", "problem": "Los agentes fallan constantemente: las herramientas expiran, las API devuelven errores, los modelos emiten salidas mal formadas, los planes llegan a callejones sin salida y los flujos de varios pasos dejan efectos secundarios parciales. Sin una ruta de recuperación explícita, un agente o bien se cae al primer error o — peor — sigue adelante con datos malos y produce en silencio resultados erróneos con aparente seguridad. Los bucles de reintento ingenuos lo empeoran, golpeando una dependencia que falla, quemando tokens y girando sin fin. Lo difícil no es capturar un error; es decidir de qué tipo de fallo se trata y qué respuesta es segura.", "context": "Usa este patrón en cualquier agente que llame a herramientas externas, ejecute planes de varios pasos o realice acciones con consecuencias donde sea posible una finalización parcial. Importa sobre todo en flujos largos o autónomos que ningún humano vigila en tiempo real, y en acciones con efectos secundarios (pagos, escrituras, correos) donde un reintento ciego podría duplicar el trabajo. Supone que puedes validar las salidas contra algún contrato y que al menos algunas operaciones pueden hacerse idempotentes o compensables. Es menos relevante para indicaciones de un solo paso, de solo lectura y de bajo riesgo.", "solution": [ "Trata la recuperación como un bucle de control de primera clase que envuelve la ejecución normal del agente. Cada llamada a herramienta y cada salida del modelo pasa por una puerta de validación: captura excepciones y tiempos de espera, y comprueba las salidas contra un esquema o contrato antes de confiar en ellas. Ante un fallo, clasifícalo. Los fallos transitorios (tiempos de espera, límites de tasa, 5xx) reciben un reintento acotado con retroceso exponencial y jitter, idealmente contra una operación idempotente para que una petición duplicada sea inofensiva. Los fallos permanentes (argumentos inválidos, errores de autenticación, violaciones de contrato) omiten los reintentos y pasan directamente a una alternativa: otra herramienta, un plan más simple o una respuesta de reserva.\n\nCuando el progreso importa, guarda puntos de control del estado para que el agente pueda reanudar desde el último paso correcto en lugar de reiniciar. Cuando un paso ya produjo efectos secundarios y no puede continuar, ejecuta acciones de compensación para revertir: cancela el pedido, elimina el borrador, revierte el cargo. Envuelve todo el bucle en presupuestos estrictos: número máximo de intentos, tiempo máximo de reloj y un techo de coste, además de un cortacircuitos que deje de llamar a una dependencia que sigue fallando. Cuando se agotan todas las opciones de recuperación, escala con limpieza: expón el fallo a un humano o a un agente supervisor con contexto suficiente para actuar, en lugar de adivinar." ], "components": [ "Puerta de validación", "Clasificador de fallos", "Reintento acotado con retroceso", "Enrutador de reserva", "Almacén de puntos de control", "Manejador de compensación" ], "benefits": [ "El agente produce un resultado parcial o de reserva y un estado claro en lugar de caerse o devolver basura con apariencia de seguridad.", "Los límites estrictos de intentos, tiempo y coste detienen los bucles de reintento descontrolados que queman presupuesto en una dependencia que falla.", "Las acciones de compensación y los puntos de control mantienen coherentes los sistemas externos y el estado de la tarea cuando un flujo se detiene a medias.", "Cuando la recuperación falla, el agente delega con contexto suficiente para que un humano o supervisor actúe, en lugar de adivinar." ], "risks": [ "Los reintentos agresivos contra una dependencia que sufre añaden carga y pueden convertir un breve fallo en una caída en cascada.", "Reintentar una acción no idempotente puede cobrar, enviar o escribir por duplicado si no se usan claves de petición.", "Las reservas demasiado ansiosas pueden ocultar fallos sistemáticos, de modo que una herramienta rota parece sana mientras degrada cada resultado en silencio.", "La lógica de reversión suele estar incompleta o fallar ella misma, dejando los sistemas en un estado incoherente difícil de detectar." ], "whenNot": [ "Para indicaciones de bajo riesgo sin efectos secundarios ni plan de varios pasos, basta con reintentar o fallar; toda la maquinaria de recuperación es sobrecarga.", "Cuando un fallo significa que la tarea es realmente imposible (permiso ausente, API obsoleta), reintentar y recurrir a alternativas solo pierde tiempo: falla rápido y escala.", "Si un efecto secundario es irreversible y no puede hacerse idempotente, no reintentes automáticamente sobre él; exige confirmación o aprobación humana en su lugar." ], "examples": [ "La herramienta de búsqueda de un agente de investigación devuelve un 503; el agente reintenta con retroceso, lo logra al tercer intento y continúa sin tumbar la ejecución.", "Un agente de código genera JSON que falla la validación de esquema; la puerta de validación lo rechaza y vuelve a indicar con el error, en lugar de pasar datos mal formados aguas abajo.", "Un agente de reservas reserva un vuelo pero el paso del hotel falla de forma permanente; el manejador de compensación cancela la reserva y escala en lugar de dejar un viaje a medio reservar." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "Los errores, abortos y timeouts en turnos autónomos se absorben con retry/backoff y una cadena de modelo de respaldo para que el agente siga funcionando.", "technology": "retryAsync con backoff exponencial y jitter, runWithModelFallback, propagación de abort y autoprotección de cron contra bucles de re-disparo.", "load": "2.942 turnos terminales; 52 errores, 126 abortos, 120 timeouts y 31 prompt-errors observados.", "results": "Tasa de error terminal del 1,77% sobre 2.942 turnos; las primitivas de recuperación absorbieron los fallos transitorios y el despliegue mantuvo 98,8% de éxito por sesión. Despliegue local-first mono-operador." }, "kpis": [ { "metric": "Tasa de éxito de recuperación", "note": "Proporción de fallos resueltos automáticamente por reintento o reserva sin ayuda humana; un valor sano es alto y estable, sin una caída silenciosa." }, { "metric": "Media de intentos por tarea exitosa", "note": "Cuántos intentos cuesta tener éxito; vigila el aumento gradual, que señala una dependencia que se degrada más que una recuperación genuina." }, { "metric": "Tasa de bucle ilimitado / ruptura de presupuesto", "note": "Con qué frecuencia las ejecuciones alcanzan los techos de reintento, tiempo o coste; debería ser raro, y los picos indican que los límites o la clasificación necesitan ajuste." }, { "metric": "Completitud de la compensación", "note": "Fracción de flujos de varios pasos fallidos que terminan en un estado coherente; el objetivo es una reversión total sin efectos secundarios huérfanos." } ], "failureModes": [ "La ausencia de límites de intentos o límites demasiado altos dejan que el agente reintente un fallo permanente para siempre, quemando coste sin avanzar.", "Tratar un error permanente como transitorio desperdicia reintentos; tratar uno transitorio como permanente se rinde demasiado pronto y dispara reservas innecesarias.", "Una ruta de reserva devuelve una respuesta plausible pero errónea sin señal de que hubo recuperación, así que los consumidores aguas abajo confían en una salida mala.", "El agente falla después de una escritura o acción externa pero antes de que corra la compensación, dejando registros duplicados o colgantes." ], "lessons": [ "La decisión de reintentar/recurrir/escalar depende de transitorio frente a permanente; invierte en una clasificación clara antes de ajustar las curvas de retroceso.", "Las claves de idempotencia convierten un reintento arriesgado en uno seguro; diséñalo desde el principio en lugar de añadir deduplicación después.", "Los límites estrictos de intentos, tiempo y coste son innegociables; un agente sin ellos acabará por encontrar la forma de correr para siempre.", "Registra cada reintento, reserva y compensación para que la degradación silenciosa aflore como una métrica en lugar de un incidente sorpresa." ], "faqs": [ { "q": "¿En qué se diferencia esto de solo añadir try/except y un bucle de reintento?", "a": "Try/except maneja un error; una estrategia de recuperación decide de qué tipo de fallo se trata y elige entre reintento, reserva, reversión y escalado bajo presupuestos estrictos. La lógica de control y la idempotencia, no el manejo de excepciones, son la sustancia." }, { "q": "¿Cuántos reintentos debería permitir?", "a": "Pocos — normalmente un límite fijo pequeño con retroceso exponencial y jitter, más techos separados de tiempo y coste. El número exacto depende de la dependencia, pero el bucle siempre debe terminar, y los fallos permanentes no deberían reintentarse en absoluto." }, { "q": "¿Y si una acción no puede deshacerse ni hacerse idempotente?", "a": "No reintentes automáticamente sobre ella. Guarda un punto de control antes del paso irreversible, y ante un fallo escala a un humano o agente supervisor en lugar de adivinar. La irreversibilidad es una señal para ir más despacio, no para reintentar con más fuerza." } ] }, "pt": { "name": "Estratégia de recuperação", "summary": "Dê ao agente um plano explícito para quando algo falha. Detecte falhas validando saídas e capturando erros de ferramentas; depois reenvie com ajuste, recorra a um caminho alternativo, reverta ações parciais ou escale. Limite as retentativas para evitar laços e custos descontrolados, torne as ações idempotentes e distinga falhas transitórias de permanentes. O objetivo é uma degradação elegante em vez de quedas ou resultados silenciosamente errados.", "problem": "Agentes falham constantemente: ferramentas expiram, APIs retornam erros, modelos emitem saídas malformadas, planos chegam a becos sem saída e fluxos de várias etapas deixam efeitos colaterais parciais. Sem um caminho de recuperação explícito, um agente ou cai no primeiro erro ou — pior — segue em frente com dados ruins e produz, em silêncio, resultados errados com aparente confiança. Laços de retentativa ingênuos pioram tudo, martelando uma dependência que falha, queimando tokens e girando sem fim. O difícil não é capturar um erro; é decidir que tipo de falha é e qual resposta é segura.", "context": "Use este padrão em qualquer agente que chame ferramentas externas, execute planos de várias etapas ou tome ações com consequências em que uma conclusão parcial seja possível. Importa sobretudo em fluxos longos ou autônomos que nenhum humano observa em tempo real, e em ações com efeitos colaterais (pagamentos, escritas, e-mails) em que uma retentativa cega poderia duplicar o trabalho. Pressupõe que você consiga validar as saídas contra algum contrato e que ao menos algumas operações possam ser tornadas idempotentes ou compensáveis. É menos relevante para prompts de uma só etapa, somente leitura e de baixo risco.", "solution": [ "Trate a recuperação como um laço de controle de primeira classe que envolve a execução normal do agente. Cada chamada de ferramenta e cada saída do modelo passa por um portão de validação: capture exceções e tempos esgotados, e verifique as saídas contra um esquema ou contrato antes de confiar nelas. Diante de uma falha, classifique-a. Falhas transitórias (timeouts, limites de taxa, 5xx) recebem uma retentativa limitada com recuo exponencial e jitter, idealmente contra uma operação idempotente para que uma requisição duplicada seja inofensiva. Falhas permanentes (argumentos inválidos, erros de autenticação, violações de contrato) pulam as retentativas e vão direto para uma alternativa: outra ferramenta, um plano mais simples ou uma resposta de reserva.\n\nQuando o progresso importa, salve pontos de verificação do estado para que o agente possa retomar a partir da última etapa boa em vez de recomeçar. Quando uma etapa já produziu efeitos colaterais e não pode prosseguir, execute ações de compensação para reverter: cancele o pedido, exclua o rascunho, estorne a cobrança. Envolva todo o laço em orçamentos rígidos: número máximo de tentativas, tempo máximo de relógio e um teto de custo, além de um disjuntor que pare de chamar uma dependência que continua falhando. Quando todas as opções de recuperação se esgotam, escale de forma limpa: exponha a falha a um humano ou a um agente supervisor com contexto suficiente para agir, em vez de adivinhar." ], "components": [ "Portão de validação", "Classificador de falhas", "Retentativa limitada com recuo", "Roteador de reserva", "Repositório de pontos de verificação", "Manipulador de compensação" ], "benefits": [ "O agente produz um resultado parcial ou de reserva e um status claro em vez de cair ou devolver lixo com aparência de confiança.", "Limites rígidos de tentativas, tempo e custo barram os laços de retentativa descontrolados que queimam orçamento em uma dependência que falha.", "Ações de compensação e pontos de verificação mantêm os sistemas externos e o estado da tarefa coerentes quando um fluxo para no meio.", "Quando a recuperação falha, o agente repassa com contexto suficiente para que um humano ou supervisor aja, em vez de adivinhar." ], "risks": [ "Retentativas agressivas contra uma dependência em sofrimento acrescentam carga e podem transformar uma falha breve em uma queda em cascata.", "Refazer uma ação não idempotente pode cobrar, enviar ou escrever em duplicidade se chaves de requisição não forem usadas.", "Reservas ansiosas demais podem esconder falhas sistemáticas, fazendo uma ferramenta quebrada parecer saudável enquanto degrada cada resultado em silêncio.", "A lógica de reversão costuma estar incompleta ou falhar ela mesma, deixando os sistemas em um estado inconsistente difícil de detectar." ], "whenNot": [ "Para prompts de baixo risco sem efeitos colaterais e sem plano de várias etapas, basta retentar ou falhar; toda a maquinaria de recuperação é sobrecarga.", "Quando uma falha significa que a tarefa é genuinamente impossível (permissão ausente, API obsoleta), retentar e recorrer a alternativas só desperdiça tempo — falhe rápido e escale.", "Se um efeito colateral é irreversível e não pode ser tornado idempotente, não retente automaticamente sobre ele; exija confirmação ou aprovação humana." ], "examples": [ "A ferramenta de busca de um agente de pesquisa retorna um 503; o agente retenta com recuo, consegue na terceira tentativa e continua sem derrubar a execução.", "Um agente de código gera JSON que falha na validação de esquema; o portão de validação o rejeita e refaz o prompt com o erro, em vez de passar dados malformados a jusante.", "Um agente de reservas reserva um voo, mas a etapa do hotel falha de forma permanente; o manipulador de compensação cancela a reserva e escala em vez de deixar uma viagem reservada pela metade." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "Erros, abortos e timeouts em turnos autônomos são absorvidos por retry/backoff e uma cadeia de modelo de fallback para que o agente continue rodando.", "technology": "retryAsync com backoff exponencial e jitter, runWithModelFallback, propagação de abort e autoproteção de cron contra loops de redisparo.", "load": "2.942 turnos terminais; 52 erros, 126 abortos, 120 timeouts e 31 prompt-errors observados.", "results": "Taxa de erro terminal de 1,77% em 2.942 turnos; as primitivas de recuperação absorveram as falhas transitórias e a implantação manteve 98,8% de sucesso por sessão. Implantação local-first de operador único." }, "kpis": [ { "metric": "Taxa de sucesso de recuperação", "note": "Proporção de falhas resolvidas automaticamente por retentativa ou reserva sem ajuda humana; um valor saudável é alto e estável, sem queda silenciosa." }, { "metric": "Média de tentativas por tarefa bem-sucedida", "note": "Quantas tentativas custa ter sucesso; observe o aumento gradual, que sinaliza uma dependência em degradação mais do que recuperação genuína." }, { "metric": "Taxa de laço ilimitado / estouro de orçamento", "note": "Com que frequência as execuções atingem os tetos de retentativa, tempo ou custo; deve ser raro, e picos indicam que limites ou classificação precisam de ajuste." }, { "metric": "Completude da compensação", "note": "Fração de fluxos de várias etapas que falham e terminam em estado consistente; o alvo é reversão total sem efeitos colaterais órfãos." } ], "failureModes": [ "Limites de tentativa ausentes ou altos demais deixam o agente retentar uma falha permanente para sempre, queimando custo sem avançar.", "Tratar um erro permanente como transitório desperdiça retentativas; tratar um transitório como permanente desiste cedo demais e dispara reservas desnecessárias.", "Um caminho de reserva devolve uma resposta plausível mas errada sem sinal de que houve recuperação, então consumidores a jusante confiam em saída ruim.", "O agente falha depois de uma escrita ou ação externa, mas antes de a compensação rodar, deixando registros duplicados ou pendentes." ], "lessons": [ "A decisão de retentar/recorrer/escalar depende de transitório versus permanente; invista em classificação clara antes de ajustar curvas de recuo.", "Chaves de idempotência transformam uma retentativa arriscada em uma segura; projete para isso desde o início em vez de acoplar deduplicação depois.", "Tetos rígidos de tentativas, tempo e custo são inegociáveis; um agente sem eles acabará achando um jeito de rodar para sempre.", "Registre cada retentativa, reserva e compensação para que a degradação silenciosa apareça como métrica em vez de incidente surpresa." ], "faqs": [ { "q": "Como isso difere de apenas adicionar try/except e um laço de retentativa?", "a": "Try/except trata um erro; uma estratégia de recuperação decide que tipo de falha é e escolhe entre retentativa, reserva, reversão e escalada sob orçamentos rígidos. A lógica de controle e a idempotência, não o tratamento de exceções, são a substância." }, { "q": "Quantas retentativas devo permitir?", "a": "Poucas — em geral um limite fixo pequeno com recuo exponencial e jitter, mais tetos separados de tempo e custo. O número exato depende da dependência, mas o laço sempre deve terminar, e falhas permanentes não deveriam ser retentadas de forma alguma." }, { "q": "E se uma ação não puder ser desfeita nem tornada idempotente?", "a": "Não retente automaticamente sobre ela. Salve um ponto de verificação antes da etapa irreversível e, diante de uma falha, escale para um humano ou agente supervisor em vez de adivinhar. A irreversibilidade é um sinal para ir mais devagar, não para retentar com mais força." } ] } } }, { "slug": "reflection", "category": "reliability", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/reflection", "api": "https://santismm.com/api/patterns/reflection", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "LangGraph", "Agent frameworks", "LLM-as-judge" ], "references": [ { "title": "Shinn et al. — Reflexion: Language Agents with Verbal Reinforcement Learning (2023)", "url": "https://arxiv.org/abs/2303.11366" } ], "related": [ "evaluator-optimizer", "prompt-chaining" ], "locales": { "en": { "name": "Reflection", "summary": "Reflection has a model critique its own output and then revise it, using the critique as feedback. It is a lightweight, single-model way to catch mistakes and improve quality on reasoning, coding and writing tasks — at the cost of extra calls.", "definition": "Reflection is a pattern in which a model reviews and critiques its own output against explicit criteria and then revises it, trading extra inference for higher quality.", "problem": "Models often produce a flawed first answer they could improve if prompted to review their own work, but a single pass gives them no chance to.", "context": "Use reflection when a self-review step measurably improves output and you want a simpler alternative to a two-model evaluator loop — common in reasoning and coding tasks.", "solution": [ "After generating an answer, prompt the same model to critique it against the goal (and any tool feedback such as test results or errors), then to produce a revised answer informed by that critique. Repeat for a bounded number of iterations.", "Reflection works best when grounded in real signals — execution errors, test output, retrieved facts — rather than pure self-assessment, which can be overconfident." ], "components": [ "Initial generation", "Self-critique step", "Grounding signal (errors / tests / facts)", "Revision", "Iteration budget" ], "benefits": [ "Improves quality with a single model — no second system.", "Effective when grounded in tool or test feedback.", "Simple to add to an existing call." ], "risks": [ "Self-critique can be overconfident or miss its own errors.", "Extra calls add latency and cost.", "Without grounding, gains are limited." ], "whenNot": [ "When you have an objective external check — use evaluator-optimizer.", "When a single pass already meets the bar.", "When latency budgets are very tight." ], "examples": [ "A coding agent reading test failures and fixing its own patch.", "A reasoning task where the model rechecks its steps before answering.", "A draft the model reviews for gaps before finalizing." ], "productionEvidence": { "context": "Tasks where output quality matters more than latency or cost — drafting, code generation, analysis — and where errors are detectable on review.", "scenario": "After producing a first answer, the model (or a separate critic) evaluates it against concrete criteria and produces a revised version; the loop is capped at one or two passes.", "technology": "A critique-then-revise prompt chain, ideally backed by external signals (tests, tools, a separate evaluator) for high-stakes work.", "load": "Each reflection pass at least doubles calls, so it is applied selectively to the outputs that justify the overhead.", "results": "Observed pattern: reflection lifts quality where the model can actually detect its own errors, but it can over-revise correct answers and at least doubles cost. Measure the quality lift against an eval set before trusting it, and prefer external signals when stakes are high." }, "kpis": [ { "metric": "Quality lift from reflection", "note": "Measured improvement in output quality with the reflection step versus without; if it's not measurable, the step isn't earning its cost." }, { "metric": "Self-correction rate", "note": "Share of genuine errors the model catches and fixes on review — distinct from cosmetic edits." }, { "metric": "Added latency & cost", "note": "Reflection at least doubles calls; track the overhead against the quality it buys." }, { "metric": "Over-revision rate", "note": "How often reflection degrades an already-good answer by second-guessing it." } ], "failureModes": [ "Self-evaluation blind spots: a model often can't see its own errors, so reflection misses them.", "Over-revision: the model 'fixes' a correct answer into a worse one.", "Cost and latency double (or more) for marginal or no quality gain.", "False confidence: the model asserts the output is now correct when it isn't." ], "lessons": [ "Measure the lift; reflection is worth it only where it demonstrably improves quality.", "Prefer external signals (tests, tools, a separate evaluator) over pure self-critique when stakes are high.", "Cap reflection to one or two passes — returns diminish fast and cost compounds.", "Give the reflection step concrete criteria, not a vague 'improve this'." ], "faqs": [ { "q": "Reflection or evaluator-optimizer?", "a": "Reflection uses one model to self-critique (simpler); evaluator-optimizer uses a separate evaluator (sharper, less biased). Choose by how reliable self-assessment is for your task." }, { "q": "Does reflection always help?", "a": "It helps most when grounded in real feedback like test results or errors. Pure self-assessment can be overconfident and add little." }, { "q": "How many reflection rounds?", "a": "Keep it bounded — often one or two. Diminishing returns and rising cost make long loops rarely worth it." } ] }, "es": { "name": "Reflexión (Reflection)", "summary": "La reflexión hace que un modelo critique su propia salida y luego la revise, usando la crítica como feedback. Es una forma ligera, de un solo modelo, de atrapar errores y mejorar la calidad en tareas de razonamiento, código y escritura, a costa de llamadas extra.", "definition": "La reflexión es un patrón en el que un modelo revisa y critica su propia salida frente a criterios explícitos y luego la corrige, cambiando inferencia adicional por mayor calidad.", "problem": "Los modelos a menudo producen una primera respuesta defectuosa que podrían mejorar si se les pide revisar su propio trabajo, pero una sola pasada no les da la oportunidad.", "context": "Usa la reflexión cuando un paso de autorrevisión mejore la salida de forma medible y quieras una alternativa más simple al bucle evaluador de dos modelos —común en tareas de razonamiento y código.", "solution": [ "Tras generar una respuesta, pide al mismo modelo que la critique frente al objetivo (y cualquier feedback de herramientas como resultados de tests o errores), y luego que produzca una respuesta revisada informada por esa crítica. Repite un número acotado de iteraciones.", "La reflexión funciona mejor anclada en señales reales —errores de ejecución, salida de tests, hechos recuperados— que en la pura autoevaluación, que puede ser demasiado confiada." ], "components": [ "Generación inicial", "Paso de autocrítica", "Señal de anclaje (errores / tests / hechos)", "Revisión", "Presupuesto de iteración" ], "benefits": [ "Mejora la calidad con un solo modelo, sin segundo sistema.", "Eficaz cuando se ancla en feedback de herramientas o tests.", "Simple de añadir a una llamada existente." ], "risks": [ "La autocrítica puede ser demasiado confiada o no ver sus errores.", "Las llamadas extra añaden latencia y coste.", "Sin anclaje, las ganancias son limitadas." ], "whenNot": [ "Cuando tienes una comprobación externa objetiva: usa evaluador-optimizador.", "Cuando una sola pasada ya alcanza el nivel.", "Cuando los presupuestos de latencia son muy ajustados." ], "examples": [ "Un agente de código que lee fallos de tests y corrige su propio parche.", "Una tarea de razonamiento donde el modelo revisa sus pasos antes de responder.", "Un borrador que el modelo revisa en busca de lagunas antes de finalizar." ], "productionEvidence": { "context": "Tareas donde la calidad importa más que la latencia o el coste —redacción, generación de código, análisis— y donde los errores son detectables al revisar.", "scenario": "Tras producir una primera respuesta, el modelo (o un crítico aparte) la evalúa frente a criterios concretos y produce una versión revisada; el bucle se limita a una o dos pasadas.", "technology": "Una cadena de prompts criticar-luego-revisar, idealmente respaldada por señales externas (tests, herramientas, un evaluador aparte) para el trabajo de alto riesgo.", "load": "Cada pasada de reflexión al menos duplica las llamadas, así que se aplica de forma selectiva a las salidas que justifican el sobrecoste.", "results": "Patrón observado: la reflexión mejora la calidad donde el modelo puede de verdad detectar sus propios errores, pero puede sobrerrevisar respuestas correctas y al menos duplica el coste. Mide la mejora frente a un conjunto de evaluación antes de confiar en ella, y prefiere señales externas cuando hay mucho en juego." }, "kpis": [ { "metric": "Mejora de calidad por reflexión", "note": "Mejora medida en la calidad con el paso de reflexión frente a sin él; si no es medible, el paso no justifica su coste." }, { "metric": "Tasa de autocorrección", "note": "Proporción de errores reales que el modelo detecta y corrige al revisar, distinta de ediciones cosméticas." }, { "metric": "Latencia y coste añadidos", "note": "La reflexión al menos duplica las llamadas; vigila el sobrecoste frente a la calidad que aporta." }, { "metric": "Tasa de sobrerrevisión", "note": "Con qué frecuencia la reflexión degrada una respuesta ya buena al cuestionarla en exceso." } ], "failureModes": [ "Puntos ciegos de autoevaluación: un modelo suele no ver sus propios errores, así que la reflexión los pasa por alto.", "Sobrerrevisión: el modelo 'corrige' una respuesta correcta y la empeora.", "Coste y latencia se duplican (o más) para una ganancia de calidad marginal o nula.", "Falsa confianza: el modelo afirma que la salida ya es correcta cuando no lo es." ], "lessons": [ "Mide la mejora; la reflexión vale la pena solo donde mejora la calidad de forma demostrable.", "Prefiere señales externas (tests, herramientas, un evaluador aparte) sobre la pura autocrítica cuando hay mucho en juego.", "Limita la reflexión a una o dos pasadas: los rendimientos caen rápido y el coste se acumula.", "Da al paso de reflexión criterios concretos, no un vago 'mejora esto'." ], "faqs": [ { "q": "¿Reflexión o evaluador-optimizador?", "a": "La reflexión usa un modelo para autocriticarse (más simple); el evaluador-optimizador usa un evaluador separado (más afilado, menos sesgado). Elige según cuán fiable sea la autoevaluación en tu tarea." }, { "q": "¿La reflexión siempre ayuda?", "a": "Ayuda más cuando se ancla en feedback real como resultados de tests o errores. La pura autoevaluación puede ser demasiado confiada y aportar poco." }, { "q": "¿Cuántas rondas de reflexión?", "a": "Mantenlo acotado, a menudo una o dos. Los rendimientos decrecientes y el coste creciente hacen que los bucles largos rara vez compensen." } ] }, "pt": { "name": "Reflexão (Reflection)", "summary": "A reflexão faz um modelo criticar sua própria saída e depois revisá-la, usando a crítica como feedback. É uma forma leve, de um único modelo, de capturar erros e melhorar a qualidade em tarefas de raciocínio, código e escrita, ao custo de chamadas extras.", "definition": "A reflexão é um padrão em que um modelo revisa e critica a própria saída frente a critérios explícitos e depois a corrige, trocando inferência adicional por mais qualidade.", "problem": "Os modelos muitas vezes produzem uma primeira resposta defeituosa que poderiam melhorar se solicitados a revisar o próprio trabalho, mas uma única passagem não lhes dá a chance.", "context": "Use a reflexão quando um passo de autorrevisão melhore a saída de forma mensurável e você queira uma alternativa mais simples ao laço avaliador de dois modelos — comum em tarefas de raciocínio e código.", "solution": [ "Após gerar uma resposta, peça ao mesmo modelo que a critique frente ao objetivo (e qualquer feedback de ferramentas como resultados de testes ou erros), e depois que produza uma resposta revisada informada por essa crítica. Repita um número limitado de iterações.", "A reflexão funciona melhor ancorada em sinais reais — erros de execução, saída de testes, fatos recuperados — que na pura autoavaliação, que pode ser confiante demais." ], "components": [ "Geração inicial", "Passo de autocrítica", "Sinal de ancoragem (erros / testes / fatos)", "Revisão", "Orçamento de iteração" ], "benefits": [ "Melhora a qualidade com um único modelo, sem segundo sistema.", "Eficaz quando ancorada em feedback de ferramentas ou testes.", "Simples de adicionar a uma chamada existente." ], "risks": [ "A autocrítica pode ser confiante demais ou não ver seus erros.", "As chamadas extras adicionam latência e custo.", "Sem ancoragem, os ganhos são limitados." ], "whenNot": [ "Quando você tem uma verificação externa objetiva: use avaliador-otimizador.", "Quando uma única passagem já alcança o nível.", "Quando os orçamentos de latência são muito apertados." ], "examples": [ "Um agente de código que lê falhas de testes e corrige seu próprio patch.", "Uma tarefa de raciocínio em que o modelo revisa seus passos antes de responder.", "Um rascunho que o modelo revisa em busca de lacunas antes de finalizar." ], "productionEvidence": { "context": "Tarefas onde a qualidade importa mais que latência ou custo —redação, geração de código, análise— e onde os erros são detectáveis na revisão.", "scenario": "Após produzir uma primeira resposta, o modelo (ou um crítico à parte) a avalia frente a critérios concretos e produz uma versão revisada; o laço é limitado a uma ou duas passagens.", "technology": "Uma cadeia de prompts criticar-depois-revisar, idealmente apoiada por sinais externos (testes, ferramentas, um avaliador à parte) para o trabalho de alto risco.", "load": "Cada passagem de reflexão ao menos duplica as chamadas, então é aplicada de forma seletiva às saídas que justificam o sobrecusto.", "results": "Padrão observado: a reflexão melhora a qualidade onde o modelo consegue de fato detectar os próprios erros, mas pode sobrerrevisar respostas corretas e ao menos duplica o custo. Meça o ganho frente a um conjunto de avaliação antes de confiar nela, e prefira sinais externos quando há muito em jogo." }, "kpis": [ { "metric": "Ganho de qualidade pela reflexão", "note": "Melhoria medida na qualidade com o passo de reflexão versus sem ele; se não for mensurável, o passo não justifica seu custo." }, { "metric": "Taxa de autocorreção", "note": "Proporção de erros reais que o modelo detecta e corrige ao revisar, distinta de edições cosméticas." }, { "metric": "Latência e custo adicionados", "note": "A reflexão ao menos duplica as chamadas; vigie o sobrecusto frente à qualidade que traz." }, { "metric": "Taxa de sobrerrevisão", "note": "Com que frequência a reflexão degrada uma resposta já boa ao questioná-la em excesso." } ], "failureModes": [ "Pontos cegos de autoavaliação: um modelo costuma não ver os próprios erros, então a reflexão os ignora.", "Sobrerrevisão: o modelo 'corrige' uma resposta correta e a piora.", "Custo e latência dobram (ou mais) para um ganho de qualidade marginal ou nulo.", "Falsa confiança: o modelo afirma que a saída já está correta quando não está." ], "lessons": [ "Meça o ganho; a reflexão vale a pena só onde melhora a qualidade de forma demonstrável.", "Prefira sinais externos (testes, ferramentas, um avaliador à parte) à pura autocrítica quando há muito em jogo.", "Limite a reflexão a uma ou duas passagens: os retornos caem rápido e o custo se acumula.", "Dê ao passo de reflexão critérios concretos, não um vago 'melhore isto'." ], "faqs": [ { "q": "Reflexão ou avaliador-otimizador?", "a": "A reflexão usa um modelo para se autocriticar (mais simples); o avaliador-otimizador usa um avaliador separado (mais afiado, menos enviesado). Escolha conforme quão confiável é a autoavaliação na sua tarefa." }, { "q": "A reflexão sempre ajuda?", "a": "Ajuda mais quando ancorada em feedback real como resultados de testes ou erros. A pura autoavaliação pode ser confiante demais e agregar pouco." }, { "q": "Quantas rodadas de reflexão?", "a": "Mantenha limitado, muitas vezes uma ou duas. Os retornos decrescentes e o custo crescente fazem laços longos raramente valerem a pena." } ] } } }, { "slug": "routing", "category": "orchestration", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/routing", "api": "https://santismm.com/api/patterns/routing", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Classifier models", "LangGraph", "Model routers", "Rules engines" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "prompt-chaining", "orchestrator-workers", "parallelization" ], "locales": { "en": { "name": "Routing", "summary": "Routing classifies an input and directs it to the most appropriate specialized handler, prompt or model. It improves quality by letting each path be optimized for its case, and controls cost by sending easy requests to cheap models and hard ones to capable models.", "definition": "Routing is a pattern that classifies each incoming request and dispatches it to the most appropriate handler or model, so easy inputs use cheap paths and hard inputs use capable ones.", "problem": "A single prompt or model handling every kind of input does each one worse, and using one expensive model for everything wastes money on easy requests.", "context": "Use routing when inputs fall into distinct categories that benefit from different handling — different prompts, tools, models or workflows — and the categories can be classified reliably.", "solution": [ "A lightweight classifier (an LLM call or a model) labels the input, then a router sends it to the matching downstream handler. Each handler is specialized and optimized for its category.", "Routing also enables cost-performance tiering: route simple queries to a fast, cheap model and complex ones to a stronger reasoning model, paying for capability only when it is needed." ], "components": [ "Classifier", "Routing logic", "Specialized handlers", "Fallback / default route" ], "benefits": [ "Each path is optimized for its case, raising quality.", "Cost control by tiering models to difficulty.", "Separation of concerns keeps each handler simple." ], "risks": [ "Misclassification sends inputs down the wrong path.", "The classifier adds a step and some latency.", "Category drift over time degrades routing accuracy." ], "whenNot": [ "When inputs are homogeneous — one handler suffices.", "When categories cannot be classified reliably.", "When the added classification step is not worth the gain." ], "examples": [ "Routing support tickets to billing, technical or sales handlers.", "Sending simple questions to a small model and hard ones to a reasoning model.", "Directing different document types to type-specific extractors." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "Inbound channel messages and autonomous wake-ups are routed to one agent through distinct entrypoints, with channel/peer/role bindings selecting the session.", "technology": "Binding + route registry (resolveAgentRoute), per-channel session keys, and a resolved-route cache.", "load": "3 channels (Telegram, web chat, WhatsApp) and 4 trigger kinds (user, heartbeat, cron, memory).", "results": "Routing held across all three channels and four trigger types with no misroute surfacing as a failure (98.8% session success overall). Single-operator local-first deployment — a working reference, not a scale benchmark." }, "kpis": [ { "metric": "Routing accuracy", "note": "Share of inputs sent to the correct handler/model; the single metric that defines the pattern's value." }, { "metric": "Cost savings vs. always-best-model", "note": "Money saved by routing easy inputs to cheaper models instead of the top one for everything." }, { "metric": "Misroute cost", "note": "The downstream damage of wrong routes — a misroute can cost far more than the savings it chased." }, { "metric": "Router latency overhead", "note": "Time the routing decision itself adds before any real work begins." } ], "failureModes": [ "Misclassification: the router sends an input to the wrong model or path, degrading the answer.", "Ambiguous inputs that don't fit any route cleanly and get forced into a poor one.", "Router becomes a bottleneck or single point of failure for every request.", "Drift: input distribution shifts over time and the router's categories go stale." ], "lessons": [ "Optimize for the cost of a misroute, not just routing accuracy — some wrong routes are far costlier than others.", "Add a default / fallback route for inputs that match nothing well.", "Keep the router cheap and fast; if it costs as much as the work, it defeats the purpose.", "Monitor input drift and re-tune routes as the distribution changes." ], "faqs": [ { "q": "What classifies the input?", "a": "Usually a lightweight LLM call or a dedicated classifier model; for clear-cut cases, deterministic rules can route without a model." }, { "q": "How does routing save cost?", "a": "By tiering: easy requests go to cheap, fast models and only hard ones reach expensive reasoning models, so you pay for capability only when needed." }, { "q": "What if the classifier is wrong?", "a": "Provide a sensible default route and monitor misroutes; a fallback handler and good observability limit the impact of misclassification." } ] }, "es": { "name": "Enrutamiento (Routing)", "summary": "El enrutamiento clasifica una entrada y la dirige al manejador, prompt o modelo especializado más adecuado. Mejora la calidad al optimizar cada camino para su caso y controla el coste enviando peticiones fáciles a modelos baratos y las difíciles a modelos capaces.", "definition": "El enrutado es un patrón que clasifica cada petición entrante y la despacha al manejador o modelo más apropiado, de modo que las entradas fáciles usan caminos baratos y las difíciles, modelos capaces.", "problem": "Un solo prompt o modelo manejando cada tipo de entrada hace cada una peor, y usar un modelo caro para todo malgasta dinero en peticiones fáciles.", "context": "Usa el enrutamiento cuando las entradas caen en categorías distintas que se benefician de un manejo diferente —distintos prompts, herramientas, modelos o flujos— y las categorías se pueden clasificar de forma fiable.", "solution": [ "Un clasificador ligero (una llamada al LLM o un modelo) etiqueta la entrada, y luego un enrutador la envía al manejador adecuado. Cada manejador está especializado y optimizado para su categoría.", "El enrutamiento también permite escalonar coste-rendimiento: enruta consultas simples a un modelo rápido y barato y las complejas a un modelo de razonamiento más fuerte, pagando por capacidad solo cuando hace falta." ], "components": [ "Clasificador", "Lógica de enrutamiento", "Manejadores especializados", "Ruta por defecto / fallback" ], "benefits": [ "Cada camino se optimiza para su caso, elevando la calidad.", "Control de coste escalonando modelos según la dificultad.", "La separación de responsabilidades mantiene simple cada manejador." ], "risks": [ "La mala clasificación envía entradas por el camino equivocado.", "El clasificador añade un paso y algo de latencia.", "La deriva de categorías en el tiempo degrada la precisión." ], "whenNot": [ "Cuando las entradas son homogéneas: basta un manejador.", "Cuando las categorías no se pueden clasificar de forma fiable.", "Cuando el paso de clasificación añadido no compensa la ganancia." ], "examples": [ "Enrutar tickets de soporte a manejadores de facturación, técnico o ventas.", "Enviar preguntas simples a un modelo pequeño y las difíciles a uno de razonamiento.", "Dirigir distintos tipos de documento a extractores específicos por tipo." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "Los mensajes entrantes de canal y los despertares autónomos se enrutan a un agente por entrypoints distintos, con bindings de canal/peer/rol que seleccionan la sesión.", "technology": "Registro de bindings y rutas (resolveAgentRoute), claves de sesión por canal y caché de ruta resuelta.", "load": "3 canales (Telegram, chat web, WhatsApp) y 4 tipos de trigger (usuario, heartbeat, cron, memoria).", "results": "El enrutado se mantuvo en los tres canales y los cuatro tipos de trigger sin que ningún error de ruta apareciera como fallo (98,8% de éxito por sesión). Despliegue local-first mono-operador — una referencia que funciona, no un benchmark de escala." }, "kpis": [ { "metric": "Precisión de enrutado", "note": "Proporción de entradas enviadas al manejador/modelo correcto; la métrica que define el valor del patrón." }, { "metric": "Ahorro vs. usar siempre el mejor modelo", "note": "Dinero ahorrado al enrutar entradas fáciles a modelos más baratos en vez del mejor para todo." }, { "metric": "Coste de mal enrutado", "note": "El daño posterior de rutas erróneas; un mal enrutado puede costar mucho más que el ahorro buscado." }, { "metric": "Sobrecoste de latencia del router", "note": "Tiempo que la propia decisión de enrutado añade antes de empezar el trabajo real." } ], "failureModes": [ "Mala clasificación: el router envía una entrada al modelo o ruta equivocados, degradando la respuesta.", "Entradas ambiguas que no encajan bien en ninguna ruta y se fuerzan a una deficiente.", "El router se convierte en cuello de botella o punto único de fallo de cada petición.", "Deriva: la distribución de entradas cambia con el tiempo y las categorías del router quedan obsoletas." ], "lessons": [ "Optimiza por el coste de un mal enrutado, no solo por la precisión: algunas rutas erróneas son mucho más caras que otras.", "Añade una ruta por defecto / de respaldo para entradas que no encajen bien en nada.", "Mantén el router barato y rápido; si cuesta tanto como el trabajo, pierde su sentido.", "Monitoriza la deriva de entradas y reajusta las rutas cuando cambie la distribución." ], "faqs": [ { "q": "¿Qué clasifica la entrada?", "a": "Normalmente una llamada ligera al LLM o un modelo clasificador dedicado; para casos claros, reglas deterministas pueden enrutar sin modelo." }, { "q": "¿Cómo ahorra coste el enrutamiento?", "a": "Escalonando: las peticiones fáciles van a modelos baratos y rápidos y solo las difíciles llegan a modelos de razonamiento caros, así pagas por capacidad solo cuando hace falta." }, { "q": "¿Y si el clasificador se equivoca?", "a": "Provee una ruta por defecto sensata y monitoriza los errores de ruta; un manejador de respaldo y buena observabilidad limitan el impacto de la mala clasificación." } ] }, "pt": { "name": "Roteamento (Routing)", "summary": "O roteamento classifica uma entrada e a direciona ao manipulador, prompt ou modelo especializado mais adequado. Melhora a qualidade ao otimizar cada caminho para seu caso e controla o custo enviando requisições fáceis a modelos baratos e as difíceis a modelos capazes.", "definition": "O roteamento é um padrão que classifica cada requisição recebida e a despacha ao manipulador ou modelo mais apropriado, de modo que entradas fáceis usam caminhos baratos e as difíceis, modelos capazes.", "problem": "Um único prompt ou modelo lidando com cada tipo de entrada faz cada uma pior, e usar um modelo caro para tudo desperdiça dinheiro em requisições fáceis.", "context": "Use o roteamento quando as entradas caem em categorias distintas que se beneficiam de tratamento diferente — diferentes prompts, ferramentas, modelos ou fluxos — e as categorias podem ser classificadas de forma confiável.", "solution": [ "Um classificador leve (uma chamada ao LLM ou um modelo) rotula a entrada, e então um roteador a envia ao manipulador adequado. Cada manipulador é especializado e otimizado para sua categoria.", "O roteamento também permite escalonar custo-desempenho: roteie consultas simples a um modelo rápido e barato e as complexas a um modelo de raciocínio mais forte, pagando por capacidade só quando necessário." ], "components": [ "Classificador", "Lógica de roteamento", "Manipuladores especializados", "Rota padrão / fallback" ], "benefits": [ "Cada caminho é otimizado para seu caso, elevando a qualidade.", "Controle de custo escalonando modelos conforme a dificuldade.", "A separação de responsabilidades mantém cada manipulador simples." ], "risks": [ "A má classificação envia entradas pelo caminho errado.", "O classificador adiciona um passo e alguma latência.", "A deriva de categorias ao longo do tempo degrada a precisão." ], "whenNot": [ "Quando as entradas são homogêneas: basta um manipulador.", "Quando as categorias não podem ser classificadas de forma confiável.", "Quando o passo de classificação adicionado não compensa o ganho." ], "examples": [ "Rotear chamados de suporte a manipuladores de faturamento, técnico ou vendas.", "Enviar perguntas simples a um modelo pequeno e as difíceis a um de raciocínio.", "Direcionar diferentes tipos de documento a extratores específicos por tipo." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "Mensagens de canal recebidas e despertares autônomos são roteados para um agente por entrypoints distintos, com bindings de canal/peer/papel selecionando a sessão.", "technology": "Registro de bindings e rotas (resolveAgentRoute), chaves de sessão por canal e cache de rota resolvida.", "load": "3 canais (Telegram, chat web, WhatsApp) e 4 tipos de gatilho (usuário, heartbeat, cron, memória).", "results": "O roteamento se manteve nos três canais e nos quatro tipos de gatilho sem que nenhum erro de rota aparecesse como falha (98,8% de sucesso por sessão). Implantação local-first de operador único — uma referência que funciona, não um benchmark de escala." }, "kpis": [ { "metric": "Precisão de roteamento", "note": "Proporção de entradas enviadas ao manipulador/modelo correto; a métrica que define o valor do padrão." }, { "metric": "Economia vs. usar sempre o melhor modelo", "note": "Dinheiro economizado ao rotear entradas fáceis para modelos mais baratos em vez do melhor para tudo." }, { "metric": "Custo de roteamento errado", "note": "O dano posterior de rotas erradas; um roteamento errado pode custar muito mais que a economia buscada." }, { "metric": "Sobrecusto de latência do roteador", "note": "Tempo que a própria decisão de roteamento adiciona antes de começar o trabalho real." } ], "failureModes": [ "Má classificação: o roteador envia uma entrada ao modelo ou rota errados, degradando a resposta.", "Entradas ambíguas que não encaixam bem em nenhuma rota e são forçadas a uma deficiente.", "O roteador vira gargalo ou ponto único de falha de cada requisição.", "Deriva: a distribuição de entradas muda com o tempo e as categorias do roteador ficam obsoletas." ], "lessons": [ "Otimize pelo custo de um roteamento errado, não só pela precisão: algumas rotas erradas são muito mais caras que outras.", "Adicione uma rota padrão / de fallback para entradas que não encaixem bem em nada.", "Mantenha o roteador barato e rápido; se custa tanto quanto o trabalho, perde o sentido.", "Monitore a deriva de entradas e reajuste as rotas quando a distribuição mudar." ], "faqs": [ { "q": "O que classifica a entrada?", "a": "Normalmente uma chamada leve ao LLM ou um modelo classificador dedicado; para casos claros, regras determinísticas podem rotear sem modelo." }, { "q": "Como o roteamento economiza custo?", "a": "Escalonando: as requisições fáceis vão a modelos baratos e rápidos e só as difíceis chegam a modelos de raciocínio caros, então você paga por capacidade só quando necessário." }, { "q": "E se o classificador errar?", "a": "Forneça uma rota padrão sensata e monitore os erros de rota; um manipulador de fallback e boa observabilidade limitam o impacto da má classificação." } ] } } }, { "slug": "semantic-caching", "category": "cost", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/semantic-caching", "api": "https://santismm.com/api/patterns/semantic-caching", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Embedding models", "Vector databases", "GPTCache", "Redis / KV stores" ], "references": [ { "title": "OpenAI — Vector embeddings guide", "url": "https://platform.openai.com/docs/guides/embeddings" } ], "related": [ "routing", "prompt-chaining" ], "locales": { "en": { "name": "Semantic Caching", "summary": "Semantic caching stores past model responses and reuses them when a new request is semantically similar to a previous one — matching by meaning via embeddings, not exact text. It cuts cost and latency for repetitive or near-duplicate queries common in production.", "problem": "Many production queries are paraphrases of ones already answered, so re-running the full model on each wastes cost and latency.", "context": "Use semantic caching when traffic contains many similar or repeated questions and answers are stable enough to reuse — FAQs, support, documentation assistants.", "solution": [ "Embed each incoming request and search a cache of prior request embeddings. If a sufficiently similar entry exists (above a similarity threshold), return its stored response; otherwise call the model and store the new pair.", "Tune the similarity threshold carefully: too loose returns wrong answers for subtly different questions; too strict misses valid hits. Add TTLs and invalidation so cached answers do not go stale." ], "components": [ "Embedding of the request", "Vector cache", "Similarity threshold", "TTL / invalidation", "Fallback to model" ], "benefits": [ "Lower cost by avoiding repeat model calls.", "Lower latency on cache hits.", "More consistent answers to similar questions." ], "risks": [ "A loose threshold serves wrong cached answers.", "Stale cache without TTL or invalidation.", "Personalized or time-sensitive answers cache poorly." ], "whenNot": [ "When most queries are unique.", "When answers depend on fresh, user- or time-specific data.", "When even small mismatches are unacceptable." ], "examples": [ "Reusing the answer to 'how do I reset my password' across its many phrasings.", "Caching common documentation questions in a support assistant.", "Short-circuiting repeated identical analytics questions." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "Prompt and context caching is engineered with cache_control markers plus a workspace file cache and a route cache, so repeated structure is served from cache.", "technology": "Anthropic cache_control injection on system and messages, OpenRouter passthrough, workspace file cache, route cache, and cache_read/write cost accounting.", "load": "28.1M total tokens over 57 days, of which ~19.6M were served as cache-read.", "results": "About 70% of tokens were served from cache, holding blended cost to $15.21 per 1M tokens ($41 of cache-read versus $374 of fresh input). Single-operator local-first deployment — the ratio reflects this workload's repetition; measure your own." }, "kpis": [ { "metric": "Cache hit rate", "note": "Share of requests served from cache; the lever for both cost and latency savings." }, { "metric": "False-hit rate", "note": "How often a semantically 'similar' hit returns a wrong or stale answer — the central risk of caching by meaning." }, { "metric": "Cost & latency saved per hit", "note": "Tokens and time avoided on cache hits, the upside you're trading the false-hit risk for." }, { "metric": "Similarity threshold calibration", "note": "Whether the match threshold balances hit rate against false hits; too loose hurts quality, too strict kills savings." } ], "failureModes": [ "False hits: two queries are similar in embedding space but need different answers, so the cache returns a wrong one.", "Staleness: cached answers go out of date while the underlying facts change.", "Threshold mis-tuning: too loose returns wrong answers, too strict yields almost no hits.", "Cache poisoning: a bad answer gets cached and then served repeatedly." ], "lessons": [ "Tune the similarity threshold against real traffic; it is the make-or-break parameter.", "Never cache where freshness or correctness is critical without an invalidation strategy.", "Validate or sample cache hits to catch false matches before users do.", "Scope caches narrowly (per tenant, per context) to avoid leaking the wrong answer across users." ], "faqs": [ { "q": "How is this different from a normal cache?", "a": "A normal cache matches exact keys; a semantic cache matches by meaning using embeddings, so paraphrased questions still hit." }, { "q": "What is the main risk?", "a": "A too-loose similarity threshold returns a cached answer for a question that is actually different. Tune the threshold and validate on real traffic." }, { "q": "How do I avoid stale answers?", "a": "Set TTLs and invalidate entries when the underlying data changes; avoid caching personalized or time-sensitive responses." } ] }, "es": { "name": "Caché Semántica (Semantic Caching)", "summary": "La caché semántica almacena respuestas pasadas del modelo y las reutiliza cuando una nueva petición es semánticamente similar a una previa, casando por significado mediante embeddings, no por texto exacto. Reduce coste y latencia en consultas repetitivas o casi duplicadas, comunes en producción.", "problem": "Muchas consultas en producción son paráfrasis de otras ya respondidas, así que reejecutar el modelo completo en cada una desperdicia coste y latencia.", "context": "Usa la caché semántica cuando el tráfico contiene muchas preguntas similares o repetidas y las respuestas son lo bastante estables para reutilizarse: FAQs, soporte, asistentes de documentación.", "solution": [ "Embebe cada petición entrante y busca en una caché de embeddings de peticiones previas. Si existe una entrada suficientemente similar (por encima de un umbral de similitud), devuelve su respuesta almacenada; si no, llama al modelo y guarda el nuevo par.", "Ajusta el umbral de similitud con cuidado: demasiado laxo devuelve respuestas erróneas a preguntas sutilmente distintas; demasiado estricto pierde aciertos válidos. Añade TTLs e invalidación para que las respuestas no queden obsoletas." ], "components": [ "Embedding de la petición", "Caché vectorial", "Umbral de similitud", "TTL / invalidación", "Fallback al modelo" ], "benefits": [ "Menor coste al evitar llamadas repetidas al modelo.", "Menor latencia en los aciertos de caché.", "Respuestas más consistentes a preguntas similares." ], "risks": [ "Un umbral laxo sirve respuestas cacheadas erróneas.", "Caché obsoleta sin TTL ni invalidación.", "Las respuestas personalizadas o sensibles al tiempo se cachean mal." ], "whenNot": [ "Cuando la mayoría de consultas son únicas.", "Cuando las respuestas dependen de datos frescos, de usuario o de tiempo.", "Cuando incluso pequeños desajustes son inaceptables." ], "examples": [ "Reutilizar la respuesta a 'cómo reseteo mi contraseña' en sus muchas formulaciones.", "Cachear preguntas comunes de documentación en un asistente de soporte.", "Cortocircuitar preguntas analíticas idénticas repetidas." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "El caching de prompt y contexto está diseñado con marcadores cache_control más una caché de archivos de workspace y una caché de rutas, de modo que la estructura repetida se sirve desde caché.", "technology": "Inyección de cache_control de Anthropic en sistema y mensajes, passthrough de OpenRouter, caché de archivos de workspace, caché de rutas y contabilidad de coste cache_read/write.", "load": "28,1M de tokens totales en 57 días, de los cuales ~19,6M se sirvieron como cache-read.", "results": "Cerca del 70% de los tokens se sirvieron desde caché, manteniendo el coste mezclado en $15,21 por 1M de tokens ($41 de cache-read frente a $374 de input nuevo). Despliegue local-first mono-operador — el ratio refleja la repetición de esta carga; mide el tuyo." }, "kpis": [ { "metric": "Tasa de aciertos de caché", "note": "Proporción de peticiones servidas desde caché; la palanca de ahorro en coste y latencia." }, { "metric": "Tasa de falsos aciertos", "note": "Con qué frecuencia un acierto 'similar' devuelve una respuesta errónea u obsoleta; el riesgo central de cachear por significado." }, { "metric": "Coste y latencia ahorrados por acierto", "note": "Tokens y tiempo evitados en los aciertos, la ventaja por la que cambias el riesgo de falso acierto." }, { "metric": "Calibración del umbral de similitud", "note": "Si el umbral equilibra tasa de aciertos y falsos aciertos; demasiado laxo daña la calidad, demasiado estricto elimina el ahorro." } ], "failureModes": [ "Falsos aciertos: dos consultas similares en el espacio de embeddings necesitan respuestas distintas, y la caché devuelve la equivocada.", "Obsolescencia: las respuestas cacheadas quedan desactualizadas mientras los hechos subyacentes cambian.", "Mal ajuste del umbral: demasiado laxo devuelve respuestas erróneas, demasiado estricto da casi ningún acierto.", "Envenenamiento de caché: una respuesta mala se cachea y luego se sirve repetidamente." ], "lessons": [ "Ajusta el umbral de similitud con tráfico real; es el parámetro decisivo.", "Nunca caches donde la frescura o la corrección sean críticas sin una estrategia de invalidación.", "Valida o muestrea los aciertos de caché para detectar falsos antes que los usuarios.", "Acota las cachés de forma estrecha (por tenant, por contexto) para no filtrar la respuesta equivocada entre usuarios." ], "faqs": [ { "q": "¿En qué se diferencia de una caché normal?", "a": "Una caché normal casa claves exactas; una caché semántica casa por significado usando embeddings, así las preguntas parafraseadas también aciertan." }, { "q": "¿Cuál es el riesgo principal?", "a": "Un umbral de similitud demasiado laxo devuelve una respuesta cacheada para una pregunta que en realidad es distinta. Ajusta el umbral y valida con tráfico real." }, { "q": "¿Cómo evito respuestas obsoletas?", "a": "Fija TTLs e invalida entradas cuando cambian los datos subyacentes; evita cachear respuestas personalizadas o sensibles al tiempo." } ] }, "pt": { "name": "Cache Semântico (Semantic Caching)", "summary": "O cache semântico armazena respostas passadas do modelo e as reutiliza quando uma nova requisição é semanticamente similar a uma anterior, casando por significado via embeddings, não por texto exato. Reduz custo e latência em consultas repetitivas ou quase duplicadas, comuns em produção.", "problem": "Muitas consultas em produção são paráfrases de outras já respondidas, então reexecutar o modelo completo em cada uma desperdiça custo e latência.", "context": "Use o cache semântico quando o tráfego contém muitas perguntas similares ou repetidas e as respostas são estáveis o bastante para reutilizar: FAQs, suporte, assistentes de documentação.", "solution": [ "Embede cada requisição recebida e busca num cache de embeddings de requisições anteriores. Se existe uma entrada suficientemente similar (acima de um limiar de similaridade), devolve sua resposta armazenada; senão, chama o modelo e guarda o novo par.", "Ajuste o limiar de similaridade com cuidado: frouxo demais devolve respostas erradas a perguntas sutilmente distintas; estrito demais perde acertos válidos. Adicione TTLs e invalidação para que as respostas não fiquem obsoletas." ], "components": [ "Embedding da requisição", "Cache vetorial", "Limiar de similaridade", "TTL / invalidação", "Fallback ao modelo" ], "benefits": [ "Menor custo ao evitar chamadas repetidas ao modelo.", "Menor latência nos acertos de cache.", "Respostas mais consistentes a perguntas similares." ], "risks": [ "Um limiar frouxo serve respostas em cache erradas.", "Cache obsoleto sem TTL nem invalidação.", "Respostas personalizadas ou sensíveis ao tempo se armazenam mal." ], "whenNot": [ "Quando a maioria das consultas é única.", "Quando as respostas dependem de dados frescos, de usuário ou de tempo.", "Quando até pequenos descompassos são inaceitáveis." ], "examples": [ "Reutilizar a resposta a 'como redefino minha senha' em suas muitas formulações.", "Armazenar perguntas comuns de documentação num assistente de suporte.", "Curto-circuitar perguntas analíticas idênticas repetidas." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "O caching de prompt e contexto é projetado com marcadores cache_control mais um cache de arquivos de workspace e um cache de rotas, de modo que a estrutura repetida é servida do cache.", "technology": "Injeção de cache_control da Anthropic em sistema e mensagens, passthrough do OpenRouter, cache de arquivos de workspace, cache de rotas e contabilidade de custo cache_read/write.", "load": "28,1M de tokens totais em 57 dias, dos quais ~19,6M foram servidos como cache-read.", "results": "Cerca de 70% dos tokens foram servidos do cache, mantendo o custo combinado em $15,21 por 1M de tokens ($41 de cache-read ante $374 de input novo). Implantação local-first de operador único — a proporção reflete a repetição desta carga; meça a sua." }, "kpis": [ { "metric": "Taxa de acertos de cache", "note": "Proporção de requisições servidas do cache; a alavanca de economia em custo e latência." }, { "metric": "Taxa de falsos acertos", "note": "Com que frequência um acerto 'similar' devolve uma resposta errada ou obsoleta; o risco central de cachear por significado." }, { "metric": "Custo e latência economizados por acerto", "note": "Tokens e tempo evitados nos acertos, a vantagem pela qual você troca o risco de falso acerto." }, { "metric": "Calibração do limiar de similaridade", "note": "Se o limiar equilibra taxa de acertos e falsos acertos; frouxo demais prejudica a qualidade, estrito demais elimina a economia." } ], "failureModes": [ "Falsos acertos: duas consultas similares no espaço de embeddings precisam de respostas distintas, e o cache devolve a errada.", "Obsolescência: as respostas cacheadas ficam desatualizadas enquanto os fatos subjacentes mudam.", "Mau ajuste do limiar: frouxo demais devolve respostas erradas, estrito demais dá quase nenhum acerto.", "Envenenamento de cache: uma resposta ruim é cacheada e depois servida repetidamente." ], "lessons": [ "Ajuste o limiar de similaridade com tráfego real; é o parâmetro decisivo.", "Nunca cacheie onde a atualidade ou a correção sejam críticas sem uma estratégia de invalidação.", "Valide ou amostre os acertos de cache para detectar falsos antes dos usuários.", "Restrinja os caches de forma estreita (por tenant, por contexto) para não vazar a resposta errada entre usuários." ], "faqs": [ { "q": "Como difere de um cache normal?", "a": "Um cache normal casa chaves exatas; um cache semântico casa por significado usando embeddings, então perguntas parafraseadas também acertam." }, { "q": "Qual é o risco principal?", "a": "Um limiar de similaridade frouxo demais devolve uma resposta em cache para uma pergunta que na verdade é distinta. Ajuste o limiar e valide com tráfego real." }, { "q": "Como evito respostas obsoletas?", "a": "Defina TTLs e invalide entradas quando os dados subjacentes mudam; evite armazenar respostas personalizadas ou sensíveis ao tempo." } ] } } }, { "slug": "supervisor-agent", "category": "orchestration", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/patterns/supervisor-agent", "api": "https://santismm.com/api/patterns/supervisor-agent", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "LangGraph (supervisor)", "OpenAI Agents SDK", "Multi-agent frameworks", "Message routing" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" }, { "title": "LangGraph — Multi-agent systems", "url": "https://langchain-ai.github.io/langgraph/concepts/multi_agent/" } ], "related": [ "orchestrator-workers", "routing", "goal-decomposition" ], "locales": { "en": { "name": "Supervisor Agent", "summary": "A supervisor agent is a persistent coordinator that manages a team of specialized sub-agents. It reads the conversation state, decides which specialist should act next, routes messages to it, and integrates returned results toward the goal. Unlike a one-shot decomposer, the supervisor stays in the loop across many turns, delegating by capability and re-planning until the task is done or handed back to the user.", "problem": "A single agent given many tools, instructions, and domains becomes unfocused: its prompt bloats, tool selection degrades, and it confuses unrelated concerns. Real workflows need different expertise at different steps (research, coding, billing, compliance), but no single flat agent reliably picks the right capability at the right moment or keeps long multi-step interactions coherent.", "context": "Use a supervisor when work spans several distinct, reusable specialist capabilities that must collaborate over a multi-turn conversation or loop, when routing decisions depend on evolving state rather than a fixed plan, and when you need a clear, central place to enforce policy, manage handoffs, and observe which agent did what. It fits heterogeneous teams of agents more than uniform parallel workers.", "solution": [ "The supervisor owns the control loop and the shared conversation state. On each turn it inspects the latest messages and goal, then decides whether to answer directly, delegate to a named specialist, or finish. Delegation is by capability: each sub-agent has a declared scope (for example a code agent, a data agent, a knowledge agent), and the supervisor routes the relevant slice of context to the chosen one. The specialist runs its own focused tool loop and returns a result or a request for clarification, which the supervisor records before deciding the next step.", "Control returns to the supervisor after every specialist turn, so it remains the single decision point rather than letting agents call each other freely. The supervisor integrates partial results, resolves conflicts between specialists, decides when a goal is satisfied, and decides when to hand back to the user. Guardrails such as step budgets, allowed-transition rules, and explicit termination conditions keep the loop from cycling. Structured handoff messages and a shared trace make every delegation auditable, so teams can see who was asked to do what and why." ], "components": [ "Supervisor (router/planner)", "Specialist sub-agents with declared scopes", "Shared conversation/state store", "Handoff protocol and message schema", "Step budget and termination guard", "Trace and per-agent observability" ], "benefits": [ "Focused specialists with smaller, cleaner prompts", "Centralized routing and policy enforcement", "Modular agents that can evolve independently", "Clear audit trail of who did what" ], "risks": [ "Infinite or ping-pong handoff loops", "Coordination overhead inflates latency and cost", "Supervisor becomes a routing bottleneck", "Context loss across handoffs degrades quality" ], "whenNot": [ "Single capability handles the whole task", "Fixed parallel fan-out fits better (orchestrator-workers)", "Latency or cost budgets forbid extra hops" ], "examples": [ "Customer support routing across billing, technical, and account specialists", "Software task split among coding, testing, and documentation agents", "Research assistant delegating to search, analysis, and writing agents" ], "kpis": [ { "metric": "Task success / goal-completion rate", "note": "Share of sessions reaching the intended outcome without human rescue; the headline quality signal for the supervisor team." }, { "metric": "Handoffs per resolved task", "note": "Average delegations to completion; watch for upward drift signaling indecision or routing thrash, not richer work." }, { "metric": "Coordination overhead", "note": "Extra tokens, calls, and latency attributable to the supervisor versus a single agent; good means routing earns its cost." }, { "metric": "Routing accuracy", "note": "Fraction of delegations sent to the correct specialist on first try, judged against labeled cases." } ], "failureModes": [ "Two agents hand work back and forth without progress until a budget cuts the loop", "Supervisor mis-routes to the wrong specialist and never recovers the thread", "Critical context is dropped in the handoff, so the specialist solves the wrong problem", "Specialists' partial results conflict and the supervisor merges them incoherently" ], "lessons": [ "Enforce hard step budgets and explicit termination so loops always end", "Make handoffs structured, with intent and scope, not raw message dumps", "Keep specialist scopes narrow and non-overlapping to reduce routing ambiguity", "Instrument every delegation; you cannot debug a multi-agent loop you cannot see" ], "faqs": [ { "q": "How is this different from orchestrator-workers?", "a": "Orchestrator-workers decomposes one task into parallel, often homogeneous worker calls and merges them. A supervisor is a persistent coordinator over heterogeneous specialists across a multi-turn loop, re-deciding routing as state evolves rather than executing a fixed plan." }, { "q": "How do I prevent infinite handoff loops?", "a": "Route control back to the supervisor after each specialist turn, forbid free peer-to-peer calls, set a step or token budget, define allowed transitions, and add explicit termination conditions so the loop cannot cycle indefinitely." }, { "q": "When should a specialist hand back to the supervisor?", "a": "Whenever it finishes its scoped task, needs a capability it does not own, hits ambiguity needing a decision, or detects it is the wrong agent for the request. The supervisor then integrates and picks the next step." } ] }, "es": { "name": "Agente Supervisor", "summary": "Un agente supervisor es un coordinador persistente que gestiona un equipo de subagentes especializados. Lee el estado de la conversación, decide qué especialista debe actuar a continuación, le enruta los mensajes e integra los resultados hacia el objetivo. A diferencia de un descompositor de un solo paso, el supervisor permanece en el bucle durante muchos turnos, delegando por capacidad y replanificando hasta que la tarea se completa o se devuelve al usuario.", "problem": "Un único agente con muchas herramientas, instrucciones y dominios pierde el foco: su prompt se infla, la selección de herramientas se degrada y confunde asuntos no relacionados. Los flujos reales requieren distinta experiencia en cada paso (investigación, código, facturación, cumplimiento), pero ningún agente plano elige de forma fiable la capacidad correcta en el momento correcto ni mantiene coherentes las interacciones largas de varios pasos.", "context": "Usa un supervisor cuando el trabajo abarca varias capacidades especializadas, distintas y reutilizables que deben colaborar en una conversación o bucle de varios turnos, cuando las decisiones de enrutamiento dependen de un estado que evoluciona en lugar de un plan fijo, y cuando necesitas un punto central claro para aplicar políticas, gestionar traspasos y observar qué hizo cada agente. Encaja con equipos heterogéneos de agentes más que con trabajadores paralelos uniformes.", "solution": [ "El supervisor posee el bucle de control y el estado compartido de la conversación. En cada turno inspecciona los últimos mensajes y el objetivo, y decide si responde directamente, delega en un especialista nombrado o termina. La delegación es por capacidad: cada subagente tiene un alcance declarado (por ejemplo un agente de código, uno de datos, uno de conocimiento), y el supervisor enruta al elegido la porción de contexto relevante. El especialista ejecuta su propio bucle de herramientas enfocado y devuelve un resultado o una solicitud de aclaración, que el supervisor registra antes de decidir el siguiente paso.", "El control regresa al supervisor después del turno de cada especialista, de modo que sigue siendo el único punto de decisión en lugar de permitir que los agentes se llamen libremente entre sí. El supervisor integra resultados parciales, resuelve conflictos entre especialistas, decide cuándo se satisface un objetivo y cuándo devolver el control al usuario. Salvaguardas como presupuestos de pasos, reglas de transiciones permitidas y condiciones de terminación explícitas evitan que el bucle se cicle. Mensajes de traspaso estructurados y una traza compartida hacen auditable cada delegación, para que los equipos vean a quién se le pidió qué y por qué." ], "components": [ "Supervisor (enrutador/planificador)", "Subagentes especialistas con alcances declarados", "Almacén compartido de conversación/estado", "Protocolo de traspaso y esquema de mensajes", "Presupuesto de pasos y guardia de terminación", "Traza y observabilidad por agente" ], "benefits": [ "Especialistas enfocados con prompts más pequeños y limpios", "Enrutamiento y aplicación de políticas centralizados", "Agentes modulares que evolucionan de forma independiente", "Rastro de auditoría claro de quién hizo qué" ], "risks": [ "Bucles de traspaso infinitos o de ida y vuelta", "La sobrecarga de coordinación infla latencia y costo", "El supervisor se convierte en cuello de botella de enrutamiento", "La pérdida de contexto en los traspasos degrada la calidad" ], "whenNot": [ "Una sola capacidad resuelve toda la tarea", "Encaja mejor un fan-out paralelo fijo (orchestrator-workers)", "Los presupuestos de latencia o costo prohíben saltos extra" ], "examples": [ "Enrutamiento de soporte al cliente entre especialistas de facturación, técnicos y de cuenta", "Tarea de software repartida entre agentes de código, pruebas y documentación", "Asistente de investigación que delega en agentes de búsqueda, análisis y redacción" ], "kpis": [ { "metric": "Tasa de éxito de tareas / cumplimiento del objetivo", "note": "Proporción de sesiones que alcanzan el resultado previsto sin rescate humano; la señal principal de calidad del equipo supervisor." }, { "metric": "Traspasos por tarea resuelta", "note": "Promedio de delegaciones hasta la finalización; vigila una deriva al alza que señale indecisión o rebote de enrutamiento, no más trabajo útil." }, { "metric": "Sobrecarga de coordinación", "note": "Tokens, llamadas y latencia extra atribuibles al supervisor frente a un solo agente; lo bueno es que el enrutamiento justifique su costo." }, { "metric": "Precisión de enrutamiento", "note": "Fracción de delegaciones enviadas al especialista correcto en el primer intento, evaluada contra casos etiquetados." } ], "failureModes": [ "Dos agentes se devuelven el trabajo sin avanzar hasta que un presupuesto corta el bucle", "El supervisor enruta mal al especialista equivocado y nunca recupera el hilo", "Se pierde contexto crítico en el traspaso, así que el especialista resuelve el problema equivocado", "Los resultados parciales de los especialistas entran en conflicto y el supervisor los integra de forma incoherente" ], "lessons": [ "Aplica presupuestos de pasos estrictos y terminación explícita para que los bucles siempre acaben", "Haz los traspasos estructurados, con intención y alcance, no volcados de mensajes en bruto", "Mantén alcances de especialista estrechos y sin solapamiento para reducir la ambigüedad de enrutamiento", "Instrumenta cada delegación; no puedes depurar un bucle multiagente que no puedes ver" ], "faqs": [ { "q": "¿En qué se diferencia de orchestrator-workers?", "a": "Orchestrator-workers descompone una tarea en llamadas paralelas, a menudo homogéneas, y las fusiona. Un supervisor es un coordinador persistente sobre especialistas heterogéneos a lo largo de un bucle de varios turnos, que vuelve a decidir el enrutamiento a medida que evoluciona el estado en lugar de ejecutar un plan fijo." }, { "q": "¿Cómo evito bucles de traspaso infinitos?", "a": "Devuelve el control al supervisor tras el turno de cada especialista, prohíbe llamadas libres entre pares, fija un presupuesto de pasos o tokens, define transiciones permitidas y añade condiciones de terminación explícitas para que el bucle no se cicle indefinidamente." }, { "q": "¿Cuándo debe un especialista devolver el control al supervisor?", "a": "Siempre que termine su tarea acotada, necesite una capacidad que no posee, encuentre ambigüedad que requiera una decisión, o detecte que es el agente equivocado para la solicitud. El supervisor entonces integra y elige el siguiente paso." } ] }, "pt": { "name": "Agente Supervisor", "summary": "Um agente supervisor é um coordenador persistente que gerencia uma equipe de subagentes especializados. Ele lê o estado da conversa, decide qual especialista deve agir em seguida, roteia mensagens para ele e integra os resultados em direção ao objetivo. Diferente de um decompositor de uma única etapa, o supervisor permanece no laço por muitos turnos, delegando por capacidade e replanejando até a tarefa terminar ou voltar ao usuário.", "problem": "Um único agente com muitas ferramentas, instruções e domínios perde o foco: seu prompt incha, a seleção de ferramentas piora e ele confunde assuntos sem relação. Fluxos reais exigem expertise diferente em cada etapa (pesquisa, código, faturamento, conformidade), mas nenhum agente plano escolhe de forma confiável a capacidade certa no momento certo nem mantém coerentes as interações longas de várias etapas.", "context": "Use um supervisor quando o trabalho abrange várias capacidades especializadas, distintas e reutilizáveis que precisam colaborar em uma conversa ou laço de vários turnos, quando as decisões de roteamento dependem de um estado em evolução em vez de um plano fixo, e quando você precisa de um ponto central claro para aplicar políticas, gerenciar transferências e observar o que cada agente fez. Ele se encaixa em equipes heterogêneas de agentes mais do que em trabalhadores paralelos uniformes.", "solution": [ "O supervisor detém o laço de controle e o estado compartilhado da conversa. A cada turno ele inspeciona as mensagens mais recentes e o objetivo, e então decide se responde diretamente, delega a um especialista nomeado ou encerra. A delegação é por capacidade: cada subagente tem um escopo declarado (por exemplo um agente de código, um de dados, um de conhecimento), e o supervisor roteia ao escolhido a fatia de contexto relevante. O especialista executa seu próprio laço de ferramentas focado e devolve um resultado ou um pedido de esclarecimento, que o supervisor registra antes de decidir o próximo passo.", "O controle volta ao supervisor após o turno de cada especialista, de modo que ele permanece o único ponto de decisão em vez de deixar os agentes se chamarem livremente. O supervisor integra resultados parciais, resolve conflitos entre especialistas, decide quando um objetivo foi satisfeito e quando devolver o controle ao usuário. Salvaguardas como orçamentos de passos, regras de transições permitidas e condições de término explícitas impedem que o laço entre em ciclo. Mensagens de transferência estruturadas e um rastro compartilhado tornam cada delegação auditável, para que as equipes vejam a quem foi pedido o quê e por quê." ], "components": [ "Supervisor (roteador/planejador)", "Subagentes especialistas com escopos declarados", "Repositório compartilhado de conversa/estado", "Protocolo de transferência e esquema de mensagens", "Orçamento de passos e guarda de término", "Rastro e observabilidade por agente" ], "benefits": [ "Especialistas focados com prompts menores e mais limpos", "Roteamento e aplicação de políticas centralizados", "Agentes modulares que evoluem de forma independente", "Trilha de auditoria clara de quem fez o quê" ], "risks": [ "Laços de transferência infinitos ou de vai e volta", "A sobrecarga de coordenação infla latência e custo", "O supervisor vira gargalo de roteamento", "A perda de contexto nas transferências degrada a qualidade" ], "whenNot": [ "Uma única capacidade resolve a tarefa inteira", "Um fan-out paralelo fixo se encaixa melhor (orchestrator-workers)", "Orçamentos de latência ou custo proíbem saltos extras" ], "examples": [ "Roteamento de suporte ao cliente entre especialistas de faturamento, técnicos e de conta", "Tarefa de software dividida entre agentes de código, testes e documentação", "Assistente de pesquisa que delega a agentes de busca, análise e redação" ], "kpis": [ { "metric": "Taxa de sucesso de tarefas / cumprimento do objetivo", "note": "Parcela de sessões que atingem o resultado pretendido sem resgate humano; o principal sinal de qualidade da equipe supervisora." }, { "metric": "Transferências por tarefa resolvida", "note": "Média de delegações até a conclusão; observe uma deriva de alta que sinalize indecisão ou repique de roteamento, e não mais trabalho útil." }, { "metric": "Sobrecarga de coordenação", "note": "Tokens, chamadas e latência extras atribuíveis ao supervisor frente a um único agente; o bom é o roteamento justificar seu custo." }, { "metric": "Acurácia de roteamento", "note": "Fração de delegações enviadas ao especialista correto na primeira tentativa, avaliada contra casos rotulados." } ], "failureModes": [ "Dois agentes devolvem o trabalho um ao outro sem progredir até um orçamento cortar o laço", "O supervisor roteia mal para o especialista errado e nunca recupera o fio", "Contexto crítico é descartado na transferência, então o especialista resolve o problema errado", "Os resultados parciais dos especialistas conflitam e o supervisor os integra de forma incoerente" ], "lessons": [ "Imponha orçamentos de passos rígidos e término explícito para que os laços sempre acabem", "Faça transferências estruturadas, com intenção e escopo, não despejos de mensagens em bruto", "Mantenha escopos de especialista estreitos e sem sobreposição para reduzir a ambiguidade de roteamento", "Instrumente cada delegação; você não consegue depurar um laço multiagente que não consegue ver" ], "faqs": [ { "q": "Como isto difere de orchestrator-workers?", "a": "Orchestrator-workers decompõe uma tarefa em chamadas paralelas, muitas vezes homogêneas, e as funde. Um supervisor é um coordenador persistente sobre especialistas heterogêneos ao longo de um laço de vários turnos, redecidindo o roteamento à medida que o estado evolui em vez de executar um plano fixo." }, { "q": "Como evito laços de transferência infinitos?", "a": "Devolva o controle ao supervisor após o turno de cada especialista, proíba chamadas livres entre pares, defina um orçamento de passos ou tokens, defina transições permitidas e adicione condições de término explícitas para que o laço não entre em ciclo indefinidamente." }, { "q": "Quando um especialista deve devolver o controle ao supervisor?", "a": "Sempre que concluir sua tarefa delimitada, precisar de uma capacidade que não possui, encontrar ambiguidade que exija uma decisão, ou detectar que é o agente errado para o pedido. O supervisor então integra e escolhe o próximo passo." } ] } } }, { "slug": "task-prioritization", "category": "orchestration", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/patterns/task-prioritization", "api": "https://santismm.com/api/patterns/task-prioritization", "evidence": { "evidenceLevel": "production", "confidenceLevel": "low", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Task queues", "Planner agents", "Scheduling / priority queues", "Cost-aware routing" ], "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" }, { "title": "Yao et al. — ReAct (2022)", "url": "https://arxiv.org/abs/2210.03629" } ], "related": [ "goal-decomposition", "supervisor-agent" ], "locales": { "en": { "name": "Task Prioritization", "summary": "Order an agent's candidate tasks by value, urgency, dependencies, and cost instead of processing them first-in-first-out. A scoring function and a priority queue decide what runs next, so limited compute, budget, and time go to the work that matters most. Re-score as state changes, and bound the queue so it cannot grow without limit.", "problem": "An agent that decomposes a goal often ends up with many candidate tasks at once: searches to run, files to read, tools to call, sub-goals to pursue. Processing them in arrival order treats a trivial cleanup step as equal to a blocking, deadline-bound task. Important work waits behind cheap noise, dependencies are violated, and budget is spent on tasks that no longer matter once the situation has changed.", "context": "Use this when an agent or orchestrator holds a backlog of independent or loosely coupled tasks and cannot run them all immediately because of compute, rate-limit, cost, or wall-clock constraints. It fits planner and supervisor architectures where one component chooses what executes next. It assumes you can attach signals — impact, deadline, dependency, cost — to each task, and that priorities may shift as new observations arrive.", "solution": [ "Attach explicit signals to every task: expected impact toward the goal, urgency or deadline, dependency relationships (what must finish first), and estimated cost in tokens, money, or latency. Combine these into a single score with a transparent, auditable function rather than an opaque model judgment. Feed scored tasks into a priority queue so the highest-value ready task runs next. Always respect dependencies first: a task whose prerequisites are unmet is not 'ready' regardless of its score, which keeps the ordering correct and prevents wasted retries.", "Make prioritization dynamic. After each step, re-score affected tasks because new results change impact, deadlines approach, and some tasks become obsolete and can be dropped. Protect against starvation by aging — gradually raising the priority of long-waiting tasks — or by reserving capacity for lower tiers. Bound the backlog with an explicit cap and an admission policy: when the queue is full, reject, merge, or evict the weakest tasks instead of letting it grow without limit. Keep the scoring weights configurable and log why each task was chosen so behavior stays explainable." ], "components": [ "Signal extractor", "Scoring function", "Priority queue", "Dependency resolver", "Re-prioritization loop", "Admission and aging controller" ], "benefits": [ "Limited compute, budget, and time are spent on high-value, time-critical work instead of whatever arrived first.", "Respecting prerequisites avoids wasted retries and rework caused by running tasks before their inputs exist.", "Re-scoring lets the agent abandon now-irrelevant tasks and promote newly urgent ones as the situation evolves.", "Cost-aware scoring and a bounded queue keep token and latency budgets under control rather than open-ended." ], "risks": [ "A wrong weighting or bad cost estimate can systematically starve important work or chase low-value tasks; the formula needs review and calibration.", "Without aging or reserved capacity, low-priority tasks may never run, leaving necessary cleanup or background work permanently undone.", "Over-eager re-scoring can cause the agent to switch focus constantly, paying context-switch cost and never finishing anything.", "If decomposition adds tasks faster than they are completed, an uncapped backlog inflates memory, cost, and planning latency." ], "whenNot": [ "When there are only a handful of similar tasks, FIFO or simple parallelism is simpler and the scoring overhead is not worth it.", "If tasks must run in a fixed sequence dictated by the domain, a static workflow or DAG is clearer than a dynamic priority queue.", "When you can run everything immediately within budget and limits, there is nothing to prioritize and ordering adds needless complexity." ], "examples": [ "An agent gathering evidence prioritizes the searches most likely to resolve open questions and skips redundant queries once a claim is confirmed.", "An operations agent orders remediation steps by blast radius and deadline, handling the customer-facing outage before low-impact warnings.", "A pipeline agent schedules high-value or near-deadline documents first and defers cheap bulk items, while aging prevents the bulk queue from stalling forever." ], "productionEvidence": { "context": "Single-operator, local-first OpenClaw deployment observed over 57 days (161 sessions / 2,776 turns), aggregated from the agent's own trajectory traces.", "scenario": "An autonomous agent is woken on a schedule (heartbeat + cron), with a top-of-hour stagger and a heartbeat cooldown providing back-pressure so jobs don't dogpile.", "technology": "CronService scheduler, heartbeat-runner, a 5-minute top-of-hour stagger, heartbeat-cooldown defer logic, and a low/normal/high priority field on heartbeat outcomes.", "load": "2,801 heartbeat turns + 57 cron turns + 106 user turns over 57 days (heartbeat ~94% of triggers).", "results": "The scheduler sustained roughly fifty autonomous wake-ups per day with stagger and cooldown preventing dogpiling; no schedule-driven failure mode surfaced. Single-operator local-first deployment." }, "kpis": [ { "metric": "Weighted task value completed per unit cost", "note": "Captures whether effort lands on high-impact work; good looks like more goal-relevant value delivered per token or dollar than a FIFO baseline." }, { "metric": "Deadline / SLA adherence on time-critical tasks", "note": "Shows urgency signals are working; good looks like urgent tasks finishing before their deadline most of the time." }, { "metric": "Starvation indicator (max and tail wait time for low-priority tasks)", "note": "Reveals whether aging is effective; good looks like bounded worst-case waits with no task stuck indefinitely." }, { "metric": "Queue depth vs. cap and admission/eviction rate", "note": "Confirms the backlog stays bounded; good looks like depth held under the cap with eviction reserved for genuinely low-value tasks." } ], "failureModes": [ "A high-priority task waits on a low-priority prerequisite that never gets scheduled; the resolver must propagate urgency to blockers.", "Priorities computed once and never refreshed drive decisions on outdated impact or deadline information, so re-scoring must be triggered on relevant state changes.", "Underestimating a task's cost lets it monopolize the budget; estimates need feedback from actual measured consumption.", "An aggressive admission policy drops a task that later turns out to be required, forcing expensive rediscovery; eviction should prefer truly redundant items." ], "lessons": [ "An auditable, configurable formula is easier to debug and tune than an opaque model judgment about what to do next.", "Treat prerequisite completion as a separate readiness check so a high score never lets a task jump ahead of its inputs.", "Add aging or reserved capacity from the start; low-priority background work that never runs becomes a silent correctness gap.", "A hard cap with a clear admission policy is the simplest defense against runaway decomposition inflating cost and latency." ], "faqs": [ { "q": "How is this different from goal decomposition?", "a": "Decomposition produces the tasks; prioritization decides the order in which the resulting tasks are executed. They are complementary: decomposition fills the backlog, prioritization drains it sensibly." }, { "q": "Should the LLM itself score priorities?", "a": "It can propose signals like estimated impact, but combine them with a transparent, auditable function. A deterministic formula over named signals is easier to calibrate, log, and trust than a single opaque ranking call." }, { "q": "How do I stop low-priority tasks from never running?", "a": "Use aging to gradually raise the priority of long-waiting tasks, or reserve a fraction of capacity for lower tiers, and monitor tail wait time to confirm nothing is starved." } ] }, "es": { "name": "Priorización de tareas", "summary": "Ordena las tareas candidatas de un agente por valor, urgencia, dependencias y coste en lugar de procesarlas por orden de llegada. Una función de puntuación y una cola de prioridad deciden qué se ejecuta a continuación, de modo que el cómputo, el presupuesto y el tiempo limitados se dedican al trabajo que más importa. Vuelve a puntuar a medida que cambia el estado y acota la cola para que no crezca sin límite.", "problem": "Un agente que descompone un objetivo suele acabar con muchas tareas candidatas a la vez: búsquedas que ejecutar, archivos que leer, herramientas que invocar, subobjetivos que perseguir. Procesarlas por orden de llegada trata un paso de limpieza trivial igual que una tarea bloqueante y con fecha límite. El trabajo importante espera detrás de ruido barato, se violan dependencias y se gasta presupuesto en tareas que ya no importan una vez que la situación ha cambiado.", "context": "Úsalo cuando un agente u orquestador mantiene una lista pendiente de tareas independientes o débilmente acopladas y no puede ejecutarlas todas de inmediato por restricciones de cómputo, límites de tasa, coste o tiempo de reloj. Encaja en arquitecturas de planificador y supervisor donde un componente elige qué se ejecuta a continuación. Supone que puedes asociar señales —impacto, fecha límite, dependencia, coste— a cada tarea y que las prioridades pueden cambiar a medida que llegan nuevas observaciones.", "solution": [ "Asocia señales explícitas a cada tarea: impacto esperado hacia el objetivo, urgencia o fecha límite, relaciones de dependencia (qué debe terminar primero) y coste estimado en tokens, dinero o latencia. Combínalas en una única puntuación con una función transparente y auditable en lugar de un juicio opaco del modelo. Introduce las tareas puntuadas en una cola de prioridad para que la tarea lista de mayor valor se ejecute a continuación. Respeta siempre primero las dependencias: una tarea cuyos prerrequisitos no se cumplen no está 'lista' sin importar su puntuación, lo que mantiene el orden correcto y evita reintentos desperdiciados.", "Haz que la priorización sea dinámica. Tras cada paso, vuelve a puntuar las tareas afectadas porque los nuevos resultados cambian el impacto, las fechas límite se acercan y algunas tareas quedan obsoletas y pueden descartarse. Protégete contra la inanición mediante envejecimiento —elevando gradualmente la prioridad de las tareas que llevan mucho esperando— o reservando capacidad para los niveles inferiores. Acota la lista pendiente con un límite explícito y una política de admisión: cuando la cola está llena, rechaza, fusiona o expulsa las tareas más débiles en lugar de dejar que crezca sin límite. Mantén configurables los pesos de la puntuación y registra por qué se eligió cada tarea para que el comportamiento siga siendo explicable." ], "components": [ "Extractor de señales", "Función de puntuación", "Cola de prioridad", "Resolutor de dependencias", "Bucle de repriorización", "Controlador de admisión y envejecimiento" ], "benefits": [ "El cómputo, el presupuesto y el tiempo limitados se dedican al trabajo de alto valor y crítico en el tiempo en lugar de a lo que llegó primero.", "Respetar los prerrequisitos evita reintentos y retrabajo causados por ejecutar tareas antes de que existan sus entradas.", "Volver a puntuar permite al agente abandonar tareas ahora irrelevantes y promover las recién urgentes a medida que evoluciona la situación.", "La puntuación consciente del coste y una cola acotada mantienen bajo control los presupuestos de tokens y latencia en lugar de dejarlos abiertos." ], "risks": [ "Una ponderación errónea o una mala estimación de coste puede dejar sin recursos sistemáticamente al trabajo importante o perseguir tareas de bajo valor; la fórmula necesita revisión y calibración.", "Sin envejecimiento ni capacidad reservada, las tareas de baja prioridad pueden no ejecutarse nunca, dejando sin hacer de forma permanente labores de limpieza o de fondo necesarias.", "Volver a puntuar con demasiado afán puede hacer que el agente cambie de foco constantemente, pagando el coste de cambio de contexto sin terminar nada.", "Si la descomposición añade tareas más rápido de lo que se completan, una lista pendiente sin límite infla la memoria, el coste y la latencia de planificación." ], "whenNot": [ "Cuando solo hay un puñado de tareas similares, FIFO o un paralelismo simple es más sencillo y la sobrecarga de puntuación no compensa.", "Si las tareas deben ejecutarse en una secuencia fija dictada por el dominio, un flujo estático o un DAG es más claro que una cola de prioridad dinámica.", "Cuando puedes ejecutar todo de inmediato dentro del presupuesto y los límites, no hay nada que priorizar y el orden añade complejidad innecesaria." ], "examples": [ "Un agente que reúne evidencia prioriza las búsquedas con más probabilidad de resolver preguntas abiertas y omite consultas redundantes una vez confirmada una afirmación.", "Un agente de operaciones ordena los pasos de remediación por radio de impacto y fecha límite, atendiendo la caída visible para el cliente antes que las advertencias de bajo impacto.", "Un agente de canalización programa primero los documentos de alto valor o cercanos a su fecha límite y aplaza los elementos masivos baratos, mientras el envejecimiento evita que la cola masiva se quede atascada para siempre." ], "productionEvidence": { "context": "Despliegue OpenClaw local-first y mono-operador observado durante 57 días (161 sesiones / 2.776 turnos), agregado desde las propias trazas del agente.", "scenario": "Un agente autónomo se despierta de forma programada (heartbeat + cron), con un escalonado al inicio de hora y un cooldown de heartbeat que dan contrapresión para que las tareas no se amontonen.", "technology": "Scheduler CronService, heartbeat-runner, escalonado de 5 min al inicio de hora, lógica de aplazamiento por cooldown y un campo de prioridad bajo/normal/alto en los resultados de heartbeat.", "load": "2.801 turnos de heartbeat + 57 de cron + 106 de usuario en 57 días (heartbeat ~94% de los triggers).", "results": "El scheduler sostuvo unos cincuenta despertares autónomos al día, con escalonado y cooldown evitando el amontonamiento; no apareció ningún fallo derivado de la programación. Despliegue local-first mono-operador." }, "kpis": [ { "metric": "Valor de tarea ponderado completado por unidad de coste", "note": "Capta si el esfuerzo recae en trabajo de alto impacto; lo bueno se parece a entregar más valor relevante para el objetivo por token o dólar que una base FIFO." }, { "metric": "Cumplimiento de fecha límite / SLA en tareas críticas en el tiempo", "note": "Muestra que las señales de urgencia funcionan; lo bueno se parece a que las tareas urgentes terminen antes de su fecha límite la mayor parte de las veces." }, { "metric": "Indicador de inanición (tiempo de espera máximo y de cola larga para tareas de baja prioridad)", "note": "Revela si el envejecimiento es eficaz; lo bueno se parece a esperas en el peor caso acotadas, sin ninguna tarea atascada indefinidamente." }, { "metric": "Profundidad de cola frente al límite y tasa de admisión/expulsión", "note": "Confirma que la lista pendiente se mantiene acotada; lo bueno se parece a una profundidad por debajo del límite con expulsiones reservadas a tareas de valor genuinamente bajo." } ], "failureModes": [ "Una tarea de alta prioridad espera por un prerrequisito de baja prioridad que nunca se programa; el resolutor debe propagar la urgencia a los bloqueadores.", "Prioridades calculadas una vez y nunca refrescadas guían las decisiones con información de impacto o fecha límite caducada, así que la repriorización debe dispararse ante cambios de estado relevantes.", "Subestimar el coste de una tarea le permite monopolizar el presupuesto; las estimaciones necesitan realimentación del consumo realmente medido.", "Una política de admisión agresiva descarta una tarea que luego resulta necesaria, forzando un redescubrimiento costoso; la expulsión debería preferir elementos verdaderamente redundantes." ], "lessons": [ "Una fórmula auditable y configurable es más fácil de depurar y ajustar que un juicio opaco del modelo sobre qué hacer a continuación.", "Trata la finalización de prerrequisitos como una comprobación de disponibilidad separada para que una puntuación alta nunca permita que una tarea se adelante a sus entradas.", "Añade envejecimiento o capacidad reservada desde el principio; el trabajo de fondo de baja prioridad que nunca se ejecuta se convierte en una brecha de corrección silenciosa.", "Un límite duro con una política de admisión clara es la defensa más simple contra una descomposición desbocada que infla el coste y la latencia." ], "faqs": [ { "q": "¿En qué se diferencia esto de la descomposición de objetivos?", "a": "La descomposición produce las tareas; la priorización decide el orden en que se ejecutan las tareas resultantes. Son complementarias: la descomposición llena la lista pendiente y la priorización la vacía con sensatez." }, { "q": "¿Debería el propio LLM puntuar las prioridades?", "a": "Puede proponer señales como el impacto estimado, pero combínalas con una función transparente y auditable. Una fórmula determinista sobre señales con nombre es más fácil de calibrar, registrar y confiar que una única llamada de ranking opaca." }, { "q": "¿Cómo evito que las tareas de baja prioridad no se ejecuten nunca?", "a": "Usa envejecimiento para elevar gradualmente la prioridad de las tareas que llevan mucho esperando, o reserva una fracción de capacidad para los niveles inferiores, y vigila el tiempo de espera de cola larga para confirmar que nada queda sin recursos." } ] }, "pt": { "name": "Priorização de tarefas", "summary": "Ordene as tarefas candidatas de um agente por valor, urgência, dependências e custo em vez de processá-las por ordem de chegada. Uma função de pontuação e uma fila de prioridade decidem o que roda em seguida, de modo que computação, orçamento e tempo limitados vão para o trabalho que mais importa. Repontue conforme o estado muda e limite a fila para que ela não cresça sem controle.", "problem": "Um agente que decompõe um objetivo costuma terminar com muitas tarefas candidatas ao mesmo tempo: buscas a executar, arquivos a ler, ferramentas a chamar, subobjetivos a perseguir. Processá-las por ordem de chegada trata uma etapa de limpeza trivial como igual a uma tarefa bloqueante e com prazo. O trabalho importante espera atrás de ruído barato, dependências são violadas e o orçamento é gasto em tarefas que já não importam quando a situação muda.", "context": "Use isto quando um agente ou orquestrador mantém uma lista de tarefas independentes ou fracamente acopladas e não pode executar todas de imediato por restrições de computação, limites de taxa, custo ou tempo de relógio. Encaixa em arquiteturas de planejador e supervisor onde um componente escolhe o que roda em seguida. Pressupõe que você consegue anexar sinais — impacto, prazo, dependência, custo — a cada tarefa e que as prioridades podem mudar conforme novas observações chegam.", "solution": [ "Anexe sinais explícitos a cada tarefa: impacto esperado rumo ao objetivo, urgência ou prazo, relações de dependência (o que precisa terminar primeiro) e custo estimado em tokens, dinheiro ou latência. Combine-os em uma única pontuação com uma função transparente e auditável em vez de um julgamento opaco do modelo. Alimente as tarefas pontuadas em uma fila de prioridade para que a tarefa pronta de maior valor rode em seguida. Respeite sempre as dependências primeiro: uma tarefa cujos pré-requisitos não foram cumpridos não está 'pronta' independentemente de sua pontuação, o que mantém a ordenação correta e evita repetições desperdiçadas.", "Torne a priorização dinâmica. Após cada etapa, repontue as tarefas afetadas porque novos resultados mudam o impacto, os prazos se aproximam e algumas tarefas ficam obsoletas e podem ser descartadas. Proteja-se contra a inanição por envelhecimento — elevando gradualmente a prioridade de tarefas que esperam há muito tempo — ou reservando capacidade para os níveis inferiores. Limite a lista pendente com um teto explícito e uma política de admissão: quando a fila está cheia, rejeite, mescle ou remova as tarefas mais fracas em vez de deixá-la crescer sem controle. Mantenha os pesos da pontuação configuráveis e registre por que cada tarefa foi escolhida para que o comportamento permaneça explicável." ], "components": [ "Extrator de sinais", "Função de pontuação", "Fila de prioridade", "Resolvedor de dependências", "Laço de repriorização", "Controlador de admissão e envelhecimento" ], "benefits": [ "Computação, orçamento e tempo limitados são gastos em trabalho de alto valor e crítico no tempo em vez do que chegou primeiro.", "Respeitar os pré-requisitos evita repetições e retrabalho causados por executar tarefas antes de suas entradas existirem.", "Repontuar permite que o agente abandone tarefas agora irrelevantes e promova as recém-urgentes conforme a situação evolui.", "A pontuação consciente de custo e uma fila limitada mantêm os orçamentos de tokens e latência sob controle em vez de abertos." ], "risks": [ "Uma ponderação errada ou uma má estimativa de custo pode privar sistematicamente o trabalho importante ou perseguir tarefas de baixo valor; a fórmula precisa de revisão e calibração.", "Sem envelhecimento ou capacidade reservada, tarefas de baixa prioridade podem nunca rodar, deixando permanentemente por fazer limpezas ou trabalho de fundo necessários.", "Repontuar com afinco demais pode fazer o agente trocar de foco constantemente, pagando o custo de troca de contexto sem terminar nada.", "Se a decomposição adiciona tarefas mais rápido do que elas concluem, uma lista pendente sem teto infla a memória, o custo e a latência de planejamento." ], "whenNot": [ "Quando há apenas um punhado de tarefas semelhantes, FIFO ou paralelismo simples é mais simples e a sobrecarga de pontuação não compensa.", "Se as tarefas precisam rodar em uma sequência fixa ditada pelo domínio, um fluxo estático ou um DAG é mais claro do que uma fila de prioridade dinâmica.", "Quando você pode executar tudo de imediato dentro do orçamento e dos limites, não há nada a priorizar e a ordenação adiciona complexidade desnecessária." ], "examples": [ "Um agente que reúne evidências prioriza as buscas com mais chance de resolver perguntas em aberto e pula consultas redundantes uma vez confirmada uma afirmação.", "Um agente de operações ordena as etapas de remediação por raio de impacto e prazo, tratando a indisponibilidade visível ao cliente antes dos alertas de baixo impacto.", "Um agente de pipeline agenda primeiro os documentos de alto valor ou perto do prazo e adia os itens em massa baratos, enquanto o envelhecimento evita que a fila em massa fique travada para sempre." ], "productionEvidence": { "context": "Implantação OpenClaw local-first e de operador único observada por 57 dias (161 sessões / 2.776 turnos), agregada a partir dos próprios rastros do agente.", "scenario": "Um agente autônomo é despertado de forma programada (heartbeat + cron), com escalonamento no início da hora e um cooldown de heartbeat fornecendo contrapressão para que as tarefas não se amontoem.", "technology": "Scheduler CronService, heartbeat-runner, escalonamento de 5 min no início da hora, lógica de adiamento por cooldown e um campo de prioridade baixo/normal/alto nos resultados de heartbeat.", "load": "2.801 turnos de heartbeat + 57 de cron + 106 de usuário em 57 dias (heartbeat ~94% dos gatilhos).", "results": "O scheduler sustentou cerca de cinquenta despertares autônomos por dia, com escalonamento e cooldown evitando o amontoamento; nenhuma falha derivada do agendamento apareceu. Implantação local-first de operador único." }, "kpis": [ { "metric": "Valor de tarefa ponderado concluído por unidade de custo", "note": "Capta se o esforço recai em trabalho de alto impacto; o bom se parece com entregar mais valor relevante ao objetivo por token ou dólar do que uma base FIFO." }, { "metric": "Cumprimento de prazo / SLA em tarefas críticas no tempo", "note": "Mostra que os sinais de urgência funcionam; o bom se parece com tarefas urgentes terminando antes do prazo na maioria das vezes." }, { "metric": "Indicador de inanição (tempo de espera máximo e de cauda para tarefas de baixa prioridade)", "note": "Revela se o envelhecimento é eficaz; o bom se parece com esperas de pior caso limitadas, sem nenhuma tarefa travada indefinidamente." }, { "metric": "Profundidade da fila ante o teto e taxa de admissão/remoção", "note": "Confirma que a lista pendente permanece limitada; o bom se parece com profundidade abaixo do teto e remoções reservadas a tarefas de valor genuinamente baixo." } ], "failureModes": [ "Uma tarefa de alta prioridade espera por um pré-requisito de baixa prioridade que nunca é agendado; o resolvedor deve propagar a urgência aos bloqueadores.", "Prioridades calculadas uma vez e nunca atualizadas guiam decisões com informação de impacto ou prazo vencida, então a repriorização deve ser disparada em mudanças de estado relevantes.", "Subestimar o custo de uma tarefa permite que ela monopolize o orçamento; as estimativas precisam de retorno do consumo realmente medido.", "Uma política de admissão agressiva descarta uma tarefa que depois se revela necessária, forçando uma redescoberta cara; a remoção deveria preferir itens verdadeiramente redundantes." ], "lessons": [ "Uma fórmula auditável e configurável é mais fácil de depurar e ajustar do que um julgamento opaco do modelo sobre o que fazer em seguida.", "Trate a conclusão de pré-requisitos como uma verificação de prontidão separada para que uma pontuação alta nunca deixe uma tarefa passar à frente de suas entradas.", "Adicione envelhecimento ou capacidade reservada desde o início; trabalho de fundo de baixa prioridade que nunca roda vira uma lacuna de correção silenciosa.", "Um teto rígido com uma política de admissão clara é a defesa mais simples contra uma decomposição descontrolada que infla o custo e a latência." ], "faqs": [ { "q": "Como isto difere da decomposição de objetivos?", "a": "A decomposição produz as tarefas; a priorização decide a ordem em que as tarefas resultantes são executadas. Elas são complementares: a decomposição enche a lista pendente e a priorização a esvazia com bom senso." }, { "q": "O próprio LLM deveria pontuar as prioridades?", "a": "Ele pode propor sinais como o impacto estimado, mas combine-os com uma função transparente e auditável. Uma fórmula determinística sobre sinais nomeados é mais fácil de calibrar, registrar e confiar do que uma única chamada de ranking opaca." }, { "q": "Como impeço que tarefas de baixa prioridade nunca rodem?", "a": "Use envelhecimento para elevar gradualmente a prioridade das tarefas que esperam há muito tempo, ou reserve uma fração de capacidade para os níveis inferiores, e monitore o tempo de espera de cauda para confirmar que nada fica sem recursos." } ] } } } ] }