{ "generated": "2026-09-11T20:55:58.260Z", "count": 21, "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": "attributed-memory", "category": "safety", "updated": "2026-08-25", "version": "1.0", "url": "https://santismm.com/en/patterns/attributed-memory", "api": "https://santismm.com/api/patterns/attributed-memory", "canonical_url": "https://santismm.com/en/patterns/attributed-memory", "api_url": "https://santismm.com/api/patterns/attributed-memory", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "medium", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "Vector stores with metadata filtering", "Append-only record stores", "TTL / retention policies", "Provenance metadata schemas", "Audit logging" ], "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "OWASP — LLM01: Prompt Injection", "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/" }, { "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems", "url": "https://atlas.mitre.org/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "long-term-memory", "context-compression", "least-privilege-tooling", "human-approval-gate", "sandboxed-execution" ], "locales": { "en": { "name": "Attributed Memory", "summary": "Store what an agent remembers as records that carry their origin, an owner who can remove them, and a lifetime — never as an anonymous blob of text. Memory is what turns a one-shot attack into one that re-triggers on future, unrelated tasks; attribution is what makes that reversible.", "definition": "Attributed memory is the practice of writing every persistent agent memory as a record with its provenance (where the claim came from and whose authority it carried), a named owner who can delete it, and an expiry — so a false fact can be traced, removed and, failing that, dies on its own.", "problem": "An agent that writes free text into persistent memory cannot tell later which of its memories it was told, which it read from a stranger's web page, and which it inferred. One poisoned write then reappears as trusted context in tasks that have nothing to do with the conversation that planted it.", "context": "Use it wherever memory outlives the session that created it: assistants that remember preferences, agents that accumulate project state, any retrieval store the agent itself writes to. The longer the retention and the more of the corpus the agent authored, the more the memory needs to be a record store rather than a notebook.", "solution": [ "Refuse anonymous writes. Every record carries where the claim came from — the session and turn, the tool or document, and the URL if it came from outside — as structured fields, not as a sentence inside the text.", "Record whose authority the claim carried. A fact the operator configured, one the end user asserted, and one the agent read on a third-party page are three different claims; keep the class explicit so the retrieval path can weight them and a reviewer can sort them.", "Give every record a lifetime, and make the default short. Memory that never expires is memory nobody will ever review, and it is the half-life of a poisoned write that decides how long an attack keeps paying.", "Make removal a first-class operation with a named owner, and make it propagate. Deleting the record is not enough if the claim survives in an embedding, a cached summary or a derived profile.", "Treat the write path as an action. Memory writes change future behaviour, so they go through the same authorisation and logging as any other write — not through a side door because the destination happens to be a file.", "Never let retrieved memory re-enter the prompt as instruction. It arrives as data with an origin attached, and a record whose origin is a third party is treated exactly as untrusted input from that party." ], "components": [ "A record schema with origin, authority class, timestamp and expiry as required fields.", "A write path that rejects a record missing any of them.", "A retrieval path that returns the origin alongside the content, so the model and the reviewer see the same thing.", "A removal operation that propagates to embeddings, summaries and any derived artefact.", "An expiry process, plus evidence that it ran.", "An audit log of memory writes and removals, separate from the conversation log." ], "benefits": [ "Makes memory poisoning reversible: you can find the write, see where it came from and remove everything derived from it.", "Turns 'what does this agent believe about me?' into a question with an answer a person can read.", "Lets retrieval weight a claim by its origin rather than by how confidently the text was written.", "Satisfies the retention and erasure obligations that apply to anything persisted about a person, without a separate mechanism bolted on later." ], "risks": [ "Provenance theatre: an origin field that always says 'agent', which documents nothing and looks like a control.", "Compaction laundering — the most common way attribution dies. Summarising ten attributed records into one paragraph produces an unattributed claim that now looks like consensus.", "Partial deletion: the primary record goes, the vector stays, and the claim keeps being retrieved.", "Over-expiry destroying the continuity the memory existed for, which pushes people to disable expiry entirely." ], "whenNot": [ "Single-session agents with no persistence: there is no memory to attribute, and the ceremony buys nothing.", "When the store is a cache of your own already-governed system of record — attribute the source system once, not every derived row.", "When the overhead would push operators to keep the real notes outside the system, which is strictly worse than an imperfect record inside it." ], "examples": [ "An assistant that writes 'prefers metric units'. The record carries the session id and the turn where the user said it, so a wrong preference can be traced to the sentence that caused it and removed.", "A research agent that reads a third-party page and stores a claim tagged 'observed at that URL, on that date', never as a fact. When the same claim is retrieved months later, its origin travels with it.", "A support agent whose memory records expire in 90 days by default, with a longer lifetime only for entries a human explicitly confirmed — so the unreviewed majority ages out and the reviewed minority persists." ], "kpis": [ { "metric": "Attributed write share", "note": "Share of memory records carrying a machine-readable origin. Below 100% the store cannot answer where a claim came from, which is the whole control." }, { "metric": "Median record age", "note": "How old the memory in play actually is. A rising median with no removals means the store is accumulating rather than being curated." }, { "metric": "Deletion propagation lag", "note": "Time between removing a record and the claim stopping being retrievable from every derived artefact. The window in which a deleted claim still acts." }, { "metric": "Expired-on-schedule share", "note": "Share of records that reached their expiry and were actually removed. Evidence the lifetime is real rather than declared." } ], "failureModes": [ "Delayed-action poisoning: a false fact planted in one conversation surfaces in an unrelated task weeks later, where nothing in the context explains why the agent believes it.", "Summary survival: the record is deleted, the compacted summary that absorbed it is not, and the claim outlives its own source.", "Shadow index: the embedding of a removed record stays searchable, so the delete succeeded everywhere the auditor looked and nowhere it mattered.", "Identity bleed: memory keyed loosely enough that one user's record is retrieved for another, turning a memory design flaw into a disclosure." ], "lessons": [ "Attribution is cheap at write time and impossible to reconstruct later. The field has to exist before the claim does.", "Every compaction step is an attribution boundary. If the summariser cannot carry origins forward, it is producing new unsourced claims.", "An expiry nobody has ever seen fire is a policy, not a control.", "Deletion is only as complete as the derived artefact you forgot about." ], "faqs": [ { "q": "Isn't this just retention policy with extra steps?", "a": "Retention answers when data goes. Attribution answers where a claim came from and who may remove it, which is what you need the moment a memory turns out to be wrong rather than merely old. The two are complementary: without expiry, attribution accumulates; without attribution, expiry deletes evidence you never understood." }, { "q": "The agent writes its own memories. Whose authority do those carry?", "a": "Its own, and that is the class worth naming. An agent-inferred claim is weaker than an operator-configured one and should be retrievable as such — otherwise the model's own guesses come back later indistinguishable from configuration." }, { "q": "How do we keep provenance through summarisation?", "a": "Either the summary carries the union of its sources' origins, or it is written as a new agent-inferred record pointing at the ones it replaced. What cannot happen is the summary quietly becoming an unsourced fact, because that is the step where poisoning becomes permanent." } ] }, "es": { "name": "Memoria atribuida", "summary": "Guarda lo que un agente recuerda como registros que llevan su origen, un responsable que puede borrarlos y una caducidad — nunca como un bloque de texto anónimo. La memoria es lo que convierte un ataque de una vez en uno que vuelve a dispararse en tareas futuras que no tienen nada que ver; la atribución es lo que lo hace reversible.", "definition": "La memoria atribuida es la práctica de escribir cada recuerdo persistente de un agente como un registro con su procedencia (de dónde salió la afirmación y con qué autoridad), un responsable con nombre que puede borrarlo y una caducidad — para que un dato falso se pueda rastrear, quitar y, si nadie lo quita, muera solo.", "problem": "Un agente que escribe texto libre en su memoria persistente no puede distinguir después qué recuerdos le dijeron, cuáles leyó en la página web de un desconocido y cuáles dedujo. Una sola escritura envenenada reaparece como contexto de confianza en tareas que no tienen nada que ver con la conversación que la plantó.", "context": "Úsalo siempre que la memoria sobreviva a la sesión que la creó: asistentes que recuerdan preferencias, agentes que acumulan estado de un proyecto, cualquier almacén de recuperación en el que escriba el propio agente. Cuanto más larga la retención y más parte del corpus haya escrito el agente, más necesita la memoria ser un almacén de registros y no un cuaderno.", "solution": [ "Rechaza las escrituras anónimas. Cada registro lleva de dónde salió la afirmación — la sesión y el turno, la herramienta o el documento, y la URL si vino de fuera — en campos estructurados, no en una frase dentro del texto.", "Anota con qué autoridad venía la afirmación. Un dato que configuró el operador, uno que afirmó el usuario final y uno que el agente leyó en una página ajena son tres afirmaciones distintas; deja la clase explícita para que la recuperación pueda ponderarlas y una persona pueda ordenarlas.", "Dale caducidad a cada registro, y que la de partida sea corta. La memoria que no caduca nunca es memoria que nadie va a revisar, y es la vida media de una escritura envenenada la que decide cuánto tiempo sigue rentando el ataque.", "Haz del borrado una operación de primera con un responsable con nombre, y que se propague. Borrar el registro no basta si la afirmación sobrevive en un embedding, en un resumen cacheado o en un perfil derivado.", "Trata el camino de escritura como una acción. Escribir en memoria cambia el comportamiento futuro, así que pasa por la misma autorización y el mismo registro que cualquier otra escritura — no por una puerta lateral porque el destino resulte ser un fichero.", "Nunca dejes que la memoria recuperada vuelva al prompt como instrucción. Llega como dato con un origen pegado, y un registro cuyo origen es un tercero se trata exactamente como entrada no confiable de ese tercero." ], "components": [ "Un esquema de registro con origen, clase de autoridad, marca de tiempo y caducidad como campos obligatorios.", "Un camino de escritura que rechaza un registro al que le falte cualquiera de ellos.", "Un camino de recuperación que devuelve el origen junto al contenido, para que el modelo y quien revisa vean lo mismo.", "Una operación de borrado que se propaga a embeddings, resúmenes y cualquier artefacto derivado.", "Un proceso de caducidad, y pruebas de que se ejecutó.", "Un registro de auditoría de escrituras y borrados de memoria, aparte del registro de conversación." ], "benefits": [ "Hace reversible el envenenamiento de memoria: puedes encontrar la escritura, ver de dónde salió y quitar todo lo derivado de ella.", "Convierte «¿qué cree este agente sobre mí?» en una pregunta con una respuesta que una persona puede leer.", "Permite que la recuperación pondere una afirmación por su origen y no por lo seguro que sonaba el texto.", "Cumple las obligaciones de retención y supresión que se aplican a cualquier dato persistido sobre una persona, sin un mecanismo aparte pegado con posterioridad." ], "risks": [ "Procedencia de teatro: un campo de origen que siempre dice «agente», que no documenta nada y parece un control.", "Blanqueo por compactación — la forma más común de que muera la atribución. Resumir diez registros atribuidos en un párrafo produce una afirmación sin origen que ahora parece consenso.", "Borrado parcial: se va el registro principal, se queda el vector, y la afirmación se sigue recuperando.", "Caducar de más y destruir la continuidad para la que existía la memoria, lo que empuja a desactivar la caducidad del todo." ], "whenNot": [ "Agentes de una sola sesión sin persistencia: no hay memoria que atribuir y la ceremonia no compra nada.", "Cuando el almacén es una caché de tu propio sistema de registro ya gobernado — atribuye el sistema de origen una vez, no cada fila derivada.", "Cuando el coste empujaría a los operadores a llevar las notas de verdad fuera del sistema, que es estrictamente peor que un registro imperfecto dentro." ], "examples": [ "Un asistente que escribe «prefiere unidades métricas». El registro lleva el id de sesión y el turno en el que el usuario lo dijo, así que una preferencia equivocada se puede rastrear hasta la frase que la causó y quitarse.", "Un agente de investigación que lee una página ajena y guarda una afirmación etiquetada «observado en esa URL, en esa fecha», nunca como un hecho. Cuando la misma afirmación se recupera meses después, su origen viaja con ella.", "Un agente de soporte cuyos registros de memoria caducan a los 90 días por defecto, con una vida más larga solo para las entradas que una persona confirmó explícitamente — así envejece y desaparece la mayoría sin revisar y persiste la minoría revisada." ], "kpis": [ { "metric": "Proporción de escrituras atribuidas", "note": "Cuántos registros llevan un origen legible por máquina. Por debajo del 100% el almacén no puede responder de dónde salió una afirmación, que es el control entero." }, { "metric": "Edad mediana del registro", "note": "Qué antigüedad tiene de verdad la memoria en juego. Una mediana que sube sin borrados significa que el almacén acumula en vez de curarse." }, { "metric": "Retraso de propagación del borrado", "note": "Tiempo entre quitar un registro y que la afirmación deje de ser recuperable desde cualquier artefacto derivado. La ventana en la que una afirmación borrada sigue actuando." }, { "metric": "Proporción caducada a tiempo", "note": "Cuántos registros llegaron a su caducidad y se quitaron de verdad. La prueba de que la vida útil es real y no declarada." } ], "failureModes": [ "Envenenamiento de acción retardada: un dato falso plantado en una conversación aparece semanas después en una tarea sin relación, donde nada del contexto explica por qué el agente lo cree.", "Supervivencia por resumen: se borra el registro, no el resumen compactado que lo absorbió, y la afirmación sobrevive a su propia fuente.", "Índice en la sombra: el embedding de un registro quitado sigue siendo buscable, así que el borrado funcionó en todos los sitios donde miró el auditor y en ninguno donde importaba.", "Fuga de identidad: memoria indexada con una clave tan laxa que el registro de un usuario se recupera para otro, convirtiendo un fallo de diseño de memoria en una divulgación." ], "lessons": [ "La atribución es barata al escribir e imposible de reconstruir después. El campo tiene que existir antes que la afirmación.", "Cada paso de compactación es una frontera de atribución. Si el resumidor no sabe arrastrar los orígenes, está produciendo afirmaciones nuevas sin fuente.", "Una caducidad que nadie ha visto dispararse es una política, no un control.", "Un borrado es tan completo como el artefacto derivado del que te olvidaste." ], "faqs": [ { "q": "¿No es esto una política de retención con pasos de más?", "a": "La retención responde cuándo se va el dato. La atribución responde de dónde salió una afirmación y quién puede quitarla, que es lo que necesitas en cuanto un recuerdo resulta estar equivocado y no simplemente viejo. Son complementarias: sin caducidad la atribución se acumula; sin atribución la caducidad borra pruebas que nunca entendiste." }, { "q": "El agente escribe sus propios recuerdos. ¿Qué autoridad llevan?", "a": "La suya, y esa es la clase que merece nombre. Una afirmación deducida por el agente es más débil que una configurada por el operador y debería poder recuperarse como tal — si no, las conjeturas del propio modelo vuelven después indistinguibles de la configuración." }, { "q": "¿Cómo mantenemos la procedencia a través del resumen?", "a": "O el resumen lleva la unión de los orígenes de sus fuentes, o se escribe como un registro nuevo deducido por el agente que apunta a los que sustituye. Lo que no puede pasar es que el resumen se convierta en silencio en un hecho sin fuente, porque ese es el paso en el que el envenenamiento se vuelve permanente." } ] }, "pt": { "name": "Memória atribuída", "summary": "Guarde o que um agente lembra como registros que carregam sua origem, um responsável que pode removê-los e um prazo de validade — nunca como um bloco de texto anônimo. A memória é o que transforma um ataque de uma vez só em um que volta a disparar em tarefas futuras sem nenhuma relação; a atribuição é o que torna isso reversível.", "definition": "Memória atribuída é a prática de escrever cada lembrança persistente de um agente como um registro com sua procedência (de onde veio a afirmação e com que autoridade), um responsável nomeado que pode apagá-lo e um prazo de validade — para que um fato falso possa ser rastreado, removido e, se ninguém o remover, morra sozinho.", "problem": "Um agente que escreve texto livre na memória persistente não consegue distinguir depois quais lembranças lhe contaram, quais leu na página web de um desconhecido e quais deduziu. Uma única escrita envenenada reaparece como contexto confiável em tarefas que não têm nada a ver com a conversa que a plantou.", "context": "Use sempre que a memória sobreviver à sessão que a criou: assistentes que lembram preferências, agentes que acumulam estado de um projeto, qualquer armazenamento de recuperação em que o próprio agente escreva. Quanto mais longa a retenção e quanto mais do corpus o agente tiver escrito, mais a memória precisa ser um armazenamento de registros e não um caderno.", "solution": [ "Recuse escritas anônimas. Cada registro carrega de onde veio a afirmação — a sessão e o turno, a ferramenta ou o documento, e a URL se veio de fora — em campos estruturados, não em uma frase dentro do texto.", "Anote com que autoridade a afirmação veio. Um fato que o operador configurou, um que o usuário final afirmou e um que o agente leu em uma página de terceiros são três afirmações diferentes; deixe a classe explícita para que a recuperação possa ponderá-las e uma pessoa possa ordená-las.", "Dê prazo de validade a cada registro, e que o padrão seja curto. Memória que nunca expira é memória que ninguém vai revisar, e é a meia-vida de uma escrita envenenada que decide por quanto tempo o ataque continua rendendo.", "Faça da remoção uma operação de primeira classe com um responsável nomeado, e que ela se propague. Apagar o registro não basta se a afirmação sobrevive em um embedding, em um resumo em cache ou em um perfil derivado.", "Trate o caminho de escrita como uma ação. Escrever na memória muda o comportamento futuro, então passa pela mesma autorização e pelo mesmo registro que qualquer outra escrita — não por uma porta lateral porque o destino é um arquivo.", "Nunca deixe a memória recuperada voltar ao prompt como instrução. Ela chega como dado com uma origem anexada, e um registro cuja origem é um terceiro é tratado exatamente como entrada não confiável desse terceiro." ], "components": [ "Um esquema de registro com origem, classe de autoridade, marca de tempo e validade como campos obrigatórios.", "Um caminho de escrita que rejeita um registro ao qual falte qualquer um deles.", "Um caminho de recuperação que devolve a origem junto com o conteúdo, para que o modelo e quem revisa vejam a mesma coisa.", "Uma operação de remoção que se propaga a embeddings, resumos e qualquer artefato derivado.", "Um processo de expiração, mais evidências de que ele rodou.", "Um log de auditoria de escritas e remoções de memória, separado do log de conversa." ], "benefits": [ "Torna reversível o envenenamento de memória: dá para achar a escrita, ver de onde veio e remover tudo o que dela derivou.", "Transforma “o que este agente acredita sobre mim?” em uma pergunta com uma resposta que uma pessoa consegue ler.", "Permite que a recuperação pondere uma afirmação pela origem e não pela segurança com que o texto foi escrito.", "Cumpre as obrigações de retenção e eliminação que se aplicam a qualquer dado persistido sobre uma pessoa, sem um mecanismo separado colado depois." ], "risks": [ "Procedência de teatro: um campo de origem que diz sempre “agente”, que não documenta nada e parece um controle.", "Lavagem por compactação — a forma mais comum de a atribuição morrer. Resumir dez registros atribuídos em um parágrafo produz uma afirmação sem origem que agora parece consenso.", "Remoção parcial: some o registro principal, fica o vetor, e a afirmação continua sendo recuperada.", "Expirar demais e destruir a continuidade para a qual a memória existia, o que empurra a desativar a expiração por completo." ], "whenNot": [ "Agentes de sessão única sem persistência: não há memória a atribuir e a cerimônia não compra nada.", "Quando o armazenamento é um cache do seu próprio sistema de registro já governado — atribua o sistema de origem uma vez, não cada linha derivada.", "Quando o custo empurraria os operadores a manter as anotações reais fora do sistema, o que é estritamente pior do que um registro imperfeito dentro dele." ], "examples": [ "Um assistente que escreve “prefere unidades métricas”. O registro carrega o id da sessão e o turno em que o usuário disse isso, então uma preferência errada pode ser rastreada até a frase que a causou e removida.", "Um agente de pesquisa que lê uma página de terceiros e guarda uma afirmação marcada “observado naquela URL, naquela data”, nunca como um fato. Quando a mesma afirmação é recuperada meses depois, sua origem viaja com ela.", "Um agente de suporte cujos registros de memória expiram em 90 dias por padrão, com vida mais longa apenas para entradas que uma pessoa confirmou explicitamente — assim a maioria não revisada envelhece e sai, e a minoria revisada permanece." ], "kpis": [ { "metric": "Proporção de escritas atribuídas", "note": "Quantos registros carregam uma origem legível por máquina. Abaixo de 100% o armazenamento não consegue responder de onde veio uma afirmação, que é o controle inteiro." }, { "metric": "Idade mediana do registro", "note": "Que antiguidade a memória em jogo realmente tem. Uma mediana que sobe sem remoções significa que o armazenamento acumula em vez de ser curado." }, { "metric": "Atraso de propagação da remoção", "note": "Tempo entre remover um registro e a afirmação deixar de ser recuperável de qualquer artefato derivado. A janela em que uma afirmação removida ainda age." }, { "metric": "Proporção expirada no prazo", "note": "Quantos registros chegaram à validade e foram de fato removidos. A prova de que o prazo é real e não apenas declarado." } ], "failureModes": [ "Envenenamento de ação retardada: um fato falso plantado em uma conversa aparece semanas depois em uma tarefa sem relação, onde nada no contexto explica por que o agente acredita nele.", "Sobrevivência por resumo: o registro é apagado, o resumo compactado que o absorveu não, e a afirmação sobrevive à própria fonte.", "Índice na sombra: o embedding de um registro removido continua pesquisável, então a remoção funcionou em todos os lugares onde o auditor olhou e em nenhum onde importava.", "Vazamento de identidade: memória indexada por uma chave tão frouxa que o registro de um usuário é recuperado para outro, transformando uma falha de projeto de memória em uma divulgação." ], "lessons": [ "A atribuição é barata na escrita e impossível de reconstruir depois. O campo precisa existir antes da afirmação.", "Cada passo de compactação é uma fronteira de atribuição. Se o resumidor não sabe carregar as origens adiante, está produzindo afirmações novas sem fonte.", "Uma expiração que ninguém nunca viu disparar é uma política, não um controle.", "Uma remoção é tão completa quanto o artefato derivado de que você esqueceu." ], "faqs": [ { "q": "Isso não é política de retenção com passos a mais?", "a": "A retenção responde quando o dado sai. A atribuição responde de onde veio uma afirmação e quem pode removê-la, que é o que você precisa no momento em que uma lembrança se revela errada e não apenas velha. As duas são complementares: sem expiração a atribuição acumula; sem atribuição a expiração apaga evidências que você nunca entendeu." }, { "q": "O agente escreve as próprias lembranças. Que autoridade elas carregam?", "a": "A dele, e essa é a classe que merece nome. Uma afirmação deduzida pelo agente é mais fraca que uma configurada pelo operador e deveria ser recuperável como tal — caso contrário, os palpites do próprio modelo voltam depois indistinguíveis da configuração." }, { "q": "Como manter a procedência através do resumo?", "a": "Ou o resumo carrega a união das origens de suas fontes, ou é escrito como um registro novo deduzido pelo agente apontando para os que substitui. O que não pode acontecer é o resumo virar em silêncio um fato sem fonte, porque esse é o passo em que o envenenamento se torna permanente." } ] }, "fr": { "name": "Mémoire attribuée", "summary": "Stockez ce dont un agent se souvient sous forme d'enregistrements indiquant leur origine, un propriétaire capable de les supprimer et une durée de vie — jamais sous la forme d'un bloc de texte anonyme. La mémoire est ce qui transforme une attaque ponctuelle en une attaque qui se déclenche à nouveau sur des tâches futures et non liées ; l'attribution est ce qui rend cela réversible.", "definition": "La mémoire attribuée est la pratique consistant à écrire chaque mémoire persistante d'un agent sous forme d'enregistrement avec sa provenance (d'où provient l'affirmation et de quelle autorité elle émane), un propriétaire désigné qui peut la supprimer et une expiration — de sorte qu'un fait erroné puisse être tracé, supprimé et, à défaut, disparaisse de lui-même.", "problem": "Un agent qui écrit du texte libre dans une mémoire persistante ne peut pas savoir plus tard quelles mémoires lui ont été dictées, lesquelles ont été lues sur la page web d'un inconnu, et lesquelles ont été déduites. Une seule écriture empoisonnée réapparaît alors comme un contexte de confiance dans des tâches qui n'ont rien à voir avec la conversation qui l'a implantée.", "context": "Utilisez-la partout où la mémoire survit à la session qui l'a créée : assistants qui mémorisent des préférences, agents qui accumulent l'état d'un projet, tout espace de stockage de récupération dans lequel l'agent lui-même écrit. Plus la rétention est longue et plus le corpus rédigé par l'agent est important, plus la mémoire doit être un stockage d'enregistrements structurés plutôt qu'un bloc-notes.", "solution": [ "Refusez les écritures anonymes. Chaque enregistrement indique d'où provient l'affirmation — la session et le tour de parole, l'outil ou le document, et l'URL si elle provient de l'extérieur — sous forme de champs structurés, et non de phrase au sein du texte.", "Enregistrez l'autorité dont émane l'affirmation. Un fait configuré par l'opérateur, un fait affirmé par l'utilisateur final et un fait lu par l'agent sur une page tierce sont trois affirmations différentes ; gardez la classe explicite afin que le chemin de récupération puisse les pondérer et qu'un réviseur puisse les trier.", "Attribuez une durée de vie à chaque enregistrement, et définissez-la par défaut comme courte. Une mémoire qui n'expire jamais est une mémoire que personne ne révisera, et c'est la demi-vie d'une écriture empoisonnée qui détermine combien de temps une attaque reste efficace.", "Faites de la suppression une opération de premier ordre avec un propriétaire désigné, et assurez sa propagation. Supprimer l'enregistrement ne suffit pas si l'affirmation survit dans un plongement (embedding), un résumé en cache ou un profil dérivé.", "Traitez le chemin d'écriture comme une action. Les écritures en mémoire modifient le comportement futur, elles doivent donc passer par les mêmes processus d'autorisation et de journalisation que toute autre écriture — et non par une porte dérobée sous prétexte que la destination s'avère être un fichier.", "Ne laissez jamais une mémoire récupérée réintégrer le prompt sous forme d'instruction. Elle arrive en tant que donnée accompagnée d'une origine, et un enregistrement dont l'origine est un tiers est traité exactement comme une entrée non fiable provenant de ce tiers." ], "components": [ "Un schéma d'enregistrement contenant l'origine, la classe d'autorité, l'horodatage et l'expiration comme champs obligatoires.", "Un chemin d'écriture qui rejette tout enregistrement auquel l'un de ces éléments fait défaut.", "Un chemin de récupération qui renvoie l'origine aux côtés du contenu, afin que le modèle et le réviseur voient la même chose.", "Une opération de suppression qui se propage aux plongements (embeddings), aux résumés et à tout artefact dérivé.", "Un processus d'expiration, accompagné de la preuve de son exécution.", "Un journal d'audit des écritures et des suppressions en mémoire, distinct du journal de conversation." ], "benefits": [ "Rend l'empoisonnement de la mémoire réversible : vous pouvez retrouver l'écriture, voir d'où elle provient et supprimer tout ce qui en découle.", "Transforme la question « que croit cet agent à mon sujet ? » en une question dotée d'une réponse lisible par un humain.", "Permet à la récupération de pondérer une affirmation en fonction de son origine plutôt que du niveau d'assurance avec lequel le texte a été rédigé.", "Satisfait aux obligations de conservation et d'effacement applicables à toute donnée persistante concernant une personne, sans nécessiter de mécanisme distinct greffé ultérieurement." ], "risks": [ "Le simulacre de provenance : un champ d'origine qui indique systématiquement « agent », ce qui ne documente rien et donne seulement l'illusion d'un contrôle.", "Le blanchiment par compaction — la manière la plus courante dont l'attribution disparaît. Résumer dix enregistrements attribués en un seul paragraphe produit une affirmation non attribuée qui ressemble désormais à un consensus.", "La suppression partielle : l'enregistrement principal disparaît, le vecteur reste, et l'affirmation continue d'être récupérée.", "Une expiration excessive détruisant la continuité pour laquelle la mémoire existait, ce qui pousse les utilisateurs à désactiver complètement l'expiration." ], "whenNot": [ "Agents à session unique sans persistance : il n'y a pas de mémoire à attribuer, et ce formalisme n'apporte rien.", "Lorsque le stockage est un cache de votre propre système d'enregistrement déjà gouverné — attribuez le système source une seule fois, et non chaque ligne dérivée.", "Lorsque la surcharge inciterait les opérateurs à conserver les véritables notes en dehors du système, ce qui est bien pire qu'un enregistrement imparfait à l'intérieur de celui-ci." ], "examples": [ "Un assistant qui écrit « préfère les unités métriques ». L'enregistrement contient l'ID de session et le tour de parole où l'utilisateur l'a mentionné, de sorte qu'une mauvaise préférence peut être tracée jusqu'à la phrase qui l'a causée et supprimée.", "Un agent de recherche qui lit une page tierce et stocke une affirmation étiquetée « observée à cette URL, à cette date », jamais comme un fait établi. Lorsque la même affirmation est récupérée des mois plus tard, son origine l'accompagne.", "Un agent de support dont les enregistrements en mémoire expirent par défaut au bout de 90 jours, avec une durée de vie plus longue uniquement pour les entrées explicitement confirmées par un humain — de sorte que la majorité non révisée expire et que la minorité révisée persiste." ], "kpis": [ { "metric": "Part des écritures attribuées", "note": "Part des enregistrements en mémoire portant une origine lisible par machine. En dessous de 100 %, le stockage ne peut pas indiquer d'où provient une affirmation, ce qui annule l'intérêt même du contrôle." }, { "metric": "Âge médian des enregistrements", "note": "L'âge réel de la mémoire exploitée. Une médiane en hausse sans suppressions signifie que le stockage accumule les données plutôt que d'être géré." }, { "metric": "Délai de propagation de la suppression", "note": "Temps écoulé entre la suppression d'un enregistrement et le moment où l'affirmation cesse d'être récupérable à partir de tout artefact dérivé. La fenêtre durant laquelle une affirmation supprimée continue d'agir." }, { "metric": "Part des expirations respectant le calendrier", "note": "Part des enregistrements ayant atteint leur expiration et ayant été effectivement supprimés. Preuve que la durée de vie est réelle et non simplement déclarée." } ], "failureModes": [ "Empoisonnement à retardement : un fait erroné implanté dans une conversation refait surface dans une tâche non liée des semaines plus tard, sans que rien dans le contexte n'explique pourquoi l'agent y croit.", "Survie dans le résumé : l'enregistrement est supprimé, mais pas le résumé compacté qui l'a absorbé, et l'affirmation survit à sa propre source.", "Index fantôme : le plongement (embedding) d'un enregistrement supprimé reste interrogeable, de sorte que la suppression a réussi partout où l'auditeur a regardé, mais nulle part où cela importait.", "Fuite d'identité : une mémoire indexée de manière trop lâche, de sorte que l'enregistrement d'un utilisateur est récupéré pour un autre, transformant un défaut de conception de la mémoire en une divulgation de données." ], "lessons": [ "L'attribution is peu coûteuse au moment de l'écriture et impossible à reconstruire plus tard. Le champ doit exister avant l'affirmation.", "Chaque étape de compaction est une frontière d'attribution. Si le module de résumé ne peut pas transmettre les origines, il produit de nouvelles affirmations sans source.", "Une expiration que personne n'a jamais vue se déclencher est une politique, pas un contrôle.", "La suppression n'est complète qu'à la mesure de l'artefact dérivé que vous avez oublié." ], "faqs": [ { "q": "N'est-ce pas simplement une politique de conservation avec des étapes supplémentaires ?", "a": "La conservation détermine quand les données disparaissent. L'attribution détermine d'où provient une affirmation et qui peut la supprimer, ce qui est indispensable dès lors qu'une mémoire s'avère erronée et non pas seulement ancienne. Les deux sont complémentaires : sans expiration, l'attribution s'accumule ; sans attribution, l'expiration supprime des preuves que vous n'avez jamais comprises." }, { "q": "L'agent écrit ses propres mémoires. De quelle autorité émanent-elles ?", "a": "La sienne, et c'est précisément la classe qu'il convient de nommer. Une affirmation déduite par l'agent est plus faible qu'une affirmation configurée par l'opérateur et doit pouvoir être récupérée comme telle — sinon, les propres suppositions du modèle reviennent plus tard sans distinction possible de la configuration." }, { "q": "Comment conserver la provenance à travers la production de résumés ?", "a": "Soit le résumé porte l'union des origines de ses sources, soit il est écrit comme un nouvel enregistrement déduit par l'agent pointant vers ceux qu'il a remplacés. Ce qui ne doit pas se produire, c'est que le résumé devienne discrètement un fait sans source, car c'est à cette étape que l'empoisonnement devient permanent." } ] }, "de": { "name": "Attributierter Speicher", "summary": "Speichern Sie das, woran sich ein Agent erinnert, als Datensätze, die ihre Herkunft, einen Eigentümer, der sie entfernen kann, und eine Lebensdauer enthalten – niemals als anonymen Text-Blob. Das Gedächtnis macht aus einem One-Shot-Angriff einen Angriff, der bei zukünftigen, nicht zusammenhängenden Aufgaben erneut ausgelöst wird; die Attribuierung macht dies umkehrbar.", "definition": "Attributierter Speicher bezeichnet die Praxis, jedes persistente Gedächtnis eines Agenten als Datensatz mit seiner Provenienz (woher die Behauptung stammt und wessen Autorität sie besaß), einem namentlich genannten Eigentümer, der sie löschen kann, und einem Ablaufdatum zu schreiben – so dass eine Falschinformation zurückverfolgt, entfernt werden kann und, falls das fehlschlägt, von selbst erlischt.", "problem": "Ein Agent, der Freitext in das persistente Gedächtnis schreibt, kann später nicht mehr unterscheiden, welche seiner Erinnerungen ihm mitgeteilt wurden, welche er auf der Webseite eines Fremden gelesen hat und welche er selbst geschlussfolgert hat. Ein einziger manipulierter Schreibvorgang (Poisoned Write) taucht dann als vertrauenswürdiger Kontext in Aufgaben auf, die nichts mit der Konversation zu tun haben, in der er platziert wurde.", "context": "Nutzen Sie dies überall dort, wo das Gedächtnis die Sitzung überdauert, die es erstellt hat: Assistenten, die sich Präferenzen merken, Agenten, die den Projektstatus akkumulieren, oder jeder Retrieval-Speicher, in den der Agent selbst schreibt. Je länger die Aufbewahrungsfrist ist und je größer der vom Agenten selbst verfasste Korpus ist, desto mehr muss das Gedächtnis ein strukturierter Datenspeicher statt eines Notizbuchs sein.", "solution": [ "Verweigern Sie anonyme Schreibvorgänge. Jeder Datensatz enthält Angaben darüber, woher die Behauptung stammt – die Sitzung und den Turn, das Tool oder Dokument sowie die URL, falls sie von außen stammt – als strukturierte Felder, nicht als Satz innerhalb des Textes.", "Erfassen Sie, wessen Autorität die Behauptung trug. Ein vom Operator konfiguriertes Faktum, ein vom Endbenutzer behauptetes Faktum und ein von einer Drittanbieterseite gelesenes Faktum sind drei verschiedene Behauptungen; halten Sie die Klasse explizit, damit der Retrieval-Pfad sie gewichten und ein Reviewer sie sortieren kann.", "Geben Sie jedem Datensatz eine Lebensdauer und wählen Sie standardmäßig eine kurze Dauer. Ein Gedächtnis, das niemals abläuft, wird niemand jemals überprüfen, und es ist die Halbwertszeit eines manipulierten Schreibvorgangs, die bestimmt, wie lange ein Angriff wirksam bleibt.", "Machen Sie das Entfernen zu einer First-Class-Operation mit einem namentlich genannten Eigentümer und sorgen Sie für eine Weitergabe (Propagation). Das Löschen des Datensatzes reicht nicht aus, wenn die Behauptung in einem Embedding, einer gecachten Zusammenfassung oder einem abgeleiteten Profil überlebt.", "Behandeln Sie den Schreibpfad als Aktion. Schreibvorgänge im Gedächtnis verändern das zukünftige Verhalten, daher durchlaufen sie dieselbe Autorisierung und Protokollierung wie jeder andere Schreibvorgang – nicht durch eine Hintertür, nur weil das Ziel zufällig eine Datei ist.", "Lassen Sie abgerufenes Gedächtnis niemals als Anweisung (Instruction) wieder in den Prompt einfließen. Es geht als Daten mit verknüpfter Herkunft ein, und ein Datensatz, dessen Herkunft ein Drittanbieter ist, wird genau wie eine nicht vertrauenswürdige Eingabe dieser Partei behandelt." ], "components": [ "Ein Datensatz-Schema mit Herkunft, Autoritätsklasse, Zeitstempel und Ablaufdatum als Pflichtfelder.", "Ein Schreibpfad, der Datensätze ablehnt, bei denen eines dieser Felder fehlt.", "Ein Retrieval-Pfad, der die Herkunft zusammen mit dem Inhalt zurückgibt, sodass das Modell und der Reviewer dasselbe sehen.", "Eine Entfernungsoperation, die sich auf Embeddings, Zusammenfassungen und alle abgeleiteten Artefakte überträgt.", "Ein Ablaufprozess sowie der Nachweis, dass er ausgeführt wurde.", "Ein Audit-Log von Schreib- und Löschvorgängen im Gedächtnis, getrennt vom Konversationsprotokoll." ], "benefits": [ "Macht die Manipulation des Gedächtnisses (Memory Poisoning) umkehrbar: Sie können den Schreibvorgang finden, sehen, woher er stammt, und alles davon Abgeleitete entfernen.", "Macht aus „Was glaubt dieser Agent über mich?“ eine Frage mit einer für Menschen lesbaren Antwort.", "Ermöglicht es dem Retrieval, eine Behauptung anhand ihrer Herkunft zu gewichten und nicht danach, wie selbstbewusst der Text verfasst wurde.", "Erfüllt die Aufbewahrungs- und Löschpflichten, die für alle über eine Person gespeicherten Daten gelten, ohne dass später ein separater Mechanismus angeflanscht werden muss." ], "risks": [ "Provenienz-Theater: ein Herkunftsfeld, das immer „Agent“ anzeigt, was nichts dokumentiert und nur wie ein Control aussieht.", "Verdichtungswäsche (Compaction Laundering) – der häufigste Weg, wie Attribuierung verloren geht. Das Zusammenfassen von zehn attributierten Datensätzen in einem einzigen Absatz erzeugt eine nicht attributierte Behauptung, die nun wie ein Konsens wirkt.", "Teillöschung: Der primäre Datensatz verschwindet, der Vektor bleibt, und die Behauptung wird weiterhin abgerufen.", "Übermäßiges Ablaufen zerstört die Kontinuität, für die das Gedächtnis eigentlich gedacht war, was dazu führt, dass das Ablaufen komplett deaktiviert wird." ], "whenNot": [ "Single-Session-Agenten ohne Persistenz: Es gibt kein Gedächtnis, das attributiert werden müsste, und der Aufwand bringt keinen Nutzen.", "Wenn der Speicher ein Cache Ihres eigenen, bereits verwalteten System of Record ist – attributieren Sie das Quellsystem einmal und nicht jede abgeleitete Zeile.", "Wenn der Overhead die Operatoren dazu verleiten würde, die eigentlichen Notizen außerhalb des Systems zu führen, was weitaus schlechter ist als ein unvollständiger Datensatz innerhalb des Systems." ], "examples": [ "Ein Assistent, der „bevorzugt metrische Einheiten“ schreibt. Der Datensatz enthält die Session-ID und den Turn, in dem der Benutzer dies gesagt hat, sodass eine falsche Präferenz auf den verursachenden Satz zurückgeführt und entfernt werden kann.", "Ein Recherche-Agent, der eine Drittanbieterseite liest und eine Behauptung mit dem Tag „an dieser URL zu diesem Datum beobachtet“ speichert, niemals als Faktum. Wenn dieselbe Behauptung Monate später abgerufen wird, reist ihre Herkunft mit.", "Ein Support-Agent, dessen Gedächtniseinträge standardmäßig nach 90 Tagen ablaufen, mit einer längeren Lebensdauer nur für Einträge, die ein Mensch explizit bestätigt hat – sodass die ungeprüfte Mehrheit veraltet und die geprüfte Minderheit bestehen bleibt." ], "kpis": [ { "metric": "Anteil attributierter Schreibvorgänge", "note": "Anteil der Gedächtniseinträge, die eine maschinenlesbare Herkunft aufweisen. Unter 100 % kann der Speicher nicht beantworten, woher eine Behauptung stammt, was das eigentliche Control hinfällig macht." }, { "metric": "Medianes Alter der Datensätze", "note": "Wie alt das aktive Gedächtnis tatsächlich ist. Ein steigender Median ohne Löschungen bedeutet, dass sich der Speicher anhäuft, anstatt kuratiert zu werden." }, { "metric": "Verzögerung bei der Löschungsweitergabe", "note": "Zeitspanne zwischen dem Entfernen eines Datensatzes und dem Zeitpunkt, an dem die Behauptung aus allen abgeleiteten Artefakten nicht mehr abrufbar ist. Das Zeitfenster, in dem eine gelöschte Behauptung noch wirkt." }, { "metric": "Anteil planmäßig abgelaufener Datensätze", "note": "Anteil der Datensätze, die ihr Ablaufdatum erreicht haben und tatsächlich entfernt wurden. Ein Beleg dafür, dass die Lebensdauer real und nicht nur deklariert ist." } ], "failureModes": [ "Verzögerte Manipulation (Delayed-Action Poisoning): Ein in einer Konversation platziertes falsches Faktum taucht Wochen später in einer nicht zusammenhängenden Aufgabe auf, wobei nichts im Kontext erklärt, warum der Agent es glaubt.", "Überleben in der Zusammenfassung: Der Datensatz wird gelöscht, die verdichtete Zusammenfassung, die ihn aufgenommen hat, jedoch nicht, und die Behauptung überlebt ihre eigene Quelle.", "Schattenindex: Das Embedding eines entfernten Datensatzes bleibt durchsuchbar, sodass die Löschung überall dort erfolgreich war, wo der Auditor hingesehen hat, aber nirgends, wo es darauf ankam.", "Identitäts-Bleed: Das Gedächtnis ist so ungenau zugeordnet, dass der Datensatz eines Benutzers für einen anderen abgerufen wird, was einen Designfehler des Gedächtnisses in eine Datenoffenlegung verwandelt." ], "lessons": [ "Die Attribuierung ist beim Schreiben kostengünstig und später unmöglich zu rekonstruieren. Das Feld muss existieren, bevor die Behauptung existiert.", "Jeder Verdichtungsschritt ist eine Attribuierungsgrenze. Wenn der Summarizer die Herkunft nicht weitergeben kann, erzeugt er neue, quellenlose Behauptungen.", "Ein Ablaufdatum, dessen Auslösung noch nie jemand beobachtet hat, ist eine Richtlinie, kein Control.", "Eine Löschung ist nur so vollständig wie das abgeleitete Artefakt, das Sie vergessen haben." ], "faqs": [ { "q": "Ist das nicht nur eine Aufbewahrungsrichtlinie mit zusätzlichem Aufwand?", "a": "Die Aufbewahrung (Retention) bestimmt, wann Daten gelöscht werden. Die Attribuierung beantwortet, woher eine Behauptung stammt und wer sie entfernen darf – genau das, was Sie in dem Moment benötigen, in dem sich eine Erinnerung als falsch und nicht nur als alt herausstellt. Beide ergänzen sich: Ohne Ablaufdatum häuft sich die Attribuierung an; ohne Attribuierung löscht das Ablaufdatum Beweise, die Sie nie verstanden haben." }, { "q": "Der Agent schreibt seine eigenen Erinnerungen. Wessen Autorität tragen diese?", "a": "Seine eigene, und das ist die Klasse, die es zu benennen gilt. Eine vom Agenten geschlussfolgerte Behauptung ist schwächer als eine vom Operator konfigurierte und sollte als solche abrufbar sein – andernfalls kehren die eigenen Vermutungen des Modells später ununterscheidbar von der Konfiguration zurück." }, { "q": "Wie bewahren wir die Provenienz bei der Zusammenfassung?", "a": "Entweder trägt die Zusammenfassung die Vereinigung der Herkunftsnachweise ihrer Quellen in sich, oder sie wird als neuer, vom Agenten geschlussfolgerter Datensatz geschrieben, der auf die ersetzten Datensätze verweist. Was nicht passieren darf, ist, dass die Zusammenfassung stillschweigend zu einem quellenlosen Faktum wird, denn das ist der Schritt, bei dem die Manipulation dauerhaft wird." } ] }, "ja": { "name": "Attributed Memory", "summary": "エージェントが記憶する内容を、匿名のテキストの塊としてではなく、そのオリジン（発生元）、削除権限を持つオーナー、および有効期間を保持するレコードとして保存します。メモリは、単発の攻撃を、将来の無関係なタスクで再トリガーされる攻撃へと変えてしまう要因です。アトリビューション（属性定義）こそが、それを可逆的なものにします。", "definition": "Attributed Memoryとは、永続的なエージェントメモリのすべてを、プロバナンス（その主張がどこから来て、誰の権限を伴っていたか）、削除可能な指名されたオーナー、および有効期限を持つレコードとして書き込むプラクティスです。これにより、誤った事実を追跡して削除することができ、それが叶わなくても自然に消滅させることができます。", "problem": "永続メモリに自由形式のテキストを書き込むエージェントは、後からどの記憶が指示されたものか、どの記憶が見知らぬ人のウェブページから読み取ったものか、そしてどの記憶を自身で推論したのかを区別できません。その結果、1つの汚染された書き込みが、それを植え付けた会話とはまったく関係のないタスクにおいて、信頼できるコンテキストとして再浮上することになります。", "context": "作成されたセッションよりもメモリが長生きするあらゆる場所で使用します。設定を記憶するアシスタント、プロジェクトの状態を蓄積するエージェント、エージェント自身が書き込む検索ストアなどです。保持期間が長くなり、エージェントが作成したコーパスの割合が増えるほど、メモリはノートブックではなくレコードストアである必要があります。", "solution": [ "匿名の書き込みを拒否します。すべてのレコードは、その主張がどこから来たのか（セッションとターン、ツールまたはドキュメント、外部からの場合はURL）を、テキスト内の文章としてではなく、構造化されたフィールドとして保持します。", "その主張が誰の権限を伴っていたかを記録します。オペレーターが設定した事実、エンドユーザーが主張した事実、エージェントがサードパーティのページで読み取った事実は、それぞれ異なる3つの主張です。検索パスがそれらに重み付けをし、レビュー担当者が分類できるように、クラスを明示的に維持します。", "すべてのレコードに有効期間を設定し、デフォルトは短くします。期限切れにならないメモリは誰もレビューすることはありません。汚染された書き込みの半減期こそが、攻撃の影響がどれだけ長く続くかを決定します。", "指名されたオーナーを伴う第一級の操作として削除を定義し、それを伝播させます。埋め込み（embedding）、キャッシュされた要約、または派生したプロファイルに主張が残っている場合、レコードを削除するだけでは不十分です。", "書き込みパスをアクションとして扱います。メモリの書き込みは将来の動作を変更するため、保存先がたまたまファイルであるからといって裏口から行うのではなく、他の書き込みと同様の認可とログ記録を経由させます。", "検索されたメモリを指示（instruction）としてプロンプトに再入力させてはなりません。それはオリジンが添付されたデータとして到達し、オリジンがサードパーティであるレコードは、そのサードパーティからの信頼できない入力とまったく同じように扱われます。" ], "components": [ "オリジン、権限クラス、タイムスタンプ、および有効期限を必須フィールドとするレコードスキーマ。", "これらのいずれかが欠けているレコードを拒否する書き込みパス。", "コンテンツと同時にオリジンを返す検索パス。これにより、モデルとレビュー担当者が同じ情報を確認できるようになります。", "埋め込み、要約、およびすべての派生アーティファクトに伝播する削除操作。", "有効期限処理、およびそれが実行された証拠。", "会話ログとは別に管理される、メモリの書き込みと削除の監査ログ。" ], "benefits": [ "メモリ汚染を可逆的なものにします。書き込みを特定し、その発生元を確認し、そこから派生したすべてのものを削除できます。", "「このエージェントは私について何を信じているのか？」という問いを、人間が読める回答が存在する質問に変えます。", "テキストがどれほど自信ありげに書かれているかではなく、そのオリジンに基づいて主張に重み付けをして検索できるようにします。", "個人に関して永続化されたあらゆるデータに適用される保持および消去の義務を、後から別の仕組みを継ぎ接ぎすることなく満たします。" ], "risks": [ "プロバナンス・シアター（形だけのプロバナンス）：オリジンフィールドが常に「agent」となっており、何も記録していないにもかかわらず、コントロールが機能しているように見せかけること。", "コンパクション・ロンダリング（要約による属性ロンダリング） — アトリビューションが失われる最も一般的な原因。属性付きの10個のレコードを1つの段落に要約すると、属性のない主張が生成され、それが合意事項のように見えてしまいます。", "部分的な削除：プライマリレコードは削除されるものの、ベクトルが残り、その主張が検索され続けること。", "過剰な期限切れによってメモリが存在していた目的である連続性が破壊され、結果として期限切れ設定を完全に無効化するようになってしまうこと。" ], "whenNot": [ "永続性のないシングルセッションのエージェント：属性を付与すべきメモリが存在せず、形式的な手続きによるメリットがありません。", "ストアが、すでにガバナンスが効いている自社のシステム・オブ・レコード（SoR）のキャッシュである場合。派生した行ごとではなく、ソースシステムに対して一度だけ属性を付与します。", "オーバーヘッドのせいでオペレーターが実際のメモをシステムの外部に保管するようになる場合。これは、システム内に不完全なレコードを保持するよりも明らかに悪質です。" ], "examples": [ "「メートル法を好む」と書き込むアシスタント。レコードにはセッションIDとユーザーがそれを発言したターンが保持されるため、誤った設定を原因となった文まで追跡して削除できます。", "サードパーティのページを読み込み、事実としてではなく「そのURLで、その日付に観測された」というタグ付きで主張を保存する調査エージェント。数ヶ月後に同じ主張が検索されたとき、そのオリジンも一緒に取得されます。", "デフォルトでメモリレコードが90日後に期限切れになるサポートエージェント。人間が明示的に確認したエントリのみ有効期間が延長されるため、レビューされていない大部分は期限切れとなり、レビュー済みの少数が残ります。" ], "kpis": [ { "metric": "属性付き書き込みの割合", "note": "機械可読なオリジンを保持しているメモリレコードの割合。これが100%未満の場合、ストアは主張がどこから来たのかを回答できず、コントロールとしての意味をなしません。" }, { "metric": "レコード年齢の中央値", "note": "実際に使用されているメモリの古さ。削除が行われずに中央値が上昇している場合、ストアがキュレーションされることなく蓄積されていることを意味します。" }, { "metric": "削除伝播の遅延", "note": "レコードが削除されてから、すべての派生アーティファクトからその主張が検索できなくなるまでの時間。削除された主張が依然として機能してしまう期間を指します。" }, { "metric": "予定通りに期限切れとなった割合", "note": "有効期限に達し、実際に削除されたレコードの割合。有効期間が単なる宣言ではなく、実際に機能している証拠となります。" } ], "failureModes": [ "遅延型汚染：ある会話で植え付けられた誤った事実が、数週間後に無関係なタスクで浮上し、コンテキストのどこにもエージェントがそれを信じる理由が説明されていない状態。", "要約の残存：レコードは削除されたものの、それを吸収した圧縮要約が削除されず、主張がその情報源よりも長生きしてしまう状態。", "シャドウインデックス：削除されたレコードの埋め込み（embedding）が検索可能なまま残っているため、監査人が確認したすべての場所では削除が成功しているように見えても、重要な場所では機能していない状態。", "アイデンティティの漏洩：メモリのキー設定が緩いため、あるユーザーのレコードが別のユーザーのために検索されてしまい、メモリ設計の欠陥が情報漏洩につながる状態。" ], "lessons": [ "アトリビューションは書き込み時には低コストですが、後から再構築することは不可能です。主張が存在する前に、フィールドが存在していなければなりません。", "すべての圧縮ステップはアトリビューションの境界です。要約処理がオリジンを引き継ぐことができない場合、それは情報源のない新しい主張を生み出していることになります。", "誰も実行されたのを見たことがない有効期限は、ポリシーであってコントロールではありません。", "削除の完全性は、忘れてしまった派生アーティファクトの存在によって左右されます。" ], "faqs": [ { "q": "これは単に、手順を増やしたデータ保持ポリシー（retention policy）ではないのですか？", "a": "保持ポリシーはデータがいつ消えるかを決定します。アトリビューションは、主張がどこから来て、誰がそれを削除できるかを決定します。これは、メモリが単に古いだけでなく、誤りであることが判明した瞬間に必要となるものです。この2つは相互補完的です。有効期限がなければアトリビューションは蓄積し続け、アトリビューションがなければ有効期限は理解していなかった証拠を削除してしまいます。" }, { "q": "エージェントが自身のメモリを書き込む場合、それらは誰の権限を伴うのですか？", "a": "エージェント自身の権限であり、それこそが定義する価値のあるクラスです。エージェントが推論した主張は、オペレーターが設定したものよりも弱く、そのように検索されるべきです。そうでなければ、モデル自身の推測が、後から設定と区別がつかない状態で戻ってくることになります。" }, { "q": "要約処理を通じてプロバナンスを維持するにはどうすればよいですか？", "a": "要約がそのソースのオリジンの和集合を保持するか、あるいは置き換えたレコードを指し示す新しいエージェント推論レコードとして書き込まれるかのいずれかです。避けるべきなのは、要約がいつの間にか情報源のない事実になってしまうことであり、それこそが汚染が永続化するステップだからです。" } ] }, "zh": { "name": "归属化记忆", "summary": "将智能体记住的内容存储为包含其来源、可将其删除的所有者以及生命周期的记录，绝不能存为匿名的文本块。记忆会将单次攻击转变为在未来无关任务中重复触发的攻击；而归属化正是让这种影响可逆的关键。", "definition": "归属化记忆是指将智能体的每条持久化记忆写入为一条记录，其中包含其出处（该断言来自何处以及承载了谁的授权）、一个有名字的且可以删除它的所有者，以及一个有效期——这样，虚假的事实就可以被追踪、移除，即使未能手动移除，也会自动失效。", "problem": "将自由文本写入持久化记忆的智能体，在以后无法区分哪些记忆是别人告诉它的、哪些是它从陌生网页上读取的、哪些是它自己推断的。这样一来，一次被污染的写入就会在与植入该写入的对话毫无关系的任务中，作为可信上下文重新出现。", "context": "适用于记忆生命周期长于创建它的会话的任何场景：记住偏好的助手、积累项目状态的智能体，以及智能体自身写入的任何检索库。保留时间越长，且智能体创作的语料库越多，记忆就越需要是一个记录存储库，而不是一个笔记本。", "solution": [ "拒绝匿名写入。每条记录都应以结构化字段（而非文本中的句子）的形式携带断言的来源——会话和轮次、工具或文档，如果来自外部，还应包括 URL。", "记录断言承载了谁的授权。操作员配置的事实、最终用户断言的事实以及智能体在第三方页面上读取的事实是三种不同的断言；保持类别明确，以便检索路径可以对其进行加权，审核人员可以对其进行分类。", "为每条记录设定生命周期，并将默认值设得很短。永不失效的记忆是永远不会有人审核的记忆，而被污染写入的半衰期决定了攻击能持续发挥作用多久。", "使删除操作成为具有具名所有者的一等公民操作，并使其能够传播。如果断言仍然存在于嵌入（embedding）、缓存的摘要或派生的画像中，仅删除记录是不够的。", "将写入路径视为一项操作。记忆写入会改变未来的行为，因此它们必须像其他任何写入一样经过相同的授权和日志记录——不能因为目的地恰好是一个文件就走旁路。", "绝不允许检索到的记忆作为指令重新进入提示词。它作为附带来源的数据到达，而来源为第三方的记录应完全被视为来自该第三方的不可信输入。" ], "components": [ "一个将来源、授权类别、时间戳和有效期作为必填字段的记录模式（schema）。", "一个拒绝缺少上述任何一项的记录的写入路径。", "一个在返回内容的同时返回来源的检索路径，以便模型和审核人员看到相同的信息。", "一个能传播到嵌入（embeddings）、摘要和任何派生产物中的删除操作。", "一个失效处理流程，以及其已运行的凭证。", "一个与对话日志分离的记忆写入和删除审计日志。" ], "benefits": [ "使记忆污染可逆：你可以找到该写入，查看其来源，并删除从中派生的所有内容。", "将“这个智能体对我的认知是什么？”变成一个人类可读的有解问题。", "允许检索根据断言的来源对其进行加权，而不是根据文本撰写时的自信程度。", "满足适用于任何关于个人的持久化数据的保留和擦除义务，而无需在以后额外拼凑独立的机制。" ], "risks": [ "出处作秀（Provenance theatre）：来源字段总是显示为“agent”，这没有记录任何实质内容，却看起来像是一个控制项。", "压缩洗白（Compaction laundering）——归属信息消亡最常见的方式。将十条带有归属信息的记录总结为一个段落，会产生一个无归属信息的断言，而这个断言现在看起来就像是共识。", "部分删除：主记录消失了，但向量保留了下来，导致该断言仍不断被检索到。", "过度失效破坏了记忆存在所需的连续性，从而迫使人们完全禁用失效机制。" ], "whenNot": [ "无持久化的单会话智能体：没有需要归属的记忆，这种仪式感毫无收益。", "当存储库是你自己已经过治理的记录系统的缓存时——只需对源系统进行一次归属标记，而不是对每个派生行都进行标记。", "当开销会迫使操作员将真实的笔记保存在系统之外时，这显然比系统内存在不完美的记录要糟糕得多。" ], "examples": [ "一个写入“偏好公制单位”的助手。该记录携带了会话 ID 和用户说出这句话的轮次，因此错误的偏好可以追溯到导致该偏好的句子并予以删除。", "一个读取第三方页面并存储带有“在某日期、某 URL 处观察到”标签的断言的研究智能体，绝不将其存为事实。当数月后检索到相同的断言时，其来源会随之呈现。", "一个支持智能体，其记忆记录默认在 90 天后失效，只有经人工明确确认的条目才具有更长的生命周期——这样，未审核的大多数记录会因过期而淘汰，而经审核的少数记录则得以保留。" ], "kpis": [ { "metric": "归属化写入占比", "note": "携带机器可读来源的记忆记录占比。如果低于 100%，存储库就无法回答断言来自何处，而这正是整个控制项的核心所在。" }, { "metric": "记录年龄中位数", "note": "实际起作用的记忆的真实年龄。在没有删除操作的情况下，中位数上升意味着存储库只是在不断累积，而不是在被精心维护。" }, { "metric": "删除传播延迟", "note": "从删除记录到该断言无法从每个派生产物中检索到之间的时间。这是已删除断言仍然起作用的时间窗口。" }, { "metric": "按期失效占比", "note": "达到有效期并被实际移除的记录占比。这是生命周期真实存在而非仅作声明的证据。" } ], "failureModes": [ "延时生效污染：在一次对话中植入的虚假事实在数周后的无关任务中浮出水面，而上下文中的任何内容都无法解释为什么智能体相信它。", "摘要残留：记录被删除了，但吸收了该记录的压缩摘要未被删除，导致断言比其自身的来源存活得更久。", "影子索引：已删除记录的嵌入（embedding）仍然可以被搜索到，导致删除操作在审计员查看的每个地方都成功了，但在真正起作用的地方却失败了。", "身份混淆（Identity bleed）：记忆的键值关联过于松散，导致一个用户的记录被另一个用户检索到，从而将记忆设计缺陷演变成信息泄露。" ], "lessons": [ "归属信息在写入时成本很低，但事后重建却是不可能的。该字段必须在断言产生之前就存在。", "每个压缩步骤都是一个归属边界。如果摘要生成器无法将来源传递下去，它就会产生新的无源断言。", "从未有人见其触发过的失效机制只是一项政策，而不是一个控制项。", "删除的彻底程度，取决于你所遗忘的派生产物。" ], "faqs": [ { "q": "这不就是步骤更繁琐的数据保留政策吗？", "a": "保留政策解决的是数据何时消失的问题。而归属信息解决的是断言来自何处以及谁可以删除它的问题，这正是当记忆被发现是错误的（而不仅仅是陈旧的）那一刻你所需要的。两者是互补的：没有失效机制，归属信息就会不断堆积；没有归属信息，失效机制就会删除你从未理解的证据。" }, { "q": "智能体自己写入记忆。这些记忆承载了谁的授权？", "a": "它自己的授权，而这正是值得命名的类别。智能体推断的断言比操作员配置的断言要弱，并且在检索时应当能够体现这一点——否则模型自身的猜测在以后返回时将与配置无法区分。" }, { "q": "我们如何在摘要生成过程中保留出处？", "a": "要么摘要携带其所有源头来源的并集，要么将其写入为一条指向其所替代记录的、由智能体推断的新记录。绝不能让摘要悄无声息地变成无源事实，因为这一步会让污染变成永久性的。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/context-compression", "api_url": "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." } ] }, "fr": { "name": "Compression de contexte", "summary": "La compression de contexte réduit les tokens fournis à un modèle lors de chaque appel tout en préservant les informations dont il a réellement besoin pour agir. Utilisez-la sur des agents à exécution longue et des conversations prolongées pour réduire les coûts et la latence, et pour rester dans les limites de la fenêtre de contexte. Les trois leviers sont le résumé de l'historique, l'élagage du contexte non pertinent et la compression des prompts. Le risque principal est la perte d'informations : omettre le seul détail qui importait. Mesurez les informations conservées, et pas seulement les tokens économisés.", "problem": "Les agents à exécution longue et les conversations multi-tours accumulent du contexte : chaque résultat d'outil, message précédent et document récupéré est rejoué lors de l'appel suivant. Le nombre de tokens augmente de manière quasi linéaire avec l'interaction, de sorte que le coût par appel et la latence grimpent, et le fenêtrage finit par déborder, tronquant silencieusement le contenu le plus ancien (parfois le plus important). Les corrections naïves — fenêtres plus grandes, troncature plus agressive — augmentent les coûts ou détruisent les informations dont le modèle a besoin pour rester cohérent.", "context": "S'applique lorsque le contexte croît de manière illimitée par rapport aux besoins d'une seule étape : assistants conversationnels avec de longs historiques, agents autonomes bouclant sur de nombreux appels d'outils, pipelines RAG qui récupèrent trop d'informations, et tâches par lots où la taille du prompt domine le coût. Cela convient lorsque la majeure partie du contexte accumulé est redondante ou obsolète, lorsque vous contrôlez l'assemblage du prompt et lorsque vous pouvez tolérer une certaine erreur de reconstruction. Cela ne convient pas lorsque chaque token est crucial (tâches juridiques, d'audit ou de rappel exact) ou lorsque les interactions sont suffisamment courtes pour que la fenêtre ne soit jamais sous pression.", "solution": [ "Traisez le contexte actif comme un budget que vous gérez activement plutôt que comme un journal en ajout uniquement. Il existe trois leviers complémentaires. La synthèse remplace une partie de l'historique par un synopsis plus court — généralement un résumé glissant des échanges plus anciens, actualisé périodiquement, tandis que les échanges récents restent textuels. L'élagage supprime le contexte non pertinent pour l'étape en cours : dédupliquez, supprimez les sorties d'outils obsolètes et sélectionnez uniquement les fragments récupérés dont le score est supérieur à un seuil de pertinence. La compression de prompt (par exemple LLMLingua) utilise un modèle plus petit pour supprimer ou reformuler les tokens à faible valeur informative avant d'envoyer le prompt, troquant une légère perte de précision contre d'importantes réductions de tokens.\\n\\nComposez ces éléments dans un pipeline aux limites explicites : conservez une fenêtre récente textuelle, un résumé glissant de l'historique plus ancien et un emplacement de récupération rempli à la demande. Protégez une zone « épinglée » pour les faits qui ne doivent jamais être compressés — identifiants, contraintes, objectif actuel. Surtout, instrumentez le résultat : exécutez un ensemble d'évaluations comparant les réponses avec et sans compression afin de détecter toute dégradation de la qualité, et ajustez l'agressivité par charge de travail plutôt que de manière globale. La compression est un curseur entre qualité et coût, pas un gain gratuit." ], "components": [ "Synthétiseur glissant", "Élagueur par pertinence", "Compresseur de prompt", "Zone épinglée", "Contrôleur de budget de contexte", "Évaluateur de rétention" ], "benefits": [ "L'envoi de moins de tokens réduit directement le coût d'entrée de chaque appel, ce qui se cumule sur les longues boucles d'agents et le trafic à haut volume.", "Des prompts plus petits signifient moins d'encodage et un délai d'obtention du premier token plus court, ce qui améliore la réactivité dans les flux interactifs et d'agents.", "Limiter le contexte actif permet aux longues conversations et aux agents multi-étapes de se poursuivre sans déborder de la fenêtre ni subir de troncature silencieuse.", "La suppression du contexte redondant et obsolète peut améliorer la qualité en réduisant les distractions, aidant ainsi le modèle à se concentrer sur ce qui importe actuellement." ], "risks": [ "Les résumés et l'élagage peuvent écarter le détail unique qui s'avérera plus tard décisif, produisant des réponses erronées formulées avec assurance.", "Les résumés glissants synthétisent des résumés antérieurs ; de petites omissions se cumulent au fil des cycles jusqu'à ce que le fil de la conversation dérive discrètement.", "L'exécution d'un synthétiseur ou d'un compresseur ajoute sa propre latence, son coût et sa surface de défaillance, ce qui peut annuler les économies réalisées sur les interactions courtes.", "Une éviction agressive peut supprimer silencieusement des contraintes ou des instructions dont le modèle dépend encore, sans signal d'erreur évident." ], "whenNot": [ "Lorsque chaque token est crucial — affaires juridiques, audit, conformité ou extraction précise de données —, une compression avec perte est inacceptable.", "Si les conversations mettent rarement la fenêtre sous pression, le surcoût de la compression dépasse les économies réalisées et ajoute une complexité inutile.", "Sans un harness d'évaluation de la rétention, ne déployez rien : vous ne pouvez pas savoir si la compression dégrade silencieusement les réponses." ], "examples": [ "Un agent itérant sur une base de code volumineuse conserve une fenêtre récente textuelle ainsi qu'un résumé glissant des étapes précédentes, en épinglant la spécification de la tâche et les chemins de fichiers afin de ne pas perdre de vue l'objectif.", "Un bot de support multi-session synthétise les échanges précédents en un résumé de dossier compact, élaguant les sous-problèmes résolus tout en épinglant les contraintes du compte client.", "Un pipeline de récupération qui extrait de nombreux fragments applique un élagage par pertinence et une compression de prompt pour n'envoyer que les passages à fort signal, réduisant les tokens sans perdre la réponse." ], "productionEvidence": { "context": "Déploiement OpenClaw mono-opérateur, local-first, observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des traces de trajectoire propres à l'agent.", "scenario": "Les longs transcriptions autonomes sont compactées de manière préventive et les résultats des outils sont tronqués pour respecter le budget du prompt.", "technology": "Compactage préventif avec marge de sécurité, troncature des résultats d'outils, hook d'élagage de contexte et pré-vérification de dépassement en milieu de tour.", "load": "2 810 événements compilés par contexte sur 2 776 tours en 57 jours.", "results": "Le compactage s'est exécuté en ligne tout au long de la fenêtre, maintenant les tours autonomes multi-étapes dans le budget (p95 87,6 s par tour) sans qu'aucune défaillance par dépassement de contexte ne survienne. Déploiement mono-opérateur local-first." }, "kpis": [ { "metric": "Tokens par appel (entrée)", "note": "Le principal facteur de coût. Suivez la distribution avant et après compression ; un résultat sain se traduit par une réduction nette sans augmentation des erreurs en aval." }, { "metric": "Rétention de l'information / qualité de la tâche", "note": "Comparez les réponses avec et sans compression sur un ensemble d'évaluation. Un bon résultat montre une qualité stable dans vos limites de tolérance à mesure que les tokens diminuent." }, { "metric": "Latence de bout en bout", "note": "Nette du surcoût de compression. Un bon résultat est une latence totale plus faible ; veillez à ce que les appels au synthétiseur ou au compresseur n'annulent pas les économies." }, { "metric": "Taux de dépassement de contexte / de troncature", "note": "Fréquence à laquelle les interactions atteignent la limite de la fenêtre. Un bon résultat consiste à ramener ce taux vers zéro sans avoir à abandonner le contenu épinglé." } ], "failureModes": [ "Un résumé omet une contrainte mentionnée au début ; de nombreux tours plus tard, l'agent la viole car ce fait a tout simplement disparu du contexte.", "La re-synthétisation répétée amplifie les erreurs de paraphrase et les omissions jusqu'à ce que le résumé glissant ne reflète plus ce qui s'est réellement passé.", "Un budget mal configuré compresse des identifiants ou des instructions qui devaient être protégés, rompant silencieusement l'exactitude.", "Un seuil de pertinence agressif filtre un contexte important pour un cas limite, de sorte que la qualité semble correcte lors des tests mais échoue en production." ], "lessons": [ "Maximiser la réduction des tokens est trivial et n'a aucun sens en soi ; la véritable métrique est de savoir si le modèle répond toujours correctement.", "Protégez explicitement les identifiants, les contraintes et l'objectif actuel afin qu'aucune étape de compression ne puisse les évincer.", "Compressez l'historique ancien, pas le contexte actif ; les échanges les plus récents portent le signal le plus pertinent pour la décision.", "Ajustez l'agressivité par charge de travail par rapport à un ensemble d'évaluation ; ce qui est sûr pour du bavardage est imprudent pour une tâche d'audit." ], "faqs": [ { "q": "En quoi cela diffère-t-il de la mémoire à long terme ?", "a": "La mémoire à long terme conserve les faits en dehors du prompt et les récupère à la demande ; la compression de contexte réduit le contexte actif envoyé à chaque appel. Elles sont complémentaires : la mémoire décide de ce qu'il faut ramener, la compression décide de la compacité de son intégration dans la fenêtre." }, { "q": "Synthétiser, élaguer ou compresser — que dois-je utiliser ?", "a": "Élaguez d'abord (gratuit, sans perte lors de la suppression d'une réelle redondance), synthétisez l'historique plus ancien lorsqu'il croît de manière illimitée, et n'ajoutez la compression de prompt que si vous avez encore besoin de marge et pouvez valider le coût en qualité. La plupart des systèmes combinent les trois." }, { "q": "Comment savoir si la compression nuit à la qualité ?", "a": "Exécutez un ensemble d'évaluation avec et sans compression et comparez les résultats des tâches, pas seulement le nombre de tokens. Surveillez les réponses erronées formulées avec assurance et les contraintes abandonnées — ce sont les signatures d'une compression avec perte qui est allée trop loin." } ] }, "de": { "name": "Kontextkomprimierung", "summary": "Die Kontextkomprimierung reduziert die Token, die einem Modell bei jedem Aufruf übergeben werden, während die Informationen, die es tatsächlich zum Handeln benötigt, erhalten bleiben. Nutzen Sie sie bei langlebigen Agenten und langen Konversationen, um Kosten und Latenzzeiten zu senken und innerhalb des Kontextfensters zu bleiben. Die drei Hebel sind das Zusammenfassen des Verlaufs, das Bereinigen irrelevanter Kontexte und das Komprimieren von Prompts. Das zentrale Risiko ist der Informationsverlust (Lossiness): das Weglassen des einen Details, auf das es ankam. Messen Sie die erhaltenen Informationen, nicht nur die eingesparten Token.", "problem": "Langlebige Agenten und Multi-Turn-Konversationen akkumulieren Kontext: Jedes Tool-Ergebnis, jede vorherige Nachricht und jedes abgerufene Dokument wird beim nächsten Aufruf erneut abgespielt. Die Token-Anzahl wächst annähernd linear mit der Interaktion, sodass die Kosten pro Aufruf und die Latenz steigen. Schließlich läuft das Kontextfenster über und die ältesten (manchmal wichtigsten) Inhalte werden stillschweigend abgeschnitten. Naive Lösungen – größere Fenster, aggressiveres Abschneiden – erhöhen entweder die Kosten oder zerstören die Informationen, die das Modell benötigt, um kohärent zu bleiben.", "context": "Trifft zu, wenn der Kontext im Verhältnis zu dem, was ein einzelner Schritt benötigt, unbegrenzt wächst: Konversationsassistenten mit langen Verläufen, autonome Agenten, die viele Tool-Aufrufe in Schleifen durchlaufen, RAG-Pipelines, die zu viele Daten abrufen (Over-Retrieval), und Batch-Jobs, bei denen die Prompt-Größe die Kosten dominiert. Es eignet sich, wenn ein Großteil des akkumulierten Kontexts redundant oder veraltet ist, wenn Sie die Prompt-Zusammenstellung kontrollieren und wenn Sie gewisse Rekonstruktionsfehler tolerieren können. Es ist ungeeignet, wenn jedes Token tragend ist (Rechts-, Audit- oder Exact-Recall-Aufgaben) oder wenn Interaktionen so kurz sind, dass das Kontextfenster nie an seine Grenzen stößt.", "solution": [ "Betrachten Sie den Live-Kontext als ein Budget, das Sie aktiv verwalten, und nicht als ein Log, an das nur angehängt wird. Es gibt drei komplementäre Hebel. Die Zusammenfassung (Summarization) ersetzt einen Teil des Verlaufs durch eine kürzere Synopse – typischerweise eine fortlaufende Zusammenfassung älterer Turns, die regelmäßig aktualisiert wird, während neuere Turns wortwörtlich erhalten bleiben. Das Pruning (Bereinigen) entfernt Kontext, der für den aktuellen Schritt irrelevant ist: Duplikate entfernen, veraltete Tool-Ausgaben verwerfen und nur diejenigen abgerufenen Chunks auswählen, deren Score über einem Relevanzschwellenwert liegt. Die Prompt-Komprimierung (z. B. LLMLingua) nutzt ein kleineres Modell, um informationsarme Token vor dem Senden des Prompts zu löschen oder umzuformulieren, was einen geringen Genauigkeitsverlust gegen eine erhebliche Token-Reduzierung eintauscht.\n\nFügen Sie diese Komponenten zu einer Pipeline mit expliziten Grenzen zusammen: Behalten Sie ein wortwörtliches aktuelles Fenster, eine fortlaufende Zusammenfassung des älteren Verlaufs und einen bei Bedarf gefüllten Retrieval-Slot bei. Schützen Sie einen „angepinnten“ Bereich für Fakten, die niemals komprimiert werden dürfen – Identifikatoren, Einschränkungen, das aktuelle Ziel. Instrumentieren Sie das Ergebnis unbedingt: Führen Sie ein Evaluierungsset aus, das Antworten mit und ohne Komprimierung vergleicht, damit Sie sehen, wann die Qualität nachlässt, und passen Sie die Aggressivität pro Workload statt global an. Komprimierung ist ein Regler zwischen Qualität und Kosten, kein kostenloser Gewinn." ], "components": [ "Fortlaufender Summarizer", "Relevanz-Pruner", "Prompt-Kompressor", "Angepinnter Bereich", "Kontext-Budget-Controller", "Retention-Evaluator" ], "benefits": [ "Das Senden von weniger Token reduziert direkt die Input-Kosten bei jedem Aufruf, was sich über lange Agenten-Schleifen und hohes Traffic-Volumen summiert.", "Kleinere Prompts bedeuten weniger Kodierungsaufwand und eine kürzere Time-to-First-Token, was die Reaktionsfähigkeit in interaktiven und agentischen Abläufen verbessert.", "Die Begrenzung des Live-Kontexts ermöglicht es, lange Konversationen und mehrschrittige Agenten fortzuführen, ohne dass das Fenster überläuft oder Inhalte stillschweigend abgeschnitten werden.", "Das Entfernen von redundantem und veraltetem Kontext kann die Qualität verbessern, indem Ablenkungen reduziert werden, sodass sich das Modell auf das konzentrieren kann, was aktuell wichtig ist." ], "risks": [ "Zusammenfassungen und Pruning können genau das eine Detail verwerfen, das sich später als entscheidend herausstellt, was zu selbstbewusst falschen Antworten führt.", "Fortlaufende Zusammenfassungen fassen vorherige Zusammenfassungen zusammen; kleine Auslassungen summieren sich über viele Zyklen, bis der rote Faden unbemerkt verloren geht.", "Der Betrieb eines Summarizers oder Kompressors verursacht eigene Latenz, Kosten und Fehlerquellen, was die Einsparungen bei kurzen Interaktionen wieder aufheben kann.", "Aggressives Verwerfen kann stillschweigend Einschränkungen oder Anweisungen entfernen, von denen das Modell weiterhin abhängt, ohne dass ein offensichtliches Fehlersignal ausgegeben wird." ], "whenNot": [ "Wenn jedes Token tragend ist – bei rechtlichen Fragen, Audits, Compliance oder präziser Datenextraktion –, ist eine verlustbehaftete Komprimierung inakzeptabel.", "Wenn Konversationen das Fenster selten an seine Grenzen bringen, kostet der Komprimierungs-Overhead mehr, als er einspart, und sorgt für unnötige Komplexität.", "Führen Sie ohne ein Retention-Evaluierungs-Harness kein Deployment durch: Sie können sonst nicht feststellen, ob die Komprimierung die Antworten stillschweigend verschlechtert." ], "examples": [ "Ein Agent, der eine große Codebasis iteriert, behält ein wortwörtliches aktuelles Fenster sowie eine fortlaufende Zusammenfassung früherer Schritte bei und pinnt die Aufgabenspezifikation sowie Dateipfade an, um das Ziel nicht aus den Augen zu verlieren.", "Ein Multi-Session-Support-Bot fasst vorherige Turns in einer kompakten Fallzusammenfassung zusammen, bereinigt gelöste Teilprobleme und pinnt gleichzeitig die Account-Einschränkungen des Kunden an.", "Eine Retrieval-Pipeline, die viele Chunks abruft, wendet Relevanz-Pruning und Prompt-Komprimierung an, um nur Passagen mit starkem Signal zu senden, wodurch Token eingespart werden, ohne die Antwort zu verlieren." ], "productionEvidence": { "context": "Single-Operator, Local-First OpenClaw-Deployment, beobachtet über 57 Tage (161 Sessions / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Lange autonome Transkripte werden präventiv verdichtet und Tool-Ergebnisse abgeschnitten, um innerhalb des Prompt-Budgets zu bleiben.", "technology": "Präventive Verdichtung mit Sicherheitsmarge, Abschneiden von Tool-Ergebnissen, ein Context-Pruning-Hook und eine Vorabprüfung auf Überlauf mitten im Turn.", "load": "2.810 kontextkompilierte Ereignisse über 2.776 Turns hinweg in 57 Tagen.", "results": "Die Verdichtung lief inline über das gesamte Fenster hinweg und hielt mehrschrittige autonome Turns im Budget (p95 87,6 s pro Turn), ohne dass Fehler durch Kontextüberlauf auftraten. Single-Operator, Local-First-Deployment." }, "kpis": [ { "metric": "Token pro Aufruf (Input)", "note": "Der primäre Kostentreiber. Verfolgen Sie die Verteilung vor und nach der Komprimierung; ein gesundes Ergebnis ist eine deutliche Reduzierung ohne Anstieg nachgelagerter Fehler." }, { "metric": "Informationserhalt / Aufgabenqualität", "note": "Vergleichen Sie Antworten mit und ohne Komprimierung in einem Evaluierungsset. Ein gutes Ergebnis zeigt sich darin, dass die Qualität bei sinkender Token-Zahl innerhalb Ihrer Toleranz stabil bleibt." }, { "metric": "End-to-End-Latenz", "note": "Netto nach Komprimierungs-Overhead. Ein gutes Ergebnis ist eine geringere Gesamtlatenz; achten Sie darauf, dass Aufrufe des Summarizers oder Kompressors die Einsparungen nicht wieder zunichtemachen." }, { "metric": "Kontextüberlauf- / Abschneiderate", "note": "Wie oft Interaktionen an das Limit des Fensters stoßen. Ein gutes Ergebnis ist es, diesen Wert gegen Null zu senken, ohne auf das Verwerfen angepinnter Inhalte zurückgreifen zu müssen." } ], "failureModes": [ "Eine Zusammenfassung lässt eine früh erwähnte Einschränkung aus; viele Turns später verletzt der Agent diese, weil dieser Fakt schlichtweg aus dem Kontext verschwunden ist.", "Wiederholtes erneutes Zusammenfassen verstärkt Paraphrasierungsfehler und Auslassungen, bis die fortlaufende Zusammenfassung nicht mehr widerspiegelt, was tatsächlich passiert ist.", "Ein falsch konfiguriertes Budget komprimiert Identifikatoren oder Anweisungen, die eigentlich geschützt sein sollten, was die Korrektheit stillschweigend beeinträchtigt.", "Ein aggressiver Relevanzschwellenwert filtert Kontext heraus, der für einen Edge Case wichtig war, sodass die Qualität in Tests gut aussieht, in der Praxis jedoch versagt." ], "lessons": [ "Die Token-Reduzierung lässt sich trivial maximieren, ist allein jedoch bedeutungslos; die eigentliche Metrik ist, ob das Modell immer noch korrekt antwortet.", "Schützen Sie Identifikatoren, Einschränkungen und das aktuelle Ziel explizit, damit keine Komprimierungsstufe sie verwerfen kann.", "Komprimieren Sie den alten Verlauf, nicht den aktiven Kontext; die jüngsten Interaktionen enthalten das am stärksten entscheidungsrelevante Signal.", "Passen Sie die Aggressivität pro Workload anhand eines Evaluierungssets an; was für Smalltalk sicher ist, ist für eine Audit-Aufgabe leichtsinnig." ], "faqs": [ { "q": "Wie unterscheidet sich dies vom Langzeitgedächtnis?", "a": "Das Langzeitgedächtnis speichert Fakten außerhalb des Prompts und ruft sie bei Bedarf ab; die Kontextkomprimierung verkleinert den bei jedem Aufruf gesendeten Live-Kontext. Sie ergänzen sich: Das Gedächtnis entscheidet, was zurückgeholt wird, die Komprimierung entscheidet, wie kompakt es im Fenster platziert wird." }, { "q": "Zusammenfassen, bereinigen oder komprimieren – was sollte ich verwenden?", "a": "Zuerst bereinigen (kostenlos, verlustfrei beim Entfernen echter Redundanz), den älteren Verlauf zusammenfassen, wenn er unbegrenzt wächst, und eine Prompt-Komprimierung erst dann hinzufügen, wenn Sie immer noch mehr Spielraum benötigen und die Qualitätskosten validieren können. Die meisten Systeme kombinieren alle drei Ansätze." }, { "q": "Woran erkenne ich, dass die Komprimierung der Qualität schadet?", "a": "Führen Sie ein Evaluierungsset mit ein- und ausgeschalteter Komprimierung aus und vergleichen Sie die Aufgabenergebnisse, nicht nur die Token-Zahlen. Achten Sie auf selbstbewusst falsche Antworten und verworfene Einschränkungen – das sind die typischen Anzeichen einer verlustbehafteten Komprimierung, die zu weit gegangen ist." } ] }, "ja": { "name": "Context Compression", "summary": "Context Compressionは、モデルが動作するために実際に必要な情報を保持しながら、各呼び出しでモデルに提供されるトークン数を削減します。長期稼働するエージェントや長い会話で使用することで、コストとレイテンシを削減し、コンテキストウィンドウ内に収めることができます。3つの手段は、履歴の要約、無関係なコンテキストの整理、およびプロンプトの圧縮です。主なリスクは、重要な詳細を1つ落としてしまうという、情報の非可逆性（ロス）です。単に節約されたトークン数だけでなく、保持された情報を測定してください。", "problem": "長時間実行されるエージェントや複数ターンの会話はコンテキストを蓄積します。すべてのツール実行結果、過去のメッセージ、取得されたドキュメントが次の呼び出し時に再送されます。トークン数はインタラクションに伴ってほぼ線形に増加するため、呼び出しごとのコストとレイテンシが上昇し、最終的にはウィンドウが溢れて最も古い（時には最も重要な）コンテンツが暗黙的に切り捨てられます。単純な解決策（ウィンドウの拡大、よりアグレッシブな切り捨てなど）は、コストを上昇させるか、モデルが一貫性を維持するために必要な情報を破壊するかのどちらかです。", "context": "単一のステップが必要とする量に対して、コンテキストが際限なく増加する場合に適用されます。例えば、長い履歴を持つ会話型アシスタント、多数のツール呼び出しをループする自律型エージェント、過剰に取得を行うRAGパイプライン、プロンプトサイズがコストの大部分を占めるバッチジョブなどです。蓄積されたコンテキストの多くが冗長または古くなっており、プロンプトの組み立てを制御でき、ある程度の再構成エラーを許容できる場合に適しています。すべてのトークンが不可欠である場合（法務、監査、正確な想起が求められるタスク）や、インタラクションが十分に短くウィンドウが圧迫されることがない場合には適していません。", "solution": [ "稼働中のコンテキストを、単なる追記専用のログではなく、能動的に管理すべき「予算」として扱います。これには、相互に補完し合う3つの手段があります。要約（Summarization）は、履歴の一部をより短い概要に置き換えます。通常、古いターンのローリングサマリーを定期的に更新し、最近のターンはそのまま残します。プルーニング（Pruning）は、現在のステップに関連のないコンテキストを削除します。重複を排除し、古いツールの出力を破棄し、関連性しきい値を超える取得済みチャンクのみを選択します。プロンプト圧縮（Prompt compression、例：LLMLingua）は、より小さなモデルを使用して、プロンプトを送信する前に情報量の少ないトークンを削除または言い換え、わずかな精度低下と引き換えに大幅なトークン削減を実現します。\n\nこれらを明確な境界を持つパイプラインに構成します。そのまま残す直近のウィンドウ、古い履歴のローリングサマリー、そしてオンデマンドで埋められる取得スロットを維持します。識別子、制約事項、現在の目標など、決して圧縮してはならない事実のために「ピン留め（pinned）」領域を保護します。極めて重要なのは、結果を計測可能にすることです。圧縮ありと圧縮なしの回答を比較する評価セットを実行して、品質が低下するタイミングを把握し、グローバルではなくワークロードごとに圧縮の強度を調整します。圧縮は品質とコストのバランスを調整するダイヤルであり、無条件のメリットではありません。" ], "components": [ "ローリングサマライザー", "関連性プルーナー", "プロンプトコンプレッサー", "ピン留め領域", "コンテキスト予算コントローラー", "保持評価器" ], "benefits": [ "送信するトークン数を減らすことで、呼び出しごとの入力コストが直接削減され、長いエージェントループや大量のトラフィック全体でその効果が累積されます。", "プロンプトが小さくなると、エンコード量が減り、Time-to-First-Token（TTFT）が短縮されるため、インタラクティブなフローやエージェントフローにおける応答性が向上します。", "稼働中のコンテキストを制限することで、ウィンドウのオーバーフローや暗黙的な切り捨てを発生させることなく、長い会話や多数のステップを持つエージェントの実行を継続できます。", "冗長で古いコンテキストを削除することで、ノイズ（注意をそらす要素）が減り、モデルが現在重要な事項に集中できるようになるため、品質が向上する可能性があります。" ], "risks": [ "要約やプルーニングによって、後から決定打となるはずだった唯一の詳細情報が破棄され、もっともらしい誤回答（ハルシネーション）が生成される可能性があります。", "ローリングサマリーは過去のサマリーをさらに要約するため、わずかな欠落が多くのサイクルを経て累積し、最終的に会話の文脈がいつの間にか逸脱してしまう可能性があります。", "要約器や圧縮器を実行すること自体がレイテンシ、コスト、および障害点を増加させ、短いインタラクティブなやり取りにおいては削減効果が相殺される可能性があります。", "アグレッシブな排除を行うと、モデルが依然として依存している制約や指示が、明確なエラーシグナルなしに暗黙的に削除されてしまう可能性があります。" ], "whenNot": [ "すべてのトークンが不可欠である場合（法務、監査、コンプライアンス、または正確なデータ抽出など）、非可逆圧縮は許容されません。", "会話がウィンドウを圧迫することがほとんどない場合、圧縮のオーバーヘッドは節約できるコストを上回り、不要な複雑さを招くだけです。", "保持評価ハーネス（retention evaluation harness）がない場合は、何もデプロイすべきではありません。圧縮によって回答の品質が暗黙的に低下しているかどうかを判断できないためです。" ], "examples": [ "大規模なコードベースを反復処理するエージェントが、直近のウィンドウをそのまま残しつつ、以前のステップのローリングサマリーを保持し、タスク仕様とファイルパスをピン留めすることで目標を見失わないようにします。", "マルチセッションのサポートボットが、過去のターンをコンパクトなケースサマリーに要約し、解決済みのサブイシューをプルーニング（削除）する一方で、顧客のアカウント制約をピン留めします。", "多数のチャンクを取得する検索パイプラインが、関連性プルーニングとプロンプト圧縮を適用してシグナルの高い一節のみを送信し、回答を損なうことなくトークンを削減します。" ], "productionEvidence": { "context": "57日間にわたり観察された、シングルオペレーターかつローカルファーストのOpenClawデプロイメント（161セッション / 2,776ターン）。エージェント自身のトラジェクトリトレースから集計。", "scenario": "長い自律的なトランスクリプトが先制的に圧縮され、プロンプト予算内に収まるようにツールの実行結果が切り捨てられます。", "technology": "安全マージンを設けた先制的な圧縮、ツール実行結果の切り捨て、コンテキストプルーニングフック、およびターン途中でのオーバーフロー事前チェック。", "load": "57日間にわたる2,776ターンにおける、2,810件のコンテキストコンパイルイベント。", "results": "圧縮処理がウィンドウ全体でインライン実行され、コンテキストオーバーフローによる障害を発生させることなく、複数ステップの自律的なターンを予算内（ターンあたりp95 87.6秒）に維持しました。シングルオペレーターかつローカルファーストのデプロイメント。" }, "kpis": [ { "metric": "呼び出しあたりのトークン数（入力）", "note": "主要なコスト要因。圧縮前後の分布を追跡します。健全な結果とは、下流の（後続の）エラーが増加することなく、明確に削減されている状態です。" }, { "metric": "情報保持 / タスク品質", "note": "評価セットを用いて、圧縮ありと圧縮なしの回答を比較します。良好な状態とは、トークン数が減少しても、許容範囲内で品質が安定している状態です。" }, { "metric": "エンドツーエンドのレイテンシ", "note": "圧縮のオーバーヘッドを差し引いた正味の値。良好な状態とは全体のレイテンシが低下することです。要約器や圧縮器の呼び出しによって削減効果が相殺されないよう注意してください。" }, { "metric": "コンテキストオーバーフロー / 切り捨て率", "note": "インタラクションがウィンドウ制限に達する頻度。良好な状態とは、ピン留めされたコンテンツの破棄に頼ることなく、この頻度をゼロに近づけることです。" } ], "failureModes": [ "要約によって初期に言及された制約が省略され、何ターンも後に、その事実がコンテキストから完全に消失したためにエージェントが制約に違反してしまいます。", "再要約が繰り返されることで、言い換えのエラーや省略が増幅され、最終的に実行中のサマリーが実際に起こったことを反映しなくなります。", "予算の設定ミスにより、保護されるべき識別子や指示が圧縮され、暗黙的に正確性が損なわれます。", "アグレッシブな関連性しきい値によって、エッジケースで重要となるコンテキストが除外されてしまい、テストでは品質に問題がないように見えても、本番環境で失敗します。" ], "lessons": [ "トークン削減を最大化することは容易ですが、それ単体では意味がありません。真の指標は、モデルが依然として正しく回答できるかどうかです。", "識別子、制約事項、および現在の目標を明示的に保護し、いかなる圧縮ステージでもそれらが排除されないようにします。", "アクティブなコンテキストではなく、古い履歴を圧縮します。直近のやり取りには、意思決定に最も関連するシグナルが含まれています。", "評価セットを用いて、ワークロードごとに圧縮の強度を調整します。雑談において安全な設定であっても、監査タスクにおいては無謀な設定になり得ます。" ], "faqs": [ { "q": "これは長期記憶とどのように違うのですか？", "a": "長期記憶はプロンプトの外部に事実を永続化し、必要に応じてそれらを取得します。一方、コンテキスト圧縮は、呼び出しごとに送信される稼働中のコンテキストを縮小します。これらは補完関係にあります。記憶が「何を呼び戻すか」を決定し、圧縮が「それをいかにコンパクトにウィンドウ内に収めるか」を決定します。" }, { "q": "要約、プルーニング、圧縮のどれを使用すべきですか？", "a": "まずプルーニングを行います（コストがかからず、真の冗長性を排除する場合はロスレスです）。次に、古い履歴が際限なく増加する場合は要約を行い、さらに余裕（ヘッドルーム）が必要で、品質への影響を検証できる場合にのみプロンプト圧縮を追加します。ほとんどのシステムでは、これら3つすべてを組み合わせて使用します。" }, { "q": "圧縮が品質を損ねているかどうかをどのように判断すればよいですか？", "a": "圧縮のオンとオフを切り替えて評価セットを実行し、トークン数だけでなくタスクの結果を比較します。もっともらしい誤回答や制約の欠落に注意してください。これらは、非可逆圧縮が過度に行われた際の特徴的な兆候です。" } ] }, "zh": { "name": "上下文压缩", "summary": "上下文压缩在减少每次调用时输入给模型的 token 数量的同时，保留了模型实际执行操作所需的信息。在长期运行的智能体和长对话中使用它，可以降低成本和延迟，并保持在上下文窗口限制之内。其三大手段是总结历史记录、剪裁无关上下文以及压缩提示词。核心风险是信息有损：遗漏了那一个至关重要的细节。应衡量保留的信息量，而不仅仅是节省的 token 数量。", "problem": "长期运行的智能体（Agent）和多轮对话会不断累积上下文：每次工具调用结果、先前的消息以及检索到的文档都会在下一次调用中被重新传入。Token 数量随着交互呈近似线性增长，导致单次调用的成本和延迟不断攀升，最终导致窗口溢出，而最旧的（有时也是最重要的）内容会被静默截断。简单的解决方法——如扩大窗口、更激进地截断——要么会增加成本，要么会破坏模型保持连贯性所需的信息。", "context": "适用于上下文增长无界且远超单步执行所需的情况：具有漫长历史记录的对话助手、循环执行多次工具调用的自主智能体、检索过度的 RAG 流水线，以及 Prompt 大小主导成本的批处理任务。当累积的大部分上下文是冗余或过时的、你可以控制 Prompt 的组装，并且可以容忍一定的重构误差时，该模式非常适用。如果每个 Token 都至关重要（如法律、审计、精确召回任务），或者交互足够短以至于窗口从未面临压力，则不适用此模式。", "solution": [ "将实时上下文视为需要主动管理的预算，而不是一个只能追加的日志。存在三种互补的手段。摘要（Summarization）用更短的梗概替换一段历史记录——通常是定期更新的旧轮次滚动摘要，而最近的轮次则保持原样。剪枝（Pruning）移除与当前步骤无关的上下文：去重、丢弃过时的工具输出，并仅选择评分高于相关性阈值的检索分块。Prompt 压缩（Prompt compression）（例如 LLMLingua）在发送 Prompt 之前，使用较小的模型删除或改写低信息量的 Token，以微小的准确率损失换取大量的 Token 减少。\\n\\n将这些组合成一个具有明确边界的流水线：保留一个原样呈现的近期窗口、一个旧历史记录的滚动摘要，以及一个按需填充的检索插槽。保护一个“固定（pinned）”区域，用于存放绝不能被压缩的事实——如标识符、约束条件、当前目标。至关重要的是，对结果进行检测：运行评估集来对比启用和未启用压缩时的回答，以便观察质量何时下降，并针对每个工作负载（而非全局）调整压缩强度。压缩是质量与成本之间的权衡拨盘，而不是无代价的获益。" ], "components": [ "滚动摘要器", "相关性剪枝器", "Prompt 压缩器", "固定区域", "上下文预算控制器", "保留评估器" ], "benefits": [ "发送更少的 Token 可以直接降低每次调用的输入成本，这在长周期的智能体循环和高并发流量中会产生累积效应。", "更小的 Prompt 意味着更少的编码工作量和更短的首字延迟（Time-to-First-Token），从而提高交互式和智能体工作流中的响应速度。", "限制实时上下文的边界可以让长对话和多步骤智能体持续运行，而不会导致窗口溢出或静默截断。", "移除冗余和过时的上下文可以通过减少干扰来提高质量，帮助模型专注于当前重要的内容。" ], "risks": [ "摘要和剪枝可能会丢弃事后证明起决定性作用的单一细节，从而导致模型给出看似笃定却完全错误的回答。", "滚动摘要是对先前的摘要进行再摘要；微小的遗漏会在多个循环中累积，直到对话主题在不知不觉中偏离。", "运行摘要器或压缩器会增加其自身的延迟、成本和故障点，这可能会抵消在短期交互中节省的开销。", "激进的剔除可能会静默移除模型仍依赖的约束或指令，且不会发出明显的错误信号。" ], "whenNot": [ "当每个 Token 都至关重要时（如法律、审计、合规或精确数据提取），有损压缩是不可接受的。", "如果对话极少对窗口造成压力，压缩带来的开销将超过其节省的成本，并增加不必要的复杂性。", "在没有保留评估框架的情况下，不要部署任何内容：因为你无法判断压缩是否在静默降低回答的质量。" ], "examples": [ "在大型代码库上进行迭代的智能体保留了原样呈现的近期窗口以及早期步骤的滚动摘要，同时固定了任务规范和文件路径，以确保不会偏离目标。", "多会话支持机器人将先前的轮次总结为紧凑的案例摘要，剪枝已解决的子问题，同时固定客户的账户限制条件。", "获取多个分块的检索流水线应用相关性剪枝和 Prompt 压缩，以仅发送高信号段落，在不丢失答案的情况下减少 Token 数量。" ], "productionEvidence": { "context": "在 57 天内（161 个会话 / 2,776 轮次）观察到的单操作员、本地优先的 OpenClaw 部署，数据从智能体自身的轨迹追踪中聚合而来。", "scenario": "预先压缩长篇自主运行记录，并截断工具调用结果，以保持在 Prompt 预算之内。", "technology": "具有安全余量的预先压缩、工具结果截断、上下文剪枝钩子（Hook）以及轮次中途溢出预检。", "load": "在 57 天内的 2,776 轮次中，共发生 2,810 次上下文编译事件。", "results": "压缩在整个窗口中内联运行，使多步自主轮次保持在预算范围内（p95 为每轮 87.6 秒），且未出现上下文溢出故障。单操作员、本地优先部署。" }, "kpis": [ { "metric": "单次调用 Token 数（输入）", "note": "主要的成本驱动因素。追踪压缩前后的分布情况；健康的结果是 Token 数量明显减少，且下游错误没有增加。" }, { "metric": "信息保留度 / 任务质量", "note": "在评估集上对比启用和未启用压缩时的回答。理想的情况是，随着 Token 数量下降，质量在可接受的容差范围内保持稳定。" }, { "metric": "端到端延迟", "note": "扣除压缩开销后的净延迟。理想情况是降低总延迟；需注意避免摘要器或压缩器的调用开销抵消了节省的延迟。" }, { "metric": "上下文溢出 / 截断率", "note": "交互触及窗口限制的频率。理想情况是将此概率降至接近零，且无需丢弃固定内容。" } ], "failureModes": [ "摘要遗漏了早期提到的约束条件；许多轮次后，智能体违反了该约束，因为该事实已完全从上下文中消失。", "重复的重新摘要会放大改写错误和遗漏，直到运行中的摘要不再反映实际发生的情况。", "预算配置错误导致本应受到保护的标识符或指令被压缩，从而静默破坏了正确性。", "激进的相关性阈值过滤掉了对边缘情况至关重要的上下文，导致质量在测试中看起来很好，但在实际应用中却出现失败。" ], "lessons": [ "最大化减少 Token 数量非常简单，但孤立来看毫无意义；真正的衡量标准是模型是否仍能正确回答。", "显式保护标识符、约束条件和当前目标，确保任何压缩阶段都无法将其剔除。", "压缩旧的历史记录，而不是当前的活跃上下文；最近的交流承载着与决策最相关的信号。", "针对评估集调整每个工作负载的压缩强度；对闲聊安全的操作在审计任务中可能是鲁莽的。" ], "faqs": [ { "q": "这与长期记忆有什么不同？", "a": "长期记忆将事实持久化保存在 Prompt 之外，并根据需要进行检索；而上下文压缩则缩小了每次调用时发送的实时上下文。两者是互补的：记忆决定召回什么内容，压缩决定这些内容在窗口中以多紧凑的方式呈现。" }, { "q": "摘要、剪枝还是压缩——我应该使用哪一种？", "a": "首先进行剪枝（免费，且在移除真正的冗余时是无损的），当旧历史记录无界增长时对其进行摘要，并且只有在仍需要更多空间且能够验证质量损失时才加入 Prompt 压缩。大多数系统会结合使用这三者。" }, { "q": "我该如何知道压缩是否损害了质量？", "a": "在启用和禁用压缩的情况下运行评估集，并对比任务结果，而不仅仅是 Token 数量。留意看似笃定却完全错误的回答以及丢失的约束条件——这些都是有损压缩过度时的典型特征。" } ] } } }, { "slug": "correlated-run-trace", "category": "reliability", "updated": "2026-08-25", "version": "1.0", "url": "https://santismm.com/en/patterns/correlated-run-trace", "api": "https://santismm.com/api/patterns/correlated-run-trace", "canonical_url": "https://santismm.com/en/patterns/correlated-run-trace", "api_url": "https://santismm.com/api/patterns/correlated-run-trace", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "medium", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "OpenTelemetry GenAI semantic conventions", "Distributed tracing backends", "Tail-based sampling", "Field-level redaction at capture", "Append-only / WORM storage", "Structured logging with a propagated run id" ], "references": [ { "title": "OpenTelemetry — semantic conventions for GenAI", "url": "https://opentelemetry.io/docs/specs/semconv/gen-ai/" }, { "title": "EU AI Act — Article 12 (record-keeping)", "url": "https://artificialintelligenceact.eu/article/12/" }, { "title": "EU AI Act — consolidated text", "url": "https://eur-lex.europa.eu/eli/reg/2024/1689/oj" }, { "title": "NIST AI Risk Management Framework", "url": "https://www.nist.gov/itl/ai-risk-management-framework" }, { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" } ], "related": [ "recovery-strategy", "evaluator-optimizer", "human-escalation", "attributed-memory", "output-boundary-encoding" ], "locales": { "en": { "name": "Correlated Run Trace", "summary": "One identifier threads a whole agent run — inputs, model and version, every tool call with its arguments and outcome, the final action — into a record you can replay months later. The hard part is not capture. It is being complete enough to reconstruct the run and restrained enough that the trace store is not a second copy of the data it describes.", "definition": "A correlated run trace is an immutable, single-identifier record of everything an agent run decided and did, captured at a fidelity that lets someone reconstruct the run end to end afterwards without access to the systems that produced it, and redacted so that the trace does not become an easier target than the source. It is a record of the agent's decisions, not a request log.", "problem": "Agents are non-deterministic and multi-step, so 'what happened' cannot be inferred from the output. Most teams do log, and still cannot answer why a specific run did what it did: the steps are in different systems with no shared identifier, the prompt was recorded as a template reference that has since changed, or the model version was never captured, so nobody can tell whether the behaviour drifted or the model did.", "context": "Any agent whose actions have consequences someone will later ask about: a regulated process where the trace is the audit trail and traceability is an obligation rather than a preference, an incident that needs a root cause, a customer disputing an outcome, or an evaluation loop that needs real failures to learn from.", "solution": [ "Mint one run identifier at the entry point and propagate it through every step, service and retry. Correlation is the whole value: unlinked records of the same run are three logs, not a trace.", "Record the rendered prompt, not a reference to it. A template id resolves to whatever the template says today, which is not what the model saw.", "Capture the model and its version alongside every call. Without it, a behaviour change and a model change are indistinguishable after the fact.", "Log tool calls as arguments plus outcome, including the failures and the retries. A trace that shows only successful calls describes a run that did not happen.", "Redact at capture, not at read. Field-level rules that drop or hash secrets and personal data before the record is written, because a redaction applied at query time still leaves the raw value in storage.", "Sample on the tail, not the head. Decide what to keep after the run finishes, so errors, escalations and anomalies are kept and the routine successes are the ones thinned.", "Make the store append-only and give it the access controls of the most sensitive system it describes, not the ones a logging backend ships with." ], "components": [ "A run identifier minted at entry and propagated through every step, service, retry and asynchronous continuation.", "A span per step with a stable schema: inputs, model and version, tool name, arguments, outcome, latency, token usage.", "Field-level redaction applied at capture, with an explicit list of what is dropped, what is hashed and what is kept whole.", "Tail-based sampling that decides after the fact, so anomalous runs survive and routine ones are thinned.", "Append-only storage with retention aligned to the obligation that justifies the record, and access control matching the source systems.", "A replay path that reconstructs a run from the trace alone, used often enough that its gaps are known." ], "benefits": [ "Makes non-deterministic failures diagnosable: you can answer why this run did this, instead of reproducing until it happens again.", "Turns record-keeping obligations into an artefact rather than a promise. The reconstruction either works on a random past run or it does not.", "Feeds evaluation with real failures instead of invented ones, which is the difference between a benchmark and a regression suite.", "Separates drift from deployment. With the model version in the record, 'it got worse' becomes a question with an answer." ], "risks": [ "The trace store as the softest target: it holds the same data as the systems it describes, usually with weaker access control and longer retention.", "Capture cost that grows with traffic until someone samples on the head to save money, quietly removing exactly the runs worth keeping.", "Redaction that removes what the reconstruction needed. Over-redaction is invisible until the day someone tries to replay a run and cannot.", "Volume mistaken for coverage. Terabytes of spans with no shared identifier still cannot answer a single question about one run." ], "whenNot": [ "Single-step, deterministic calls where the input and the output are the whole story. A request log already reconstructs those.", "Prototypes with no users and no obligations, where the cost of the trace pipeline exceeds anything you would learn from it.", "Where the applicable rule forbids retaining the content at all. Then the trace records that a decision happened and its metadata, and the content stays out — that is a different artefact, and pretending otherwise creates the liability the rule was written to avoid." ], "examples": [ "An incident where an agent emailed the wrong customer. The run identifier links the retrieval that returned the wrong record, the tool call that used it and the message sent, so the root cause is one query rather than a week of reproduction attempts.", "A regulator asks how a decision was reached six months ago. The replay path rebuilds the run from the trace alone, including the model version in force that day.", "A quality drop after a model upgrade. Because every span carries the model version, the comparison is between two populations of real runs rather than between impressions." ], "kpis": [ { "metric": "Reconstruction success rate", "note": "Share of randomly chosen past runs that can be rebuilt end to end from the trace alone. This is the control's own test, and it is the only number here that cannot be satisfied by capturing more." }, { "metric": "Correlation completeness", "note": "Share of spans in a run that carry the run identifier. Anything below 100% means some step is invisible, and the missing one is rarely the boring one." }, { "metric": "Sensitive-field escape rate", "note": "Share of sampled records containing a value the redaction rules should have removed. The target is zero; any other number means the trace store is accumulating a liability." }, { "metric": "Anomalous-run retention", "note": "Share of errored or escalated runs retained after sampling. Head-based sampling drives this toward the sample rate, which is the failure this metric exists to catch." } ], "failureModes": [ "The trace that proves nothing: every step is logged, no step shares an identifier, and reconstructing one run means correlating timestamps by hand.", "The prompt recorded by reference. The template changed, so the log now describes a prompt the model never saw, and nobody notices until a reconstruction contradicts the output.", "Head-based sampling that keeps the ordinary. The run you need was dropped at the entry point, before anything knew it was going to be interesting.", "The log as the breach: raw tool arguments carry personal data into a store with broader access and longer retention than the database they came from.", "Missing model version. A behaviour change and a silent model update look identical in the record, and the investigation stalls on a question the trace should have answered." ], "lessons": [ "Correlation is the product; capture is the raw material. Teams that buy a tracing backend and skip the identifier end up with storage rather than answers.", "Test the reconstruction, not the pipeline. Pick a random past run and rebuild it — the gaps are always somewhere nobody instrumented, and only the attempt finds them.", "Redact at write time. Every redaction deferred to read time is a decision to keep the raw value, and storage outlives the intention.", "Sample on the tail. Head-based sampling is a decision to discard the interesting runs made before anything knows which ones those are.", "Record the model version everywhere. It costs a field and it is the difference between diagnosing drift and arguing about it." ], "faqs": [ { "q": "We already use a tracing backend. Isn't this solved?", "a": "A backend gives you capture and storage. This pattern is about the three things a backend does not decide for you: whether one identifier threads the whole run, whether the fidelity is enough to reconstruct it without the source systems, and whether what you wrote down is safe to keep. Teams with excellent tooling routinely fail the reconstruction test." }, { "q": "Doesn't full capture conflict with data minimisation?", "a": "It would, if capture meant keeping everything raw. The control states both halves on purpose — enough to reconstruct, nothing that turns the log into the breach — and the way to hold both is field-level redaction at capture plus retention tied to the obligation that justifies the record. What you cannot do is decide the tension away by keeping everything and calling it compliance." }, { "q": "How much fidelity is enough?", "a": "Exactly enough to pass the reconstruction test on a run picked at random, and no more. That threshold is discoverable by trying it, which is why the test belongs in the routine rather than in an audit. Anything captured beyond it is cost and liability without a question it answers." } ] }, "es": { "name": "Traza de ejecución correlada", "summary": "Un identificador hilvana la ejecución entera de un agente —entradas, modelo y versión, cada llamada a herramienta con sus argumentos y su resultado, la acción final— en un registro que puedes reproducir meses después. Lo difícil no es capturar. Es ser lo bastante completo para reconstruir la ejecución y lo bastante contenido para que el almacén de trazas no sea una segunda copia de los datos que describe.", "definition": "Una traza de ejecución correlada es un registro inmutable, con un único identificador, de todo lo que una ejecución de agente decidió e hizo, capturado con la fidelidad suficiente para que alguien pueda reconstruirla de punta a punta después sin acceso a los sistemas que la produjeron, y redactado de forma que la traza no sea un objetivo más fácil que el origen. Es el registro de decisiones del agente, no un log de peticiones.", "problem": "Los agentes son no deterministas y de varios pasos, así que «qué pasó» no se deduce de la salida. Casi todos los equipos registran algo y aun así no pueden explicar por qué una ejecución concreta hizo lo que hizo: los pasos están en sistemas distintos sin identificador común, el prompt se guardó como referencia a una plantilla que ya ha cambiado, o nunca se capturó la versión del modelo, así que nadie puede decir si derivó el comportamiento o cambió el modelo.", "context": "Cualquier agente cuyas acciones tengan consecuencias por las que alguien vaya a preguntar después: un proceso regulado donde la traza es el rastro de auditoría y la trazabilidad es una obligación y no una preferencia, un incidente que necesita causa raíz, un cliente que discute un resultado, o un bucle de evaluación que necesita fallos reales de los que aprender.", "solution": [ "Emite un identificador de ejecución en el punto de entrada y propágalo por cada paso, servicio y reintento. La correlación es todo el valor: registros sin enlazar de la misma ejecución son tres logs, no una traza.", "Guarda el prompt renderizado, no una referencia a él. Un identificador de plantilla resuelve a lo que la plantilla diga hoy, que no es lo que vio el modelo.", "Captura el modelo y su versión junto a cada llamada. Sin eso, un cambio de comportamiento y un cambio de modelo son indistinguibles a posteriori.", "Registra las llamadas a herramientas como argumentos más resultado, incluidos los fallos y los reintentos. Una traza que solo enseña las llamadas que salieron bien describe una ejecución que no ocurrió.", "Redacta en la captura, no en la lectura. Reglas por campo que descartan o hashean secretos y datos personales antes de escribir el registro, porque una redacción aplicada al consultar deja el valor crudo en el almacenamiento.", "Muestrea por la cola, no por la cabeza. Decide qué conservar cuando la ejecución ha terminado, de modo que se guarden los errores, los escalados y las anomalías y se adelgacen los éxitos rutinarios.", "Haz el almacén de solo anexado y dale los controles de acceso del sistema más sensible que describe, no los que trae por defecto un backend de logs." ], "components": [ "Un identificador de ejecución emitido en la entrada y propagado por cada paso, servicio, reintento y continuación asíncrona.", "Un span por paso con esquema estable: entradas, modelo y versión, nombre de herramienta, argumentos, resultado, latencia, consumo de tokens.", "Redacción por campo aplicada en la captura, con una lista explícita de qué se descarta, qué se hashea y qué se guarda entero.", "Muestreo por la cola que decide a posteriori, para que las ejecuciones anómalas sobrevivan y se adelgacen las rutinarias.", "Almacenamiento de solo anexado, con retención alineada a la obligación que justifica el registro y control de acceso equivalente al de los sistemas de origen.", "Un camino de reproducción que reconstruya una ejecución solo desde la traza, usado con la frecuencia suficiente para que sus huecos se conozcan." ], "benefits": [ "Hace diagnosticables los fallos no deterministas: puedes responder por qué esta ejecución hizo esto, en vez de reproducir hasta que vuelva a pasar.", "Convierte las obligaciones de registro en un artefacto en vez de una promesa. La reconstrucción funciona sobre una ejecución pasada al azar o no funciona.", "Alimenta la evaluación con fallos reales en vez de inventados, que es la diferencia entre un benchmark y una suite de regresión.", "Separa la deriva del despliegue. Con la versión del modelo en el registro, «ha empeorado» pasa a ser una pregunta con respuesta." ], "risks": [ "El almacén de trazas como el blanco más blando: guarda los mismos datos que los sistemas que describe, normalmente con menos control de acceso y más retención.", "Coste de captura que crece con el tráfico hasta que alguien muestrea por la cabeza para ahorrar, eliminando en silencio justo las ejecuciones que merecía la pena guardar.", "Redacción que se lleva por delante lo que la reconstrucción necesitaba. Redactar de más es invisible hasta el día en que alguien intenta reproducir una ejecución y no puede.", "Confundir volumen con cobertura. Terabytes de spans sin identificador común siguen sin poder responder ni una pregunta sobre una ejecución." ], "whenNot": [ "Llamadas deterministas de un solo paso donde la entrada y la salida son toda la historia. Un log de peticiones ya las reconstruye.", "Prototipos sin usuarios ni obligaciones, donde el coste del pipeline de trazas supera cualquier cosa que fueras a aprender de él.", "Donde la norma aplicable prohíba retener el contenido. Entonces la traza registra que hubo una decisión y sus metadatos, y el contenido se queda fuera: es otro artefacto, y fingir lo contrario crea justo la responsabilidad que la norma quería evitar." ], "examples": [ "Un incidente en el que un agente escribió al cliente equivocado. El identificador de ejecución enlaza la recuperación que devolvió el registro erróneo, la llamada a herramienta que lo usó y el mensaje enviado, así que la causa raíz es una consulta y no una semana de intentos de reproducción.", "Un regulador pregunta cómo se tomó una decisión hace seis meses. El camino de reproducción reconstruye la ejecución solo desde la traza, incluida la versión del modelo vigente aquel día.", "Una caída de calidad tras actualizar el modelo. Como cada span lleva la versión, la comparación es entre dos poblaciones de ejecuciones reales y no entre impresiones." ], "kpis": [ { "metric": "Tasa de reconstrucción con éxito", "note": "Proporción de ejecuciones pasadas elegidas al azar que se pueden rehacer de punta a punta solo desde la traza. Es la prueba que el propio control define, y el único número de esta lista que no se satisface capturando más." }, { "metric": "Completitud de la correlación", "note": "Proporción de spans de una ejecución que llevan el identificador. Cualquier cifra por debajo del 100% significa que hay un paso invisible, y el que falta rara vez es el aburrido." }, { "metric": "Tasa de fuga de campos sensibles", "note": "Proporción de registros muestreados que contienen un valor que las reglas de redacción debían haber quitado. El objetivo es cero; cualquier otra cifra significa que el almacén de trazas está acumulando una responsabilidad." }, { "metric": "Retención de ejecuciones anómalas", "note": "Proporción de ejecuciones con error o escalado que sobreviven al muestreo. El muestreo por cabeza lleva esta cifra hacia la tasa de muestreo, que es justo el fallo que esta métrica existe para cazar." } ], "failureModes": [ "La traza que no prueba nada: cada paso está registrado, ninguno comparte identificador, y reconstruir una ejecución significa correlacionar marcas de tiempo a mano.", "El prompt guardado por referencia. La plantilla cambió, así que el log describe ahora un prompt que el modelo nunca vio, y nadie se entera hasta que una reconstrucción contradice la salida.", "Muestreo por cabeza que se queda lo corriente. La ejecución que necesitas se descartó en el punto de entrada, antes de que nada supiera que iba a ser interesante.", "El log como brecha: argumentos de herramienta en crudo llevan datos personales a un almacén con más acceso y más retención que la base de datos de la que salieron.", "Falta la versión del modelo. Un cambio de comportamiento y una actualización silenciosa del modelo se ven idénticos en el registro, y la investigación se atasca en una pregunta que la traza debería haber respondido." ], "lessons": [ "La correlación es el producto; la captura es la materia prima. Los equipos que compran un backend de trazas y se saltan el identificador acaban con almacenamiento, no con respuestas.", "Prueba la reconstrucción, no el pipeline. Coge una ejecución pasada al azar y rehazla: los huecos están siempre donde nadie instrumentó, y solo el intento los encuentra.", "Redacta al escribir. Cada redacción aplazada a la lectura es una decisión de conservar el valor crudo, y el almacenamiento sobrevive a la intención.", "Muestrea por la cola. El muestreo por cabeza es una decisión de tirar las ejecuciones interesantes tomada antes de que nada sepa cuáles son.", "Registra la versión del modelo en todas partes. Cuesta un campo y es la diferencia entre diagnosticar la deriva y discutir sobre ella." ], "faqs": [ { "q": "Ya usamos un backend de trazas. ¿No está resuelto?", "a": "Un backend te da captura y almacenamiento. Este patrón trata las tres cosas que un backend no decide por ti: si un único identificador hilvana la ejecución entera, si la fidelidad basta para reconstruirla sin los sistemas de origen, y si lo que anotaste es seguro de conservar. Equipos con herramientas excelentes fallan la prueba de reconstrucción con toda normalidad." }, { "q": "¿La captura completa no choca con la minimización de datos?", "a": "Chocaría si capturar significara guardarlo todo en crudo. El control enuncia las dos mitades a propósito —lo suficiente para reconstruir, nada que convierta el log en la brecha— y la manera de sostener ambas es redacción por campo en la captura más retención atada a la obligación que justifica el registro. Lo que no vale es zanjar la tensión guardándolo todo y llamarlo cumplimiento." }, { "q": "¿Cuánta fidelidad es suficiente?", "a": "Exactamente la que hace falta para pasar la prueba de reconstrucción sobre una ejecución elegida al azar, y ni una más. Ese umbral se descubre intentándolo, que es la razón de que la prueba pertenezca a la rutina y no a una auditoría. Todo lo capturado por encima es coste y responsabilidad sin una pregunta a la que responda." } ] }, "pt": { "name": "Trace de execução correlacionado", "summary": "Um identificador costura a execução inteira de um agente — entradas, modelo e versão, cada chamada de ferramenta com seus argumentos e resultado, a ação final — em um registro que se pode reproduzir meses depois. O difícil não é capturar. É ser completo o bastante para reconstruir a execução e contido o bastante para que o repositório de traces não seja uma segunda cópia dos dados que descreve.", "definition": "Um trace de execução correlacionado é um registro imutável, com um único identificador, de tudo o que uma execução de agente decidiu e fez, capturado com fidelidade suficiente para que alguém possa reconstruí-la de ponta a ponta depois, sem acesso aos sistemas que a produziram, e redigido de modo que o trace não seja um alvo mais fácil do que a origem. É o registro de decisões do agente, não um log de requisições.", "problem": "Agentes são não determinísticos e de vários passos, então “o que aconteceu” não se deduz da saída. Quase todas as equipes registram algo e ainda assim não conseguem explicar por que uma execução específica fez o que fez: os passos estão em sistemas diferentes sem identificador comum, o prompt foi salvo como referência a um template que já mudou, ou a versão do modelo nunca foi capturada, então ninguém consegue dizer se o comportamento derivou ou se o modelo mudou.", "context": "Qualquer agente cujas ações tenham consequências sobre as quais alguém vai perguntar depois: um processo regulado onde o trace é a trilha de auditoria e a rastreabilidade é uma obrigação e não uma preferência, um incidente que precisa de causa raiz, um cliente que contesta um resultado, ou um ciclo de avaliação que precisa de falhas reais para aprender.", "solution": [ "Emita um identificador de execução no ponto de entrada e propague-o por cada passo, serviço e nova tentativa. A correlação é todo o valor: registros desconectados da mesma execução são três logs, não um trace.", "Grave o prompt renderizado, não uma referência a ele. Um identificador de template resolve para o que o template diz hoje, que não é o que o modelo viu.", "Capture o modelo e sua versão junto de cada chamada. Sem isso, uma mudança de comportamento e uma mudança de modelo são indistinguíveis depois do fato.", "Registre as chamadas de ferramenta como argumentos mais resultado, incluindo as falhas e as novas tentativas. Um trace que mostra só as chamadas bem-sucedidas descreve uma execução que não aconteceu.", "Redija na captura, não na leitura. Regras por campo que descartam ou aplicam hash a segredos e dados pessoais antes de o registro ser escrito, porque uma redação aplicada na consulta deixa o valor cru no armazenamento.", "Amostre pela cauda, não pela cabeça. Decida o que guardar depois que a execução termina, de modo que erros, escalonamentos e anomalias sejam mantidos e os sucessos rotineiros sejam os afinados.", "Faça o repositório apenas de acréscimo e dê a ele os controles de acesso do sistema mais sensível que descreve, não os que um backend de logs traz por padrão." ], "components": [ "Um identificador de execução emitido na entrada e propagado por cada passo, serviço, nova tentativa e continuação assíncrona.", "Um span por passo com esquema estável: entradas, modelo e versão, nome da ferramenta, argumentos, resultado, latência, consumo de tokens.", "Redação por campo aplicada na captura, com uma lista explícita do que é descartado, do que recebe hash e do que é guardado inteiro.", "Amostragem pela cauda que decide depois do fato, para que execuções anômalas sobrevivam e as rotineiras sejam afinadas.", "Armazenamento apenas de acréscimo, com retenção alinhada à obrigação que justifica o registro e controle de acesso equivalente ao dos sistemas de origem.", "Um caminho de reprodução que reconstrua uma execução só a partir do trace, usado com frequência suficiente para que suas lacunas sejam conhecidas." ], "benefits": [ "Torna diagnosticáveis as falhas não determinísticas: dá para responder por que esta execução fez isto, em vez de reproduzir até acontecer de novo.", "Transforma obrigações de registro em artefato e não em promessa. A reconstrução funciona sobre uma execução passada ao acaso, ou não funciona.", "Alimenta a avaliação com falhas reais em vez de inventadas, que é a diferença entre um benchmark e uma suíte de regressão.", "Separa a deriva do deploy. Com a versão do modelo no registro, “piorou” vira uma pergunta com resposta." ], "risks": [ "O repositório de traces como o alvo mais fraco: guarda os mesmos dados dos sistemas que descreve, em geral com menos controle de acesso e mais retenção.", "Custo de captura que cresce com o tráfego até alguém amostrar pela cabeça para economizar, removendo em silêncio justamente as execuções que valia a pena guardar.", "Redação que leva embora o que a reconstrução precisava. Redigir demais é invisível até o dia em que alguém tenta reproduzir uma execução e não consegue.", "Confundir volume com cobertura. Terabytes de spans sem identificador comum continuam sem responder uma única pergunta sobre uma execução." ], "whenNot": [ "Chamadas determinísticas de um só passo, onde a entrada e a saída são a história inteira. Um log de requisições já as reconstrói.", "Protótipos sem usuários e sem obrigações, onde o custo do pipeline de traces supera qualquer coisa que você fosse aprender com ele.", "Onde a norma aplicável proíba reter o conteúdo. Então o trace registra que houve uma decisão e seus metadados, e o conteúdo fica de fora: é outro artefato, e fingir o contrário cria exatamente a responsabilidade que a norma queria evitar." ], "examples": [ "Um incidente em que um agente escreveu ao cliente errado. O identificador de execução liga a recuperação que devolveu o registro errado, a chamada de ferramenta que o usou e a mensagem enviada, então a causa raiz é uma consulta e não uma semana de tentativas de reprodução.", "Um regulador pergunta como uma decisão foi tomada seis meses atrás. O caminho de reprodução reconstrói a execução só a partir do trace, incluindo a versão do modelo vigente naquele dia.", "Uma queda de qualidade depois de atualizar o modelo. Como cada span carrega a versão, a comparação é entre duas populações de execuções reais e não entre impressões." ], "kpis": [ { "metric": "Taxa de reconstrução bem-sucedida", "note": "Proporção de execuções passadas escolhidas ao acaso que podem ser refeitas de ponta a ponta só a partir do trace. É o teste que o próprio controle define, e o único número desta lista que não se satisfaz capturando mais." }, { "metric": "Completude da correlação", "note": "Proporção de spans de uma execução que carregam o identificador. Qualquer número abaixo de 100% significa que há um passo invisível, e o que falta raramente é o entediante." }, { "metric": "Taxa de vazamento de campos sensíveis", "note": "Proporção de registros amostrados que contêm um valor que as regras de redação deveriam ter removido. O alvo é zero; qualquer outro número significa que o repositório de traces está acumulando uma responsabilidade." }, { "metric": "Retenção de execuções anômalas", "note": "Proporção de execuções com erro ou escalonamento que sobrevivem à amostragem. A amostragem pela cabeça leva esse número para perto da taxa de amostragem, que é justamente a falha que esta métrica existe para pegar." } ], "failureModes": [ "O trace que não prova nada: cada passo está registrado, nenhum compartilha identificador, e reconstruir uma execução significa correlacionar marcas de tempo à mão.", "O prompt salvo por referência. O template mudou, então o log agora descreve um prompt que o modelo nunca viu, e ninguém percebe até uma reconstrução contradizer a saída.", "Amostragem pela cabeça que fica com o comum. A execução de que você precisa foi descartada no ponto de entrada, antes de qualquer coisa saber que seria interessante.", "O log como brecha: argumentos de ferramenta crus levam dados pessoais para um repositório com mais acesso e mais retenção do que o banco de dados de onde saíram.", "Falta a versão do modelo. Uma mudança de comportamento e uma atualização silenciosa do modelo parecem idênticas no registro, e a investigação empaca numa pergunta que o trace deveria ter respondido." ], "lessons": [ "A correlação é o produto; a captura é a matéria-prima. Equipes que compram um backend de traces e pulam o identificador acabam com armazenamento, não com respostas.", "Teste a reconstrução, não o pipeline. Pegue uma execução passada ao acaso e refaça-a: as lacunas estão sempre onde ninguém instrumentou, e só a tentativa as encontra.", "Redija na escrita. Toda redação adiada para a leitura é uma decisão de conservar o valor cru, e o armazenamento sobrevive à intenção.", "Amostre pela cauda. A amostragem pela cabeça é uma decisão de jogar fora as execuções interessantes tomada antes de qualquer coisa saber quais são.", "Registre a versão do modelo em todo lugar. Custa um campo e é a diferença entre diagnosticar a deriva e discutir sobre ela." ], "faqs": [ { "q": "Já usamos um backend de traces. Isso não está resolvido?", "a": "Um backend dá captura e armazenamento. Este padrão trata das três coisas que um backend não decide por você: se um único identificador costura a execução inteira, se a fidelidade basta para reconstruí-la sem os sistemas de origem, e se o que você anotou é seguro de guardar. Equipes com ferramentas excelentes falham o teste de reconstrução com toda a naturalidade." }, { "q": "A captura completa não conflita com a minimização de dados?", "a": "Conflitaria, se capturar significasse guardar tudo cru. O controle enuncia as duas metades de propósito — o suficiente para reconstruir, nada que transforme o log na brecha — e a maneira de sustentar ambas é redação por campo na captura mais retenção atada à obrigação que justifica o registro. O que não vale é resolver a tensão guardando tudo e chamando isso de conformidade." }, { "q": "Quanta fidelidade é suficiente?", "a": "Exatamente a necessária para passar no teste de reconstrução sobre uma execução escolhida ao acaso, e nada além. Esse limiar se descobre tentando, e é por isso que o teste pertence à rotina e não a uma auditoria. Tudo o que for capturado além disso é custo e responsabilidade sem uma pergunta a que responda." } ] }, "fr": { "name": "Trace d'exécution corrélée", "summary": "Un identifiant unique relie toute une exécution d'agent — entrées, modèle et version, chaque appel d'outil avec ses arguments et son résultat, l'action finale — dans un enregistrement que vous pouvez rejouer des mois plus tard. Le plus difficile n'est pas la capture. C'est d'être assez complet pour reconstruire l'exécution et assez mesuré pour que le stockage des traces ne devienne pas une seconde copie des données qu'il décrit.", "definition": "Une trace d'exécution corrélée est un enregistrement immuable, doté d'un identifiant unique, de tout ce qu'une exécution d'agent a décidé et fait, capturé avec une fidélité qui permet de reconstruire l'exécution de bout en bout a posteriori sans accès aux systèmes qui l'ont produite, et expurgé afin que la trace ne devienne pas une cible plus facile que la source. Il s'agit d'un enregistrement des décisions de l'agent, et non d'un journal de requêtes.", "problem": "Les agents sont non déterministes et multi-étapes, de sorte que « ce qui s'est passé » ne peut être déduit du résultat. La plupart des équipes effectuent des journaux d'activité, mais ne peuvent toujours pas expliquer pourquoi une exécution spécifique a agi ainsi : les étapes se trouvent dans des systèmes différents sans identifiant partagé, le prompt a été enregistré sous forme de référence de modèle qui a changé depuis, ou la version du modèle n'a jamais été capturée, de sorte que personne ne peut dire si c'est le comportement ou le modèle qui a dérivé.", "context": "Tout agent dont les actions ont des conséquences sur lesquelles on s'interrogera plus tard : un processus réglementé où la trace constitue la piste d'audit et où la traçabilité est une obligation plutôt qu'une préférence, un incident nécessitant une analyse de cause racine, un client contestant un résultat, ou une boucle d'évaluation qui a besoin de défaillances réelles pour apprendre.", "solution": [ "Générez un identifiant d'exécution unique au point d'entrée et propagez-le à travers chaque étape, service et tentative. La corrélation fait toute la valeur : des enregistrements non liés d'une même exécution ne sont que trois journaux, pas une trace.", "Enregistrez le prompt généré, pas une référence à celui-ci. Un ID de template résout ce que le template contient aujourd'hui, ce qui n'est pas ce que le modèle a vu.", "Capturez le modèle et sa version lors de chaque appel. Sans cela, un changement de comportement et un changement de modèle sont impossibles à distinguer après coup.", "Enregistrez les appels d'outils sous forme d'arguments accompagnés de leur résultat, y compris les échecs et les tentatives. Une trace qui ne montre que les appels réussis décrit une exécution qui n'a pas eu lieu.", "Masquez lors de la capture, pas à la lecture. Appliquez des règles au niveau des champs pour supprimer ou hacher les secrets et les données personnelles avant l'écriture de l'enregistrement, car un masquage appliqué au moment de la requête laisse toujours la valeur brute dans le stockage.", "Échantillonnez sur la fin (tail-based), pas au début (head-based). Décidez de ce qu'il faut conserver après la fin de l'exécution, afin que les erreurs, les escalades et les anomalies soient conservées et que les succès de routine soient ceux qui sont réduits.", "Rendez le stockage accessible uniquement en écriture à la suite (append-only) et attribuez-lui les contrôles d'accès du système le plus sensible qu'il décrit, et non ceux fournis par défaut avec un backend de journalisation." ], "components": [ "Un identifiant d'exécution généré à l'entrée et propagé à travers chaque étape, service, tentative et continuation asynchrone.", "Un span par étape avec un schéma stable : entrées, modèle et version, nom de l'outil, arguments, résultat, latence, utilisation des tokens.", "Un masquage au niveau des champs appliqué lors de la capture, avec une liste explicite de ce qui est supprimé, de ce qui est haché et de ce qui est conservé intact.", "Un échantillonnage tail-based qui décide après coup, de sorte que les exécutions anormales survivent et que les exécutions de routine soient réduites.", "Un stockage en écriture à la suite (append-only) avec une rétention alignée sur l'obligation qui justifie l'enregistrement, et un contrôle d'accès correspondant aux systèmes sources.", "Un chemin de relecture qui reconstruit une exécution à partir de la seule trace, utilisé assez souvent pour que ses lacunes soient connues." ], "benefits": [ "Rend les échecs non déterministes diagnostiquables : vous pouvez expliquer pourquoi cette exécution a agi ainsi, au lieu de la reproduire jusqu'à ce que cela se reproduise.", "Transforme les obligations de tenue de registres en un artefact plutôt qu'en une promesse. La reconstruction fonctionne sur une exécution passée aléatoire, ou elle ne fonctionne pas.", "Alimente l'évaluation avec des échecs réels plutôt qu'inventés, ce qui fait toute la différence entre un benchmark et une suite de non-régression.", "Sépare la dérive du déploiement. Avec la version du modèle dans l'enregistrement, « cela s'est dégradé » devient une question qui a une réponse." ], "risks": [ "Le stockage des traces comme cible la plus vulnérable : il contient les mêmes données que les systèmes qu'il décrit, généralement avec un contrôle d'accès plus faible et une rétention plus longue.", "Un coût de capture qui augmente avec le trafic jusqu'à ce que quelqu'un applique un échantillonnage head-based pour économiser de l'argent, supprimant discrètement les exécutions qui méritaient précisément d'être conservées.", "Un masquage qui supprime ce dont la reconstruction avait besoin. Un sur-masquage reste invisible jusqu'au jour où quelqu'un tente de rejouer une exécution et n'y parvient pas.", "Le volume confondu avec la couverture. Des téraoctets de spans sans identifiant partagé ne permettent toujours pas de répondre à une seule question sur une exécution donnée." ], "whenNot": [ "Appels déterministes à étape unique où l'entrée et la sortie résument toute l'histoire. Un journal de requêtes permet déjà de les reconstruire.", "Prototypes sans utilisateurs ni obligations, où le coût du pipeline de traces dépasse tout ce que vous pourriez en apprendre.", "Lorsque la règle applicable interdit totalement de conserver le contenu. Dans ce cas, la trace enregistre qu'une décision a eu lieu ainsi que ses métadonnées, et le contenu reste exclu — il s'agit d'un artefact différent, et prétendre le contraire crée la responsabilité que la règle visait à éviter." ], "examples": [ "Un incident où un agent a envoyé un e-mail au mauvais client. L'identifiant d'exécution lie la récupération qui a renvoyé le mauvais enregistrement, l'appel d'outil qui l'a utilisé et le message envoyé, de sorte que la cause racine se résume à une seule requête plutôt qu'à une semaine de tentatives de reproduction.", "Un régulateur demande comment une décision a été prise il y a six mois. Le chemin de relecture reconstruit l'exécution à partir de la seule trace, y compris la version du modèle en vigueur ce jour-là.", "Une baisse de qualité après la mise à niveau d'un modèle. Comme chaque span contient la version du modèle, la comparaison s'effectue entre deux populations d'exécutions réelles plutôt qu'entre des impressions." ], "kpis": [ { "metric": "Taux de réussite de la reconstruction", "note": "Part des exécutions passées choisies au hasard qui peuvent être reconstruites de bout en bout à partir de la seule trace. Il s'agit du propre test du contrôle, et c'est le seul chiffre ici qui ne peut pas être amélioré simplement en capturant davantage de données." }, { "metric": "Complétude de la corrélation", "note": "Part des spans d'une exécution qui portent l'identifiant d'exécution. Tout résultat inférieur à 100 % signifie qu'une étape est invisible, et l'étape manquante est rarement la plus banale." }, { "metric": "Taux d'échappement des champs sensibles", "note": "Part des enregistrements échantillonnés contenant une valeur que les règles de masquage auraient dû supprimer. L'objectif est de zéro ; tout autre chiffre signifie que le stockage des traces accumule un risque juridique." }, { "metric": "Rétention des exécutions anormales", "note": "Part des exécutions en erreur ou escaladées conservées après échantillonnage. L'échantillonnage head-based pousse ce chiffre vers le taux d'échantillonnage global, ce qui constitue précisément la défaillance que cette métrique vise à détecter." } ], "failureModes": [ "La trace qui ne prouve rien : chaque étape est journalisée, aucune étape ne partage d'identifiant, et reconstruire une exécution implique de corréler les horodatages à la main.", "Le prompt enregistré par référence. Le template a changé, de sorte que le journal décrit désormais un prompt que le modèle n'a jamais vu, et personne ne s'en aperçoit jusqu'à ce qu'une reconstruction contredise la sortie.", "L'échantillonnage head-based qui conserve l'ordinaire. L'exécution dont vous avez besoin a été rejetée au point d'entrée, avant même que l'on sache qu'elle allait être intéressante.", "Le journal comme source de violation de données : les arguments bruts des outils acheminent des données personnelles vers un stockage doté d'un accès plus large et d'une rétention plus longue que la base de données dont ils proviennent.", "Version du modèle manquante. Un changement de comportement et une mise à jour silencieuse du modèle semblent identiques dans l'enregistrement, et l'investigation stagne sur une question à laquelle la trace aurait dû répondre." ], "lessons": [ "La corrélation est le produit ; la capture est la matière première. Les équipes qui achètent un backend de tracing et font l'impasse sur l'identifiant se retrouvent avec du stockage plutôt qu'avec des réponses.", "Testez la reconstruction, pas le pipeline. Choisissez une exécution passée au hasard et reconstruisez-la — les lacunes se trouvent toujours là où personne n'a placé d'instrumentation, et seule cette tentative permet de les trouver.", "Masquez au moment de l'écriture. Chaque masquage différé au moment de la lecture est une décision de conserver la valeur brute, et le stockage survit à l'intention.", "Échantillonnez sur la fin (tail-based). L'échantillonnage head-based est une décision d'écarter les exécutions intéressantes avant même de savoir de quelles exécutions il s'agit.", "Enregistrez la version du modèle partout. Cela ne coûte qu'un champ et cela fait toute la différence entre diagnostiquer une dérive et en débattre." ], "faqs": [ { "q": "Nous utilisons déjà un backend de tracing. Le problème n'est-il pas résolu ?", "a": "Un backend vous fournit la capture et le stockage. Ce pattern concerne les trois aspects qu'un backend ne décide pas pour vous : si un identifiant unique relie l'ensemble de l'exécution, si la fidélité est suffisante pour la reconstruire sans les systèmes sources, et si ce que vous avez enregistré peut être conservé en toute sécurité. Des équipes disposant d'excellents outils échouent régulièrement au test de reconstruction." }, { "q": "Une capture complète n'entre-t-elle pas en conflit avec la minimisation des données ?", "a": "Ce serait le cas si la capture signifiait tout conserver à l'état brut. Le contrôle énonce délibérément les deux aspects — assez pour reconstruire, rien qui ne transforme le journal en violation de données — et le moyen de concilier les deux est le masquage au niveau des champs lors de la capture, associé à une rétention liée à l'obligation qui justifie l'enregistrement. Ce que vous ne pouvez pas faire, c'est éluder cette tension en conservant tout et en qualifiant cela de conformité." }, { "q": "Quel niveau de fidélité est suffisant ?", "a": "Exactement assez pour réussir le test de reconstruction sur une exécution choisie au hasard, et pas plus. Ce seuil peut être découvert en essayant, c'est pourquoi le test doit faire partie de la routine plutôt que d'un audit. Tout ce qui est capturé au-delà représente un coût et un risque juridique sans répondre à aucune question." } ] }, "de": { "name": "Correlated Run Trace", "summary": "Ein einziger Identifikator verknüpft einen gesamten Agenten-Run – Inputs, Modell und Version, jeden Tool-Aufruf mit seinen Argumenten und Ergebnissen, die finale Aktion – zu einem Datensatz, den Sie Monate später erneut abspielen können. Der schwierige Teil ist nicht die Erfassung. Es geht darum, vollständig genug zu sein, um den Run zu rekonstruieren, und gleichzeitig so zurückhaltend, dass der Trace-Speicher nicht zu einer zweiten Kopie der beschriebenen Daten wird.", "definition": "Ein Correlated Run Trace ist eine unveränderliche Aufzeichnung mit einem einzigen Identifikator, die alles erfasst, was ein Agenten-Run entschieden und getan hat. Sie wird mit einer Detailgenauigkeit aufgezeichnet, die es ermöglicht, den Run im Nachhinein lückenlos zu rekonstruieren, ohne Zugriff auf die erzeugenden Systeme zu haben, und ist so redigiert, dass der Trace kein leichteres Angriffsziel darstellt als die Quelle. Es handelt sich um eine Aufzeichnung der Entscheidungen des Agenten, nicht um ein Request-Log.", "problem": "Agenten sind nicht-deterministisch und arbeiten mehrschrittig, sodass sich das Geschehene nicht einfach aus dem Output ableiten lässt. Die meisten Teams protokollieren zwar, können aber dennoch nicht beantworten, warum ein bestimmter Run so agiert hat: Die Schritte befinden sich in verschiedenen Systemen ohne gemeinsamen Identifikator, der Prompt wurde als Template-Referenz aufgezeichnet, die sich inzwischen geändert hat, oder die Modellversion wurde nie erfasst, sodass niemand sagen kann, ob sich das Verhalten oder das Modell verändert hat.", "context": "Jeder Agent, dessen Aktionen Konsequenzen haben, nach denen später gefragt wird: ein regulierter Prozess, bei dem der Trace der Audit-Trail ist und Nachvollziehbarkeit eine Pflicht statt einer Präferenz darstellt, ein Vorfall, der eine Ursachenanalyse erfordert, ein Kunde, der ein Ergebnis anfechtet, oder eine Evaluierungsschleife, die echte Fehler benötigt, um daraus zu lernen.", "solution": [ "Erzeugen Sie am Einstiegspunkt einen eindeutigen Run-Identifikator und leiten Sie diesen durch jeden Schritt, Service und Wiederholungsversuch (Retry) weiter. Die Korrelation macht den gesamten Wert aus: Unverknüpfte Datensätze desselben Runs sind lediglich drei Protokolleinträge, kein Trace.", "Erfassen Sie den gerenderten Prompt, nicht nur einen Verweis darauf. Eine Template-ID verweist auf den aktuellen Stand des Templates, der sich von dem unterscheiden kann, was das Modell tatsächlich gesehen hat.", "Erfassen Sie bei jedem Aufruf das Modell und seine Version. Ohne diese Angaben lassen sich eine Verhaltensänderung und eine Modelländerung im Nachhinein nicht voneinander unterscheiden.", "Protokollieren Sie Tool-Aufrufe als Argumente plus Ergebnis, einschließlich Fehlern und Wiederholungsversuchen. Ein Trace, der nur erfolgreiche Aufrufe zeigt, beschreibt einen Run, der so nie stattgefunden hat.", "Schwärzen Sie Daten bei der Erfassung, nicht erst beim Lesen. Nutzen Sie Regeln auf Feldebene, die Geheimnisse und personenbezogene Daten verwerfen oder hashen, bevor der Datensatz geschrieben wird. Eine Schwärzung bei der Abfrage belässt den Rohwert weiterhin im Speicher.", "Führen Sie das Sampling am Ende (Tail-based Sampling) und nicht am Anfang (Head-based Sampling) durch. Entscheide erst nach Abschluss des Runs, was aufbewahrt wird, damit Fehler, Eskalationen und Anomalien erhalten bleiben und nur routinemäßige Erfolge ausgedünnt werden.", "Gestalten Sie den Speicher als Append-only und versehen Sie ihn mit den Zugriffskontrollen des sensibelsten Systems, das er beschreibt – nicht mit den Standardeinstellungen eines Logging-Backends." ], "components": [ "Ein am Einstiegspunkt erzeugter Run-Identifikator, der durch jeden Schritt, Service, Wiederholungsversuch und jede asynchrone Fortsetzung weitergeleitet wird.", "Ein Span pro Schritt mit einem stabilen Schema: Inputs, Modell und Version, Tool-Name, Argumente, Ergebnis, Latenz, Token-Nutzung.", "Schwärzung auf Feldebene bei der Erfassung mit einer expliziten Liste darüber, was verworfen, was gehasht und was unverändert beibehalten wird.", "Tail-based Sampling, das im Nachhinein entscheidet, sodass anomale Runs erhalten bleiben und routinemäßige ausgedünnt werden.", "Append-only-Speicher mit einer Aufbewahrungsfrist, die auf die Verpflichtung zur Protokollierung abgestimmt ist, und Zugriffskontrollen, die denen der Quellsysteme entsprechen.", "Ein Replay-Pfad, der einen Run allein aus dem Trace rekonstruiert und oft genug genutzt wird, damit etwaige Lücken bekannt sind." ], "benefits": [ "Macht nicht-deterministische Fehler diagnostizierbar: Sie können beantworten, warum dieser spezifische Run so reagiert hat, anstatt den Fehler so lange zu reproduzieren, bis er wieder auftritt.", "Macht Nachweispflichten zu einem greifbaren Artefakt statt zu einem bloßen Versprechen. Die Rekonstruktion eines zufällig ausgewählten vergangenen Runs funktioniert entweder oder sie funktioniert nicht.", "Speist die Evaluierung mit echten statt mit erfundenen Fehlern – das ist der Unterschied zwischen einem Benchmark und einer Regressions-Testsuite.", "Trennt Drift von Deployments. Wenn die Modellversion im Datensatz enthalten ist, wird aus der vagen Aussage „Es ist schlechter geworden“ eine präzise beantwortbare Frage." ], "risks": [ "Der Trace-Speicher als leichtestes Angriffsziel: Er enthält dieselben Daten wie die Systeme, die er beschreibt, meist jedoch mit schwächeren Zugriffskontrollen und längeren Aufbewahrungsfristen.", "Erfassungskosten, die mit dem Traffic steigen, bis jemand aus Kostengründen auf Head-based Sampling umstellt und damit unbemerkt genau die Runs verwirft, die erhaltenswert gewesen wären.", "Eine Schwärzung, die Daten entfernt, die für die Rekonstruktion benötigt worden wären. Eine Überschwärzung bleibt so lange unbemerkt, bis jemand versucht, einen Run zu replizieren, und scheitert.", "Datenvolumen wird mit Abdeckung verwechselt. Terabytes an Spans ohne gemeinsamen Identifikator können dennoch keine einzige Frage zu einem bestimmten Run beantworten." ], "whenNot": [ "Einstufige, deterministische Aufrufe, bei denen Input und Output bereits die gesamte Geschichte erzählen. Diese lassen sich bereits über ein einfaches Request-Log rekonstruieren.", "Prototypen ohne Nutzer und ohne Verpflichtungen, bei denen die Kosten für die Trace-Pipeline den Erkenntnisgewinn übersteigen würden.", "Fälle, in denen geltende Regeln die Aufbewahrung von Inhalten gänzlich untersagen. In diesem Fall protokolliert der Trace lediglich, dass eine Entscheidung getroffen wurde, sowie deren Metadaten, während der Inhalt außen vor bleibt. Dies ist ein anderes Artefakt, und etwas anderes vorzugeben, schafft genau die Haftungsrisiken, die die Regel eigentlich verhindern sollte." ], "examples": [ "Ein Vorfall, bei dem ein Agent eine E-Mail an den falschen Kunden gesendet hat. Der Run-Identifikator verknüpft den Retrieval-Vorgang, der den falschen Datensatz zurückgegeben hat, den Tool-Aufruf, der ihn verwendet hat, und die gesendete Nachricht. So lässt sich die Ursache auf eine einzige Abfrage zurückführen, statt eine Woche lang Reproduktionsversuche zu starten.", "Eine Regulierungsbehörde fragt nach, wie eine Entscheidung vor sechs Monaten zustande kam. Der Replay-Pfad rekonstruiert den Run allein aus dem Trace, einschließlich der an diesem Tag aktiven Modellversion.", "Ein Qualitätsabfall nach einem Modell-Upgrade. Da jeder Span die Modellversion enthält, basiert der Vergleich auf zwei Gruppen realer Runs und nicht auf subjektiven Eindrücken." ], "kpis": [ { "metric": "Erfolgsquote der Rekonstruktion", "note": "Anteil zufällig ausgewählter vergangener Runs, die sich allein aus dem Trace durchgängig rekonstruieren lassen. Dies ist der eigentliche Test für diese Kontrollmaßnahme und die einzige Kennzahl hier, die sich nicht einfach durch das Erfassen von mehr Daten verbessern lässt." }, { "metric": "Vollständigkeit der Korrelation", "note": "Anteil der Spans in einem Run, die den Run-Identifikator tragen. Jeder Wert unter 100 % bedeutet, dass ein Schritt unsichtbar ist – und der fehlende Schritt ist selten der uninteressante." }, { "metric": "Abflussrate sensibler Felder", "note": "Anteil der stichprobenartig geprüften Datensätze, die einen Wert enthalten, den die Schwärzungsregeln hätten entfernen müssen. Der Zielwert ist null; jeder andere Wert bedeutet, dass der Trace-Speicher Haftungsrisiken anhäuft." }, { "metric": "Aufbewahrungsquote anomaler Runs", "note": "Anteil fehlerhafter oder eskalierter Runs, die nach dem Sampling aufbewahrt werden. Head-based Sampling drückt diesen Wert in Richtung der allgemeinen Sampling-Rate – genau das ist der Fehler, den diese Metrik aufdecken soll." } ], "failureModes": [ "Der Trace, der nichts beweist: Jeder Schritt wird protokolliert, kein Schritt teilt sich einen Identifikator, und die Rekonstruktion eines Runs erfordert das manuelle Korrelieren von Zeitstempeln.", "Der per Verweis aufgezeichnete Prompt. Das Template wurde geändert, sodass das Protokoll nun einen Prompt beschreibt, den das Modell nie gesehen hat – was niemand bemerkt, bis eine Rekonstruktion im Widerspruch zum Output steht.", "Head-based Sampling, das das Gewöhnliche bewahrt. Der benötigte Run wurde bereits am Einstiegspunkt verworfen, noch bevor absehbar war, dass er von Interesse sein würde.", "Das Protokoll als Sicherheitslücke: Unbearbeitete Tool-Argumente übertragen personenbezogene Daten in einen Speicher mit breiterem Zugriff und längerer Aufbewahrungsfrist als die Datenbank, aus der sie stammen.", "Fehlende Modellversion. Eine Verhaltensänderung und ein stilles Modell-Update sehen im Datensatz identisch aus, und die Untersuchung scheitert an einer Frage, die der Trace hätte beantworten müssen." ], "lessons": [ "Die Korrelation ist das Produkt, die Erfassung nur das Rohmaterial. Teams, die ein Tracing-Backend kaufen, aber auf den Identifikator verzichten, erhalten lediglich Speicherplatz statt Antworten.", "Testen Sie die Rekonstruktion, nicht die Pipeline. Wählen Sie einen zufälligen vergangenen Run aus und bauen Sie ihn nach – Lücken befinden sich immer dort, wo niemand eine Instrumentierung vorgenommen hat, und nur der Versuch deckt sie auf.", "Schwärzen Sie beim Schreiben. Jede Schwärzung, die auf den Lesezeitpunkt verschoben wird, ist eine Entscheidung, den Rohwert aufzubewahren – und Speicher überdauert die ursprüngliche Absicht.", "Führen Sie das Sampling am Ende (Tail-based) durch. Head-based Sampling ist die Entscheidung, interessante Runs zu verwerfen, noch bevor man wissen kann, welche das sein werden.", "Erfassen Sie überall die Modellversion. Das kostet nur ein Feld und macht den Unterschied aus, ob man Drift diagnostizieren oder nur darüber spekulieren kann." ], "faqs": [ { "q": "Wir nutzen bereits ein Tracing-Backend. Ist das Problem damit nicht gelöst?", "a": "Ein Backend bietet Ihnen Erfassung und Speicherung. Bei diesem Pattern geht es um drei Dinge, die ein Backend Ihnen nicht abnimmt: ob ein einziger Identifikator den gesamten Run durchzieht, ob die Detailgenauigkeit ausreicht, um ihn ohne die Quellsysteme zu rekonstruieren, und ob die aufgezeichneten Daten sicher aufbewahrt werden können. Teams mit hervorragenden Tools scheitern regelmäßig am Rekonstruktionstest." }, { "q": "Steht eine vollständige Erfassung nicht im Widerspruch zur Datenminimierung?", "a": "Das würde es, wenn Erfassung bedeuten würde, alles im Rohzustand aufzubewahren. Die Kontrollmaßnahme formuliert bewusst beide Seiten – genug zur Rekonstruktion, aber nichts, was das Protokoll zur Sicherheitslücke macht. Der Weg, beides zu vereinbaren, ist die Schwärzung auf Feldebene bei der Erfassung in Kombination mit einer Aufbewahrungsfrist, die an die rechtfertigende Verpflichtung gekoppelt ist. Was Sie nicht tun können, ist, diesen Konflikt zu ignorieren, indem Sie einfach alles aufbewahren und es Compliance nennen." }, { "q": "Wie viel Detailgenauigkeit ist ausreichend?", "a": "Genau so viel, wie nötig ist, um den Rekonstruktionstest bei einem zufällig ausgewählten Run zu bestehen – nicht mehr. Dieser Schwellenwert lässt sich durch Ausprobieren ermitteln, weshalb der Test in die Routine und nicht erst in ein Audit gehört. Alles, was darüber hinaus erfasst wird, verursacht Kosten und Risiken, ohne eine konkrete Frage zu beantworten." } ] }, "ja": { "name": "関連付けられた実行トレース (Correlated Run Trace)", "summary": "単一の識別子が、エージェントの実行全体（入力、モデルとバージョン、引数と結果を伴うすべてのツール呼び出し、最終的なアクション）をスレッド化し、数ヶ月後でも再現可能な記録としてまとめます。難しいのはキャプチャすること自体ではありません。実行を再構成できるほど完全でありながら、トレースストアが記述対象データの単なる二重コピーにならないよう抑制を効かせることです。", "definition": "関連付けられた実行トレースとは、エージェントの実行におけるすべての決定と行動を記録した、単一の識別子を持つ不変のレコードです。これは、実行を生成したシステムにアクセスすることなく、後からエンドツーエンドで実行を再構成できるほどの忠実度でキャプチャされ、かつトレース自体が元のソースよりも脆弱な標的にならないよう墨消し（編集）が施されています。これはリクエストログではなく、エージェントの意思決定の記録です。", "problem": "エージェントは非決定論的かつマルチステップであるため、出力から「何が起こったか」を推測することはできません。ほとんどの開発チームはログを記録していますが、それでも特定の実行がなぜそのような動作をしたのかを説明できません。各ステップが共有識別子のない異なるシステムに存在していたり、プロンプトがその後変更されたテンプレート参照として記録されていたり、モデルのバージョンがキャプチャされていなかったりするため、動作が変化したのか、それともモデル自体が変化したのかを誰も判断できないのです。", "context": "後から誰かにその行動の結果について問われる可能性のある、あらゆるエージェントが対象となります。例えば、トレースが監査証跡となり、トレーサビリティが単なる好みではなく義務である規制プロセス、根本原因の特定が必要なインシデント、結果に異議を唱える顧客、あるいは学習のために実際の失敗事例を必要とする評価ループなどがこれに該当します。", "solution": [ "エントリーポイントで実行識別子を1つ生成し、すべてのステップ、サービス、リトライに伝播させます。相関関係こそが価値のすべてです。同じ実行のリンクされていないレコードは、トレースではなく、単なる3つのログにすぎません。", "テンプレートへの参照ではなく、レンダリングされたプロンプトそのものを記録します。テンプレートIDが解決するのは「今日のテンプレートの内容」であり、モデルが実際に目にしたものではありません。", "すべての呼び出しにおいて、モデルとそのバージョンを併せてキャプチャします。これがないと、事後的に挙動の変化とモデルの変化を区別することができなくなります。", "ツール呼び出しは、引数と結果（失敗やリトライを含む）をログに記録します。成功した呼び出しのみを示すトレースは、実際には起こらなかった実行を記述していることになります。", "読み取り時ではなく、キャプチャ時にマスキングを行います。レコードが書き込まれる前に、機密情報や個人データを削除またはハッシュ化するフィールドレベルのルールを適用します。クエリ実行時にマスキングを適用しても、ストレージには生の値が残ったままになるためです。", "ヘッド（開始時）ではなく、テール（終了時）でサンプリングを行います。実行が終了した後に何を保持するかを決定することで、エラー、エスカレーション、異常値は保持し、日常的な成功例を間引くことができます。", "ストアを追記専用（append-only）にし、ロギングバックエンドにデフォルトで付属しているものではなく、そのストアが記述している最も機密性の高いシステムと同等のアクセス制御を設定します。" ], "components": [ "エントリー時に生成され、すべてのステップ、サービス、リトライ、および非同期の継続処理に伝播される実行識別子。", "安定したスキーマ（入力、モデルとバージョン、ツール名、引数、結果、レイテンシ、トークン使用量）を持つ、ステップごとのスパン。", "キャプチャ時に適用されるフィールドレベルのマスキング。何を削除し、何をハッシュ化し、何をそのまま保持するかを明示したリストを含みます。", "事後に決定を行うテールベースのサンプリング。これにより、異常な実行は残され、日常的な実行は間引かれます。", "記録を正当化する義務に合わせた保存期間を持ち、ソースシステムと一致するアクセス制御を備えた、追記専用のストレージ。", "トレースのみから実行を再構築するリプレイパス。そのギャップが把握できるほど十分に頻繁に使用されているもの。" ], "benefits": [ "非決定論的な失敗の診断を可能にします。再現するまで何度も実行を繰り返す代わりに、「なぜこの実行がこのような挙動を示したのか」に答えることができます。", "記録保持の義務を、単なる約束事ではなく「成果物」へと変えます。過去のランダムな実行に対する再構築が機能するか、機能しないかのどちらかです。", "作り出された失敗ではなく、実際の失敗を評価にフィードバックします。これは、ベンチマークと回帰テストスイートの違いに相当します。", "ドリフト（傾向の変化）とデプロイを分離します。レコードにモデルバージョンが含まれていれば、「悪化した」という問題に対して明確な答えを出すことができます。" ], "risks": [ "最も脆弱な標的としてのトレースストア：記述対象のシステムと同じデータを保持しているにもかかわらず、通常はアクセス制御がより脆弱で、保存期間がより長く設定されています。", "トラフィックとともに増大するキャプチャコスト。コスト削減のために誰かがヘッド（開始時）でサンプリングを行うようになると、保持する価値のある実行が密かに、かつ確実に削除されてしまいます。", "再構築に必要な情報まで削除してしまうマスキング。過剰なマスキングは、ある日誰かが実行をリプレイしようとして失敗するまで、表面化することはありません。", "ボリューム（データ量）をカバレッジと誤認すること。共有識別子のないテラバイト規模のスパンがあっても、特定の1つの実行に関する疑問には何一つ答えることができません。" ], "whenNot": [ "入力と出力がすべてである、単一ステップの決定論的な呼び出し。これらはリクエストログだけで十分に再構築可能です。", "ユーザーもおらず義務もないプロトタイプであり、トレースパイプラインのコストが、そこから得られる知見を上回る場合。", "適用される規則によってコンテンツの保持が一切禁止されている場合。その場合、トレースには決定が行われたこととそのメタデータのみを記録し、コンテンツ自体は除外します。これは別の成果物であり、そうでないふりをすることは、その規則が回避するために作られた法的責任（ライアビリティ）を生み出すことになります。" ], "examples": [ "エージェントが誤った顧客にメールを送信したインシデント。実行識別子によって、誤ったレコードを返したリトリーバル、それを使用したツール呼び出し、および送信されたメッセージがリンクされるため、1週間の再現テストを繰り返すことなく、1つのクエリが根本原因であることを特定できます。", "規制当局から、6ヶ月前にどのように決定が下されたかについての問い合わせがあった場合。リプレイパスにより、その日に有効だったモデルバージョンを含め、トレースのみから実行を再構築します。", "モデルのアップグレード後に品質が低下した場合。すべてのスパンにモデルバージョンが含まれているため、主観的な印象ではなく、実際の実行における2つの母集団を比較することができます。" ], "kpis": [ { "metric": "再構築成功率", "note": "トレースのみからエンドツーエンドで再構築できる、ランダムに選択された過去の実行の割合。これはコントロール自体のテストであり、単にキャプチャ量を増やすだけでは改善できない、ここでの唯一の数値です。" }, { "metric": "相関関係の完全性", "note": "実行識別子を持つ、実行内のスパンの割合。100%未満であることは、一部のステップが不可視であることを意味し、欠落しているステップが退屈なものであることは滅多にありません。" }, { "metric": "機密フィールドの漏洩率", "note": "マスキングルールによって削除されるべき値が含まれている、サンプリングされたレコードの割合。目標値はゼロです。それ以外の数値は、トレースストアに法的責任（ライアビリティ）が蓄積されていることを意味します。" }, { "metric": "異常な実行の保持率", "note": "サンプリング後に保持される、エラーまたはエスカレーションが発生した実行の割合。ヘッドベースのサンプリングでは、この数値がサンプリング率に近づいてしまいます。この指標は、まさにその失敗を検知するために存在します。" } ], "failureModes": [ "何も証明できないトレース：すべてのステップがログに記録されているものの、どのステップも識別子を共有しておらず、1つの実行を再構築するためにタイムスタンプを手動で関連付ける必要があります。", "参照によって記録されたプロンプト。テンプレートが変更されたため、ログにはモデルが実際には見ていないプロンプトが記述されるようになり、再構築結果が出力と矛盾するまで誰もそのことに気づきません。", "平凡な実行を保持するヘッドベースのサンプリング。必要となる実行は、それが興味深いものになると判明する前に、エントリーポイントで破棄されてしまいます。", "情報漏洩の原因となるログ：ツールの生の引数によって個人データがストアに持ち込まれ、そのデータが元々あったデータベースよりも広いアクセス権限と長い保存期間で保管されてしまいます。", "モデルバージョンの欠落。挙動の変化とサイレントなモデルアップデートがレコード上で同一に見えてしまい、トレースが答えるべきであった疑問のところで調査が頓挫します。" ], "lessons": [ "相関関係こそが成果物であり、キャプチャは原材料にすぎません。トレースバックエンドを購入しながら識別子の付与を省くチームは、答えではなく、単なるストレージを手に入れることになります。", "パイプラインではなく、再構築をテストします。過去のランダムな実行を選択して再構築してみてください。ギャップは常に誰もインスツルメンテーションを行わなかった場所にあり、実際に試してみることでしか見つけることができません。", "書き込み時にマスキングを行います。読み取り時までマスキングを延期することは、生の実データを保持することを決定したのと同じであり、ストレージは意図よりも長く存続します。", "テールでサンプリングを行います。ヘッドベースのサンプリングは、どの実行が興味深いものになるか判明する前に、それらを破棄することを決定してしまいます。", "すべての場所でモデルバージョンを記録します。必要なコストはフィールド1つ分であり、これによってドリフトを診断できるか、それとも不毛な議論に終始するかの違いが生まれます。" ], "faqs": [ { "q": "すでにトレースバックエンドを使用しています。これで解決しているのではないでしょうか？", "a": "バックエンドが提供するのはキャプチャとストレージです。このパターンが扱うのは、バックエンドが決定してくれない3つの事項です。すなわち、1つの識別子が実行全体を貫いているか、ソースシステムなしで再構築できるほどの十分な忠実度（fidelity）があるか、そして記録した内容を安全に保持できるか、です。優れたツールを導入しているチームであっても、再構築テストに日常的に失敗しています。" }, { "q": "完全なキャプチャはデータの最小化原則と矛盾しませんか？", "a": "キャプチャが生のデータですべてを保持することを意味するのであれば、矛盾するでしょう。このコントロールは意図的に両面を規定しています。つまり、再構築には十分でありながら、ログが情報漏洩の原因にならないようにすることです。この両立を実現する方法は、キャプチャ時のフィールドレベルのマスキングと、記録を正当化する義務に紐づいた保存期間の設定です。やってはならないのは、すべてを保持した上でそれをコンプライアンスと呼び、この対立から目を背けることです。" }, { "q": "どの程度の忠実度（fidelity）があれば十分ですか？", "a": "ランダムに選ばれた実行に対する再構築テストに合格するのに必要十分なレベルであり、それ以上は不要です。そのしきい値は実際に試してみることで発見できるため、このテストは監査時ではなく日常のルーティンに組み込むべきです。それを超えてキャプチャされたものはすべて、何の疑問にも答えないまま、コストと法的責任（ライアビリティ）を増大させるだけです。" } ] }, "zh": { "name": "关联运行追踪", "summary": "一个标识符将整个智能体运行过程串联起来——输入、模型及版本、每次工具调用及其参数和结果、最终动作——形成一条可在数月后重新播放的记录。难点不在于捕获，而在于既要足够完整以重构运行过程，又要足够克制以避免追踪存储库成为其所描述数据的第二份副本。", "definition": "关联运行追踪是关于智能体运行所做出的所有决策和行为的不可变、单标识符记录。它以极高的保真度进行捕获，以便他人事后能够在无法访问生成该运行的系统的情况下，端到端地重构该运行，并经过脱敏处理，以确保追踪记录不会比源系统更容易成为攻击目标。它是智能体决策的记录，而不是请求日志。", "problem": "智能体具有非确定性和多步骤的特点，因此无法仅从输出中推断出“发生了什么”。大多数团队确实进行了日志记录，但仍然无法回答为什么特定的运行会做出那样的行为：各步骤分散在不同的系统中且没有共享的标识符，Prompt 被记录为自那以后已发生更改的模板引用，或者从未捕获模型版本，导致无人能分清是行为发生了漂移还是模型发生了漂移。", "context": "适用于任何其行为后果在日后会被追问的智能体：如追踪记录作为审计线索且可追溯性是义务而非偏好的受监管流程、需要寻找根本原因的事件、客户对结果提出异议，或者需要从真实失败中学习的评估循环。", "solution": [ "在入口点生成一个运行标识符，并将其传播到每个步骤、服务和重试中。关联性是其全部价值所在：同一运行中未关联的记录只是三条日志，而不是一条追踪。", "记录渲染后的提示词，而不是其引用。模板 ID 解析出的是该模板今天的具体内容，这与模型当时看到的并不相同。", "在每次调用时同时捕获模型及其版本。如果没有它，事后将无法区分是行为变化还是模型变化。", "将工具调用记录为参数加结果，包括失败和重试。仅显示成功调用的追踪所描述的运行在现实中并未发生。", "在捕获时进行脱敏，而不是在读取时。在写入记录之前，通过字段级规则丢弃或哈希处理机密和个人数据，因为在查询时应用的脱敏仍会将原始值留在存储中。", "在尾部进行采样，而不是在头部。在运行结束后决定保留什么，以便保留错误、升级和异常，而稀释常规的成功记录。", "使存储保持只追加（append-only）状态，并为其赋予其所描述的最敏感系统的访问控制权限，而不是日志后端自带的权限。" ], "components": [ "在入口处生成的运行标识符，并传播到每个步骤、服务、重试和异步延续中。", "每个步骤一个具有稳定 Schema 的 Span：输入、模型与版本、工具名称、参数、结果、延迟、Token 使用情况。", "在捕获时应用的字段级脱敏，并附有明确的列表，说明哪些被丢弃、哪些被哈希处理以及哪些被完整保留。", "基于尾部的采样，在事后做出决定，从而保留异常运行并稀释常规运行。", "只追加存储，其保留期限与证明该记录合理性的合规义务相一致，且访问控制与源系统相匹配。", "一条仅凭追踪即可重构运行的重放路径，其使用频率足够高，以至于其缺陷是已知的。" ], "benefits": [ "使非确定性故障可诊断：你可以回答为什么这次运行会执行此操作，而不是不断复现直到它再次发生。", "将记录保存义务转化为具体的产物，而不是一种承诺。重构要么对随机选择的过去运行有效，要么无效。", "用真实的失败而非虚构的失败来喂养评估，这就是基准测试（benchmark）与回归测试套件（regression suite）之间的区别。", "将漂移与部署分离开来。通过在记录中包含模型版本，“情况变糟了”就变成了一个有答案的问题。" ], "risks": [ "追踪存储是最容易受到攻击的目标：它保存着与其所描述的系统相同的数据，但通常访问控制更弱且保留时间更长。", "捕获成本随着流量增长，直到有人为了省钱而在头部进行采样，从而悄无声息地移除了恰恰最值得保留的运行记录。", "脱敏移除了重构所需的内容。过度脱敏是隐蔽的，直到有一天有人试图重放某次运行却无法实现时才会暴露。", "将数据量误认为覆盖率。数 TB 没有共享标识符的 Span 仍然无法回答关于单次运行的任何一个问题。" ], "whenNot": [ "单步、确定性的调用，其中输入和输出就是全部内容。请求日志已经可以重构这些调用。", "没有用户且没有合规义务的原型，其追踪流水线的成本超过了你能从中获得的任何收获。", "适用规则完全禁止保留内容的情况。此时，追踪仅记录决策的发生及其元数据，而内容则不予保留——这是一种不同的产物，假装并非如此会产生该规则旨在避免的法律责任。" ], "examples": [ "智能体向错误的客户发送电子邮件的事件。运行标识符将返回错误记录的检索、使用该记录的工具调用以及发送的消息关联起来，因此根本原因在于某一次查询，而不是耗费一周时间去尝试复现。", "监管机构询问六个月前是如何做出某项决策的。重放路径仅凭追踪即可重建该运行，包括当天生效的模型版本。", "模型升级后质量下降。因为每个 Span 都带有模型版本，所以对比是在两组真实运行的数据之间进行，而不是凭主观印象。" ], "kpis": [ { "metric": "重构成功率", "note": "仅凭追踪即可端到端重建的随机选择的过去运行的比例。这是该控制项自身的测试，也是此处唯一一个无法通过捕获更多数据来满足的数字。" }, { "metric": "关联完整性", "note": "一次运行中带有运行标识符的 Span 比例。任何低于 100% 的情况都意味着某些步骤是不可见的，而缺失的步骤往往不是无关紧要的步骤。" }, { "metric": "敏感字段逃逸率", "note": "抽样记录中包含脱敏规则本应移除的值的比例。目标是零；任何其他数字都意味着追踪存储正在累积法律责任。" }, { "metric": "异常运行保留率", "note": "采样后保留的出错或升级运行的比例。基于头部的采样会使该指标趋向于采样率，而这正是该指标旨在捕获的失效情况。" } ], "failureModes": [ "无法证明任何事情的追踪：记录了每个步骤，但没有步骤共享标识符，重构一次运行意味着需要手动关联时间戳。", "通过引用记录的提示词。模板发生了变化，因此日志现在描述的是模型从未见过的提示词，而且直到重构与输出相矛盾时才有人注意到。", "保留常规记录的头部采样。你需要的运行在入口点就被丢弃了，而当时还没有人知道它会变得有价值。", "作为泄露源的日志：原始工具参数将个人数据带入了一个比其来源数据库具有更广泛访问权限和更长保留期限的存储中。", "缺失模型版本。行为变化和静默的模型更新在记录中看起来完全相同，导致调查卡在了一个本应由追踪来回答的问题上。" ], "lessons": [ "关联性是最终产物，捕获只是原材料。购买了追踪后端却跳过标识符的团队，最终得到的只是存储空间而不是答案。", "测试重构，而不是流水线。随机选择一次过去的运行并重建它——缺陷总是存在于没有人进行插桩的地方，只有尝试才能发现它们。", "在写入时进行脱敏。任何推迟到读取时的脱敏都是保留原始值的决定，而存储的寿命往往比意图更长。", "在尾部进行采样。基于头部的采样是在知道哪些运行有价值之前，就做出了丢弃这些有价值运行的决定。", "在所有地方记录模型版本。它只占用一个字段，却能决定你是能诊断漂移还是只能为此争论不休。" ], "faqs": [ { "q": "我们已经使用了追踪后端。这难道还没有解决吗？", "a": "后端为你提供捕获和存储。而此模式关注的是后端无法为你决定的三件事：是否有一个标识符贯穿整个运行、保真度是否足以在没有源系统的情况下重构它，以及你记录的内容是否可以安全保留。拥有优秀工具链的团队也经常无法通过重构测试。" }, { "q": "完整捕获是否与数据最小化原则相冲突？", "a": "如果捕获意味着保留所有原始数据，那确实会冲突。该控制项有意兼顾了这两个方面——既足以重构，又不会使日志变成泄露源——而兼顾两者的关键在于捕获时的字段级脱敏，以及与证明记录合理性的合规义务相绑定的保留期限。你不能通过保留所有内容并称之为合规来消除这种张力。" }, { "q": "多高的保真度才足够？", "a": "恰好足以通过对随机抽取的运行进行的重构测试即可，无需更多。这个阈值可以通过尝试来发现，这就是为什么该测试应该属于日常工作而不是审计。超出此范围捕获的任何内容都是成本和法律责任，而无法回答任何问题。" } ] } } }, { "slug": "egress-allowlist", "category": "safety", "updated": "2026-08-25", "version": "1.1", "url": "https://santismm.com/en/patterns/egress-allowlist", "api": "https://santismm.com/api/patterns/egress-allowlist", "canonical_url": "https://santismm.com/en/patterns/egress-allowlist", "api_url": "https://santismm.com/api/patterns/egress-allowlist", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "personal_experience", "paper" ] }, "technologies": [ "Egress proxies", "Container network policies", "Service mesh policy", "DNS filtering", "Denial logging and alerting" ], "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "OWASP — LLM01: Prompt Injection", "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/" }, { "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems", "url": "https://atlas.mitre.org/" } ], "related": [ "least-privilege-tooling", "human-approval-gate", "recovery-strategy", "output-boundary-encoding" ], "locales": { "en": { "name": "Egress Allowlist", "summary": "Restrict where an agent's traffic is allowed to go. Data theft and injection payload delivery both end in an outbound request, so a default-deny list of permitted destinations is the control that still works after every other one has failed.", "definition": "An egress allowlist is a network- or sandbox-level policy that permits an agent's outbound requests only to an explicitly named set of destinations and denies everything else by default, so data cannot leave to an attacker-chosen endpoint even when the agent has been fully hijacked.", "problem": "Every exfiltration path ends in an outbound request. An agent that can reach arbitrary hosts can be instructed to send anything it has read to any address, and no prompt-level instruction prevents that.", "context": "Use it wherever an agent both processes untrusted content and can make network requests — fetching pages, calling tools, rendering images, running generated code. The pattern is most valuable exactly where injection is most likely.", "solution": [ "Default deny. The allowlist is the only way out; anything not named is refused, and the refusal is logged as a signal rather than swallowed as an error.", "Enumerate destinations from the task: the APIs the agent must call, the domains it must fetch, the registries it must install from — each with an owner and a written reason.", "Enforce below the agent. Put the policy in the sandbox, the proxy or the network, never in tool code the model can be argued out of. A rule the agent can talk its way past is documentation, not a control.", "Close the quiet channels. Rendered image URLs, link previews, DNS lookups, webhooks, error reporters and package installs are all egress, and all of them get used.", "Allow hosts you can reason about. A wildcard over a host that serves user-supplied content — a raw-file CDN, a paste site, a public object store — is an open channel wearing an allowlist's clothes.", "Derive the list from measurement and re-derive it when the task changes. Start from what the agent actually calls, not from what someone assumes it calls." ], "components": [ "An egress gateway or sandbox network policy that all traffic must traverse.", "A deny-by-default rule with an explicit, owned destination inventory.", "Per-role policies, so a research agent and a deployment agent do not share one list.", "Denial logging wired to alerting, because a denial is a high-signal event.", "Method and payload constraints where the destination alone is not enough (GET-only, body size caps).", "A review cadence that removes destinations nothing has used." ], "benefits": [ "Bounds exfiltration even after a complete compromise of the agent's reasoning.", "Makes attempts visible: a denied destination is one of the few unambiguous attack signals an agent stack produces.", "Model-independent — it keeps working across model swaps, prompt changes and framework migrations.", "Cheap to extend once the gateway exists; each new agent inherits the enforcement point." ], "risks": [ "The allowlisted relay: a permitted host that itself forwards data onward turns the allowlist into a formality.", "Breakage when a legitimate dependency moves host, which creates pressure to widen the list under time pressure.", "Wildcard erosion: each broad entry added 'temporarily' is permanent until someone audits it.", "Enforcement at the wrong layer — an in-process check the generated code can simply bypass." ], "whenNot": [ "Fully offline agents, where there is no egress to constrain and the control would be theatre.", "When the design already permits exactly one destination, so the allowlist is a property of the architecture rather than a policy to add.", "When a corporate proxy already enforces the same policy and a second list would split ownership without adding a constraint." ], "examples": [ "A coding agent in a container whose egress policy names the package registry and the internal Git host and nothing else. An injected instruction to POST the repository to an external collector fails at the network layer and shows up as a denial.", "A research agent allowed to fetch widely but forced through a proxy that permits GET only and caps outbound bodies — able to read the web without having a channel to write to it.", "The stdio package published for this knowledge base: its only outbound destination is the public endpoint it proxies, so the allowlist is a property of the design rather than a policy layered on afterwards." ], "kpis": [ { "metric": "Denied egress attempts", "note": "The signal the pattern exists to produce. A sustained rise is either an attack or a task that outgrew its list — both worth knowing." }, { "metric": "Allowlist size", "note": "Destinations permitted per agent role. Growth without removals is the list decaying toward 'allow all'." }, { "metric": "Wildcard entries", "note": "Count of broad entries. Every one is a channel you cannot reason about; the target is zero." }, { "metric": "Time from denial to triage", "note": "How long a denial waits before a human looks. An unread denial is an alert you do not actually have." } ], "failureModes": [ "The allowlisted relay: an approved host that will forward whatever it is given, so the destination check passes and the data still leaves.", "Wildcard erosion: temporary broad entries that outlive the reason they were added.", "In-process enforcement: the check lives where the generated code runs, so the code can skip it.", "Silent denials: refusals logged as ordinary network errors, so the one signal the pattern generates never reaches anyone." ], "lessons": [ "Egress is the last control that still works after the model has been convinced. Build it before you need it.", "Derive the list from measured traffic rather than assumption. Doing exactly that for the inbound origin rule on our own MCP endpoint produced a rule that differed from the one we would have written from a default.", "Treat a denial as an alert, not an error. It is the cheapest attack signal in the stack.", "Every wildcard is a promise you cannot keep. Name hosts, or accept that you do not have an allowlist." ], "faqs": [ { "q": "Is an egress allowlist realistic for an agent that browses the web?", "a": "Yes, if you constrain the shape rather than the set. Permit wide GET traffic through a proxy that forbids request bodies and caps sizes: the agent can read broadly while having no channel wide enough to write out what it read." }, { "q": "Does DNS need to be on the list?", "a": "It does. A resolver the agent can query freely is an exfiltration channel — data encoded into subdomain lookups leaves without a single HTTP request. Route DNS through the same policy." }, { "q": "We already have least-privilege tools. Is this redundant?", "a": "No; they cover different halves. Least privilege bounds what the agent can do, egress control bounds where what it already read can go. A read-only agent with open egress can still leak everything it can read." } ] }, "es": { "name": "Lista de Salida Permitida", "summary": "Restringe adónde puede ir el tráfico de un agente. El robo de datos y la entrega de un payload de inyección terminan ambos en una petición saliente, así que una lista de destinos permitidos con denegación por defecto es el control que sigue funcionando cuando todos los demás ya han fallado.", "definition": "Una lista de salida permitida es una política de red o de sandbox que solo autoriza las peticiones salientes del agente hacia un conjunto de destinos nombrados explícitamente y deniega todo lo demás por defecto, de modo que los datos no puedan salir hacia un endpoint elegido por el atacante ni siquiera con el agente completamente secuestrado.", "problem": "Toda ruta de exfiltración termina en una petición saliente. Un agente que puede llegar a hosts arbitrarios puede recibir la instrucción de enviar todo lo que ha leído a cualquier dirección, y ninguna instrucción a nivel de prompt lo impide.", "context": "Úsala allí donde un agente procesa contenido no confiable y además puede hacer peticiones de red: descargar páginas, invocar herramientas, renderizar imágenes, ejecutar código generado. El patrón vale más justo donde la inyección es más probable.", "solution": [ "Deniega por defecto. La lista es la única salida; lo que no esté nombrado se rechaza, y el rechazo se registra como señal en lugar de tragarse como error.", "Enumera los destinos a partir de la tarea: las APIs que el agente debe llamar, los dominios que debe descargar, los registros de los que debe instalar, cada uno con responsable y motivo escrito.", "Aplica la política por debajo del agente. Ponla en el sandbox, en el proxy o en la red, nunca en el código de la herramienta del que se puede convencer al modelo. Una regla que el agente puede sortear hablando es documentación, no un control.", "Cierra los canales silenciosos. Las URLs de imágenes renderizadas, las previsualizaciones de enlaces, las resoluciones DNS, los webhooks, los reportes de error y las instalaciones de paquetes son todos salida, y todos se usan.", "Permite hosts sobre los que puedas razonar. Un comodín sobre un host que sirve contenido de usuario —un CDN de ficheros crudos, un sitio de pastes, un almacén de objetos público— es un canal abierto disfrazado de lista de permitidos.", "Deriva la lista de la medición y vuelve a derivarla cuando cambie la tarea. Parte de lo que el agente llama de verdad, no de lo que alguien supone que llama." ], "components": [ "Una pasarela de salida o política de red del sandbox que todo el tráfico deba atravesar.", "Una regla de denegación por defecto con un inventario de destinos explícito y con responsables.", "Políticas por rol, para que un agente de investigación y uno de despliegue no compartan una misma lista.", "Registro de denegaciones conectado a alertas, porque una denegación es un evento de alta señal.", "Restricciones de método y de payload donde el destino por sí solo no basta (solo GET, límites de tamaño de cuerpo).", "Una cadencia de revisión que retire los destinos que nadie ha usado." ], "benefits": [ "Acota la exfiltración incluso tras un compromiso total del razonamiento del agente.", "Hace visibles los intentos: un destino denegado es una de las pocas señales de ataque inequívocas que produce una pila agéntica.", "Es independiente del modelo: sigue funcionando entre cambios de modelo, de prompt y de framework.", "Es barata de extender una vez existe la pasarela; cada agente nuevo hereda el punto de aplicación." ], "risks": [ "El relé permitido: un host autorizado que a su vez reenvía los datos convierte la lista en un trámite.", "Roturas cuando una dependencia legítima cambia de host, lo que genera presión para ampliar la lista con prisa.", "Erosión por comodines: cada entrada amplia añadida «temporalmente» es permanente hasta que alguien la audita.", "Aplicación en la capa equivocada: una comprobación en el propio proceso que el código generado simplemente esquiva." ], "whenNot": [ "Agentes completamente sin red, donde no hay salida que acotar y el control sería teatro.", "Cuando el diseño ya permite exactamente un destino, así que la lista es una propiedad de la arquitectura y no una política que añadir.", "Cuando un proxy corporativo ya aplica la misma política y una segunda lista repartiría la responsabilidad sin añadir restricción." ], "examples": [ "Un agente de programación en un contenedor cuya política de salida nombra el registro de paquetes y el host Git interno, y nada más. Una instrucción inyectada para hacer POST del repositorio a un recolector externo falla en la capa de red y aparece como denegación.", "Un agente de investigación con permiso para descargar ampliamente pero forzado a pasar por un proxy que solo permite GET y limita el tamaño de los cuerpos salientes: puede leer la web sin tener un canal para escribir en ella.", "El paquete stdio publicado para esta base de conocimiento: su único destino saliente es el endpoint público del que hace de proxy, así que la lista de permitidos es una propiedad del diseño y no una política añadida después." ], "kpis": [ { "metric": "Intentos de salida denegados", "note": "La señal que el patrón existe para producir. Una subida sostenida es un ataque o una tarea que se ha salido de su lista; conviene saber cuál." }, { "metric": "Tamaño de la lista", "note": "Destinos permitidos por rol de agente. Crecer sin retirar es la lista degradándose hacia «permitir todo»." }, { "metric": "Entradas con comodín", "note": "Número de entradas amplias. Cada una es un canal sobre el que no puedes razonar; el objetivo es cero." }, { "metric": "Tiempo de denegación a triaje", "note": "Cuánto espera una denegación antes de que alguien la mire. Una denegación sin leer es una alerta que en realidad no tienes." } ], "failureModes": [ "El relé permitido: un host aprobado que reenvía lo que le den, así que la comprobación de destino pasa y los datos salen igual.", "Erosión por comodines: entradas amplias temporales que sobreviven al motivo por el que se añadieron.", "Aplicación en el propio proceso: la comprobación vive donde corre el código generado, así que el código puede saltársela.", "Denegaciones silenciosas: rechazos registrados como errores de red corrientes, así que la única señal que genera el patrón no llega a nadie." ], "lessons": [ "La salida es el último control que sigue funcionando cuando ya han convencido al modelo. Constrúyelo antes de necesitarlo.", "Deriva la lista de tráfico medido y no de suposiciones. Hacer exactamente eso para la regla de origen entrante de nuestro propio endpoint MCP produjo una regla distinta de la que habríamos escrito partiendo de un valor por defecto.", "Trata una denegación como alerta, no como error. Es la señal de ataque más barata de toda la pila.", "Cada comodín es una promesa que no puedes cumplir. Nombra hosts, o admite que no tienes una lista de permitidos." ], "faqs": [ { "q": "¿Es realista una lista de salida para un agente que navega por la web?", "a": "Sí, si acotas la forma en lugar del conjunto. Permite tráfico GET amplio a través de un proxy que prohíba cuerpos de petición y limite tamaños: el agente puede leer mucho sin tener un canal lo bastante ancho para sacar lo que ha leído." }, { "q": "¿Hay que incluir el DNS?", "a": "Sí. Un resolutor que el agente puede consultar libremente es un canal de exfiltración: los datos codificados en consultas de subdominio salen sin una sola petición HTTP. Enruta el DNS por la misma política." }, { "q": "Ya tenemos herramientas con mínimo privilegio, ¿esto es redundante?", "a": "No; cubren mitades distintas. El mínimo privilegio acota lo que el agente puede hacer; el control de salida acota adónde puede ir lo que ya leyó. Un agente de solo lectura con salida abierta puede filtrar todo lo que es capaz de leer." } ] }, "pt": { "name": "Lista de Saída Permitida", "summary": "Restrinja para onde o tráfego de um agente pode ir. O roubo de dados e a entrega de um payload de injeção terminam ambos em uma requisição de saída, então uma lista de destinos permitidos com negação por padrão é o controle que continua funcionando depois que todos os outros já falharam.", "definition": "Uma lista de saída permitida é uma política de rede ou de sandbox que autoriza as requisições de saída do agente apenas para um conjunto de destinos nomeados explicitamente e nega todo o resto por padrão, de modo que os dados não possam sair para um endpoint escolhido pelo atacante mesmo com o agente totalmente sequestrado.", "problem": "Todo caminho de exfiltração termina em uma requisição de saída. Um agente que alcança hosts arbitrários pode ser instruído a enviar tudo o que leu para qualquer endereço, e nenhuma instrução no nível do prompt impede isso.", "context": "Use onde um agente processa conteúdo não confiável e também faz requisições de rede: baixar páginas, invocar ferramentas, renderizar imagens, executar código gerado. O padrão vale mais exatamente onde a injeção é mais provável.", "solution": [ "Negue por padrão. A lista é a única saída; o que não estiver nomeado é recusado, e a recusa é registrada como sinal em vez de engolida como erro.", "Enumere os destinos a partir da tarefa: as APIs que o agente precisa chamar, os domínios que precisa baixar, os registries de onde precisa instalar — cada um com responsável e motivo escrito.", "Aplique a política abaixo do agente. Coloque-a no sandbox, no proxy ou na rede, nunca no código da ferramenta do qual o modelo pode ser convencido. Uma regra que o agente contorna conversando é documentação, não controle.", "Feche os canais silenciosos. URLs de imagens renderizadas, pré-visualizações de links, resoluções DNS, webhooks, relatores de erro e instalações de pacotes são todos saída, e todos são usados.", "Permita hosts sobre os quais você consiga raciocinar. Um curinga sobre um host que serve conteúdo de usuário — um CDN de arquivos crus, um site de pastes, um object store público — é um canal aberto fantasiado de lista de permitidos.", "Derive a lista da medição e volte a derivá-la quando a tarefa mudar. Parta do que o agente realmente chama, não do que alguém supõe que ele chama." ], "components": [ "Um gateway de saída ou política de rede do sandbox que todo o tráfego precise atravessar.", "Uma regra de negação por padrão com um inventário de destinos explícito e com responsáveis.", "Políticas por papel, para que um agente de pesquisa e um de implantação não compartilhem uma mesma lista.", "Registro de negações ligado a alertas, porque uma negação é um evento de alto sinal.", "Restrições de método e de payload onde o destino sozinho não basta (somente GET, limites de tamanho de corpo).", "Uma cadência de revisão que remova os destinos que ninguém usou." ], "benefits": [ "Limita a exfiltração mesmo após um comprometimento completo do raciocínio do agente.", "Torna as tentativas visíveis: um destino negado é um dos poucos sinais de ataque inequívocos que uma pilha agêntica produz.", "É independente do modelo: continua funcionando entre trocas de modelo, mudanças de prompt e migrações de framework.", "É barata de estender depois que o gateway existe; cada agente novo herda o ponto de aplicação." ], "risks": [ "O relé permitido: um host autorizado que por sua vez repassa os dados transforma a lista em formalidade.", "Quebras quando uma dependência legítima muda de host, o que gera pressão para ampliar a lista com pressa.", "Erosão por curingas: cada entrada ampla adicionada “temporariamente” é permanente até alguém auditá-la.", "Aplicação na camada errada: uma verificação no próprio processo que o código gerado simplesmente contorna." ], "whenNot": [ "Agentes totalmente sem rede, onde não há saída a limitar e o controle seria encenação.", "Quando o design já permite exatamente um destino, então a lista é propriedade da arquitetura e não política a acrescentar.", "Quando um proxy corporativo já aplica a mesma política e uma segunda lista dividiria a responsabilidade sem acrescentar restrição." ], "examples": [ "Um agente de programação em um contêiner cuja política de saída nomeia o registry de pacotes e o host Git interno, e nada mais. Uma instrução injetada para dar POST do repositório a um coletor externo falha na camada de rede e aparece como negação.", "Um agente de pesquisa autorizado a baixar amplamente, mas forçado por um proxy que permite apenas GET e limita o tamanho dos corpos de saída: consegue ler a web sem ter um canal para escrever nela.", "O pacote stdio publicado para esta base de conhecimento: seu único destino de saída é o endpoint público do qual ele é proxy, então a lista de permitidos é propriedade do design e não política acrescentada depois." ], "kpis": [ { "metric": "Tentativas de saída negadas", "note": "O sinal que o padrão existe para produzir. Uma alta sustentada é um ataque ou uma tarefa que ultrapassou sua lista; vale saber qual." }, { "metric": "Tamanho da lista", "note": "Destinos permitidos por papel de agente. Crescer sem remover é a lista degradando para “permitir tudo”." }, { "metric": "Entradas com curinga", "note": "Número de entradas amplas. Cada uma é um canal sobre o qual você não consegue raciocinar; o alvo é zero." }, { "metric": "Tempo de negação até triagem", "note": "Quanto uma negação espera até alguém olhar. Uma negação não lida é um alerta que você não tem de fato." } ], "failureModes": [ "O relé permitido: um host aprovado que repassa o que receber, então a verificação de destino passa e os dados saem do mesmo jeito.", "Erosão por curingas: entradas amplas temporárias que sobrevivem ao motivo pelo qual foram adicionadas.", "Aplicação no próprio processo: a verificação mora onde o código gerado roda, então o código consegue pulá-la.", "Negações silenciosas: recusas registradas como erros de rede comuns, então o único sinal que o padrão gera nunca chega a ninguém." ], "lessons": [ "A saída é o último controle que ainda funciona depois que o modelo foi convencido. Construa antes de precisar.", "Derive a lista de tráfego medido e não de suposição. Fazer exatamente isso para a regra de origem de entrada do nosso próprio endpoint MCP produziu uma regra diferente da que teríamos escrito a partir de um padrão.", "Trate uma negação como alerta, não como erro. É o sinal de ataque mais barato de toda a pilha.", "Todo curinga é uma promessa que você não consegue cumprir. Nomeie hosts, ou admita que não tem uma lista de permitidos." ], "faqs": [ { "q": "Uma lista de saída é realista para um agente que navega na web?", "a": "Sim, se você limitar a forma em vez do conjunto. Permita tráfego GET amplo através de um proxy que proíba corpos de requisição e limite tamanhos: o agente lê muito sem ter um canal largo o bastante para tirar o que leu." }, { "q": "O DNS precisa entrar na lista?", "a": "Precisa. Um resolvedor que o agente consulta livremente é um canal de exfiltração: dados codificados em consultas de subdomínio saem sem uma única requisição HTTP. Roteie o DNS pela mesma política." }, { "q": "Já temos ferramentas com privilégio mínimo. Isto é redundante?", "a": "Não; cobrem metades diferentes. O privilégio mínimo limita o que o agente pode fazer; o controle de saída limita para onde pode ir o que ele já leu. Um agente somente leitura com saída aberta ainda vaza tudo o que consegue ler." } ] }, "fr": { "name": "Liste d'autorisation de sortie", "summary": "Restreignez les destinations autorisées pour le trafic d'un agent. Le vol de données et la livraison de charges utiles d'injection se terminent tous deux par une requête sortante, de sorte qu'une liste de destinations autorisées avec refus par défaut est le contrôle qui fonctionne encore lorsque tous les autres ont échoué.", "definition": "Une liste d'autorisation de sortie est une politique au niveau du réseau ou du bac à sable (sandbox) qui n'autorise les requêtes sortantes d'un agent que vers un ensemble de destinations explicitement nommées et refuse tout le reste par défaut, de sorte que les données ne peuvent pas être envoyées vers un point de terminaison choisi par un attaquant, même si l'agent a été entièrement compromis.", "problem": "Chaque chemin d'exfiltration se termine par une requête sortante. Un agent capable d'atteindre des hôtes arbitraires peut recevoir l'instruction d'envoyer tout ce qu'il a lu à n'importe quelle adresse, et aucune instruction au niveau du prompt ne peut l'empêcher.", "context": "Utilisez-le partout où un agent traite du contenu non approuvé et peut effectuer des requêtes réseau — récupération de pages, appels d'outils, rendu d'images, exécution de code généré. Ce pattern est le plus précieux là où l'injection est la plus probable.", "solution": [ "Refus par défaut. La liste d'autorisation est la seule issue ; tout ce qui n'y figure pas est refusé, et le refus est journalisé comme un signal plutôt que d'être étouffé sous forme d'erreur.", "Énumérez les destinations à partir de la tâche : les API que l'agent doit appeler, les domaines qu'il doit récupérer, les registres à partir desquels il doit installer — chacun avec un propriétaire et un motif écrit.", "Appliquez les règles en aval de l'agent. Placez la politique dans le sandbox, le proxy ou le réseau, jamais dans le code de l'outil dont le modèle pourrait s'affranchir par la discussion. Une règle qu'un agent peut contourner par la persuasion est une simple documentation, pas un contrôle.", "Fermez les canaux discrets. Les URL d'images générées, les aperçus de liens, les requêtes DNS, les webhooks, les rapports d'erreurs et les installations de paquets constituent tous des flux sortants (egress), et ils sont tous exploités.", "Autorisez les hôtes dont vous pouvez analyser le comportement. Un caractère générique (wildcard) sur un hôte qui héberge du contenu fourni par l'utilisateur — un CDN de fichiers bruts, un site de partage de texte (paste site), un stockage d'objets public — est un canal ouvert déguisé en liste d'autorisation.", "Déduisez la liste à partir de mesures réelles et recalculez-la lorsque la tâche change. Partez de ce que l'agent appelle réellement, et non de ce que l'on suppose qu'il appelle." ], "components": [ "Une passerelle de sortie (egress gateway) ou une politique réseau de sandbox que tout le trafic doit obligatoirement traverser.", "Une règle de refus par défaut avec un inventaire explicite et géré des destinations autorisées.", "Des politiques par rôle, afin qu'un agent de recherche et un agent de déploiement ne partagent pas la même liste.", "La journalisation des refus connectée à un système d'alerte, car un refus est un événement à fort signal.", "Des contraintes sur les méthodes et les charges utiles (payloads) lorsque la destination seule ne suffit pas (GET uniquement, limites de taille du corps de la requête).", "Un cycle de révision régulier pour supprimer les destinations qui n'ont pas été utilisées." ], "benefits": [ "Limite l'exfiltration de données même après un compromis total du raisonnement de l'agent.", "Rend les tentatives visibles : une destination refusée est l'un des rares signaux d'attaque non ambigus générés par une pile d'agents.", "Indépendant du modèle — il continue de fonctionner lors des changements de modèle, des modifications de prompt et des migrations de framework.", "Peu coûteux à étendre une fois la passerelle en place ; chaque nouvel agent hérite du point de contrôle." ], "risks": [ "Le relais sur liste d'autorisation : un hôte autorisé qui réachemine lui-même les données réduit la liste d'autorisation à une simple formalité.", "Risque de rupture lorsqu'une dépendance légitime change d'hôte, ce qui pousse à élargir la liste dans l'urgence.", "L'érosion par caractères génériques (wildcards) : chaque entrée large ajoutée « temporairement » devient permanente tant qu'aucun audit n'est réalisé.", "Application au mauvais niveau — un contrôle au sein du processus (in-process) que le code généré peut simplement contourner." ], "whenNot": [ "Agents entièrement hors ligne, pour lesquels il n'y a aucun flux sortant à restreindre et où le contrôle ne serait que de la figuration.", "Lorsque la conception n'autorise déjà qu'une seule et unique destination, faisant de la liste d'autorisation une propriété intrinsèque de l'architecture plutôt qu'une politique à ajouter.", "Lorsqu'un proxy d'entreprise applique déjà la même politique et qu'une seconde liste diviserait la responsabilité sans ajouter de contrainte réelle." ], "examples": [ "Un agent de codage dans un conteneur dont la politique de sortie (egress) ne mentionne que le registre de paquets et l'hôte Git interne. Une instruction injectée visant à envoyer un POST du dépôt vers un collecteur externe échoue au niveau de la couche réseau et apparaît comme un refus.", "Un agent de recherche autorisé à effectuer des requêtes étendues mais contraint de passer par un proxy qui n'autorise que le GET et limite la taille des corps sortants — lui permettant ainsi de lire le web sans disposer de canal pour y écrire.", "Le paquet stdio publié pour cette base de connaissances : sa seule destination sortante est le point de terminaison public pour lequel il sert de proxy, de sorte que la liste d'autorisation est une propriété de la conception plutôt qu'une politique superposée a posteriori." ], "kpis": [ { "metric": "Tentatives de sortie (egress) refusées", "note": "Le signal que ce pattern a pour but de produire. Une hausse prolongée indique soit une attaque, soit une tâche devenue trop large pour sa liste — deux informations cruciales à connaître." }, { "metric": "Taille de la liste d'autorisation", "note": "Destinations autorisées par rôle d'agent. Une croissance sans suppression correspond à une dérive de la liste vers un mode « tout autoriser »." }, { "metric": "Entrées avec caractères génériques (wildcards)", "note": "Nombre d'entrées larges. Chacune d'elles représente un canal dont vous ne pouvez pas analyser le comportement ; l'objectif est d'en avoir zéro." }, { "metric": "Délai entre le refus et le tri", "note": "Le temps d'attente d'un refus avant qu'un humain ne l'examine. Un refus non consulté est une alerte qui n'existe pas réellement." } ], "failureModes": [ "Le relais sur liste d'autorisation : un hôte approuvé qui réacheminera tout ce qu'il reçoit, de sorte que la vérification de la destination réussit et que les données s'échappent tout de même.", "L'érosion par caractères génériques (wildcards) : des entrées larges temporaires qui survivent à la raison pour laquelle elles ont été ajoutées.", "Application au sein du processus (in-process) : le contrôle réside là où le code généré s'exécute, permettant à ce dernier de l'ignorer.", "Refus silencieux : des refus enregistrés comme de simples erreurs réseau ordinaires, de sorte que l'unique signal généré par le pattern ne parvient jamais à personne." ], "lessons": [ "Le contrôle des flux sortants (egress) est le dernier rempart qui fonctionne encore une fois que le modèle a été manipulé. Mettez-le en place avant d'en avoir besoin.", "Déduisez la liste à partir du trafic mesuré plutôt que de suppositions. C'est précisément ce que nous avons fait pour la règle d'origine entrante sur notre propre point de terminaison MCP, ce qui a produit une règle bien différente de celle que nous aurions écrite par défaut.", "Traitez un refus comme une alerte, pas comme une erreur. C'est le signal d'attaque le plus économique de la pile.", "Chaque caractère générique (wildcard) est une promesse que vous ne pouvez pas tenir. Nommez explicitement les hôtes, ou acceptez le fait que vous n'avez pas de liste d'autorisation." ], "faqs": [ { "q": "Une liste d'autorisation de sortie (egress) est-elle réaliste pour un agent qui navigue sur le web ?", "a": "Oui, si vous limitez la forme plutôt que l'ensemble. Autorisez un large trafic GET via un proxy qui interdit les corps de requête et limite les tailles : l'agent peut ainsi lire à grande échelle sans disposer de canal suffisant pour exporter ce qu'il a lu." }, { "q": "Le DNS doit-il figurer sur la liste ?", "a": "Tout à fait. Un résolveur que l'agent peut interroger librement constitue un canal d'exfiltration — les données encodées dans des requêtes de sous-domaines s'échappent sans la moindre requête HTTP. Soumettez le DNS à la même politique." }, { "q": "Nous disposons déjà d'outils de moindre privilège. Est-ce redondant ?", "a": "Non, ils couvrent deux aspects complémentaires. Le moindre privilège limite ce que l'agent peut faire, tandis que le contrôle des flux sortants (egress) limite la destination de ce qu'il a déjà lu. Un agent en lecture seule avec un accès sortant ouvert peut tout de même divulguer l'intégralité de ce qu'il est capable de lire." } ] }, "de": { "name": "Egress-Allowlist", "summary": "Schränken Sie ein, wohin der Traffic eines Agenten fließen darf. Datendiebstahl und die Übertragung von Injection-Payloads enden beide in einem ausgehenden Request. Eine Default-Deny-Liste zugelassener Ziele ist daher die Kontrollmaßnahme, die selbst dann noch greift, wenn alle anderen versagt haben.", "definition": "Eine Egress-Allowlist ist eine Richtlinie auf Netzwerk- oder Sandbox-Ebene, die ausgehende Requests eines Agenten nur an eine explizit definierte Gruppe von Zielen zulässt und alles andere standardmäßig blockiert. So können selbst bei einer vollständigen Übernahme des Agenten keine Daten an einen vom Angreifer gewählten Endpunkt abfließen.", "problem": "Jeder Exfiltrationspfad endet in einem ausgehenden Request. Ein Agent, der beliebige Hosts erreichen kann, kann angewiesen werden, alle gelesenen Daten an eine beliebige Adresse zu senden – und keine Anweisung auf Prompt-Ebene kann das verhindern.", "context": "Nutzen Sie dieses Pattern überall dort, wo ein Agent sowohl nicht vertrauenswürdige Inhalte verarbeitet als auch Netzwerkanfragen stellen kann – sei es beim Abrufen von Seiten, Aufrufen von Tools, Rendern von Bildern oder Ausführen von generiertem Code. Das Pattern ist genau dort am wertvollsten, wo Injections am wahrscheinlichsten sind.", "solution": [ "Default-Deny. Die Allowlist ist der einzige Ausweg; alles, was nicht explizit aufgeführt ist, wird blockiert. Diese Blockierung wird als Signal protokolliert und nicht einfach als Fehler verschluckt.", "Listen Sie die Ziele basierend auf der Aufgabe auf: die APIs, die der Agent aufrufen muss, die Domains, die er abrufen muss, die Registries, aus denen er installieren muss – jeweils mit einem Verantwortlichen und einer schriftlichen Begründung.", "Erzwingen Sie dies unterhalb des Agenten. Platzieren Sie die Richtlinie in der Sandbox, im Proxy oder im Netzwerk, niemals im Tool-Code, von dem das Modell abgebracht werden kann. Eine Regel, die der Agent wegdiskutieren kann, ist eine Dokumentation, keine Kontrollmaßnahme.", "Schließen Sie die stillen Kanäle. Gerenderte Bild-URLs, Link-Vorschauen, DNS-Abfragen, Webhooks, Fehlerberichterstatter und Paketinstallationen sind alle Egress, und sie alle werden genutzt.", "Erlauben Sie Hosts, über die Sie logisch urteilen können. Eine Wildcard für einen Host, der vom Benutzer bereitgestellte Inhalte bereitstellt – ein Raw-File-CDN, eine Paste-Website, ein öffentlicher Objektspeicher –, ist ein offener Kanal im Gewand einer Allowlist.", "Leiten Sie die Liste aus Messungen ab und leiten Sie sie erneut ab, wenn sich die Aufgabe ändert. Gehen Sie von dem aus, was der Agent tatsächlich aufruft, nicht von dem, was jemand vermutet." ], "components": [ "Ein Egress-Gateway oder eine Sandbox-Netzwerkrichtlinie, die der gesamte Datenverkehr durchlaufen muss.", "Eine Deny-by-Default-Regel mit einem expliziten, verwalteten Zielinventar.", "Rollenbasierte Richtlinien, damit ein Forschungs-Agent und ein Deployment-Agent nicht dieselbe Liste teilen.", "Protokollierung von Blockierungen (Denial Logging) gekoppelt mit Alarmierung, da eine Blockierung ein Signal mit hohem Informationsgehalt ist.", "Methoden- und Payload-Einschränkungen, wenn das Ziel allein nicht ausreicht (nur GET, Begrenzung der Body-Größe).", "Ein regelmäßiger Überprüfungszyklus, der Ziele entfernt, die von nichts genutzt wurden." ], "benefits": [ "Begrenzt die Datenexfiltration selbst nach einer vollständigen Kompromittierung der Logik des Agenten.", "Macht Versuche sichtbar: Ein blockiertes Ziel ist eines der wenigen eindeutigen Angriffssignale, die ein Agenten-Stack erzeugt.", "Modellunabhängig – es funktioniert auch bei Modellwechseln, Prompt-Änderungen und Framework-Migrationen weiterhin.", "Kostengünstig zu erweitern, sobald das Gateway existiert; jeder neue Agent erbt den Durchsetzungspunkt." ], "risks": [ "Das freigegebene Relay: Ein erlaubter Host, der selbst Daten weiterleitet, macht die Allowlist zu einer reinen Formalität.", "Ausfälle, wenn eine legitime Abhängigkeit den Host wechselt, was unter Zeitdruck Druck erzeugt, die Liste zu erweitern.", "Wildcard-Erosion: Jeder grobe Eintrag, der \"vorübergehend\" hinzugefügt wird, bleibt dauerhaft bestehen, bis ihn jemand überprüft.", "Durchsetzung auf der falschen Ebene – eine In-Process-Prüfung, die der generierte Code einfach umgehen kann." ], "whenNot": [ "Vollständig Offline-Agenten, bei denen es keinen Egress einzuschränken gibt und die Kontrollmaßnahme reine Show wäre.", "Wenn das Design bereits genau ein Ziel zulässt, sodass die Allowlist eine Eigenschaft der Architektur ist und keine zusätzlich hinzuzufügende Richtlinie.", "Wenn ein Unternehmens-Proxy bereits dieselbe Richtlinie erzwingt und eine zweite Liste die Zuständigkeit aufteilen würde, ohne eine Einschränkung hinzuzufügen." ], "examples": [ "Ein Coding-Agent in einem Container, dessen Egress-Richtlinie nur die Paketregistrierung und den internen Git-Host nennt. Eine injizierte Anweisung, das Repository per POST an einen externen Collector zu senden, schlägt auf der Netzwerkesbene fehl und wird als Blockierung erfasst.", "Ein Forschungs-Agent, der weitreichende Abrufe durchführen darf, aber über einen Proxy geleitet wird, der nur GET erlaubt und ausgehende Bodys begrenzt – er kann das Web lesen, hat aber keinen Kanal, um darauf zu schreiben.", "Das für diese Wissensdatenbank veröffentlichte stdio-Paket: Sein einziges ausgehendes Ziel ist der öffentliche Endpunkt, den es per Proxy anspricht, sodass die Allowlist eine Eigenschaft des Designs ist und keine nachträglich überlagerte Richtlinie." ], "kpis": [ { "metric": "Blockierte Egress-Versuche", "note": "Das Signal, für dessen Erzeugung das Pattern existiert. Ein anhaltender Anstieg ist entweder ein Angriff oder eine Aufgabe, die über ihre Liste hinausgewachsen ist – beides ist wissenswert." }, { "metric": "Größe der Allowlist", "note": "Zugelassene Ziele pro Agentenrolle. Ein Wachstum ohne Löschungen führt dazu, dass die Liste in Richtung \"Alles erlauben\" verfällt." }, { "metric": "Wildcard-Einträge", "note": "Anzahl grober Einträge. Jeder einzelne ist ein Kanal, über den Sie nicht logisch urteilen können; das Ziel ist null." }, { "metric": "Zeit von der Blockierung bis zur Triage", "note": "Wie lange eine Blockierung wartet, bevor ein Mensch sie ansieht. Eine ungelesene Blockierung ist ein Alarm, den Sie eigentlich nicht haben." } ], "failureModes": [ "Das freigegebene Relay: Ein zugelassener Host, der alles weiterleitet, was er erhält, sodass die Zielprüfung erfolgreich ist und die Daten dennoch abfließen.", "Wildcard-Erosion: Temporäre grobe Einträge, die den Grund für ihre Hinzufügung überdauern.", "In-Process-Durchsetzung: Die Prüfung findet dort statt, wo der generierte Code ausgeführt wird, sodass der Code sie umgehen kann.", "Stille Blockierungen: Ablehnungen, die als gewöhnliche Netzwerkfehler protokolliert werden, sodass das einzige Signal, das das Pattern erzeugt, niemanden erreicht." ], "lessons": [ "Egress is die letzte Kontrollmaßnahme, die noch funktioniert, nachdem das Modell überzeugt wurde. Bauen Sie sie auf, bevor Sie sie benötigen.", "Leiten Sie die Liste aus dem gemessenen Datenverkehr ab und nicht aus Annahmen. Genau das für die Inbound-Origin-Regel an unserem eigenen MCP-Endpunkt zu tun, führte zu einer Regel, die sich von der unterschied, die wir standardmäßig geschrieben hätten.", "Behandeln Sie eine Blockierung als Alarm, nicht als Fehler. Sie ist das kostengünstigste Angriffssignal im Stack.", "Jede Wildcard ist ein Versprechen, das Sie nicht halten können. Nennen Sie konkrete Hosts, oder akzeptieren Sie, dass Sie keine Allowlist haben." ], "faqs": [ { "q": "Ist eine Egress-Allowlist für einen Agenten, der im Web surft, realistisch?", "a": "Ja, wenn Sie eher die Form als die Menge einschränken. Erlauben Sie weitreichenden GET-Datenverkehr über einen Proxy, der Request-Bodys verbietet und die Größe begrenzt: Der Agent kann umfassend lesen, hat aber keinen Kanal, der breit genug ist, um das Gelesene herauszuschreiben." }, { "q": "Muss DNS auf der Liste stehen?", "a": "Ja. Ein Resolver, den der Agent frei abfragen kann, ist ein Exfiltrationskanal – Daten, die in Subdomain-Abfragen codiert sind, fließen ohne eine einzige HTTP-Anfrage ab. Leiten Sie DNS über dieselbe Richtlinie." }, { "q": "Wir haben bereits Tools mit dem Prinzip der minimalen Rechtevergabe (Least Privilege). Ist das redundant?", "a": "Nein; sie decken unterschiedliche Hälften ab. Least Privilege begrenzt, was der Agent tun kann, Egress-Kontrolle begrenzt, wohin das bereits Gelesene gelangen kann. Ein Read-Only-Agent mit offenem Egress kann dennoch alles leaken, was er lesen kann." } ] }, "ja": { "name": "エグレス許可リスト", "summary": "エージェントのトラフィックの送信先を制限します。データの窃盗もインジェクションペイロードの配信も、最終的には外部へのリクエストに行き着くため、許可された送信先のみを定義するデフォルト拒否（default-deny）リストは、他のすべてのコントロールが失敗した後に機能する最後の砦となります。", "definition": "エグレス許可リストとは、エージェントの外部へのリクエストを明示的に指定された送信先セットのみに許可し、それ以外をデフォルトで拒否する、ネットワークまたはサンドボックスレベルのポリシーです。これにより、エージェントが完全にハイジャックされた場合でも、攻撃者が指定したエンドポイントにデータが流出するのを防ぐことができます。", "problem": "すべてのデータ流出経路は、外部へのリクエストで行き着きます。任意のホストにアクセスできるエージェントは、読み取ったすべてのデータを任意のアドレスに送信するように指示される可能性があり、プロンプトレベルの指示ではこれを防ぐことはできません。", "context": "エージェントが信頼できないコンテンツを処理し、かつネットワークリクエスト（ページの取得、ツールの呼び出し、画像のレンダリング、生成されたコードの実行など）を実行できるすべての場所で使用します。このパターンは、インジェクションが発生する可能性が最も高い場所で最大の価値を発揮します。", "solution": [ "デフォルト拒否。許可リストのみが唯一の送信経路となります。指定されていないものはすべて拒否され、その拒否はエラーとして握り潰されるのではなく、シグナルとしてログに記録されます。", "タスクに基づいて送信先を列挙します。エージェントが呼び出す必要のあるAPI、取得する必要のあるドメイン、インストール元のレジストリなど、それぞれに所有者と書面による理由を明記します。", "エージェントの下層で強制します。ポリシーはサンドボックス、プロキシ、またはネットワークに配置し、モデルが言いくるめて回避できるようなツールのコード内には決して配置しないでください。エージェントが言いくるめて回避できるルールは、コントロールではなく単なるドキュメントです。", "目立たないチャネルを閉鎖します。レンダリングされた画像URL、リンクプレビュー、DNSルックアップ、Webhook、エラーリポーター、パッケージのインストールはすべてエグレスであり、そのすべてが利用されます。", "動作を論理的に推測できるホストのみを許可します。ユーザー提供のコンテンツを配信するホスト（生のファイルのCDN、ペーストサイト、パブリックオブジェクトストレージなど）に対するワイルドカードは、許可リストの皮を被ったオープンなチャネルにすぎません。", "測定に基づいてリストを導出し、タスクが変更されたときに再導出します。誰かが呼び出すと想定しているものではなく、エージェントが実際に呼び出すものから開始します。" ], "components": [ "すべてのトラフィックが通過しなければならないエグレスゲートウェイまたはサンドボックスネットワークポリシー。", "明示的かつ管理された宛先インベントリを持つ、デフォルト拒否（deny-by-default）ルール。", "調査用エージェントとデプロイ用エージェントが1つのリストを共有しないようにするための、ロールごとのポリシー。", "拒否はシグナル強度の高いイベントであるため、アラート送信に連携された拒否ログ。", "宛先だけでは不十分な場合における、メソッドとペイロードの制約（GETのみ、ボディサイズ制限など）。", "誰も使用していない宛先を削除するための定期的なレビュー。" ], "benefits": [ "エージェントの推論プロセスが完全に侵害された後でも、データの持ち出しを制限します。", "試行を可視化します。拒否された宛先は、エージェントスタックが生成する数少ない明白な攻撃シグナルの1つです。", "モデルに依存しません。モデルの入れ替え、プロンプトの変更、フレームワークの移行を行っても機能し続けます。", "ゲートウェイが存在すれば拡張コストが低く、新しいエージェントはそれぞれその強制ポイントを継承します。" ], "risks": [ "許可リストに登録されたリレー：許可されたホスト自体がデータをさらに転送する場合、許可リストは形骸化します。", "正当な依存関係のホストが移動したときに破損が発生し、時間のプレッシャーの中でリストを拡張せざるを得なくなる状況。", "ワイルドカードの浸食：「一時的」に追加された広範なエントリは、誰かが監査するまで永続的に残ります。", "誤ったレイヤーでの強制：生成されたコードが簡単にバイパスできるインプロセスチェック。" ], "whenNot": [ "完全にオフラインのエージェント。制限すべきエグレスが存在せず、コントロールが形骸化（形だけ）になります。", "設計上、すでに宛先が厳密に1つしか許可されていない場合。この場合、許可リストは追加すべきポリシーではなく、アーキテクチャの特性となります。", "企業のプロキシがすでに同じポリシーを強制しており、2つ目のリストを作成すると制約を追加することなく所有権が分散してしまう場合。" ], "examples": [ "コンテナ内のコーディングエージェントで、そのエグレスポリシーにパッケージレジストリと内部Gitホストのみが指定されている場合。リポジトリを外部のコレクターにPOSTするように注入された指示は、ネットワークレイヤーで失敗し、拒否として表示されます。", "広範囲のフェッチは許可されているものの、GETのみを許可し送信ボディを制限するプロキシの通過を強制される調査用エージェント。Webを読み取ることはできますが、Webに書き込むためのチャネルは持ちません。", "このナレッジベース向けに公開されているstdioパッケージ：その唯一の送信先はプロキシ先であるパブリックエンドポイントであるため、許可リストは後から重ねるポリシーではなく、設計の特性となります。" ], "kpis": [ { "metric": "拒否されたエグレス試行", "note": "このパターンが存在する目的であるシグナル。持続的な増加は、攻撃が発生しているか、タスクがリストの規模を超えたかのいずれかであり、どちらも把握する価値があります。" }, { "metric": "許可リストのサイズ", "note": "エージェントのロールごとに許可されている宛先。削除を伴わない増加は、リストが「すべて許可」に向かって形骸化していることを意味します。" }, { "metric": "ワイルドカードエントリ", "note": "広範なエントリの数。これらはすべて、動作を論理的に推測できないチャネルであり、目標値はゼロです。" }, { "metric": "拒否からトリアージまでの時間", "note": "拒否が発生してから人間が確認するまでの待ち時間。確認されない拒否は、実際には存在しないアラートと同じです。" } ], "failureModes": [ "許可リストに登録されたリレー：渡されたものを何でも転送する承認済みホスト。これにより、宛先チェックはパスし、データは流出し続けます。", "ワイルドカードの浸食：追加された理由よりも長生きする、一時的な広範なエントリ。", "インプロセスでの強制：生成されたコードが実行される場所でチェックが行われるため、コードがチェックをスキップできてしまいます。", "サイレントな拒否：拒否が通常のネットワークエラーとしてログに記録されるため、このパターンが生成する唯一のシグナルが誰にも届きません。" ], "lessons": [ "エグレスは、モデルが言いくるめられた後でも機能する最後のコントロールです。必要になる前に構築してください。", "想定ではなく、測定されたトラフィックからリストを導出します。独自のMCPエンドポイントのインバウンドオリジンルールでまさにこれを行ったところ、デフォルトから作成したであろうルールとは異なるルールが生成されました。", "拒否をエラーではなくアラートとして扱います。これはスタックの中で最も低コストな攻撃シグナルです。", "すべてのワイルドカードは、守ることのできない約束です。ホスト名を指定するか、許可リストが存在しないことを受け入れてください。" ], "faqs": [ { "q": "Webを閲覧するエージェントにとって、エグレス許可リストは現実的ですか？", "a": "はい、セットではなく形状を制約すれば可能です。リクエストボディを禁止しサイズを制限するプロキシを介して広範なGETトラフィックを許可します。これにより、エージェントは広く読み取ることができますが、読み取った内容を書き出すのに十分な広さのチャネルは持ちません。" }, { "q": "DNSをリストに含める必要がありますか？", "a": "必要です。エージェントが自由にクエリできるリゾルバーは、データの持ち出しチャネルになります。サブドメインのルックアップにエンコードされたデータは、HTTPリクエストを1回も送信することなく流出します。DNSも同じポリシーを介してルーティングしてください。" }, { "q": "すでに最小権限のツールを導入しています。これは冗長ですか？", "a": "いいえ、これらは異なる半分をカバーしています。最小権限はエージェントができることを制限し、エグレスコントロールはすでに読み取ったデータの送信先を制限します。エグレスが開放されている読み取り専用エージェントは、読み取ることができるすべての情報を漏洩させる可能性があります。" } ] }, "zh": { "name": "出口允许列表", "summary": "限制智能体的流量允许流向何处。数据窃取和注入有效载荷的传递都以出站请求结束，因此默认拒绝的允许目标地址列表是在其他所有控制措施都失效后仍然有效的控制手段。", "definition": "出口允许列表是一种网络或沙箱级别的策略，它仅允许智能体向明确指定的目的地集合发送出站请求，并默认拒绝其他所有请求，因此即使智能体已被完全劫持，数据也无法流向攻击者选择的端点。", "problem": "每条外发路径都以出站请求结束。可以访问任意主机的智能体可能会被指示将其读取的任何内容发送到任何地址，而没有任何提示词级别的指令可以阻止这一点。", "context": "在智能体既处理不可信内容又可以发起网络请求的任何地方使用它——例如获取页面、调用工具、渲染图像、运行生成的代码。该模式在最容易发生注入的地方价值最大。", "solution": [ "默认拒绝。允许列表是唯一的出口；任何未列出的请求都会被拒绝，并且该拒绝会被记录为信号，而不是作为错误被吞掉。", "根据任务列举目的地：智能体必须调用的 API、必须获取的域名、必须从中安装的注册表——每个目的地都应有所有者和书面理由。", "在智能体底层进行强制执行。将策略置于沙箱、代理或网络中，绝不要放在模型可以通过辩解绕过的工具代码中。一条智能体可以说服绕过的规则只是文档，而不是控制措施。", "关闭隐蔽通道。渲染的图像 URL、链接预览、DNS 查询、webhook、错误报告程序和包安装都属于出站流量，而且它们都会被利用。", "仅允许您可以推断其行为的主机。在提供用户生成内容的主机（如原始文件 CDN、剪贴板网站、公共对象存储）上使用通配符，无异于披着白名单外衣的开放通道。", "通过实际测量来推导白名单，并在任务改变时重新推导。从智能体实际调用的内容开始，而不是基于某人假设它会调用的内容。" ], "components": [ "所有流量都必须通过的出站网关或沙箱网络策略。", "默认拒绝规则，并配有明确且有专人维护的目标地址清单。", "基于角色的策略，使研究智能体和部署智能体不共享同一个白名单。", "将拒绝日志与告警关联，因为拒绝事件是高信号强度的事件。", "在仅靠目标地址还不够时的请求方法和载荷限制（例如：仅限 GET、限制主体大小）。", "定期审查机制，用于移除从未被使用过的目标地址。" ], "benefits": [ "即使在智能体的推理能力被完全攻破后，也能限制数据外泄。", "使尝试行为可视化：被拒绝的目标地址是智能体技术栈产生的少数几个明确无误的攻击信号之一。", "独立于模型 —— 在更换模型、修改提示词和迁移框架时依然有效。", "一旦网关建立，扩展成本极低；每个新智能体都会继承该执行点。" ], "risks": [ "白名单中的中继：允许的主机自身如果转发数据，会使白名单流于形式。", "当合法的依赖项迁移主机时会导致服务中断，从而在时间紧迫的情况下产生扩大白名单的压力。", "通配符侵蚀：每个“临时”添加的宽泛条目在有人审计之前都会变成永久条目。", "在错误的层级进行强制执行 —— 例如生成的代码可以轻易绕过的进程内检查。" ], "whenNot": [ "完全离线的智能体，此时没有需要限制的出站流量，这种控制措施只是流于形式。", "当设计上已经仅允许一个目标地址时，白名单已是架构本身的属性，无需额外添加策略。", "当企业代理已经强制执行相同的策略时，设置第二个白名单会在不增加任何限制的情况下分散所有权。" ], "examples": [ "容器中的编码智能体，其出站策略仅指定了包注册表和内部 Git 主机。注入的将代码库 POST 到外部收集器的指令会在网络层失败，并显示为拒绝事件。", "允许广泛获取数据但必须通过代理的研究智能体，该代理仅允许 GET 请求并限制出站主体大小 —— 使其能够读取网页，但没有向外写入数据的通道。", "为此知识库发布的 stdio 包：其唯一的出站目标是它所代理的公共端点，因此白名单是设计本身的属性，而不是事后叠加的策略。" ], "kpis": [ { "metric": "被拒绝的出站尝试", "note": "该模式旨在产生的信号。持续上升要么意味着遭受攻击，要么意味着任务超出了其白名单范围 —— 这两者都值得关注。" }, { "metric": "白名单大小", "note": "每个智能体角色允许的目标地址数量。只增不减会导致白名单逐渐退化为“允许所有”。" }, { "metric": "通配符条目", "note": "宽泛条目的数量。每一个宽泛条目都是一个您无法推断其行为的通道；目标值应为零。" }, { "metric": "从拒绝到分类处置的时间", "note": "拒绝事件在人工查看前等待了多长时间。未读的拒绝事件等于不存在的告警。" } ], "failureModes": [ "白名单中的中继：一个被批准的主机会转发接收到的任何内容，从而使目标检查通过，而数据仍然会外泄。", "通配符侵蚀：临时的宽泛条目生命周期超出了其添加的初衷。", "进程内强制执行：检查存在于生成代码运行的地方，因此代码可以跳过它。", "静默拒绝：拒绝被记录为普通的网络错误，导致该模式生成的唯一信号永远无法送达任何人。" ], "lessons": [ "出站控制是模型被说服后仍然有效的最后一道防线。在需要它之前就构建好它。", "通过测量流量而非假设来推导白名单。在针对我们自己的 MCP 端点的入站来源规则进行此操作时，产生了一条与我们默认编写的规则完全不同的规则。", "将拒绝事件视为告警，而非错误。它是技术栈中成本最低的攻击信号。", "每一个通配符都是一个您无法兑现的承诺。明确指定主机，否则就承认您并没有白名单。" ], "faqs": [ { "q": "对于需要浏览网页的智能体，出站白名单现实吗？", "a": "是的，前提是您限制其形式而不是集合。通过禁止请求主体并限制大小的代理来允许广泛的 GET 流量：智能体可以广泛读取，但没有足够宽的通道来写出它所读取的内容。" }, { "q": "DNS 需要在白名单中吗？", "a": "需要。智能体可以自由查询的解析器是一个数据外泄通道 —— 编码到子域名查询中的数据无需单个 HTTP 请求即可流出。请通过相同的策略路由 DNS。" }, { "q": "我们已经有了最小权限工具。这是否多余？", "a": "不，它们涵盖了不同的方面。最小权限限制了智能体可以执行的操作，而出站控制限制了它已经读取的内容可以流向何处。一个具有开放出站通道的只读智能体仍然可以泄露它能读取的所有内容。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/evaluator-optimizer", "api_url": "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." } ] }, "fr": { "name": "Évaluateur-Optimiseur", "summary": "Un premier LLM génère une réponse tandis qu'un second l'évalue par rapport à des critères et renvoie des commentaires ; le générateur la révise et la boucle se répète jusqu'à ce que l'évaluation soit validée. Cela améliore la qualité sur les tâches dotées de critères d'évaluation clairs, au prix d'appels supplémentaires.", "problem": "Un résultat généré en une seule passe peut omettre certaines exigences, et il n'existe aucun mécanisme intégré pour le vérifier et l'améliorer avant son utilisation.", "context": "Utilisez le pattern évaluateur-optimiseur lorsque vous pouvez formuler des critères d'évaluation clairs et que l'affinement itératif améliore le résultat de manière mesurable — par exemple pour la qualité d'une traduction, du code devant passer des tests ou de la rédaction basée sur une grille d'évaluation.", "solution": [ "Un générateur produit une proposition ; un évaluateur (un appel LLM distinct ou un contrôle déterministe) lui attribue un score selon des critères explicites et renvoie des commentaires exploitables. Le générateur révise sa proposition, et le cycle se répète jusqu'à ce que les critères soient satisfaits ou qu'un budget limite soit atteint.", "Séparer la génération de l'évaluation s'apparente à la relation entre un auteur et son éditeur : le critique détecte les problèmes qui ont échappé à l'auteur, et des critères explicites permettent à la boucle de converger." ], "components": [ "Générateur", "Évaluateur (juge LLM ou contrôle de règles)", "Critères explicites", "Boucle de révision", "Condition d'arrêt / budget" ], "benefits": [ "Qualité supérieure sur les tâches dotées de critères clairs.", "Détecte les erreurs qu'une seule passe aurait laissées passer.", "Les retours sont explicites et exploitables." ], "risks": [ "Les appels supplémentaires augmentent la latence et les coûts.", "Un évaluateur peu performant fournit des retours trompeurs.", "Les boucles peuvent ne pas converger en l'absence de budget limite." ], "whenNot": [ "Lorsque les critères ne peuvent pas être définis clairement.", "Lorsqu'une seule passe est déjà amplement suffisante.", "Lorsque les budgets de latence ou de coût sont très serrés." ], "examples": [ "Générer du code, exécuter des tests et réviser jusqu'à ce qu'ils réussissent.", "Rédiger une traduction et l'affiner par rapport au texte source.", "Rédiger selon une grille d'évaluation avec un critique veillant au respect de chaque critère." ], "kpis": [ { "metric": "Taux d'acceptation", "note": "Part des propositions acceptées par l'évaluateur dès la première passe — un taux trop élevé signifie que la barre est placée trop bas, un taux trop bas indique un problème avec le générateur ou la grille d'évaluation." }, { "metric": "Itérations jusqu'à acceptation", "note": "Nombre moyen de boucles évaluation→révision avant acceptation ; une augmentation de ce nombre signale un générateur faible ou des critères vagues." }, { "metric": "Coût et latence par résultat accepté", "note": "Nombre total de tokens et temps réel écoulé sur l'ensemble des itérations de la boucle, et pas seulement lors de l'appel final — la boucle multipliant ces deux facteurs." }, { "metric": "Accord évaluateur-humain", "note": "Fréquence à laquelle le verdict de l'évaluateur correspond à celui d'un réviseur humain sur un ensemble échantillonné ; la boucle ne vaut que ce que vaut l'évaluateur." } ], "failureModes": [ "Détournement de récompense (reward hacking) : le générateur apprend à satisfaire la formulation de l'évaluateur plutôt que l'objectif réel.", "Évaluateur faible ou mal calibré : il accepte de mauvaises sorties ou rejette les bonnes, de sorte que la boucle ajoute du coût sans apporter de qualité.", "Boucles infinies ou oscillantes lorsqu'aucun candidat ne franchit le seuil — sans limite d'itérations, le coût est illimité.", "Dérive des critères : des grilles d'évaluation vagues ou changeantes rendent l'acceptation non déterministe et difficile à auditer." ], "lessons": [ "Limitez les itérations et définissez une solution de repli (renvoyer le meilleur résultat obtenu jusqu'à présent, ou escalader) afin que la boucle se termine toujours.", "Rendez les critères d'acceptation explicites et stables ; un évaluateur ne vaut que ce que vaut sa grille d'évaluation.", "Validez l'évaluateur par rapport au jugement humain avant de lui faire confiance comme filtre de validation.", "N'utilisez la boucle que là où la qualité justifie le coût multiplié — pas pour des sorties peu coûteuses et à faibles enjeux." ], "faqs": [ { "q": "En quoi cela diffère-t-il de la réflexion ?", "a": "La réflexion repose sur l'autocritique du même modèle. Le modèle évaluateur-optimisateur sépare les rôles : un évaluateur distinct juge le générateur, ce qui donne souvent des retours plus précis et moins biaisés." }, { "q": "L'évaluateur peut-il être déterministe ?", "a": "Oui. Pour du code, un exécuteur de tests est un évaluateur idéal ; pour une sortie structurée, une vérification de schéma convient. Utilisez un modèle comme juge pour des critères nuancés." }, { "q": "Combien d'itérations ?", "a": "Définissez un budget (par exemple, 2 à 3) et arrêtez-vous lorsque les critères sont respectés. Les boucles illimitées gaspillent du budget et peuvent ne pas converger." } ] }, "de": { "name": "Evaluator-Optimizer", "summary": "Ein LLM generiert eine Antwort, während ein zweites LLM diese anhand von Kriterien bewertet und Feedback zurückgibt; der Generator überarbeitet die Antwort und die Schleife wiederholt sich, bis die Bewertung erfolgreich ist. Dies steigert die Qualität bei Aufgaben mit klaren Bewertungskriterien auf Kosten zusätzlicher Aufrufe.", "problem": "Eine im ersten Durchlauf generierte Ausgabe erfüllt möglicherweise nicht alle Anforderungen, und es gibt keinen integrierten Mechanismus, um sie vor der Verwendung zu überprüfen und zu verbessern.", "context": "Verwenden Sie den Evaluator-Optimizer, wenn Sie klare Bewertungskriterien formulieren können und eine iterative Verfeinerung das Ergebnis messbar verbessert – beispielsweise bei der Übersetzungsqualität, bei Code, der Tests bestehen muss, oder beim Schreiben anhand eines Bewertungsbogens.", "solution": [ "Ein Generator erzeugt einen Kandidaten; ein Evaluator (ein separater LLM-Aufruf oder eine deterministische Prüfung) bewertet diesen anhand expliziter Kriterien und liefert umsetzbares Feedback. Der Generator überarbeitet den Entwurf, und der Zyklus wiederholt sich, bis die Kriterien erfüllt sind oder ein Budget erreicht ist.", "Die Trennung von Generierung und Bewertung spiegelt wider, wie ein menschlicher Autor von einem Lektor profitiert: Der Kritiker findet Probleme, die der Autor übersieht, und explizite Kriterien sorgen dafür, dass die Schleife konvergiert." ], "components": [ "Generator", "Evaluator (LLM-Judge oder Regelprüfung)", "Explizite Kriterien", "Überarbeitungsschleife", "Stoppbedingung / Budget" ], "benefits": [ "Höhere Qualität bei Aufgaben mit klaren Kriterien.", "Erfasst Fehler, die bei einem einzigen Durchlauf ausgeliefert würden.", "Feedback ist explizit und umsetzbar." ], "risks": [ "Zusätzliche Aufrufe erhöhen die Latenz und die Kosten.", "Ein schwacher Evaluator liefert irreführendes Feedback.", "Schleifen konvergieren möglicherweise nicht, wenn kein Budget festgelegt ist." ], "whenNot": [ "Wenn Kriterien nicht klar definiert werden können.", "Wenn ein einziger Durchlauf bereits gut genug ist.", "Wenn Latenz- oder Kostenbudgets sehr knapp bemessen sind." ], "examples": [ "Generieren von Code, Ausführen von Tests und Überarbeiten, bis diese bestanden werden.", "Entwerfen einer Übersetzung und Verfeinern im Abgleich mit der Quelle.", "Schreiben anhand eines Bewertungsbogens, wobei ein Kritiker jedes Kriterium durchsetzt." ], "kpis": [ { "metric": "Akzeptanzrate", "note": "Anteil der Kandidatenausgaben, die der Evaluator im ersten Durchlauf akzeptiert – ein zu hoher Wert bedeutet, dass die Messlatte zu niedrig liegt, ein zu niedriger Wert bedeutet, dass der Generator oder der Bewertungsbogen fehlerhaft ist." }, { "metric": "Iterationen bis zur Akzeptanz", "note": "Durchschnittliche evaluate→revise-Schleifen vor der Akzeptanz; steigende Zahlen weisen auf einen schwachen Generator oder vage Kriterien hin." }, { "metric": "Kosten und Latenz pro akzeptierter Ausgabe", "note": "Gesamtzahl der Token und reale Laufzeit über alle Schleifeniterationen hinweg, nicht nur für den finalen Aufruf – die Schleife multipliziert beides." }, { "metric": "Übereinstimmung zwischen Evaluator und Mensch", "note": "Wie oft das Urteil des Evaluators mit dem eines menschlichen Prüfers bei einer Stichprobe übereinstimmt; die Schleife ist nur so gut wie der Evaluator." } ], "failureModes": [ "Reward Hacking: Der Generator lernt, die Formulierung des Evaluators zu bedienen, anstatt das eigentliche Ziel zu erreichen.", "Schwacher oder falsch kalibrierter Evaluator: Er akzeptiert schlechte Ausgaben oder lehnt gute ab, sodass die Schleife Kosten verursacht, ohne die Qualität zu steigern.", "Unendliche oder oszillierende Schleifen, wenn kein Kandidat jemals die Hürde nimmt – ohne eine Iterationsbegrenzung sind die Kosten unbegrenzt.", "Kriteriendrift: Vage oder sich ändernde Bewertungsrichtlinien machen die Abnahme nicht-deterministisch und schwer überprüfbar." ], "lessons": [ "Begrenzen Sie die Iterationen und definieren Sie einen Fallback (das bisher beste Ergebnis zurückgeben oder eskalieren), damit die Schleife immer beendet wird.", "Machen Sie die Abnahkriterien explizit und stabil; ein Evaluator ist nur so gut wie seine Bewertungsrichtlinie.", "Validieren Sie den Evaluator anhand menschlicher Urteile, bevor Sie ihm als Kontrollinstanz vertrauen.", "Nutzen Sie die Schleife nur dort, wo die Qualität die multiplizierten Kosten rechtfertigt – nicht für günstige Ausgaben mit geringer Tragweite." ], "faqs": [ { "q": "Wie unterscheidet sich dies von Reflection?", "a": "Reflection nutzt die Selbstkritik desselben Modells. Evaluator-Optimizer trennt die Rollen: Ein separater Evaluator beurteilt den Generator, was oft präziseres und unvoreingenommeneres Feedback liefert." }, { "q": "Kann der Evaluator deterministisch sein?", "a": "Ja. Für Code ist ein Test-Runner ein idealer Evaluator; für strukturierten Output eignet sich eine Schema-Prüfung. Nutzen Sie ein Modell als Richter für nuancierte Kriterien." }, { "q": "Wie viele Iterationen?", "a": "Legen Sie ein Budget fest (z. B. 2–3) und stoppen Sie, sobald die Kriterien erfüllt sind. Unbegrenzte Schleifen verursachen unnötige Kosten und konvergieren möglicherweise nicht." } ] }, "ja": { "name": "エバリュエーター・オプティマイザー", "summary": "1つのLLMが応答を生成し、2つ目のLLMが基準に照らしてそれを評価してフィードバックを返します。生成器（ジェネレーター）が修正を行い、評価をクリアするまでループが繰り返されます。追加の呼び出しコストが発生する代わりに、明確な評価基準を持つタスクの品質を向上させます。", "problem": "1回の実行（シングルパス）による出力では要件を満たせない可能性があり、使用前にそれをチェックして改善するための組み込みメカニズムが存在しません。", "context": "明確な評価基準を定義でき、反復的な改善によって結果が測定可能に向上する場合（翻訳品質、テストに合格する必要があるコード、ルーブリックに沿った執筆など）に、エバリュエーター・オプティマイザーを使用します。", "solution": [ "生成器（ジェネレーター）が候補を作成し、評価器（エバリュエーター：別のLLM呼び出しまたは決定論的チェック）が明示的な基準に照らしてスコアを測定し、実行可能なフィードバックを返します。生成器が修正を行い、基準が満たされるか予算（上限）に達するまでサイクルが繰り返されます。", "生成と評価を分離することは、人間のライターが編集者から恩恵を受ける仕組みに似ています。批評家は著者が気づかない問題を捉え、明示的な基準によってループを収束へと導きます。" ], "components": [ "ジェネレーター", "エバリュエーター（LLMによる判定またはルールチェック）", "明示的な基準", "修正ループ", "停止条件 / 予算（上限）" ], "benefits": [ "明確な基準を持つタスクにおける品質の向上。", "1回の実行（シングルパス）では見逃されてリリースされてしまうエラーを検出。", "フィードバックが明示的かつ実行可能。" ], "risks": [ "追加の呼び出しにより、レイテンシーとコストが増加。", "性能の低いエバリュエーターが誤解を招くフィードバックを提供する。", "予算（上限）がないと、ループが収束しない可能性がある。" ], "whenNot": [ "基準を明確に定義できない場合。", "1回の実行（シングルパス）で十分に良好な結果が得られる場合。", "レイテンシーやコストの予算（上限）が非常に厳しい場合。" ], "examples": [ "コードを生成し、テストを実行し、合格するまで修正する。", "翻訳の下訳を作成し、原文に照らし合わせて洗練させる。", "批評家が各基準を強制するルーブリックに沿って執筆する。" ], "kpis": [ { "metric": "承認率", "note": "エバリュエーターが最初のパスで承認した候補出力の割合。高すぎる場合は基準が低すぎ、低すぎる場合はジェネレーターまたはルーブリックに問題があります。" }, { "metric": "承認までの反復回数", "note": "承認されるまでの平均的な「評価→修正」ループ回数。回数の増加は、ジェネレーターの性能不足または基準の曖昧さを示しています。" }, { "metric": "承認された出力あたりのコストとレイテンシー", "note": "最終的な呼び出しだけでなく、すべてのループ反復における総トークン数と実時間（ウォールクロック時間）。ループによって両方が乗算されます。" }, { "metric": "評価と人間の合致度", "note": "サンプルセットにおいて、評価器の判定が人間のレビュー担当者と一致する頻度。ループの品質は評価器の品質に依存します。" } ], "failureModes": [ "報酬ハッキング：生成器が本来の目標ではなく、評価器の文言を満たすように学習してしまうこと。", "脆弱または調整不足の評価器：不適切な出力を受け入れたり、適切な出力を拒否したりするため、品質が向上しないままループのコストだけが増加すること。", "無限ループまたは振動ループ：どの候補も基準をクリアできない場合、反復回数の上限を設定していないとコストが無限に膨らむこと。", "基準のドリフト：評価基準（ルーブリック）が曖昧または変動することで、承認プロセスが非決定論的になり、監査が困難になること。" ], "lessons": [ "反復回数に上限を設け、フォールバック（これまでの最善策を返す、またはエスカレーションする）を定義して、ループが必ず終了するようにします。", "承認基準を明確かつ安定したものにします。評価器の品質は、その評価基準（ルーブリック）の品質に依存します。", "評価器をゲートとして信頼する前に、人間の判断と照らし合わせて検証します。", "コストの倍増に見合う品質が求められる場合にのみループを使用し、低コストでリスクの低い出力には使用しません。" ], "faqs": [ { "q": "リフレクション（自己反省）とはどのように違うのですか？", "a": "リフレクションは、同一のモデルが自己批判を行います。評価器-最適化器（Evaluator-Optimizer）パターンでは役割を分離し、独立した評価器が生成器を判定するため、より鋭く偏りの少ないフィードバックが得られることが多くなります。" }, { "q": "評価器を決定論的にすることはできますか？", "a": "はい。コードの場合はテストランナーが理想的な評価器となり、構造化出力の場合はスキーマチェックが有効です。ニュアンスの伴う基準には、モデルによる判定（Model Judge）を使用します。" }, { "q": "反復回数は何回にすべきですか？", "a": "予算（例：2〜3回）を設定し、基準をクリアした時点で停止します。制限のないループはコストを浪費し、収束しない可能性があります。" } ] }, "zh": { "name": "评估器-优化器", "summary": "一个 LLM 生成响应，而第二个 LLM 根据标准对其进行评估并返回反馈；生成器进行修改，循环重复，直到评估通过。它以增加额外调用为代价，提高了具有明确评估标准的任务的质量。", "problem": "单次输出可能会遗漏要求，并且在使用之前没有内置机制来检查和改进它。", "context": "当您可以制定明确的评估标准，并且迭代优化能显著改善结果时（例如翻译质量、必须通过测试的代码或根据评分标准进行写作），请使用评估器-优化器。", "solution": [ "生成器产生一个候选结果；评估器（独立的 LLM 调用或确定性检查）根据明确的标准对其进行评分并返回可操作的反馈。生成器进行修改，循环往复，直到满足标准或达到预算上限。", "将生成与评估分离，类似于人类作者如何从编辑中受益：批评者发现作者遗漏的问题，而明确的标准使循环保持收敛。" ], "components": [ "生成器", "评估器（LLM 裁判或规则检查）", "明确的标准", "修改循环", "停止条件 / 预算" ], "benefits": [ "在具有明确标准的任务上获得更高的质量。", "捕获单次运行可能会漏过的错误。", "反馈明确且具有可操作性。" ], "risks": [ "额外的调用会增加延迟和成本。", "能力较弱的评估器会给出误导性的反馈。", "在没有预算限制的情况下，循环可能无法收敛。" ], "whenNot": [ "当无法明确定义标准时。", "当单次运行的结果已经足够好时。", "当延迟或成本预算非常紧张时。" ], "examples": [ "生成代码、运行测试并进行修改，直到测试通过。", "起草翻译并对照原文进行润色。", "根据评分标准进行写作，并由评审人员强制执行每项标准。" ], "kpis": [ { "metric": "采纳率", "note": "评估器在首轮通过中接受的候选输出比例 —— 比例过高意味着门槛太低，过低则意味着生成器或评分标准存在偏差。" }, { "metric": "达到接受所需的迭代次数", "note": "接受前平均经历的“评估→修改”循环次数；次数上升标志着生成器较弱或标准模糊。" }, { "metric": "每个被接受输出的成本与延迟", "note": "所有循环迭代中的总 token 数和实际消耗时间（Wall-clock time），而不仅仅是最终调用 —— 循环会使这两者成倍增加。" }, { "metric": "评估器与人工的一致性", "note": "评估器的判定在抽样集合中与人工评审员一致的频率；该循环的效果完全取决于评估器的质量。" } ], "failureModes": [ "奖励黑客行为（Reward hacking）：生成器学会了迎合评估器的措辞，而不是实现真正的目标。", "评估器较弱或校准不当：它接受了糟糕的输出或拒绝了优秀的输出，导致循环增加了成本却未能提升质量。", "当没有候选方案能够达标时，会出现无限循环或振荡循环——如果没有迭代上限，成本将是无底洞。", "标准漂移：模糊或不断变化的评估细则导致采纳结果具有不确定性，且难以审计。" ], "lessons": [ "限制迭代次数并定义回退方案（返回迄今为止的最佳结果，或进行升级上报），以确保循环始终能够终止。", "使准入标准明确且稳定；评估器的效果完全取决于其评估细则。", "在将评估器作为准入关卡予以信任之前，先对照人工判断对其进行验证。", "仅在质量提升能够证明成倍增加的成本是合理的情况下才使用该循环——不要用于廉价、低风险的输出。" ], "faqs": [ { "q": "这与自我反思（reflection）有什么不同？", "a": "自我反思是由同一个模型进行自我批判。评估器-优化器（Evaluator-optimizer）则分离了角色：由一个独立的评估器来评判生成器，这通常能提供更敏锐、更少偏见的反馈。" }, { "q": "评估器可以是确定性的吗？", "a": "可以。对于代码，测试运行器（test runner）是理想的评估器；对于结构化输出，Schema 检查非常有效。对于微妙复杂的标准，可以使用模型作为裁判。" }, { "q": "需要迭代多少次？", "a": "设定一个预算（例如 2-3 次），并在标准通过时停止。无限制的循环会浪费成本，且可能无法收敛。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/goal-decomposition", "api_url": "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." } ] }, "fr": { "name": "Décomposition d'objectifs", "summary": "La décomposition d'objectifs consiste à faire en sorte qu'un agent décompose un objectif de haut niveau en un ensemble ordonné de sous-tâches plus petites et gérables — un plan — avant d'agir, puis exécute et surveille ce plan, en replanifiant lorsque des étapes échouent. Le plan explicite devient un artefact inspectable que vous pouvez examiner, valider et déboguer. Utilisez cette approche lorsqu'un objectif nécessite plusieurs étapes dépendantes et que les agents réactifs, qui avancent étape par étape, s'égarent ou bloquent ; évitez-la pour les tâches simples et ponctuelles.", "problem": "Un simple appel de LLM confronté à un objectif large et multi-étapes a tendance à improviser. Les agents réactifs qui choisissent une action à la fois peuvent perdre le fil sur de longs horizons : ils répètent des tâches, ignorent des prérequis ou s'engagent dans des impasses sans réaliser que l'objectif global est désormais inatteignable. Comme aucun plan n'existe sous forme d'artefact, vous ne pouvez pas examiner les étapes prévues avant leur exécution, vous ne pouvez pas savoir si un échec provient d'une mauvaise stratégie ou d'une mauvaise exécution, et vous ne pouvez pas facilement reprendre après une interruption. Le raisonnement de l'agent est implicite, transitoire et difficile à auditer.", "context": "Ce modèle convient aux objectifs qui se décomposent en plusieurs étapes interdépendantes avec un ordre logique — rechercher puis synthétiser, migrer puis vérifier, collecter puis rapprocher puis rapporter. Il suppose que le modèle peut produire un plan raisonnable à partir de l'objectif et des outils disponibles, et que les étapes sont suffisamment observables pour détecter un échec. Il est particulièrement précieux lorsque les étapes sont coûteuses, ont des effets secondaires ou sont difficiles à annuler, de sorte que l'examen du plan avant l'exécution est rentable. Il est peu adapté lorsque l'action suivante est évidente à partir de l'état actuel, ou lorsque l'environnement change si rapidement que tout plan initial devient obsolète avant la deuxième étape.", "solution": [ "Divisez l'agent en une phase de planification et une phase d'exécution. Le planificateur lit l'objectif, les outils disponibles et l'état actuel, puis émet un plan explicite et ordonné : une liste (ou un graphe) de sous-tâches avec leurs dépendances et les résultats attendus. Traiter le plan comme un artefact de premier ordre est l'idée centrale — il peut être consigné, présenté à un humain pour approbation, évalué par rapport à des règles et comparé d'une exécution à l'autre. Encodez explicitement les dépendances afin que les sous-tâches indépendantes puissent s'exécuter en parallèle et que les tâches dépendantes attendent leurs entrées, plutôt que d'imposer une séquence linéaire fragile inventée par le modèle.", "Un exécuteur déroule ensuite le plan étape par étape, en transmettant le résultat de chaque étape à la suivante et en le vérifiant par rapport au résultat attendu. Lorsqu'une étape échoue, renvoie un résultat inutilisable ou invalide une hypothèse en aval, redonnez le contrôle au planificateur pour qu'il replanifie à partir de l'état actuel au lieu de continuer aveuglément — cette boucle fermée est ce qui distingue la décomposition robuste de la planification ponctuelle (one-shot). Gardez les plans aussi simples que l'objectif le permet : préférez quelques étapes bien choisies à un arbre profond, limitez la replanification avec un budget pour éviter que l'agent ne boucle indéfiniment, et permettez aux objectifs triviaux de contourner complètement la planification." ], "components": [ "Planificateur qui émet un plan ordonné et sensible aux dépendances", "Représentation du plan (liste ou graphe de tâches) sous forme d'artefact inspectable", "Exécuteur qui lance les étapes et transmet les résultats", "Vérification à chaque étape par rapport aux résultats attendus", "Déclencheur de replanification et boucle avec un budget d'étapes/itérations", "Étape d'approbation humaine optionnelle avant l'exécution" ], "benefits": [ "Les objectifs à long terme restent cohérents car les étapes prévues sont décidées à l'avance, et non improvisées une par une.", "Le plan explicite est inspectable : il peut être examiné, approuvé, audité et comparé avant l'exécution de tout effet secondaire.", "Les échecs sont plus faciles à localiser — un mauvais plan se distingue d'une mauvaise exécution d'étape.", "Les sous-tâches indépendantes permettent le parallélisme et permettent de reprendre le travail à partir de la dernière étape terminée après une interruption." ], "risks": [ "Une décomposition initiale défectueuse se propage : chaque étape en aval hérite d'une hypothèse erronée ou d'un prérequis manquant.", "La sur-planification ajoute de la latence et des coûts pour des objectifs simples qu'un agent réactif résoudrait en une seule étape.", "Les plans deviennent obsolètes dans des environnements qui changent rapidement, ce qui conduit à exécuter une étape basée sur un état du monde dépassé.", "Boucles de replanification illimitées où l'agent réécrit sans cesse le plan sans faire de progrès réels." ], "whenNot": [ "L'action suivante est évidente à partir de l'état actuel et une seule étape réactive suffit à résoudre l'objectif.", "L'environnement change plus vite que la durée de validité d'un plan, ce qui rend obsolète toute séquence définie à l'avance.", "Les étapes sont peu coûteuses, réversibles et indépendantes, de sorte que la surcharge liée à la planification l'emporte sur ses avantages." ], "examples": [ "Un assistant de recherche planifie la collecte de sources, l'extraction d'affirmations, la vérification croisée, puis la synthèse, en exécutant la collecte de sources en parallèle avant l'étape de synthèse dépendante.", "Un agent de migration de code planifie l'inventaire des utilisations, la transformation des fichiers, l'exécution des tests, puis replanifie l'étape de transformation lorsque l'étape de test révèle un cas limite non pris en compte.", "Un agent de rapprochement de données décompose un objectif de « clôture des comptes » en : extraction des grands livres, normalisation, appariement des écritures et signalement des exceptions, l'appariement étant conditionné par la réussite de la normalisation." ], "kpis": [ { "metric": "Taux de réussite des objectifs", "note": "Part des objectifs entièrement atteints de bout en bout ; un bon résultat se traduit par une décomposition surpassant une référence réactive sur les mêmes tâches multi-étapes." }, { "metric": "Fréquence de replanification", "note": "Fréquence à laquelle une exécution déclenche une replanification ; une plage saine signifie que la boucle détecte les échecs réels sans s'emballer à chaque étape." }, { "metric": "Nombre d'étapes par objectif par rapport au minimum", "note": "Longueur du plan par rapport à un minimum raisonnable ; surveillez la sur-planification qui gonfle le nombre d'étapes pour des objectifs simples." }, { "metric": "Taux d'approbation des plans", "note": "Fraction de plans acceptés par les réviseurs ou les contrôles de conformité avant exécution ; des taux faibles signalent une décomposition systématiquement faible." } ], "failureModes": [ "Une mauvaise décomposition se propage : une hypothèse initiale erronée corrompt chaque étape dépendante en aval.", "Boucle de replanification : l'agent réécrit le plan de manière répétée sans converger ni progresser.", "Exécution d'un plan obsolète : une étape s'exécute par rapport à un état du monde qui a changé depuis l'élaboration du plan.", "Sur-décomposition : un objectif trivial est divisé en étapes inutiles, ce qui ajoute de la latence, des coûts et de la surface d'échec." ], "lessons": [ "Faites du plan un véritable artefact — consignez-le, affichez-le, comparez-le — afin que les échecs soient déboguables plutôt que mystérieux.", "Bouclez toujours la boucle : détectez l'échec d'une étape et replanifiez à partir de l'état actuel au lieu de continuer aveuglément.", "Limitez à la fois la profondeur du plan et la replanification avec des budgets explicites pour éviter que des objectifs simples ne partent en spirale.", "Permettez aux objectifs triviaux de contourner le planificateur ; réservez la décomposition aux travaux véritablement multi-étapes et dépendants." ], "faqs": [ { "q": "En quoi cela diffère-t-il d'un agent réactif de style ReAct ?", "a": "Un agent réactif décide d'une action à la fois à partir de l'état actuel, sans plan sous forme d'artefact. La décomposition d'objectifs s'engage à l'avance sur un plan ordonné, rendant les étapes prévues inspectables et l'ordre des dépendances explicite. En pratique, les deux sont souvent combinés : planifier d'abord, puis exécuter de manière réactive au sein de chaque étape et replanifier lorsqu'une étape échoue." }, { "q": "Que se passe-t-il lorsqu'une étape échoue au milieu du plan ?", "a": "Redonnez le contrôle au planificateur pour qu'il replanifie à partir de l'état actuel plutôt que de continuer aveuglément. La boucle fermée de replanification est ce qui rend la décomposition robuste. Limitez-la avec un budget afin qu'une étape en échec persistant ne puisse pas déclencher des réécritures infinies sans progrès." }, { "q": "Quand la planification nuit-elle plus qu'elle n'aide ?", "a": "Pour des objectifs simples et en une seule étape où l'action suivante est évidente, ou dans des environnements qui changent plus vite que la validité d'un plan. Dans ces cas, la planification préalable ajoute de la latence et un risque de plan obsolète. Détectez les objectifs triviaux et laissez-les contourner le planificateur, en réservant la décomposition aux tâches véritablement multi-étapes et interdépendantes." } ] }, "de": { "name": "Goal Decomposition", "summary": "Bei der Goal Decomposition zerlegt ein Agent ein übergeordnetes Ziel vor dem Handeln in eine geordnete Reihe kleinerer, handhabbarer Teilaufgaben – einen Plan –, führt diesen Plan aus, überwacht ihn und plant neu, wenn Schritte fehlschlagen. Der explizite Plan wird zu einem überprüfbaren Artefakt, das Sie reviewen, steuern und debuggen können. Nutzen Sie dieses Pattern, wenn ein Ziel mehrere voneinander abhängige Schritte erfordert und reaktive, schrittweise agierende Agenten abweichen oder ins Stocken geraten; überspringen Sie es bei einfachen Single-Shot-Aufgaben.", "problem": "Ein einzelner LLM-Aufruf, dem ein umfassendes, mehrstufiges Ziel übergeben wird, neigt zum Improvisieren. Reaktive Agenten, die jeweils nur eine Aktion auswählen, können bei langen Zeithorizonten den Faden verlieren: Sie wiederholen Arbeitsschritte, überspringen Voraussetzungen oder laufen in eine Sackgasse, ohne zu merken, dass das Gesamtziel mittlerweile unerreichbar ist. Da kein Plan als Artefakt existiert, können Sie die beabsichtigten Schritte vor ihrer Ausführung nicht überprüfen, nicht feststellen, ob ein Fehler auf eine schlechte Strategie oder eine fehlerhafte Ausführung zurückzuführen ist, und nach einer Unterbrechung nicht einfach fortfahren. Die Argumentation des Agenten ist implizit, flüchtig und schwer zu auditieren.", "context": "Dieses Pattern eignet sich für Ziele, die sich in mehrere voneinander abhängige Schritte mit einer sinnvollen Reihenfolge zerlegen lassen – z. B. erst recherchieren, dann synthetisieren; erst migrieren, dann verifizieren; erst erfassen, dann abgleichen, dann berichten. Es setzt voraus, dass das Modell aus dem Ziel und den verfügbaren Tools einen vernünftigen Plan erstellen kann und dass die Schritte ausreichend beobachtbar sind, um Fehler zu erkennen. Es ist besonders wertvoll, wenn Schritte kostspielig sind, Nebenwirkungen haben oder schwer rückgängig zu machen sind, sodass sich eine Überprüfung des Plans vor der Ausführung auszahlt. Es ist ungeeignet, wenn die nächste Aktion aus dem aktuellen Zustand offensichtlich ist oder wenn sich die Umgebung so schnell ändert, dass jeder im Voraus erstellte Plan bereits vor dem zweiten Schritt veraltet ist.", "solution": [ "Teilen Sie den Agenten in eine Planungsphase und eine Ausführungsphase auf. Der Planer liest das Ziel, die verfügbaren Tools sowie den aktuellen Zustand und gibt einen expliziten, geordneten Plan aus: eine Liste (oder einen Graphen) von Teilaufgaben mit ihren Abhängigkeiten und erwarteten Ergebnissen. Den Plan als First-Class-Artefakt zu behandeln, ist die Kernidee – er kann protokolliert, einem Menschen zur Genehmigung vorgelegt, mit Richtlinien abgeglichen und über verschiedene Durchläufe hinweg verglichen (diffed) werden. Codieren Sie Abhängigkeiten explizit, sodass unabhängige Teilaufgaben parallel ausgeführt werden können und abhängige auf ihre Eingaben warten, anstatt eine fragile lineare Sequenz zu erzwingen, die das Modell erfunden hat.", "Ein Executor führt den Plan anschließend Schritt für Schritt aus, leitet das Ergebnis jedes Schritts weiter und gleicht es mit der erwarteten Ausgabe des Schritts ab. Wenn ein Schritt fehlschlägt, ein unbrauchbares Ergebnis liefert oder eine nachgelagerte Annahme entkräftet, übergeben Sie die Kontrolle wieder an den Planer, um ausgehend vom aktuellen Zustand neu zu planen, anstatt blind fortzufahren – dieser geschlossene Regelkreis unterscheidet eine robuste Dekomposition von einer einmaligen Planung (One-Shot Planning). Halten Sie Pläne so flach, wie es das Ziel erlaubt: Bevorzugen Sie wenige, gut gewählte Schritte gegenüber einem tiefen Baum, begrenzen Sie die Neuplanung durch ein Budget, damit der Agent nicht in Endlosschleifen gerät, und lassen Sie triviale Ziele die Planung komplett umgehen." ], "components": [ "Planer, der einen geordneten, abhängigkeitsbewussten Plan ausgibt", "Plandarstellung (Aufgabenliste oder Aufgabengraph) als überprüfbares Artefakt", "Executor, der Schritte ausführt und Ergebnisse weiterleitet", "Schrittweise Verifizierung anhand der erwarteten Ausgaben", "Trigger für Neuplanung und Schleife mit einem Schritt-/Iterationsbudget", "Optionaler Freigabeschritt durch einen Menschen vor der Ausführung" ], "benefits": [ "Ziele mit langem Zeithorizont bleiben kohärent, da die beabsichtigten Schritte im Voraus festgelegt und nicht einzeln improvisiert werden.", "Der explizite Plan ist überprüfbar: Er kann gereviewt, genehmigt, auditiert und verglichen werden, bevor Nebenwirkungen auftreten.", "Fehler lassen sich leichter lokalisieren – ein schlechter Plan lässt sich von einer fehlerhaften Ausführung eines Schritts unterscheiden.", "Unabhängige Teilaufgaben ermöglichen Parallelisierung und erlauben es, die Arbeit nach einer Unterbrechung ab dem zuletzt abgeschlossenen Schritt wieder aufzunehmen." ], "risks": [ "Eine fehlerhafte anfängliche Dekomposition pflanzt sich fort: Jeder nachfolgende Schritt übernimmt eine falsche Annahme oder eine fehlende Voraussetzung.", "Übermäßige Planung (Over-Planning) erhöht die Latenz und die Kosten bei einfachen Zielen, die ein reaktiver Agent in einem einzigen Schritt erledigen würde.", "Pläne veralten in sich schnell verändernden Umgebungen, sodass ein Schritt auf Basis eines veralteten Weltzustands ausgeführt wird.", "Unbegrenzte Neuplanungsschleifen, in denen der Agent den Plan wiederholt umschreibt, ohne echten Fortschritt zu erzielen." ], "whenNot": [ "Die nächste Aktion ist aus dem aktuellen Zustand offensichtlich und ein einzelner reaktiver Schritt löst das Ziel.", "Die Umgebung ändert sich schneller, als ein Plan gültig bleibt, wodurch jede im Voraus geplante Sequenz veraltet.", "Schritte sind kostengünstig, umkehrbar und unabhängig, sodass der Planungsaufwand den Nutzen übersteigt." ], "examples": [ "Ein Forschungsassistent plant die Schritte Quellen-sammeln, Behauptungen-extrahieren, Gegenprüfung und anschließende Synthese, wobei die Quellensammlung parallel vor dem abhängigen Syntheseschritt ausgeführt wird.", "Ein Code-Migrations-Agent plant die Schritte Verwendungen-inventarisieren, Dateien-transformieren, Tests-ausführen und plant den Transformationsschritt neu, wenn der Testschritt einen übersehenen Sonderfall aufdeckt.", "Ein Datenabgleichs-Agent zerlegt das Ziel 'Bücher schließen' in Hauptbücher-abrufen, Normalisieren, Einträge-abgleichen und Ausnahmen-kennzeichnen, wobei der Abgleich erst nach erfolgreicher Normalisierung erfolgt." ], "kpis": [ { "metric": "Zielerreichungsquote", "note": "Anteil der vollständig erreichten End-to-End-Ziele; ein gutes Ergebnis zeigt sich darin, dass die Dekomposition eine reaktive Baseline bei denselben mehrstufigen Aufgaben übertrifft." }, { "metric": "Neuplanungshäufigkeit", "note": "Wie oft ein Durchlauf eine Neuplanung auslöst; ein gesunder Bereich bedeutet, dass die Schleife echte Fehler abfängt, ohne bei jedem Schritt ins Stocken zu geraten." }, { "metric": "Schritte pro Ziel im Vergleich zum Minimum", "note": "Planlänge im Verhältnis zu einem sinnvollen Minimum; achten Sie auf Over-Planning, das die Anzahl der Schritte bei einfachen Zielen unnötig aufbläht." }, { "metric": "Freigabequote für Pläne", "note": "Anteil der Pläne, die vor der Ausführung von Reviewern oder Richtlinienprüfungen akzeptiert werden; niedrige Quoten weisen auf eine systematisch schwache Dekomposition hin." } ], "failureModes": [ "Fehlerhafte Dekomposition pflanzt sich fort: Eine falsche frühe Annahme beeinträchtigt jeden nachfolgenden abhängigen Schritt.", "Neuplanungsschleife: Der Agent schreibt den Plan wiederholt um, ohne zu konvergieren oder Fortschritte zu erzielen.", "Ausführung eines veralteten Plans: Ein Schritt wird auf Basis eines Weltzustands ausgeführt, der sich seit der Erstellung des Plans geändert hat.", "Über-Dekomposition: Ein triviales Ziel wird in unnötige Schritte zerlegt, was Latenz, Kosten und die Fehleranfälligkeit erhöht." ], "lessons": [ "Machen Sie den Plan zu einem echten Artefakt – protokollieren Sie ihn, zeigen Sie ihn an, vergleichen Sie ihn –, damit Fehler debuggbar und nicht rätselhaft sind.", "Schließen Sie immer den Regelkreis: Erkennen Sie das Fehlschlagen von Schritten und planen Sie ausgehend vom aktuellen Zustand neu, anstatt blind fortzufahren.", "Begrenzen Sie sowohl die Plantiefe als auch die Neuplanung durch explizite Budgets, um zu verhindern, dass einfache Ziele aus dem Ruder laufen.", "Lassen Sie triviale Ziele den Planer umgehen; reservieren Sie die Dekomposition für wirklich mehrstufige, voneinander abhängige Aufgaben." ], "faqs": [ { "q": "Wie unterscheidet sich dies von einem reaktiven Agenten im ReAct-Stil?", "a": "Ein reaktiver Agent entscheidet jeweils eine Aktion auf Basis des aktuellen Zustands, ohne einen Plan als Artefakt zu haben. Goal Decomposition legt im Voraus einen geordneten Plan fest, wodurch die beabsichtigten Schritte überprüfbar und die Abhängigkeiten explizit werden. In der Praxis werden beide Ansätze oft kombiniert: Zuerst wird geplant, dann wird innerhalb jedes Schritts reaktiv ausgeführt und bei einem Fehlschlag neu geplant." }, { "q": "Was passiert, wenn ein Schritt mitten im Plan fehlschlägt?", "a": "Übergeben Sie die Kontrolle wieder an den Planer, um ausgehend vom aktuellen Zustand neu zu planen, anstatt blind fortzufahren. Der geschlossene Regelkreis der Neuplanung macht die Dekomposition robust. Begrenzen Sie diesen durch ein Budget, damit ein dauerhaft fehlschlagender Schritt keine endlosen Umschreibungen ohne Fortschritt auslöst." }, { "q": "Wann schadet die Planung mehr, als sie nützt?", "a": "Bei einfachen, einstufigen Zielen, bei denen die nächste Aktion offensichtlich ist, oder in Umgebungen, die sich schneller ändern, als ein Plan gültig bleibt. Dort führt eine Vorabplanung zu zusätzlicher Latenz und dem Risiko veralteter Pläne. Erkennen Sie triviale Ziele und lassen Sie diese den Planer umgehen, während Sie die Dekomposition für echte mehrstufige, voneinander abhängige Aufgaben reservieren." } ] }, "ja": { "name": "ゴール分解（Goal Decomposition）", "summary": "ゴール分解（Goal Decomposition）では、エージェントが行動を起こす前に、高レベルのゴールを処理可能な小さなサブタスクの順序付きセット（計画）に分解します。その後、その計画を実行および監視し、ステップが失敗した場合には再計画を行います。明示的な計画は、レビュー、ゲート制御、デバッグが可能な「検査可能なアーティファクト」になります。このパターンは、ゴールに複数の依存ステップが必要であり、その場しのぎで一歩ずつ進むリアクティブなエージェントでは方向性を見失ったり失速したりする場合に使用します。単純なワンショットのタスクではスキップしてください。", "problem": "広範で複数ステップにわたるゴールを1回のLLM呼び出しに委ねると、その場しのぎの対応になりがちです。一度に1つのアクションを選択するリアクティブなエージェントは、長期的な展望において文脈を見失う傾向があります。同じ作業を繰り返したり、前提条件をスキップしたり、全体の目標がすでに達成不可能になっていることに気づかずに袋小路に入り込んだりします。計画がアーティファクトとして存在しないため、実行前に予定されているステップをレビューできず、失敗の原因が戦略の誤りなのか実行の誤りなのかを判断することもできず、中断後に簡単に再開することもできません。エージェントの推論は暗黙的かつ一時的であり、監査が困難です。", "context": "このパターンは、意味のある順序を持つ、相互に依存する複数のステップに分解できるゴール（「調査してから統合する」、「移行してから検証する」、「収集してから照合し、報告する」など）に適しています。モデルがゴールと利用可能なツールから妥当な計画を作成でき、各ステップが失敗を検知できるほど十分に観察可能であることを前提としています。ステップのコストが高く、副作用があり、または取り消しが困難な場合に最も価値を発揮し、実行前に計画をレビューするメリットが大きくなります。現在の状態から次のアクションが明白である場合や、環境の変化が非常に速く、事前に立てた計画が2番目のステップに進む前に陳腐化してしまう場合には適していません。", "solution": [ "エージェントを計画フェーズと実行フェーズに分割します。プランナーはゴール、利用可能なツール、および現在の状態を読み取り、明示的で順序付けられた計画（依存関係と期待される出力を伴うサブタスクのリストまたはグラフ）を出力します。計画を第一級のアーティファクトとして扱うことが核心的なアイデアです。これにより、ログへの記録、人間による承認のための提示、ポリシーに照らしたスコアリング、実行間での差分（diff）比較が可能になります。モデルが考案した脆弱な線形シーケンスを強制するのではなく、依存関係を明示的にエンコードすることで、独立したサブタスクを並行して実行し、依存関係のあるサブタスクは入力が揃うまで待機できるようにします。", "次に、エグゼキューターが計画をステップバイステップで実行し、各ステップの結果を次のステップに送りながら、そのステップの期待される出力と照合します。ステップが失敗したとき、使用不可能な結果を返したとき、または下流の前提条件を無効にしたときは、盲目的に実行を続けるのではなく、制御をプランナーに戻して現在の状態から再計画を行います。このクローズドループこそが、堅牢な分解とワンショットの計画を分ける要素です。計画はゴールが許す限り浅く保ちます。深いツリー構造よりも、厳選された少数のステップを優先し、エージェントが無限ループに陥らないよう予算（バジェット）で再計画を制限し、些細なゴールは計画プロセスを完全にバイパスできるようにします。" ], "components": [ "依存関係を認識した順序付きの計画を出力するプランナー", "検査可能なアーティファクトとしての計画表現（タスクリストまたはタスクグラフ）", "ステップを実行し、結果を転送するエグゼキューター", "期待される出力に対するステップごとの検証", "ステップ/反復の予算制限を伴う再計画トリガーおよびループ", "実行前のオプションの人による承認ゲート" ], "benefits": [ "予定されているステップがその場しのぎで一つずつ決定されるのではなく、事前に決定されるため、長期的なゴールの一貫性が維持されます。", "明示的な計画は検査可能です。副作用が発生する前に、レビュー、承認、監査、および差分比較を行うことができます。", "失敗箇所の特定が容易になります。不適切な計画と、不適切なステップ実行を区別できます。", "独立したサブタスクにより並行処理が可能になり、中断が発生した場合でも最後に完了したステップから作業を再開できます。" ], "risks": [ "初期段階の分解に欠陥があるとそれが伝播します。下流のすべてのステップが、誤った前提条件や欠落した前提条件を引き継ぐことになります。", "過剰な計画（オーバープランニング）は、リアクティブなエージェントなら1ステップで完了できるような単純なゴールにおいて、遅延とコストを増加させます。", "変化の速い環境では計画が陳腐化し、古い世界の状態に基づいたままステップが実行されてしまう可能性があります。", "エージェントが実際の進捗を生まないまま計画を繰り返し書き換える、制限のない再計画ループが発生するリスクがあります。" ], "whenNot": [ "現在の状態から次のアクションが明白であり、単一のリアクティブなステップでゴールを解決できる場合。", "計画の有効性が維持されるよりも早く環境が変化し、事前のシーケンスが陳腐化してしまう場合。", "ステップが低コストで、取り消し可能であり、かつ独立しているため、計画に伴うオーバーヘッドがそのメリットを上回る場合。" ], "examples": [ "リサーチアシスタントが「情報源の収集」、「主張の抽出」、「クロスチェック」、「統合」を計画し、依存関係のある統合ステップの前に、情報源の収集を並行して実行します。", "コード移行エージェントが「使用状況のインベントリ作成」、「ファイルの変換」、「テストの実行」を計画し、テストステップで見落とされていたエッジケースが明らかになった際に、変換ステップを再計画します。", "データ照合エージェントが「決算」というゴールを「元帳の取得」、「正規化」、「エントリーの照合」、「例外のフラグ立て」に分解し、正規化の成功を条件として照合を実行します。" ], "kpis": [ { "metric": "ゴール達成率", "note": "エンドツーエンドで完全に達成されたゴールの割合。同じ複数ステップのタスクにおいて、ゴール分解がリアクティブなベースラインを上回っている状態が良好とみなされます。" }, { "metric": "再計画の頻度", "note": "実行時に再計画がトリガーされる頻度。健全な範囲とは、すべてのステップで混乱（スラッシング）することなく、ループが実際の失敗を捉えている状態を指します。" }, { "metric": "ゴールあたりのステップ数と最小ステップ数の比較", "note": "妥当な最小値に対する計画の長さ。単純なゴールにおいてステップ数を膨らませてしまう過剰な計画（オーバープランニング）に注意してください。" }, { "metric": "計画承認の合格率", "note": "実行前にレビュー担当者またはポリシーチェックによって承認された計画の割合。合格率が低い場合は、システム的に分解の精度が低いことを示しています。" } ], "failureModes": [ "不適切な分解の伝播：初期段階の誤った前提条件が、下流のすべての依存ステップを損なうこと。", "再計画ループ：エージェントが収束や進捗を得られないまま、計画を繰り返し書き換えること。", "陳腐化した計画の実行：計画作成後に変化した世界の状態に対してステップが実行されること。", "過剰な分解：些細なゴールが必要のないステップに分割され、遅延、コスト、および障害発生領域が増加すること。" ], "lessons": [ "計画を実際のアーティファクト（ログへの記録、表示、差分比較など）にすることで、失敗の原因を不可解なものにせず、デバッグ可能にします。", "常にループを閉じます。盲目的に継続するのではなく、ステップの失敗を検知し、現在の状態から再計画を行います。", "浅いゴールがスパイラルに陥るのを防ぐため、計画の深さと再計画の両方に明示的な予算（バジェット）を設定して制限します。", "些細なゴールはプランナーをスキップできるようにします。分解は、真に複数ステップに及び、依存関係のある作業に限定して使用します。" ], "faqs": [ { "q": "リアクティブなReActスタイルのエージェントとはどのように違うのですか？", "a": "リアクティブなエージェントは、計画をアーティファクトとして持たず、現在の状態から一度に1つのアクションを決定します。ゴール分解（Goal Decomposition）では、事前に順序付けられた計画を確定させるため、予定されているステップが検査可能になり、依存関係の順序が明示的になります。実際には、これら2つは組み合わせて使用されることが多く、最初に計画を立て、各ステップ内ではリアクティブに実行し、ステップが失敗したときに再計画を行います。" }, { "q": "計画の途中でステップが失敗した場合はどうなりますか？", "a": "盲目的に継続するのではなく、制御をプランナーに戻して現在の状態から再計画を行います。このクローズドな再計画ループこそが、分解を堅牢にする要素です。継続的に失敗するステップが進捗のないまま無限に書き換えをトリガーしないよう、予算（バジェット）を設定して制限してください。" }, { "q": "計画を立てることが、メリットよりもデメリットをもたらすのはどのような場合ですか？", "a": "次のアクションが明白な、単純な単一ステップのゴールや、計画の有効性が維持されるよりも早く変化する環境においてです。そのようなケースでは、事前の計画立案はレイテンシーを増大させ、計画が陳腐化するリスクを生みます。些細なゴールを検出し、プランナーをバイパスさせるようにして、分解（Decomposition）は真に複数ステップで依存関係のある作業にのみ残しておきます。" } ] }, "zh": { "name": "目标分解", "summary": "目标分解让智能体在行动之前，将高层目标拆分为一组有序的、易于处理的子任务（即计划），然后执行并监控该计划，在步骤失败时重新规划。显式计划会成为一个可检查的产物，供您进行评审、把关和调试。当目标需要多个相互依赖的步骤，且反应式、逐步执行的智能体容易偏离方向或停滞不前时，请使用此模式；对于简单的单次任务，请跳过此模式。", "problem": "当单个 LLM 调用被赋予一个宽泛的多步骤目标时，往往会即兴发挥。一次只选择一个动作的反应式智能体在面对长周期任务时可能会迷失方向：它们会重复工作、遗漏前提条件，或者在没有意识到整体目标已无法实现的情况下陷入死胡同。由于没有作为产物的计划存在，您无法在运行前评审预期的步骤，无法判断失败是源于糟糕的策略还是糟糕的执行，也无法在中断后轻松恢复。智能体的推理是隐式的、瞬态的，且难以审计。", "context": "此模式适用于可分解为多个具有明确顺序且相互依赖的步骤的目标——例如“先研究后综合”、“先迁移后验证”、“先收集后对账再报告”。它假设模型能够根据目标和可用工具制定出合理的计划，并且步骤具有足够的可见性以检测失败。在步骤成本高昂、会产生副作用或难以撤销的情况下，此模式最具价值，因为在执行前评审计划是值得的。如果根据当前状态下一步行动显而易见，或者环境变化极快以至于任何预先制定的计划在执行第二步之前就已经过时，则不适合使用此模式。", "solution": [ "将智能体拆分为规划阶段和执行阶段。规划器读取目标、可用工具和当前状态，并输出一个显式的、有序的计划：包含子任务及其依赖关系和预期输出的列表（或图）。将计划视为一等公民（first-class artifact）是核心思想——它可以被记录、展示给人工审批、根据策略进行评分，以及在不同运行之间进行差异对比（diff）。显式地对依赖关系进行编码，以便独立的子任务可以并行运行，而有依赖关系的子任务则等待其输入，而不是强行采用模型凭空捏造的脆弱线性顺序。", "然后，执行器逐步运行计划，将每一步的结果向前传递，并对照该步骤的预期输出进行检查。当某个步骤失败、返回不可用的内容或使下游假设失效时，将控制权交回给规划器，以便从当前状态重新规划，而不是盲目继续——这种闭环正是将鲁棒的分解与单次规划区分开来的关键。保持计划在目标允许的范围内尽可能浅显：相比于深层树状结构，更倾向于少数精心选择的步骤；通过预算限制重新规划，以防止智能体陷入无限循环；并允许简单的目标完全绕过规划。" ], "components": [ "输出有序且感知依赖关系的计划的规划器", "作为可检查产物的计划表示（任务列表或任务图）", "运行步骤并转发结果的执行器", "对照预期输出进行逐步验证", "带有步骤/迭代预算的重新规划触发器和循环", "执行前可选的人工审批关卡" ], "benefits": [ "长周期目标能够保持连贯性，因为预期的步骤是预先决定的，而不是一次一个即兴发挥。", "显式计划是可检查的：在产生任何副作用之前，可以对其进行评审、批准、审计和差异对比。", "失败更容易定位——糟糕的计划与糟糕的步骤执行是可以区分开来的。", "独立的子任务展现了并行性，并允许在中断后从上一个已完成的步骤恢复工作。" ], "risks": [ "有缺陷的初始分解会产生连锁反应：每一个下游步骤都会继承错误的假设或缺失的前提条件。", "过度规划会增加简单目标的延迟和成本，而反应式智能体本可以在一步内完成这些目标。", "在快速变化的环境中，计划会过时，导致执行步骤时仍基于陈旧的世界状态。", "无限制的重新规划循环，即智能体反复重写计划而没有取得实质性进展。" ], "whenNot": [ "根据当前状态，下一步行动显而易见，且单个反应式步骤即可解决目标。", "环境变化的速度快于计划保持有效的时间，导致任何预先制定的顺序都会过时。", "步骤成本低廉、可逆且相互独立，因此规划的开销超过了其带来的收益。" ], "examples": [ "研究助手规划“收集来源”、“提取主张”、“交叉核对”然后“综合”，在依赖综合的步骤之前并行运行来源收集。", "代码迁移智能体规划“盘点使用情况”、“转换文件”、“运行测试”，并在测试步骤暴露遗漏的边缘情况时，重新规划转换步骤。", "数据对账智能体将“结账”目标分解为“拉取账簿”、“归一化”、“匹配条目”和“标记异常”，其中匹配步骤以成功归一化为前提。" ], "kpis": [ { "metric": "目标完成率", "note": "端到端完全实现的目标比例；优秀的表现意味着在相同的多步骤任务中，分解模式的效果超越了反应式基线。" }, { "metric": "重新规划频率", "note": "一次运行触发重新规划的频率；健康的区间意味着循环能够捕获真正的失败，而不会在每一步都发生剧烈震荡。" }, { "metric": "每个目标的步骤数与最小步骤数对比", "note": "计划长度相对于合理最小值的比例；注意防范过度规划导致简单目标的步骤数虚高。" }, { "metric": "计划审批通过率", "note": "在执行前被评审员或策略检查接受的计划比例；低通过率表明系统性分解能力较弱。" } ], "failureModes": [ "糟糕的分解会产生连锁反应：早期错误的假设会破坏下游的每一个依赖步骤。", "重新规划循环：智能体反复重写计划，而无法收敛或取得进展。", "执行过时的计划：执行某个步骤时，所针对的世界状态自计划制定以来已发生变化。", "过度分解：将一个简单的目标拆分为不必要的步骤，增加了延迟、成本和失败面。" ], "lessons": [ "使计划成为真正的产物——记录它、展示它、对比它——这样失败就是可调试的，而不是神秘莫测的。", "始终闭环：检测步骤失败并从当前状态重新规划，而不是盲目继续。", "通过显式预算限制计划深度和重新规划，防止简单的目标陷入无休止的循环。", "允许简单的目标跳过规划器；将分解保留给真正具有多步骤、依赖性的工作。" ], "faqs": [ { "q": "这与反应式 ReAct 风格的智能体有什么不同？", "a": "反应式智能体根据当前状态一次决定一个动作，没有作为产物的计划。目标分解则预先确定一个有序的计划，使预期的步骤可检查，且依赖顺序明确。在实践中，两者经常结合使用：先规划，然后在每个步骤中反应式地执行，并在步骤失败时重新规划。" }, { "q": "当步骤在计划执行中途失败时会发生什么？", "a": "将控制权交回给规划器，以便从当前状态重新规划，而不是盲目继续。闭环重新规划是使分解具备鲁棒性的关键。通过预算对其进行限制，以防止持续失败的步骤在没有进展的情况下触发无休止的重写。" }, { "q": "什么时候规划弊大于利？", "a": "适用于简单的、单步骤的目标（此时下一步行动显而易见），或者适用于变化速度快于计划失效速度的环境。在这些情况下，前期规划会增加延迟和计划过时的风险。检测简单目标并让其绕过规划器，将分解保留给真正多步骤、存在依赖关系的工作。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/human-approval-gate", "api_url": "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", "least-privilege-tooling" ], "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." } ] }, "fr": { "name": "Porte d'approbation humaine", "summary": "Une porte d'approbation humaine suspend un flux de travail automatisé à un point de contrôle défini afin qu'une personne puisse examiner, modifier ou rejeter une action proposée avant son exécution — en particulier pour les opérations à fort impact, irréversibles ou réglementées. C'est la forme opérationnelle de la supervision humaine (human-in-the-loop).", "definition": "Une porte d'approbation humaine est un point de contrôle inséré avant une action automatisée à fort impact, où une personne examine et approuve, modifie ou rejette l'action proposée avant son exécution.", "problem": "Laisser un système d'IA exécuter de manière autonome des actions à fort impact présente un risque d'erreurs coûteuses, irréversibles ou non conformes, sans possibilité d'intervention du jugement humain.", "context": "Utilisez une porte d'approbation pour les actions dont le coût de l'erreur l'emporte sur la latence de l'examen : paiements, suppressions, communications externes, modifications en production ou tout ce qui est réglementé.", "solution": [ "Insérez un point de contrôle avant l'action sensible : le système prépare l'action proposée avec suffisamment de contexte, puis la suspend et l'oriente vers un humain qui l'approuve, la modifie ou la rejette. En cas d'approbation, elle se poursuit ; en cas de dépassement de délai (timeout), elle se replie de manière sécurisée. Chaque décision est enregistrée pour audit.", "Ne soumettez à approbation que les étapes à fort impact, pas la totalité — un excès de contrôle détruit la valeur de l'automatisation et provoque une lassitude face aux approbations. Choisissez les points de contrôle en fonction du risque." ], "components": [ "Point de contrôle basé sur le risque", "Aperçu de l'action proposée", "Approuver / modifier / rejeter", "Dépassement de délai et repli sécurisé", "Journal d'audit" ], "benefits": [ "Prévient les erreurs coûteuses ou irréversibles.", "Maintient la responsabilité chez l'humain.", "Répond aux exigences de conformité et de supervision.", "Renforce la confiance, permettant une autonomie progressive." ], "risks": [ "Ajoute de la latence et limite le débit.", "Approbation automatique (rubber-stamping) si les réviseurs manquent de contexte ou de temps.", "Lassitude face aux approbations en raison d'un trop grand nombre de contrôles.", "Goulots d'étranglement si les réviseurs ne sont pas disponibles." ], "whenNot": [ "Pour les actions à faible impact et facilement réversibles.", "Lorsque le débit doit être élevé et le risque est faible.", "Lorsqu'un garde-fou déterministe peut approuver automatiquement en toute sécurité." ], "examples": [ "Un agent rédigeant un remboursement qu'un humain approuve avant qu'il ne soit émis.", "Une modification en production qui se suspend pour validation avant le déploiement.", "Un e-mail sortant mis en attente pour examen avant envoi." ], "productionEvidence": { "context": "Flux de travail d'entreprise où un agent peut déclencher des actions irréversibles ou réglementées — remboursements, modifications de compte, communications sortantes, déploiements en production.", "scenario": "L'agent prépare l'action avec tout le contexte nécessaire et se met en pause ; un réviseur l'approuve, la modifie ou la rejette ; après approbation, elle s'exécute, en cas de dépassement de délai, elle se replie de manière sécurisée. Chaque décision est enregistrée.", "technology": "Un moteur de flux de travail avec interruptions (par ex. LangGraph), une file d'attente/interface utilisateur d'approbation et un journal d'audit.", "load": "Seule une minorité d'étapes à fort impact est soumise à approbation ; la majeure partie des étapes à faible impact s'exécute automatiquement, de sorte que le volume de travail des réviseurs reste limité.", "results": "Modèle observé : les erreurs irréversibles sont interceptées avant l'exécution et la responsabilité reste humaine, au prix d'une latence accrue sur les étapes contrôlées. Filtrez par risque et mesurez la latence d'approbation ainsi que le taux d'approbation automatique sur votre propre flux de travail — il s'agit d'observations de référence, pas de chiffres garantis." }, "kpis": [ { "metric": "Latence d'approbation", "note": "Temps pendant lequel une action attend à la porte ; le coût principal de ce modèle et le premier élément à surveiller pour détecter les goulots d'étranglement." }, { "metric": "Taux de rejet / modification", "note": "Part des propositions qu'un humain rejette ou modifie — un taux proche de zéro signifie souvent une approbation automatique sans examen, un taux très élevé signifie que l'agent n'est pas encore digne de confiance." }, { "metric": "Débit par rapport aux étapes contrôlées", "note": "Tâches accomplies par heure par rapport au nombre d'étapes contrôlées ; un excès de contrôle effondre le débit." }, { "metric": "Taux de dépassement de délai / repli", "note": "Fréquence à laquelle les actions atteignent le dépassement de délai et adoptent le repli sécurisé ; un taux en hausse signale une surcharge des réviseurs." } ], "failureModes": [ "Approbation automatique (rubber-stamping) : les réviseurs approuvent sans examen réel lorsqu'ils manquent de contexte ou de temps, ce qui neutralise l'utilité de la porte.", "Lassitude face aux approbations et goulots d'étranglement dus à un excès de contrôle sur les étapes à faible impact.", "Auto-exécution silencieuse en cas de dépassement de délai lorsqu'aucun repli sécurisé n'est défini.", "Contexte insuffisant dans la proposition, empêchant l'humain de prendre une décision éclairée." ], "lessons": [ "Contrôlez en fonction du risque, pas par défaut — automatisez les étapes à faible impact et réservez les portes d'approbation aux actions irréversibles ou réglementées.", "Fournissez aux réviseurs suffisamment de contexte et un choix clair entre approuver, modifier ou rejeter pour éviter l'approbation automatique.", "Définissez toujours un repli sécurisé en cas de dépassement de délai ; n'exécutez jamais silencieusement une action contrôlée.", "Enregistrez chaque décision pour audit — la porte d'approbation constitue également votre preuve de conformité." ], "faqs": [ { "q": "En quoi cela diffère-t-il du concept de « human-in-the-loop » ?", "a": "C'est la mise en œuvre concrète du principe de « human-in-the-loop » : un point de contrôle d'approbation spécifique dans un flux de travail avant une action sensible." }, { "q": "Les approbations ne risquent-elles pas de tout ralentir ?", "a": "Seulement si vous abusez des contrôles. Appliquez des portes d'approbation en fonction du risque — automatisez les étapes à faible impact et réservez l'approbation aux actions à fort impact, irréversibles ou réglementées." }, { "q": "Que se passe-t-il en cas de dépassement de délai ?", "a": "Définissez un repli sécurisé : suspendez l'action, escaladez ou annulez. N'exécutez jamais automatiquement et silencieusement une action contrôlée simplement parce que personne n'a répondu." } ] }, "de": { "name": "Human-Approval-Gate", "summary": "Ein Human-Approval-Gate pausiert einen automatisierten Workflow an einem definierten Kontrollpunkt, sodass eine Person eine vorgeschlagene Aktion überprüfen, bearbeiten oder ablehnen kann, bevor sie ausgeführt wird – insbesondere bei folgenschweren, unumkehrbaren oder regulierten Operationen. Es ist die operative Form der Human-in-the-Loop-Überwachung.", "definition": "Ein Human-Approval-Gate ist ein Kontrollpunkt, der vor einer folgenschweren automatisierten Aktion eingefügt wird und an dem eine Person die vorgeschlagene Aktion überprüft und genehmigt, bearbeitet oder ablehnt, bevor sie ausgeführt wird.", "problem": "Wenn man ein KI-System folgenschwere Aktionen autonom ausführen lässt, riskieren Sie kostspielige, unumkehrbare oder nicht-konforme Fehler, ohne dass die Möglichkeit einer menschlichen Beurteilung besteht.", "context": "Verwenden Sie ein Freigabe-Gate für Aktionen, bei denen die Fehlerkosten die Latenz der Überprüfung überwiegen: Zahlungen, Löschungen, externe Kommunikation, Änderungen in der Produktion oder alles Regulierte.", "solution": [ "Fügen Sie vor der sensiblen Aktion einen Kontrollpunkt ein: Das System bereitet die vorgeschlagene Aktion mit ausreichend Kontext vor, pausiert sie dann und leitet sie an einen Menschen weiter, der sie genehmigt, bearbeitet oder ablehnt. Nach der Freigabe wird sie fortgesetzt; bei einer Zeitüberschreitung greift ein sicherer Fallback. Jede Entscheidung wird für Audits protokolliert.", "Versehen Sie nur die folgenschweren Schritte mit einem Gate, nicht alles – ein Übermaß an Gates zerstört den Wert der Automatisierung und führt zu Freigabemüdigkeit. Wählen Sie Kontrollpunkte nach Risiko aus." ], "components": [ "Risikobasierter Kontrollpunkt", "Vorschau der vorgeschlagenen Aktion", "Genehmigen / Bearbeiten / Ablehnen", "Zeitüberschreitung & sicherer Fallback", "Audit-Protokoll" ], "benefits": [ "Verhindert kostspielige oder unumkehrbare Fehler.", "Belässt die Verantwortung beim Menschen.", "Erfüllt Compliance- und Überwachungsanforderungen.", "Baut Vertrauen auf und ermöglicht eine schrittweise Autonomie." ], "risks": [ "Erhöht die Latenz und schränkt den Durchsatz ein.", "Abnicken (Rubber-Stamping), wenn Prüfern Kontext oder Zeit fehlt.", "Freigabemüdigkeit durch zu viele Gates.", "Engpässe, wenn Prüfer nicht verfügbar sind." ], "whenNot": [ "Für risikoarme, leicht umkehrbare Aktionen.", "Wenn der Durchsatz hoch und das Risiko gering sein muss.", "Wenn eine deterministische Guardrail sicher automatisch freigeben kann." ], "examples": [ "Ein Agent, der eine Rückerstattung entwirft, die ein Mensch vor der Auszahlung freigibt.", "Eine Produktionsänderung, die vor dem Deployment für eine Freigabe pausiert.", "Eine ausgehende E-Mail, die vor dem Senden zur Überprüfung in die Warteschlange gestellt wird." ], "productionEvidence": { "context": "Unternehmens-Workflows, bei denen ein Agent unumkehrbare oder regulierte Aktionen auslösen kann – Rückerstattungen, Kontoänderungen, ausgehende Kommunikation, Produktions-Deployments.", "scenario": "Der Agent bereitet die Aktion mit vollständigem Kontext vor und pausiert; ein Prüfer genehmigt, bearbeitet oder lehnt sie ab; nach der Freigabe wird sie ausgeführt, bei einer Zeitüberschreitung greift ein sicherer Fallback. Jede Entscheidung wird protokolliert.", "technology": "Eine Workflow-Engine mit Interrupts (z. B. LangGraph), einer Freigabe-Warteschlange/UI und einem Audit-Protokoll.", "load": "Nur eine Minderheit der folgenschweren Schritte wird mit einem Gate versehen; der Großteil der risikoarmen Schritte läuft automatisch ab, sodass das Prüfvolumen begrenzt bleibt.", "results": "Beobachtetes Muster: Unumkehrbare Fehler werden vor der Ausführung abgefangen und die Verantwortung verbleibt beim Menschen, auf Kosten einer zusätzlichen Latenz bei den mit Gates versehenen Schritten. Setzen Sie Gates risikobasiert ein und messen Sie die Freigabelatenz sowie die Abnick-Rate (Rubber-Stamp-Rate) in Ihrem eigenen Workflow – dies sind Referenzbeobachtungen, keine garantierten Zahlen." }, "kpis": [ { "metric": "Freigabelatenz", "note": "Zeit, die eine Aktion am Gate wartet; die Hauptkosten des Musters und der erste Punkt, an dem auf Engpässe geachtet werden sollte." }, { "metric": "Ablehnungs- / Bearbeitungsrate", "note": "Anteil der Vorschläge, die ein Mensch ablehnt oder bearbeitet – ein Wert nahe Null bedeutet oft bloßes Abnicken, ein sehr hoher Wert zeigt, dass dem Agenten noch nicht vertraut wird." }, { "metric": "Durchsatz vs. mit Gates versehene Schritte", "note": "Pro Stunde abgeschlossene Aufgaben im Verhältnis zu den mit Gates versehenen Schritten; ein Übermaß an Gates lässt den Durchsatz einbrechen." }, { "metric": "Zeitüberschreitungs- / Fallback-Rate", "note": "Wie oft Aktionen das Timeout erreichen und den sicheren Fallback nutzen; eine steigende Rate signalisiert eine Überlastung der Prüfer." } ], "failureModes": [ "Abnicken (Rubber-Stamping): Prüfer genehmigen ohne echte Prüfung, wenn ihnen Kontext oder Zeit fehlt, was das Gate wirkungslos macht.", "Freigabemüdigkeit und Engpässe durch ein Übermaß an Gates bei risikoarmen Schritten.", "Stille automatische Ausführung bei Zeitüberschreitung, wenn kein sicherer Fallback definiert ist.", "Unzureichender Kontext im Vorschlag, sodass der Mensch keine fundierte Entscheidung treffen kann." ], "lessons": [ "Setzen Sie Gates risikobasiert ein, nicht standardmäßig – automatisieren Sie risikoarme Schritte und reservieren Sie Gates für unumkehrbare oder regulierte Aktionen.", "Geben Sie Prüfern ausreichend Kontext und eine klare Auswahl zwischen Genehmigen, Bearbeiten und Ablehnen, um bloßes Abnicken zu verhindern.", "Definieren Sie bei einer Zeitüberschreitung immer einen sicheren Fallback; führen Sie eine mit einem Gate versehene Aktion niemals stillschweigend aus.", "Protokollieren Sie jede Entscheidung für Audits – das Gate ist gleichzeitig Ihr Compliance-Nachweis." ], "faqs": [ { "q": "Wie unterscheidet sich dies von Human-in-the-Loop?", "a": "Es ist die konkrete Implementierung des Human-in-the-Loop-Prinzips: ein spezifischer Freigabe-Kontrollpunkt in einem Workflow vor einer sensiblen Aktion." }, { "q": "Werden Freigaben nicht alles verlangsamen?", "a": "Nur, wenn Sie zu viele Gates einsetzen. Wenden Sie Gates risikobasiert an – automatisieren Sie risikoarme Schritte und reservieren Sie Freigaben für folgenschwere, unumkehrbare oder regulierte Aktionen." }, { "q": "Was passiert bei einer Zeitüberschreitung?", "a": "Definieren einen sicheren Fallback: Halten Sie die Aktion an, eskalieren Sie sie oder brechen Sie sie ab. Führen Sie eine mit einem Gate versehene Aktion niemals stillschweigend automatisch aus, nur weil niemand geantwortet hat." } ] }, "ja": { "name": "人による承認ゲート", "summary": "人による承認ゲートは、定義されたチェックポイントで自動化されたワークフローを一時停止し、提案されたアクションが実行される前に、人がそれをレビュー、編集、または拒否できるようにするものです。これは特に、影響が大きく、不可逆的、または規制対象となる操作に有効です。これは、Human-in-the-Loop（人間関与）による監視を運用可能な形にしたものです。", "definition": "人による承認ゲートとは、影響の大きい自動化アクションの前に挿入される制御チェックポイントであり、アクションが実行される前に、人が提案されたアクションをレビューし、承認、編集、または拒否する場所です。", "problem": "AIシステムに影響の大きいアクションを自律的に実行させると、人間の判断が介在する余地がなくなり、コストがかさむ不可逆的なミスや、コンプライアンス違反のミスが発生するリスクがあります。", "context": "エラーによるコストがレビューのレイテンシーを上回るようなアクション（支払い、削除、外部通信、本番環境の変更、または規制対象のあらゆる処理）に対して、承認ゲートを使用します。", "solution": [ "機密性の高いアクションの前にチェックポイントを挿入します。システムは十分なコンテキストを添えて提案されたアクションを準備し、処理を一時停止して、承認、編集、または拒否を行う担当者にルーティングします。承認されれば処理が進み、タイムアウトした場合は安全にフォールバックします。すべての決定は監査のためにログに記録されます。", "すべてのステップではなく、影響の大きいステップのみにゲートを設定します。過剰なゲート設定は自動化の価値を損ない、承認疲れを引き起こします。リスクに基づいてチェックポイントを選択してください。" ], "components": [ "リスクベースのチェックポイント", "提案されたアクションのプレビュー", "承認 / 編集 / 拒否", "タイムアウトと安全なフォールバック", "監査ログ" ], "benefits": [ "コストのかさむミスや不可逆的なミスを防ぎます。", "説明責任を人間に留めます。", "コンプライアンスおよび監視の要件を満たします。", "信頼を構築し、段階的な自律性を可能にします。" ], "risks": [ "レイテンシーを追加し、スループットを制限します。", "レビュー担当者にコンテキストや時間が不足している場合、形骸化（目くら判）が発生します。", "ゲートが多すぎることによる承認疲れ。", "レビュー担当者が対応できない場合のボトルネック。" ], "whenNot": [ "影響が小さく、簡単に元に戻せるアクションの場合。", "スループットを高く維持する必要があり、リスクが低い場合。", "決定論的なガードレールによって安全に自動承認できる場合。" ], "examples": [ "エージェントが返金を起票し、発行前に人間が承認する。", "デプロイ前にサインオフ（承認）のために一時停止する本番環境の変更。", "送信前にレビューのためにキューに入れられる送信メール。" ], "productionEvidence": { "context": "エージェントが不可逆的または規制対象のアクション（返金、アカウント変更、外部通信、本番環境へのデプロイなど）をトリガーする可能性のあるエンタープライズワークフロー。", "scenario": "エージェントは完全なコンテキストを添えてアクションを準備し、一時停止します。レビュー担当者がそれを承認、編集、または拒否します。承認されると実行され、タイムアウトした場合は安全にフォールバックします。すべての決定はログに記録されます。", "technology": "割り込み機能を備えたワークフローエンジン（例：LangGraph）、承認キュー/UI、および監査ログ。", "load": "影響の大きい少数のステップのみにゲートが設定され、影響の小さい大部分のステップは自動的に実行されるため、レビュー担当者の作業量は制限された範囲内に収まります。", "results": "観察されたパターン：ゲートが設定されたステップでレイテンシーが追加される代わりに、実行前に不可逆的なエラーが捕捉され、説明責任が人間に留まります。リスクに基づいてゲートを設定し、独自のワークフローで承認レイテンシーと形骸化率を測定してください。これらは参照用の観察結果であり、保証された数値ではありません。" }, "kpis": [ { "metric": "承認レイテンシー", "note": "アクションがゲートで待機する時間。このパターンの主なコストであり、ボトルネックとして最初に監視すべき項目です。" }, { "metric": "拒否 / 編集率", "note": "人間が拒否または編集した提案の割合。ほぼゼロの場合は形骸化（目くら判）を意味することが多く、非常に高い場合はエージェントがまだ信頼されていないことを意味します。" }, { "metric": "スループットとゲート設定ステップの比率", "note": "ゲートが設定されたステップ数に対する1時間あたりの完了タスク数。過剰なゲート設定はスループットを崩壊させます。" }, { "metric": "タイムアウト / フォールバック率", "note": "アクションがタイムアウトに達し、安全なフォールバックが実行される頻度。この割合の上昇は、レビュー担当者の過負荷を示しています。" } ], "failureModes": [ "形骸化（目くら判）：レビュー担当者にコンテキストや時間が不足している場合、十分な精査なしに承認してしまい、ゲートの目的が果たせなくなります。", "影響の小さいステップへの過剰なゲート設定による、承認疲れとボトルネック。", "安全なフォールバックが定義されていない場合に、タイムアウト時にサイレントで自動実行されてしまうこと。", "提案に含まれるコンテキストが不十分なため、人間が十分な情報に基づいた意思決定を行えないこと。" ], "lessons": [ "デフォルトではなくリスクに基づいてゲートを設定します。影響の小さいステップは自動化し、不可逆的または規制対象のアクションのためにゲートを予約しておきます。", "形骸化を防ぐために、レビュー担当者に十分なコンテキストと、明確な「承認/編集/拒否」の選択肢を提供します。", "タイムアウト時には必ず安全なフォールバックを定義してください。ゲートされたアクションをサイレントで実行してはなりません。", "すべての決定を監査用にログ記録します。ゲートはコンプライアンスの証拠でもあります。" ], "faqs": [ { "q": "Human-in-the-Loop（人間関与）と何が違うのですか？", "a": "これはHuman-in-the-Loop原則の具体的な実装です。機密性の高いアクションの前に、ワークフロー内に特定の承認チェックポイントを設けます。" }, { "q": "承認によってすべての処理が遅くなりませんか？", "a": "過剰にゲートを設定した場合のみです。リスクに基づいてゲートを適用してください。影響の小さいステップは自動化し、影響が大きい、不可逆的、または規制対象のアクションのために承認を予約しておきます。" }, { "q": "タイムアウト時には何が起こりますか？", "a": "安全なフォールバック（アクションの保留、エスカレーション、またはキャンセル）を定義してください。誰も応答しなかったからといって、ゲートされたアクションをサイレントで自動実行してはなりません。" } ] }, "zh": { "name": "人工审批关卡", "summary": "人工审批关卡在定义的检查点暂停自动化工作流，以便人员在执行建议的操作之前进行审查、编辑或拒绝——特别是针对高影响、不可逆或受监管的操作。它是人机回环（human-in-the-loop）监督的运行形式。", "definition": "人工审批关卡是在高影响自动化操作之前插入的控制检查点，人员在操作执行前对其进行审查并批准、编辑或拒绝。", "problem": "让 AI 系统自主执行高影响操作会带来代价高昂、不可逆或违规的错误风险，且人类无法进行判断。", "context": "对于错误成本超过审查延迟的操作，请使用审批关卡：例如支付、删除、外部通信、生产变更或任何受监管的事项。", "solution": [ "在敏感操作之前插入一个检查点：系统准备好包含足够上下文的建议操作，然后暂停并将其路由给人工进行批准、编辑或拒绝。批准后继续执行；超时则安全回退。每个决策都会记录在日志中以备审计。", "仅对高影响步骤设置关卡，而不是所有步骤——过度设置关卡会破坏自动化的价值并导致审批疲劳。根据风险选择检查点。" ], "components": [ "基于风险的检查点", "建议操作预览", "批准 / 编辑 / 拒绝", "超时与安全回退", "审计日志" ], "benefits": [ "防止代价高昂或不可逆的错误。", "保持由人类承担责任。", "满足合规和监督要求。", "建立信任，从而逐步实现自主性。" ], "risks": [ "增加延迟并限制吞吐量。", "如果审查人员缺乏上下文或时间，审批会流于形式。", "关卡过多导致审批疲劳。", "如果审查人员不可用，会造成瓶颈。" ], "whenNot": [ "适用于低影响、易于逆转的操作。", "适用于吞吐量要求高且风险低的情况。", "适用于确定性护栏可以安全自动批准的情况。" ], "examples": [ "智能体起草退款，人工在发放前进行审批。", "生产变更在部署前暂停以等待签字批准。", "外发电子邮件在发送前排队等待审查。" ], "productionEvidence": { "context": "智能体可能触发不可逆或受监管操作的企业工作流——退款、账户变更、外部通信、生产部署。", "scenario": "智能体准备好包含完整上下文的操作并暂停；审查人员对其进行批准、编辑或拒绝；批准后执行，超时则安全回退。每个决策都会记录在日志中。", "technology": "具有中断功能的工作流引擎（例如 LangGraph）、审批队列/UI 以及审计日志。", "load": "仅对少数高影响步骤设置关卡；大部分低影响步骤自动运行，因此审查人员的工作量保持在有限范围内。", "results": "观察到的模式：不可逆的错误在执行前被拦截，责任由人类承担，代价是设置关卡的步骤增加了延迟。请根据风险设置关卡，并在您自己的工作流中衡量审批延迟和流于形式率——这些是参考观察结果，而非保证的数据。" }, "kpis": [ { "metric": "审批延迟", "note": "操作在关卡处等待的时间；该模式的核心成本，也是寻找瓶颈时首先需要关注的指标。" }, { "metric": "拒绝 / 编辑率", "note": "人工拒绝或编辑的建议比例——接近零通常意味着审批流于形式，非常高则意味着智能体尚未获得信任。" }, { "metric": "吞吐量与设关步骤对比", "note": "每小时完成的任务数与设置关卡的步骤数对比；过度设置关卡会导致吞吐量骤降。" }, { "metric": "超时 / 回退率", "note": "操作触发超时并采用安全回退的频率；该比例上升表明审查人员过载。" } ], "failureModes": [ "审批流于形式：当审查人员缺乏上下文或时间时，他们会在没有真正审查的情况下予以批准，从而使关卡失效。", "对低影响步骤过度设置关卡导致审批疲劳和瓶颈。", "未定义安全回退时，超时后静默自动执行。", "建议中上下文不足，导致人类无法做出知情决策。" ], "lessons": [ "根据风险设置关卡，而非默认设置——自动执行低影响步骤，并将关卡保留给不可逆或受监管的操作。", "为审查人员提供足够的上下文以及明确的批准/编辑/拒绝选项，以防止审批流于形式。", "始终定义超时安全回退；绝不静默执行设置了关卡的操作。", "记录每个决策以备审计——关卡也是您的合规证据。" ], "faqs": [ { "q": "这与人机协同（human-in-the-loop）有什么不同？", "a": "它是人机回环原则的具体实现：工作流中敏感操作之前的特定审批检查点。" }, { "q": "审批难道不会拖慢一切吗？", "a": "只有在过度设置关卡时才会如此。根据风险应用关卡——自动执行低影响步骤，并将审批保留给高影响、不可逆或受监管的操作。" }, { "q": "超时会发生什么？", "a": "定义安全回退：挂起操作、升级或取消。绝不能仅仅因为无人响应就静默自动执行设置了关卡的操作。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/human-escalation", "api_url": "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", "least-privilege-tooling" ], "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." } ] }, "fr": { "name": "Escalade humaine", "summary": "Confiez l'intégralité de la tâche à un humain lorsque l'agent détecte qu'il est dépassé — faible confiance, échecs répétés, ambiguïté ou situations sensibles — et transmettez tout le contexte pour que la personne puisse prendre le relais sans avoir à tout réanalyser. Contrairement à une porte d'approbation, qui suspend une action pour validation, l'escalade transfère la responsabilité de sorte que l'agent cesse de piloter. La difficulté réside dans le calibrage des déclencheurs pour éviter à la fois la sur-escalade et la sous-escalade.", "problem": "Un agent autonome rencontrera inévitablement des cas qu'il ne peut pas gérer correctement : des entrées hors de sa distribution d'entraînement, des requêtes qu'il ne parvient pas à satisfaire de manière répétée, des objectifs réellement ambigus ou des moments sensibles sur le plan émotionnel ou juridique. S'il s'obstine malgré tout, il produit des réponses erronées avec assurance, tourne en boucle ou génère des actions préjudiciables — et l'utilisateur découvre la défaillance trop tard. Pourtant, tout orienter vers des humains va à l'encontre de l'intérêt de l'automatisation et surcharge le personnel. Le système a besoin d'un moyen rigoureux pour reconnaître les limites de sa compétence et transférer la tâche avant que des dommages ne surviennent.", "context": "Utilisez ce modèle partout où un agent agit avec une autonomie significative et où le coût d'un résultat erroné dépasse le coût d'un examen rapide par un humain : support client, gestion des réclamations et des dossiers, tri financier ou médical, modération de contenu et copilotes opérationnels. Il suppose qu'une file d'attente humaine ou une fonction d'astreinte existe pour recevoir les escalades et que l'agent peut observer des signaux concernant ses propres performances. Il est particulièrement précieux lorsque les défaillances sont silencieuses — lorsqu'une réponse erronée formulée avec assurance est pire que l'absence de réponse — et lorsqu'un sous-ensemble de cas est connu pour être difficile, rare ou réglementé.", "solution": [ "Définissez des déclencheurs d'escalade explicites et intégrez-les dans la boucle principale de l'agent en tant que conditions de sortie de premier ordre, et non après coup. Les déclencheurs courants sont un niveau de confiance inférieur à un seuil (issu des scores du modèle, d'une auto-critique ou d'un vérificateur), la détection de boucles ou d'échecs répétés (l'agent réessaie la même étape sans progresser), une ambiguïté structurelle (plusieurs interprétations valides de l'objectif) et des signaux de sensibilité (sentiment négatif, mots-clés de sécurité, comptes à haute valeur ou sujets réglementés). Chaque déclencheur doit correspondre à une décision d'aiguillage : vers quel humain ou équipe, avec quelle priorité. Traitez les seuils comme des paramètres ajustables appartenant à l'équipe, examinés par rapport aux résultats réels, car ils traduisent le compromis entre le taux d'automatisation et le taux d'erreur.\n\nLorsqu'un déclencheur s'active, l'agent doit effectuer un transfert propre : cesser d'agir, rassembler tout le contexte — requête d'origine, tentatives effectuées, résultats intermédiaires, sa meilleure estimation actuelle et la raison de l'escalade — et l'orienter vers la bonne file d'attente via un ticket ou un transfert en direct. L'humain qui reçoit la tâche doit pouvoir prendre le relais sans avoir à tout réanalyser depuis le début ; la qualité du contexte est ce qui fait de l'escalade une aide plutôt qu'un abandon de tâche. Fournissez toujours un message de repli bienveillant à l'utilisateur final (« Je fais appel à un spécialiste ») afin que l'expérience se dégrade en douceur. Enfin, enregistrez chaque escalade avec son déclencheur et sa résolution afin de pouvoir mesurer sa pertinence et réajuster les déclencheurs." ], "components": [ "Évaluateur de déclencheur", "Assembleur de contexte", "Routeur", "Canal de transfert", "Répondeur de repli", "Journal d'audit" ], "benefits": [ "Les cas difficiles parviennent à un humain avant que l'agent ne produise un résultat erroné avec assurance, limitant ainsi la zone d'impact des erreurs.", "Seuls les cas réellement complexes sont transmis, de sorte que le volume d'opérations courantes reste automatisé et que le personnel se concentre sur ce qui requiert du discernement.", "Un transfert propre accompagné de contexte permet d'aider les utilisateurs plutôt que de les renvoyer d'un service à l'autre, et les humains reprennent le fil sans avoir à tout recommencer.", "L'enregistrement des déclencheurs et des résolutions fournit la piste d'audit que les régulateurs et les responsables des risques attendent pour une supervision humaine significative." ], "risks": [ "Des seuils définis de manière trop prudente renvoient les cas simples vers les humains, annulant les gains de l'automatisation et submergeant le personnel sous un bruit inutile.", "Des seuils définis de manière trop permissive permettent à l'agent de traiter des cas qu'il aurait dû transférer, entraînant des échecs silencieux.", "Si les données transmises sont insuffisantes, l'humain doit reprendre l'investigation à zéro et l'escalade est perçue comme une tâche abandonnée plutôt que comme une assistance.", "L'auto-évaluation de la confiance d'un modèle ne correspond souvent pas à sa précision réelle ; ainsi, des seuils de score simplistes escaladent les mauvais cas dans les deux sens." ], "whenNot": [ "S'il n'y a pas de file d'attente gérée par du personnel ou de fonction d'astreinte pour prendre le relais, l'escalade n'aboutira nulle part ; investissez plutôt dans un arrêt sécurisé ou un chemin de récupération.", "Lorsque vous avez uniquement besoin d'une approbation pour une étape spécifique à fort impact alors que l'agent conserve la tâche, utilisez une barrière d'approbation humaine (human-approval gate) plutôt qu'un transfert complet de responsabilité.", "Pour des tâches peu coûteuses et facilement réversibles où une mauvaise réponse n'a aucune conséquence, la surcharge et la latence de l'escalade l'emportent sur les bénéfices." ], "examples": [ "Un agent de support résout les questions courantes mais escalade vers une file d'attente humaine en cas de frustration détectée, de réponses répétées inutiles ou de demandes sensibles liées au compte, en transmettant l'intégralité de la conversation.", "Un agent d'assurance traite automatiquement les sinistres clairs et escalade ceux qui sont ambigus, de grande valeur ou signalés comme frauduleux vers un gestionnaire de sinistres, en y joignant ses conclusions et le motif.", "Un agent de codage autonome qui échoue à plusieurs reprises au même test s'arrête, résume ce qu'il a tenté et l'endroit où il est bloqué, puis confie la tâche à un ingénieur au lieu de tourner en boucle." ], "kpis": [ { "metric": "Taux d'escalade", "note": "Part des tâches confiées à des humains. Surveillez la tendance et la distribution plutôt qu'un chiffre cible — un pic ou une baisse soudaine signale un déclencheur mal calibré ou un changement dans la répartition des entrées." }, { "metric": "Pertinence de l'escalade", "note": "Parmi les cas escaladés, combien nécessitaient réellement un humain (vrais positifs) par rapport à ceux qui auraient pu être traités automatiquement. Une revue humaine par échantillonnage des escalades constitue la mesure la plus fiable." }, { "metric": "Taux d'escalades manquées", "note": "Parmi les résolutions automatisées, combien se sont avérées erronées par la suite et auraient dû être escaladées. C'est le signal le plus difficile et le plus important à obtenir ; analysez les plaintes, les réouvertures de tickets et les audits pour les identifier." }, { "metric": "Suffisance du contexte de transfert", "note": "Fréquence à laquelle l'humain qui reçoit le relais peut prendre la suite sans recontacter l'utilisateur ni refaire l'investigation. À suivre via les retours des agents sur la complétude des informations fournies." } ], "failureModes": [ "Les déclencheurs configurés une fois pour toutes et jamais réévalués deviennent obsolètes à mesure que les entrées et les modèles évoluent, déplaçant silencieusement l'équilibre entre automatisation et erreurs.", "Les cas sont orientés vers une file d'attente sans responsable ou surchargée, de sorte que les utilisateurs escaladés attendent indéfiniment — ce qui est pire qu'une mauvaise réponse.", "Un agent optimisé pour éviter l'escalade apprend à exprimer une fausse confiance, supprimant ainsi le signal même sur lequel repose ce modèle.", "Le transfert supprime la mise en forme, le raisonnement intermédiaire ou les pièces jointes, obligeant l'humain à reconstituer la situation et annulant le gain de rapidité." ], "lessons": [ "Validez que votre signal de confiance est corrélé à la précision réelle avant de définir un seuil basé sur celui-ci ; associez les scores du modèle à un vérificateur ou à une auto-critique.", "La différence entre une bonne et une mauvaise escalade réside presque entièrement dans les données de transfert ; investissez dans cet aspect avant d'ajuster les seuils.", "Traisez les seuils comme des paramètres vivants, examinés par rapport à des échantillons d'escalades et d'escalades manquées, gérés par l'équipe et non figés lors du lancement.", "Même un déclencheur parfait échoue parfois ; un message d'attente soigné et une file d'attente bien gérée évitent que les échecs ne se transforment en abandons." ], "faqs": [ { "q": "En quoi cela diffère-t-il d'une barrière d'approbation humaine (human-approval gate) ?", "a": "Une barrière d'approbation suspend une action spécifique à fort impact et demande la validation d'un humain, après quoi l'agent continue. L'escalade transfère la responsabilité de l'ensemble de la tâche — l'agent cesse de la piloter car il ne doit plus progresser du tout. Utilisez une barrière pour la question « Dois-je faire cette action précise ? » et l'escalade pour « Je suis dépassé, veuillez prendre le relais »." }, { "q": "Quel est le bon taux d'escalade ?", "a": "Il n'y a pas de chiffre universel ; cela dépend de la complexité des tâches et du coût des erreurs. Optimisez la pertinence plutôt qu'un taux cible : escaladez les cas qui nécessitent réellement un humain et minimisez à la fois les transferts inutiles et les escalades manquées. Analysez le taux comme un signal de mauvais calibrage, et non comme un objectif en soi." }, { "q": "Puis-je simplement escalader chaque fois que la confiance du modèle est faible ?", "a": "C'est un déclencheur utile mais rarement suffisant à lui seul, car l'auto-évaluation de la confiance d'un modèle ne correspond souvent pas à sa précision réelle. Combinez-le avec la détection de boucles, des vérifications d'ambiguïté et des signaux de sensibilité, et validez que votre mesure de confiance est réellement corrélée à des résultats corrects avant de vous fier à un seuil." } ] }, "de": { "name": "Menschliche Eskalation", "summary": "Übergeben Sie die gesamte Aufgabe an einen Menschen, wenn der Agent erkennt, dass er überfordert ist – bei geringem Vertrauen, wiederholtem Scheitern, Mehrdeutigkeit oder sensiblen Situationen – und übermitteln Sie den vollständigen Kontext, damit die Person die Aufgabe ohne erneute Untersuchung übernehmen kann. Im Gegensatz zu einem Freigabe-Gate, das eine einzelne Aktion für eine Freigabe pausiert, überträgt die Eskalation die Verantwortung, sodass der Agent die Steuerung abgibt. Die Schwierigkeit liegt in der Kalibrierung der Trigger, um sowohl Über- als auch Untereskalation zu vermeiden.", "problem": "Ein autonomer Agent wird unweigerlich auf Fälle stoßen, die er nicht gut bewältigen kann: Eingaben außerhalb seiner Trainingsverteilung, Anfragen, die er wiederholt nicht erfüllen kann, wirklich mehrdeutige Ziele oder emotional und rechtlich sensible Momente. Wenn er dennoch weitermacht, erzeugt er selbstbewusst falsche Antworten, Schleifen oder schädliche Aktionen – und der Benutzer entdeckt den Fehler erst zu spät. Doch alles an Menschen weiterzuleiten, macht den Zweck der Automatisierung zunichte und überlastet das Personal. Das System benötigt eine disziplinierte Methode, um die Grenzen seiner Kompetenz zu erkennen und die Aufgabe zu übertragen, bevor Schaden entsteht.", "context": "Verwenden Sie dieses Muster überall dort, wo ein Agent mit nennenswerter Autonomie agiert und die Kosten eines falschen Ergebnisses die Kosten eines kurzen Blicks durch einen Menschen übersteigen: im Kundensupport, bei der Schadens- und Fallbearbeitung, bei der finanziellen oder medizinischen Triage, bei der Inhaltsmoderation und bei operativen Copilots. Es setzt voraus, dass eine menschliche Warteschlange oder ein Bereitschaftsdienst für den Empfang von Eskalationen existiert und dass der Agent Signale über seine eigene Leistung beobachten kann. Es ist am wertvollsten, wenn Fehler unbemerkt bleiben – wenn eine selbstbewusst falsche Antwort schlimmer ist als keine Antwort – und wenn eine Teilmenge von Fällen bekanntermaßen schwierig, selten oder reguliert ist.", "solution": [ "Definieren Sie explizite Eskalationstrigger und binden Sie diese als erstklassige Exit-Bedingungen in die Hauptschleife des Agenten ein, nicht als nachträglichen Einfall. Typische Trigger sind ein Konfidenzwert unter einem Schwellenwert (aus Modell-Scores, Selbstkritik oder einem Verifizierer), die Erkennung von Schleifen oder wiederholten Fehlern (der Agent versucht denselben Schritt ohne Fortschritt erneut), strukturelle Mehrdeutigkeit (mehrere gültige Interpretationen des Ziels) und Sensibilitätssignale (negative Stimmung, Sicherheits-Keywords, wertvolle Konten oder regulierte Themen). Jeder Trigger sollte einer Routing-Entscheidung zugeordnet sein: welcher Mensch oder welches Team mit welcher Priorität. Behandeln Sie Schwellenwerte als anpassbare Parameter im Besitz des Teams, die anhand realer Ergebnisse überprüft werden, da sie den Kompromiss zwischen Automatisierungsrate und Fehlerrate codieren.\n\nWenn ein Trigger auslöst, muss der Agent eine saubere Übergabe durchführen: die Aktivität einstellen, den vollständigen Kontext packen – ursprüngliche Anfrage, was versucht wurde, Zwischenergebnisse, die aktuelle beste Vermutung und der Grund für die Eskalation – und ihn über ein Ticket oder eine Live-Übergabe an die richtige Warteschlange leiten. Der empfangende Mensch sollte in der Lage sein, die Aufgabe zu übernehmen, ohne von vorne recherchieren zu müssen; die Qualität des Kontextes entscheidet darüber, ob sich die Eskalation wie eine Hilfe oder wie ein fallengelassener Ball anfühlt. Bieten Sie dem Endbenutzer immer eine freundliche Fallback-Nachricht an („Ich ziehe einen Spezialisten hinzu“), damit sich das Benutzererlebnis nahtlos anpasst. Protokollieren Sie schließlich jede Eskalation mit ihrem Trigger und ihrer Lösung, damit die Angemessenheit gemessen und die Trigger neu kalibriert werden können." ], "components": [ "Trigger-Evaluator", "Kontext-Packager", "Router", "Übergabekanal", "Fallback-Responder", "Audit-Protokoll" ], "benefits": [ "Schwierige Fälle erreichen einen Menschen, bevor der Agent ein selbstbewusst falsches Ergebnis liefert, was den Schadensradius von Fehlern begrenzt.", "Nur wirklich schwierige Fälle werden übergeben, sodass das Routinevolumen automatisiert bleibt und sich die Mitarbeiter auf Aufgaben konzentrieren können, die menschliches Urteilsvermögen erfordern.", "Eine saubere Übergabe mit Kontext sorgt dafür, dass Benutzern geholfen wird, anstatt sie abzuweisen, und Menschen die Arbeit fortsetzen können, ohne von vorn beginnen zu müssen.", "Protokollierte Auslöser und Lösungen liefern den Nachweispfad, den Regulierungsbehörden und Risikoverantwortliche für eine sinnvolle menschliche Aufsicht erwarten." ], "risks": [ "Zu konservativ gesetzte Schwellenwerte leiten einfache Fälle an Menschen weiter, was die Automatisierungsgewinne zunichte macht und die Mitarbeiter in Rauschen untergehen lässt.", "Zu locker gesetzte Schwellenwerte führen dazu, dass der Agent Fälle durcharbeitet, die er hätte übergeben müssen, was zu unbemerkt schlechten Ergebnissen führt.", "Wenn die Payload unvollständig ist, muss der Mensch die Untersuchung von Grund auf neu beginnen, und die Eskalation fühlt sich wie eine fallengelassene Aufgabe an, nicht wie eine Unterstützung.", "Das Selbstvertrauen des Modells korreliert oft nicht mit der tatsächlichen Genauigkeit, sodass naive Score-Schwellenwerte in beide Richtungen die falschen Fälle eskalieren." ], "whenNot": [ "Wenn es keine besetzte Warteschlange oder Rufbereitschaft zur Übernahme gibt, läuft die Eskalation ins Leere; investieren Sie stattdessen in einen sicheren Stopp oder einen Wiederherstellungspfad.", "Wenn Sie nur die Genehmigung für einen bestimmten, folgenschweren Schritt benötigen, während der Agent die Aufgabe behält, nutzen Sie ein Human-Approval-Gate und keine vollständige Übergabe der Verantwortung.", "Bei kostengünstigen, leicht umkehrbaren Aufgaben, bei denen eine falsche Antwort nichts kostet, überwiegen der Overhead und die Latenz einer Eskalation den Nutzen." ], "examples": [ "Ein Support-Agent beantwortet Routinefragen, eskaliert jedoch bei erkannter Frustration, wiederholt nicht hilfreichen Antworten oder kontosensitiven Anfragen an eine menschliche Warteschlange und übergibt dabei den gesamten Gesprächsverlauf.", "Ein Versicherungs-Agent verarbeitet eindeutige Schadensfälle automatisch und eskaliert unklare, wertvolle oder als betrugsverdächtig markierte Fälle an einen Schadensregulierer, inklusive der eigenen Erkenntnisse und der Begründung.", "Ein autonomer Coding-Agent, der wiederholt am selben Test scheitert, stoppt, fasst zusammen, was er versucht hat und wo er blockiert ist, und übergibt die Aufgabe an einen Entwickler, anstatt sich im Kreis zu drehen." ], "kpis": [ { "metric": "Eskalationsrate", "note": "Anteil der an Menschen übergebenen Aufgaben. Achten Sie auf den Trend und die Verteilung, nicht auf einen Zielwert – ein plötzlicher Anstieg oder Abfall signalisiert einen falsch kalibrierten Auslöser oder eine Verschiebung im Input-Mix." }, { "metric": "Angemessenheit der Eskalation", "note": "Wie viele der eskalierten Fälle benötigten tatsächlich einen Menschen (True Positives) im Vergleich zu solchen, die hätten automatisiert verarbeitet werden können. Eine stichprobenartige menschliche Überprüfung der Eskalationen liefert die verlässlichsten Erkenntnisse." }, { "metric": "Rate verpasster Eskalationen", "note": "Wie viele der automatisierten Lösungen stellten sich später als falsch heraus und hätten eskaliert werden müssen. Das schwierigste und wichtigste Signal; werten Sie Beschwerden, Wiedereröffnungen und Audits aus, um diese zu finden." }, { "metric": "Kontextvollständigkeit bei der Übergabe", "note": "Wie oft der übernehmende Mensch die Aufgabe fortführen kann, ohne den Benutzer erneut kontaktieren oder den Fall neu untersuchen zu müssen. Messen Sie dies über das Feedback der Mitarbeiter zur Vollständigkeit des übergebenen Pakets." } ], "failureModes": [ "Einmalig eingestellte und nie wieder überprüfte Auslöser geraten aus dem Takt, wenn sich Inputs und Modelle ändern, was das Verhältnis zwischen Automatisierung und Fehlern unbemerkt verschiebt.", "Fälle werden in eine Warteschlange geleitet, für die niemand zuständig oder die überlastet ist, sodass eskalierte Benutzer unbegrenzt warten – was schlimmer ist als eine falsche Antwort.", "Ein Agent, der darauf optimiert ist, Eskalationen zu vermeiden, lernt, falsches Selbstvertrauen vorzutäuschen, wodurch genau das Signal unterdrückt wird, auf dem dieses Pattern basiert.", "Die Übergabe entfernt Formatierungen, Zwischenschritte der Argumentation oder Anhänge, was den Menschen zwingt, die Situation mühsam zu rekonstruieren, und den Geschwindigkeitsvorteil zunichtemacht." ], "lessons": [ "Validieren Sie, dass Ihr Konfidenzsignal mit der tatsächlichen Genauigkeit korreliert, bevor Sie Schwellenwerte darauf anwenden; kombinieren Sie Modell-Scores mit einem Verifizierer oder einer Selbstkritik.", "Der Unterschied zwischen einer guten und einer schlechten Eskalation liegt fast ausschließlich in der übergebenen Payload; investieren Sie hier, bevor Sie Schwellenwerte anpassen.", "Betrachten Sie Schwellenwerte als lebendige Parameter, die anhand von stichprobenartigen Eskalationen und verpassten Eskalationen überprüft werden. Sie sollten im Verantwortungsbereich des Teams liegen und nicht nach dem Go-Live unverändert bleiben.", "Selbst ein perfekter Auslöser versagt manchmal; eine freundliche Wartemeldung und eine klar zugewiesene Warteschlange verhindern, dass aus Fehlern Abbrüche werden." ], "faqs": [ { "q": "Wie unterscheidet sich dies von einem Human-Approval-Gate?", "a": "Ein Approval-Gate pausiert eine bestimmte, folgenschwere Aktion und bittet einen Menschen um Freigabe, woraufhin der Agent fortfährt. Eine Eskalation überträgt die Verantwortung für die gesamte Aufgabe – der Agent stoppt die Ausführung, da er überhaupt nicht weitermachen sollte. Nutzen Sie ein Gate für „Soll ich diese eine Sache tun?“ und eine Eskalation für „Ich weiß nicht mehr weiter, bitte übernehmen“." }, { "q": "Was ist die richtige Eskalationsrate?", "a": "Es gibt keinen universellen Wert; er hängt von der Mischung der Aufgabenschwierigkeiten und den Fehlerkosten ab. Optimieren Sie auf Angemessenheit, nicht auf eine Zielrate: Eskalieren Sie Fälle, die tatsächlich einen Menschen erfordern, und minimieren Sie sowohl unnötige Übergaben als auch verpasste Eskalationen. Betrachten Sie die Rate als Signal für eine Fehlkalibrierung, nicht als Selbstzweck." }, { "q": "Kann ich nicht einfach immer dann eskalieren, wenn die Konfidenz des Modells niedrig ist?", "a": "Das ist ein nützlicher Auslöser, reicht aber allein selten aus, da das Selbstvertrauen des Modells oft nicht mit der tatsächlichen Genauigkeit korreliert. Kombinieren Sie es mit Schleifenerkennung, Eindeutigkeitsprüfungen und Sensitivitätssignalen und validieren Sie, dass Ihr Konfidenzmaß tatsächlich mit korrekten Ergebnissen korreliert, bevor Sie einem Schwellenwert vertrauen." } ] }, "ja": { "name": "人へのエスカレーション", "summary": "エージェントが自身の能力を超えている（信頼度の低さ、繰り返される失敗、曖昧さ、または機密性の高い状況など）と検出した場合、タスク全体を人間に引き渡し、十分なコンテキストを渡すことで、その人が再調査することなく引き継げるようにします。1つのアクションをサインオフのために一時停止する承認ゲートとは異なり、エスカレーションは所有権を移転するため、エージェントは処理の主導を停止します。難しいのは、過剰なエスカレーションとエスカレーション不足の両方を避けるためにトリガーを調整することです。", "problem": "自律型エージェントは、トレーニングデータの分布外の入力、対応に失敗し続けるリクエスト、真に曖昧なゴール、感情的または法的にデリケートな状況など、うまく処理できないケースに必ず遭遇します。それでも処理を強行すると、自信満々に間違った回答を出力したり、ループに陥ったり、有害なアクションを実行したりして、ユーザーが失敗に気づくのが遅すぎることになります。しかし、すべてを人間にルーティングしていては自動化の意味がなくなり、スタッフが過負荷になります。システムには、自身の能力の限界を認識し、被害が発生する前にタスクを移転するための規律ある方法が必要です。", "context": "エージェントが実質的な自律性を持って動作し、誤った結果によるコストが、人間が目を通すコストを上回るあらゆる場所（カスタマーサポート、請求およびケース処理、財務または医療のトリアージ、コンテンツモデレーション、運用のコパイロットなど）でこのパターンを使用します。これは、エスカレーションを受け取るための人間のキューまたはオンコール機能が存在し、エージェントが自身のパフォーマンスに関するシグナルを観察できることを前提としています。このパターンが最も価値を発揮するのは、失敗がサイレントである場合（自信満々に間違った回答をすることが、回答がないことよりも悪い場合）、および一部のケースが困難、稀、または規制対象であることがわかっている場合です。", "solution": [ "明示的なエスカレーショントリガーを定義し、後付けではなく、第一級の終了条件としてエージェントのメインループに組み込みます。一般的なトリガーには、しきい値未満の信頼度（モデルのスコア、自己批判、または検証器によるもの）、ループまたは繰り返される失敗の検出（エージェントが進捗なしに同じステップを再試行する）、構造的な曖昧さ（ゴールの複数の有効な解釈）、および機密性シグナル（ネガティブな感情、セーフティキーワード、高価値のアカウント、または規制対象のトピック）があります。各トリガーは、どの人間またはチームに、どの優先度でルーティングするかという決定にマッピングされる必要があります。しきい値は、自動化率とエラー率のトレードオフを規定するものであるため、チームが所有し、実際の結果に照らし合わせてレビューする調整可能なパラメータとして扱います。\\n\\nトリガーが起動すると、エージェントはクリーンなハンドオフを実行する必要があります。つまり、動作を停止し、元のリクエスト、試みたこと、中間結果、現在の最善の推測、およびエスカレーションした理由を含む完全なコンテキストをパッケージ化し、チケットまたはライブハンドオフを介して適切なキューにルーティングします。受け取る人間は、最初から再調査することなく引き継ぐことができる必要があります。コンテキストの品質こそが、エスカレーションを「丸投げ」ではなく「支援」と感じさせる要素です。エンドユーザーには、体験がスムーズに移行するよう、常に適切なフォールバックメッセージ（「専門の担当者にお繋ぎします」など）を提供してください。最後に、適切性を測定しトリガーを再調整できるよう、すべてのエスカレーションをそのトリガーおよび解決策とともにログに記録します。" ], "components": [ "トリガー評価器", "コンテキストパケッジャー", "ルーター", "ハンドオフチャネル", "フォールバック応答器", "監査ログ" ], "benefits": [ "エージェントが自信満々に間違った結果を出す前に、困難なケースが人間に届くため、ミスの影響範囲を最小限に抑えることができます。", "本当に困難なケースのみが引き継がれるため、定型的な業務は自動化されたまま維持され、スタッフは判断を要する業務に集中できます。", "コンテキストを伴うスムーズな引き継ぎにより、ユーザーはたらい回しにされることなくサポートを受けられ、担当者は最初からやり直すことなく業務を再開できます。", "記録されたトリガーと解決策は、規制当局やリスク所有者が実質的な人間による監視に期待する証跡を提供します。" ], "risks": [ "しきい値を保守的に設定しすぎると、簡単なケースまで人間に回されてしまい、自動化によるメリットが失われ、スタッフがノイズに埋もれてしまいます。", "しきい値を緩く設定しすぎると、エージェントが引き継ぐべきケースまで無理に進めてしまい、気付かないうちに悪い結果を招くことになります。", "ペイロード（引き継ぎ情報）が不十分な場合、人間が最初から調査し直すことになり、エスカレーションは支援ではなく、放置されたタスクのように感じられます。", "モデルの自己確信度は実際の正確性と一致しないことが多いため、単純なスコアしきい値では、両方の方向で誤ったケースをエスカレーションしてしまいます。" ], "whenNot": [ "引き継ぎ先となるスタッフの控えるキューやオンコール機能がない場合、エスカレーションの行き先がありません。代わりに、安全停止やリカバリパスに投資してください。", "エージェントがタスクを維持したまま、影響の大きい特定の1ステップのみに承認が必要な場合は、完全な所有権の移転ではなく、人間による承認ゲートを使用してください。", "誤った回答によるコストが発生しない、低コストで容易に差し戻し可能なタスクの場合、エスカレーションのオーバーヘッドと遅延はメリットを上回ります。" ], "examples": [ "サポートエージェントは定型的な質問を解決しますが、不満の検出、役に立たない回答の繰り返し、またはアカウントに影響する機密性の高いリクエストが発生した場合は、会話の全履歴を渡して人間のキューにエスカレーションします。", "保険エージェントは、明確な請求を自動処理し、曖昧な請求、高額な請求、または不正のフラグが立った請求については、調査結果と理由を添付してアジャスターにエスカレーションします。", "自律型コーディングエージェントは、同じテストに繰り返し失敗した場合、処理を空回りさせるのではなく、停止して試行内容とブロックされている箇所を要約し、タスクをエンジニアに引き継ぎます。" ], "kpis": [ { "metric": "エスカレーション率", "note": "人間に引き継がれたタスクの割合。目標値ではなく、トレンドと分布を監視してください。急激な上昇や低下は、トリガーの調整ミスや入力ミックスの変化を示しています。" }, { "metric": "エスカレーションの適切性", "note": "エスカレーションされたケースのうち、本当に人間が必要だったもの（真陽性）と、自動処理できたものの割合。エスカレーションのサンプリングによる人間によるレビューが、最も信頼性の高い把握方法です。" }, { "metric": "エスカレーション漏れ率", "note": "自動解決されたもののうち、後から誤りであることが判明し、エスカレーションすべきだったケースの割合。最も困難でありながら最も重要なシグナルです。これらを発見するには、苦情、再オープン、監査を分析してください。" }, { "metric": "引き継ぎコンテキストの十分性", "note": "引き継ぎを受けた人間が、ユーザーに再連絡したり再調査したりすることなく、どの程度の割合で業務を引き継げるか。パッケージが完全であったかどうかに関するエージェントのフィードバックを通じて追跡します。" } ], "failureModes": [ "一度調整されたきり見直されないトリガーは、入力やモデルの変化に伴って乖離が生じ、自動化とエラーのバランスを気付かないうちに変化させてしまいます。", "ケースが、誰も所有していないキューや、処理能力を超えたキューにルーティングされるため、エスカレーションされたユーザーがいつまでも待たされることになります。これは誤った回答よりも悪質です。", "エスカレーションを回避するように最適化されたエージェントは、誤った自信を表現することを学習し、このパターンが依存しているシグナルそのものを抑制してしまいます。", "引き継ぎによってフォーマット、中間推論、または添付ファイルが失われると、人間が状況を再構築せざるを得なくなり、速度のメリットが失われます。" ], "lessons": [ "確信度シグナルをしきい値として使用する前に、それが実際の正確性と相関していることを検証してください。モデルのスコアを検証器や自己批判と組み合わせてください。", "優れたエスカレーションと不適切なエスカレーションの違いは、ほぼ完全に引き継ぎペイロードにあります。しきい値を調整する前に、そこに投資してください。", "しきい値は、リリース時に固定するのではなく、サンプリングされたエスカレーションやエスカレーション漏れに照らして見直される、チームが所有する動的なパラメータとして扱ってください。", "完璧なトリガーであっても失敗することはあります。適切な保留メッセージと所有者の明確なキューを用意することで、失敗がユーザーの離脱につながるのを防ぐことができます。" ], "faqs": [ { "q": "これは人間による承認ゲートとどう違うのですか？", "a": "承認ゲートは、影響の大きい特定の1つのアクションを一時停止し、人間に承認を求めた後、エージェントが処理を続行します。エスカレーションはタスク全体の所有権を移転します。これ以上進めるべきではないため、エージェントは主導を停止します。『この1つのことを行うべきか？』にはゲートを使用し、『私の手には負えないので、引き継いでください』にはエスカレーションを使用します。" }, { "q": "適切なエスカレーション率はどれくらいですか？", "a": "普遍的な数値はありません。タスクの難易度の組み合わせやエラーのコストによって異なります。目標率ではなく適切性を最適化してください。本当に人間が必要なケースをエスカレーションし、不要な引き継ぎとエスカレーション漏れの両方を最小限に抑えます。エスカレーション率は、それ自体を目標とするのではなく、調整ミスのシグナルとして見直してください。" }, { "q": "モデルの確信度が低いときは、いつでもエスカレーションしてよいですか？", "a": "これは有用なトリガーですが、モデルの自己確信度は実際の正確性と一致しないことが多いため、単独では不十分なことがほとんどです。ループ検出、曖昧さのチェック、感度シグナルと組み合わせ、しきい値を信頼する前に、確信度の測定値が実際に正しい結果と相関していることを検証してください。" } ] }, "zh": { "name": "人工升级", "summary": "当智能体检测到自身无能为力时（置信度低、重复失败、存在歧义或敏感情况），将整个任务移交给人类，并传递完整的上下文，以便人员无需重新调查即可接管。与暂停单个操作以等待签字批准的审批关卡不同，升级会转移所有权，使智能体停止主导。难点在于校准触发器，以避免过度升级和升级不足。", "problem": "自主智能体不可避免地会遇到其无法妥善处理的情况：超出其训练分布的输入、持续无法满足的请求、真正模糊的目标，或者在情感和法律上敏感的时刻。如果它仍然强行推进，就会产生看似自信却错误的答案、陷入死循环或采取有害的操作，而用户发现失败时为时已晚。然而，将所有事情都路由给人类又违背了自动化的初衷，并会让员工不堪重负。系统需要一种规范的方法来识别其能力的边界，并在造成损害之前转移任务。", "context": "只要智能体在进行具有实质自主性的操作，且错误结果的成本超过人类快速浏览的成本，就可以使用此模式：例如客户支持、索赔和案件处理、财务或医疗分诊、内容审核以及运营 Copilot。它假设存在人工队列或值班机制来接收升级，并且智能体能够观察到有关自身表现的信号。当失败是隐性的时候（即看似自信却错误的答案比没有答案更糟糕），以及已知某些子集案例属于困难、罕见或受监管的情况时，该模式最具价值。", "solution": [ "定义明确的升级触发器，并将其作为一等公民（first-class）退出条件接入智能体的主循环中，而不是事后补救。常见的触发器包括置信度低于阈值（来自模型评分、自我批判或验证器）、死循环或重复失败检测（智能体在没有进展的情况下重试同一步骤）、结构性歧义（对目标有多种有效解释）以及敏感性信号（负面情绪、安全关键词、高价值账户或受监管的主题）。每个触发器都应映射到一个路由决策：路由给哪个人员或团队，以及具有什么优先级。将阈值视为由团队拥有的可调参数，并根据实际结果进行审查，因为它们体现了自动化率与错误率之间的权衡。\\n\\n当触发器激活时，智能体必须执行干净的交接：停止操作，打包完整的上下文——原始请求、尝试过的操作、中间结果、当前的最佳猜测以及升级原因——并通过工单或实时交接将其路由到正确的队列。接收的人员应该能够直接接管，而无需从头开始重新调查；上下文的质量决定了升级是真正提供帮助，还是像一次搞砸的交接。始终向终端用户提供友好的回退消息（“我正在为您引入专家”），以便体验平稳降级。最后，记录每次升级及其触发器和解决结果，以便衡量其合理性并重新调整触发器。" ], "components": [ "触发器评估器", "上下文打包器", "路由器", "交接通道", "回退响应器", "审计日志" ], "benefits": [ "棘手的案例会在智能体产生看似自信却错误的结果之前到达人类手中，从而限制了错误的影响范围。", "仅将真正困难的案例进行交接，从而使常规工作保持自动化，让员工专注于需要判断力的事务。", "带有上下文的清晰交接意味着用户能得到切实帮助，而不是被推诿，且人工客服可以直接继续处理而无需重新开始。", "记录在案的触发因素和解决方案提供了监管机构和风险所有者所期望的证据链，以实现有意义的人工监督。" ], "risks": [ "阈值设置过于保守会将简单的案例推给人工，从而抹杀自动化带来的收益，并使员工淹没在噪音中。", "阈值设置过于宽松会导致智能体强行处理本应交接的案例，从而引发隐性的不良后果。", "如果传递的数据（payload）过于单薄，人工人员就必须从头开始重新调查，这会让升级感觉像是被丢弃的任务，而不是协助。", "模型的置信度往往与实际准确率不一致，因此简单的分数阈值会导致双向的错误升级。" ], "whenNot": [ "如果没有配备人员的队列或值班功能来接管，升级将无处可去；此时应转而投资于安全停止或恢复路径。", "当您只需要对某个特定的高影响步骤进行审批，而智能体仍保留该任务时，请使用人工审批关卡，而不是完全转移所有权。", "对于成本低、易于逆转且错误答案无需付出代价的任务，升级带来的开销和延迟将大于其收益。" ], "examples": [ "支持智能体负责解答常规问题，但在检测到用户沮丧情绪、重复出现无用回答或涉及账户敏感的请求时，会升级到人工队列，并传递完整的对话内容。", "保险智能体自动处理明确的理赔，并将含糊不清、高价值或标记为欺诈的理赔升级给理赔员，并附带其调查结果和原因。", "自主编码智能体在重复失败于同一个测试时会停止运行，总结已尝试的操作和受阻的位置，并将任务移交给工程师，而不是无休止地无效循环。" ], "kpis": [ { "metric": "升级率", "note": "移交给人工的任务比例。应关注趋势和分布，而不是单一的目标数值——突然的飙升或下降表明触发器校准有误或输入组合发生了变化。" }, { "metric": "升级合理性", "note": "在升级的案例中，有多少是真正需要人工处理的（真阳性），有多少是本可以自动处理的。对升级案例进行人工抽样审查是最可靠的评估方式。" }, { "metric": "漏升级率", "note": "在自动解决的案例中，事后证明有多少是错误的且本应升级的。这是最难也最重要的信号；可通过挖掘投诉、重新打开的工单和审计来发现它们。" }, { "metric": "交接上下文充分性", "note": "接收人员在无需重新联系用户或重新调查的情况下即可接管工作的频率。通过人工对交接包是否完整提供的反馈来进行跟踪。" } ], "failureModes": [ "一次性调优后便不再维护的触发器会随着输入和模型的改变而脱节，从而在无形中打破自动化与错误之间的平衡。", "案例被路由到无人负责或已超负荷的队列中，导致升级的用户无限期等待——这比得到错误的答案还要糟糕。", "为了避免升级而进行优化的智能体会学会表达虚假的置信度，从而抑制了该模式所依赖的关键信号。", "交接过程丢失了格式、中间推理或附件，迫使人工重新构建场景，从而抹杀了速度优势。" ], "lessons": [ "在根据置信度信号设置阈值之前，先验证其是否与实际准确率相关；将模型评分与验证器或自我批判相结合。", "好升级与坏升级之间的区别几乎完全取决于交接的数据（payload）；在调整阈值之前，应先在这方面进行投入。", "将阈值视为动态参数，根据抽样的升级和漏升级案例进行审查，由团队共同维护，而不是在发布后便一成不变。", "即使是完美的触发器有时也会失效；友好的等待提示和专人负责的队列可以防止失败演变成用户流失。" ], "faqs": [ { "q": "这与人工审批关卡有什么不同？", "a": "审批关卡会暂停某个特定的高影响操作，并要求人工进行审批，通过后智能体继续执行。而升级则会转移整个任务的所有权——智能体停止主导，因为它根本不应该继续进行。对于“我是否应该做这一件事？”使用关卡；对于“我无能为力了，请接管”，则使用升级。" }, { "q": "合适的升级率是多少？", "a": "没有一个通用的数值；这取决于任务难度的组合和错误的成本。应针对合理性进行优化，而不是针对目标率：将真正需要人工的案例进行升级，并尽量减少不必要的交接和漏升级。将升级率视为校准失误的信号，而不是其本身的目标。" }, { "q": "我可以在模型置信度低时直接进行升级吗？", "a": "这是一个有用的触发因素，但仅凭这一点很少足够，因为模型的自我置信度往往与实际准确率不一致。应将其与循环检测、歧义检查和敏感性信号相结合，并在信任某个阈值之前，先验证您的置信度度量是否确实与正确的结果相关。" } ] } } }, { "slug": "least-privilege-tooling", "category": "safety", "updated": "2026-08-22", "version": "1.0", "url": "https://santismm.com/en/patterns/least-privilege-tooling", "api": "https://santismm.com/api/patterns/least-privilege-tooling", "canonical_url": "https://santismm.com/en/patterns/least-privilege-tooling", "api_url": "https://santismm.com/api/patterns/least-privilege-tooling", "evidence": { "evidenceLevel": "production", "confidenceLevel": "high", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "technologies": [ "Scoped API tokens", "Policy engines (OPA / Cedar)", "MCP tool scoping", "Per-tool service accounts", "Audit logging" ], "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "OWASP — LLM01: Prompt Injection", "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "egress-allowlist", "sandboxed-execution", "human-approval-gate", "human-escalation", "recovery-strategy" ], "locales": { "en": { "name": "Least-Privilege Tooling", "summary": "Give an agent the narrowest set of tools, and each tool the narrowest scope, that the task actually needs. The pattern accepts that prompt injection will sometimes succeed and bounds what a hijacked agent can do — you cannot patch the model, but you can decide what it is able to reach.", "definition": "Least-privilege tooling is the practice of scoping an agent's tool catalogue, and each tool's underlying credential, to the minimum the task requires — so the consequences of a successful attack or a model error are bounded by design rather than by the model's compliance.", "problem": "An agent given broad tools and broad credentials turns any successful injection, jailbreak or hallucination into a real action carrying the full reach of the account behind it.", "context": "Use it wherever an agent can act — call APIs, write files, send messages, move money. The more autonomy and the less human review, the more the blast radius has to be set at the permission layer rather than in the prompt.", "solution": [ "Start from the task, not from the platform. List the operations the agent must perform and expose exactly those. A catalogue assembled from 'what the API offers' is a permission grant nobody reviewed.", "Split read from write: separate tools, separate credentials, and no write path reachable by an argument to a read tool. 'Query' endpoints that can also mutate are the most common quiet escalation.", "Scope the credential, not only the tool. A read-only tool backed by an admin token is one bug away from being a write tool; issue per-tool credentials at the narrowest scope the upstream system supports.", "Bound the parameters. Allowlist the paths, repositories, tables, accounts or recipients a tool may address, so a hijacked agent cannot repoint a legitimate tool at an illegitimate target.", "Make grants expire and be reviewed. Tools accumulate; remove what nothing has called, and treat adding a tool as the permission change that it is.", "Log the grant and the call separately. What the agent could do and what it did are two different audits, and an incident needs both." ], "components": [ "A tool catalogue with an explicit, written scope per tool.", "Per-tool credentials issued at the narrowest scope the upstream system offers.", "Parameter allowlists for the targets a tool may address.", "A policy layer that authorises each call independently of the model.", "An audit log covering both grants and invocations.", "A review cadence that removes tools nothing calls." ], "benefits": [ "Bounds the damage of a successful injection without depending on the model behaving well.", "Turns 'is this agent safe?' into a reviewable artefact: a list of tools, scopes and owners.", "Improves tool-selection accuracy as a side effect — fewer, sharper tools are easier for a model to choose between.", "Makes incidents investigable, because the reachable set was known before the incident." ], "risks": [ "Scope creep by convenience: a broad token pasted in while debugging and never narrowed afterwards.", "Fragmentation: dozens of hair-thin tools the model cannot distinguish, trading a security win for a reliability loss.", "False comfort. Least privilege bounds consequences; it does not prevent the attack, and it says nothing about exfiltration through a legitimately granted read tool.", "Process drag: if issuing a scoped credential is harder than reusing a broad one, the process itself becomes the vulnerability." ], "whenNot": [ "Prototypes on synthetic data with no production reach, where the ceremony costs more than the risk it removes.", "When the upstream platform cannot express scopes at all — then the control moves to a proxy in front of it, rather than being declared satisfied.", "When narrowing the agent would push the work onto a human path that is itself less bounded and less audited." ], "examples": [ "A coding agent given a repository token scoped to one repository and one branch prefix, with no organisation-wide read. An injection through a dependency README can still open a branch; it cannot reach the other forty repositories.", "A support agent whose CRM tools are split: read_customer with a read-only key, and update_ticket restricted to tickets already in the conversation. A hijacked session can annoy one ticket, not export the customer base.", "A public MCP server whose entire catalogue is getters over already-published content, backed by no credential at all — there is nothing to revoke because there is nothing to leak." ], "kpis": [ { "metric": "Tools per agent", "note": "The size of the catalogue. Growth without removals is the signal that grants are accumulating unreviewed." }, { "metric": "Write-capable tool share", "note": "How much of the catalogue can change state. The number worth driving toward the minimum the task allows." }, { "metric": "Age of the oldest unused tool", "note": "Days since a granted tool was last called. An old unused grant is reach nobody needs and an attacker inherits." }, { "metric": "Scope documentation coverage", "note": "Share of tools with a written scope and a named owner. An undocumented tool is an unbounded one." } ], "failureModes": [ "The admin token behind the read-only tool: scope declared at the tool layer, unbounded at the credential layer.", "Parameter repointing: the tool is legitimate and the target is not, because nothing constrained the argument.", "Confused deputy: narrowing the tools without narrowing whose authority they run under changes nothing, because the caller still inherits the agent's reach.", "Catalogue drift: tools added for an experiment stay, and the permission set that was reviewed is no longer the one deployed." ], "lessons": [ "Write down the blast radius before granting the tool, not after the incident.", "A tool's name is not its scope. Only the server-side credential is.", "Removing a tool nothing calls is the cheapest security work available.", "Least privilege pays twice: it bounds attacks, and it makes the agent choose tools better." ], "faqs": [ { "q": "Does least privilege stop prompt injection?", "a": "No, and it is not meant to. It assumes injection will sometimes succeed and decides in advance what a successful one can accomplish. Prevention and containment are different jobs; only containment is under your control." }, { "q": "How narrow is too narrow?", "a": "When the model can no longer tell two tools apart, or when a routine task needs four calls that could safely have been one. Splitting improves security until it starts producing wrong tool choices, and a wrong call is its own failure." }, { "q": "We use one service account for everything. Is that so bad?", "a": "It means every agent, and every attacker who reaches one, has the reach of the widest task any of them performs. One account is the version of this pattern where the blast radius is 'all of it'." } ], "productionEvidence": { "context": "The public MCP endpoint for this knowledge base, reachable by any agent on the internet.", "scenario": "The corpus is public and read-only, so the catalogue is entirely getters. There is no tool that writes, no tool that reaches a database the site does not already publish, and no credential reachable from any tool.", "technology": "Stateless JSON-RPC over HTTP on a Next.js route handler, origin allowlist checked before any handler runs, per-caller rate limiting in Redis, structured per-call audit logging.", "load": "Continuous unattended agent traffic since launch, plus registry crawlers and directory health checks.", "results": "A client of this server that is hijacked by prompt injection can obtain nothing it could not have fetched from the public site, because the reachable set is exactly the published corpus. There is no credential to revoke and no write path to abuse." } }, "es": { "name": "Herramientas con Mínimo Privilegio", "summary": "Dale al agente el conjunto de herramientas más estrecho, y a cada herramienta el alcance más estrecho, que la tarea realmente necesita. El patrón asume que la inyección de prompts a veces tendrá éxito y acota lo que un agente secuestrado puede hacer: no puedes parchear el modelo, pero sí decidir a qué es capaz de llegar.", "definition": "Las herramientas con mínimo privilegio son la práctica de acotar el catálogo de herramientas de un agente, y la credencial que hay bajo cada una, al mínimo que la tarea requiere, de modo que las consecuencias de un ataque con éxito o de un error del modelo queden acotadas por diseño y no por la obediencia del modelo.", "problem": "Un agente con herramientas amplias y credenciales amplias convierte cualquier inyección, jailbreak o alucinación con éxito en una acción real con todo el alcance de la cuenta que hay detrás.", "context": "Úsalo allí donde un agente pueda actuar: llamar APIs, escribir ficheros, enviar mensajes, mover dinero. Cuanta más autonomía y menos revisión humana, más hay que fijar el radio de impacto en la capa de permisos y no en el prompt.", "solution": [ "Parte de la tarea, no de la plataforma. Lista las operaciones que el agente debe realizar y expón exactamente esas. Un catálogo montado a partir de «lo que ofrece la API» es una concesión de permisos que nadie revisó.", "Separa lectura de escritura: herramientas distintas, credenciales distintas y ninguna ruta de escritura alcanzable por un argumento de una herramienta de lectura. Los endpoints de «consulta» que además mutan son la escalada silenciosa más común.", "Acota la credencial, no solo la herramienta. Una herramienta de solo lectura respaldada por un token de administrador está a un bug de ser una herramienta de escritura; emite credenciales por herramienta con el alcance más estrecho que soporte el sistema de arriba.", "Acota los parámetros. Pon en lista de permitidos las rutas, repositorios, tablas, cuentas o destinatarios a los que una herramienta puede dirigirse, para que un agente secuestrado no pueda reapuntar una herramienta legítima a un objetivo ilegítimo.", "Haz que las concesiones caduquen y se revisen. Las herramientas se acumulan; retira lo que nadie invoca y trata añadir una herramienta como el cambio de permisos que es.", "Registra la concesión y la llamada por separado. Lo que el agente podía hacer y lo que hizo son dos auditorías distintas, y un incidente necesita las dos." ], "components": [ "Un catálogo de herramientas con un alcance explícito y escrito por herramienta.", "Credenciales por herramienta emitidas con el alcance más estrecho que ofrezca el sistema de arriba.", "Listas de permitidos de parámetros para los objetivos a los que una herramienta puede dirigirse.", "Una capa de política que autoriza cada llamada con independencia del modelo.", "Un log de auditoría que cubra tanto concesiones como invocaciones.", "Una cadencia de revisión que retire las herramientas que nadie invoca." ], "benefits": [ "Acota el daño de una inyección con éxito sin depender de que el modelo se porte bien.", "Convierte «¿es seguro este agente?» en un artefacto revisable: una lista de herramientas, alcances y responsables.", "Mejora de rebote la precisión al elegir herramienta: menos herramientas y más nítidas son más fáciles de distinguir para un modelo.", "Hace investigables los incidentes, porque el conjunto alcanzable se conocía antes del incidente." ], "risks": [ "Ampliación por comodidad: un token amplio pegado durante una depuración y nunca estrechado después.", "Fragmentación: decenas de herramientas finísimas que el modelo no sabe distinguir, cambiando una victoria de seguridad por una pérdida de fiabilidad.", "Falsa tranquilidad. El mínimo privilegio acota consecuencias; no evita el ataque, y no dice nada sobre la exfiltración a través de una herramienta de lectura legítimamente concedida.", "Fricción de proceso: si emitir una credencial acotada cuesta más que reutilizar una amplia, el proceso se convierte en la vulnerabilidad." ], "whenNot": [ "Prototipos sobre datos sintéticos sin alcance a producción, donde la ceremonia cuesta más que el riesgo que elimina.", "Cuando la plataforma de arriba no sabe expresar alcances: entonces el control se mueve a un proxy delante, en lugar de darse por satisfecho.", "Cuando estrechar al agente empujaría el trabajo a una vía humana que está peor acotada y peor auditada." ], "examples": [ "Un agente de programación con un token de repositorio acotado a un repositorio y un prefijo de rama, sin lectura a nivel de organización. Una inyección por el README de una dependencia todavía puede abrir una rama; no puede llegar a los otros cuarenta repositorios.", "Un agente de soporte con las herramientas de CRM separadas: read_customer con una clave de solo lectura y update_ticket restringida a los tickets ya presentes en la conversación. Una sesión secuestrada puede molestar a un ticket, no exportar la base de clientes.", "Un servidor MCP público cuyo catálogo entero son getters sobre contenido ya publicado, respaldado por ninguna credencial: no hay nada que revocar porque no hay nada que filtrar." ], "kpis": [ { "metric": "Herramientas por agente", "note": "El tamaño del catálogo. Crecer sin retirar es la señal de que las concesiones se acumulan sin revisión." }, { "metric": "Porcentaje de herramientas con escritura", "note": "Cuánto del catálogo puede cambiar estado. El número que conviene llevar al mínimo que la tarea permita." }, { "metric": "Antigüedad de la herramienta sin uso más vieja", "note": "Días desde la última invocación de una herramienta concedida. Una concesión vieja sin uso es alcance que nadie necesita y que un atacante hereda." }, { "metric": "Cobertura de alcance documentado", "note": "Porcentaje de herramientas con alcance escrito y responsable con nombre. Una herramienta sin documentar es una herramienta sin acotar." } ], "failureModes": [ "El token de administrador detrás de la herramienta de solo lectura: alcance declarado en la capa de herramienta, sin acotar en la capa de credencial.", "Reapuntado de parámetros: la herramienta es legítima y el objetivo no, porque nada restringió el argumento.", "Diputado confundido: estrechar las herramientas sin estrechar bajo qué autoridad corren no cambia nada, porque quien llama sigue heredando el alcance del agente.", "Deriva del catálogo: las herramientas añadidas para un experimento se quedan, y el conjunto de permisos que se revisó ya no es el desplegado." ], "lessons": [ "Escribe el radio de impacto antes de conceder la herramienta, no después del incidente.", "El nombre de una herramienta no es su alcance. Solo lo es la credencial del lado servidor.", "Retirar una herramienta que nadie invoca es el trabajo de seguridad más barato que existe.", "El mínimo privilegio paga dos veces: acota ataques y hace que el agente elija mejor sus herramientas." ], "faqs": [ { "q": "¿El mínimo privilegio detiene la inyección de prompts?", "a": "No, ni pretende hacerlo. Asume que a veces tendrá éxito y decide de antemano qué puede conseguir un ataque exitoso. Prevenir y contener son trabajos distintos, y solo contener está bajo tu control." }, { "q": "¿Cuánto es demasiado estrecho?", "a": "Cuando el modelo ya no distingue dos herramientas, o cuando una tarea rutinaria necesita cuatro llamadas que podrían haber sido una con seguridad. Dividir mejora hasta que empieza a producir elecciones erróneas, y una llamada equivocada es un fallo por derecho propio." }, { "q": "Usamos una sola cuenta de servicio para todo, ¿tan malo es?", "a": "Significa que cada agente, y cada atacante que llegue a uno, tiene el alcance de la tarea más amplia que realice cualquiera de ellos. Una sola cuenta es la versión de este patrón en la que el radio de impacto es «todo»." } ], "productionEvidence": { "context": "El endpoint MCP público de esta base de conocimiento, accesible para cualquier agente de internet.", "scenario": "El corpus es público y de solo lectura, así que el catálogo son íntegramente getters. No hay herramienta que escriba, ninguna que llegue a datos que el sitio no publique ya y ninguna credencial alcanzable desde una herramienta.", "technology": "JSON-RPC sin estado sobre HTTP en un route handler de Next.js, lista de orígenes permitidos comprobada antes de ejecutar ningún handler, límite de tasa por llamante en Redis y log de auditoría estructurado por llamada.", "load": "Tráfico continuo y desatendido de agentes desde el lanzamiento, más rastreadores de registros y comprobaciones de salud de directorios.", "results": "Un cliente de este servidor secuestrado por inyección de prompts no puede obtener nada que no pudiera haber descargado del sitio público, porque el conjunto alcanzable es exactamente el corpus publicado. No hay credencial que revocar ni ruta de escritura que abusar." } }, "pt": { "name": "Ferramentas com Privilégio Mínimo", "summary": "Dê ao agente o conjunto de ferramentas mais estreito, e a cada ferramenta o escopo mais estreito, que a tarefa realmente exige. O padrão assume que a injeção de prompts às vezes terá êxito e limita o que um agente sequestrado pode fazer: você não consegue corrigir o modelo, mas consegue decidir o que ele é capaz de alcançar.", "definition": "Ferramentas com privilégio mínimo são a prática de restringir o catálogo de ferramentas de um agente, e a credencial por trás de cada uma, ao mínimo que a tarefa exige — de modo que as consequências de um ataque bem-sucedido ou de um erro do modelo fiquem limitadas por design, e não pela obediência do modelo.", "problem": "Um agente com ferramentas amplas e credenciais amplas transforma qualquer injeção, jailbreak ou alucinação bem-sucedida em uma ação real com todo o alcance da conta por trás dela.", "context": "Use onde um agente puder agir: chamar APIs, escrever arquivos, enviar mensagens, movimentar dinheiro. Quanto mais autonomia e menos revisão humana, mais o raio de impacto precisa ser definido na camada de permissões e não no prompt.", "solution": [ "Parta da tarefa, não da plataforma. Liste as operações que o agente precisa executar e exponha exatamente essas. Um catálogo montado a partir de “o que a API oferece” é uma concessão de permissões que ninguém revisou.", "Separe leitura de escrita: ferramentas distintas, credenciais distintas e nenhum caminho de escrita alcançável por um argumento de uma ferramenta de leitura. Endpoints de “consulta” que também mutam são a escalada silenciosa mais comum.", "Restrinja a credencial, não apenas a ferramenta. Uma ferramenta somente leitura apoiada por um token de administrador está a um bug de virar ferramenta de escrita; emita credenciais por ferramenta com o escopo mais estreito que o sistema a montante suporte.", "Limite os parâmetros. Coloque em lista de permitidos os caminhos, repositórios, tabelas, contas ou destinatários que uma ferramenta pode endereçar, para que um agente sequestrado não consiga reapontar uma ferramenta legítima para um alvo ilegítimo.", "Faça as concessões expirarem e serem revisadas. Ferramentas se acumulam; remova o que ninguém invoca e trate adicionar uma ferramenta como a mudança de permissão que ela é.", "Registre a concessão e a chamada separadamente. O que o agente podia fazer e o que ele fez são duas auditorias diferentes, e um incidente precisa das duas." ], "components": [ "Um catálogo de ferramentas com escopo explícito e escrito por ferramenta.", "Credenciais por ferramenta emitidas no escopo mais estreito que o sistema a montante oferecer.", "Listas de permitidos de parâmetros para os alvos que uma ferramenta pode endereçar.", "Uma camada de política que autoriza cada chamada independentemente do modelo.", "Um log de auditoria cobrindo tanto concessões quanto invocações.", "Uma cadência de revisão que remove as ferramentas que ninguém chama." ], "benefits": [ "Limita o dano de uma injeção bem-sucedida sem depender de o modelo se comportar.", "Transforma “este agente é seguro?” em um artefato revisável: uma lista de ferramentas, escopos e responsáveis.", "Melhora de tabela a precisão na escolha de ferramenta: menos ferramentas e mais nítidas são mais fáceis de distinguir para um modelo.", "Torna incidentes investigáveis, porque o conjunto alcançável já era conhecido antes do incidente." ], "risks": [ "Ampliação por conveniência: um token amplo colado durante uma depuração e nunca estreitado depois.", "Fragmentação: dezenas de ferramentas finíssimas que o modelo não distingue, trocando um ganho de segurança por uma perda de confiabilidade.", "Falsa tranquilidade. O privilégio mínimo limita consequências; não evita o ataque, e nada diz sobre exfiltração por uma ferramenta de leitura legitimamente concedida.", "Atrito de processo: se emitir uma credencial restrita custa mais do que reutilizar uma ampla, o processo vira a vulnerabilidade." ], "whenNot": [ "Protótipos sobre dados sintéticos sem alcance à produção, onde a cerimônia custa mais do que o risco que elimina.", "Quando a plataforma a montante não sabe expressar escopos: aí o controle se muda para um proxy à frente, em vez de ser dado por satisfeito.", "Quando estreitar o agente empurraria o trabalho para uma via humana pior limitada e pior auditada." ], "examples": [ "Um agente de programação com um token de repositório restrito a um repositório e a um prefixo de branch, sem leitura no nível da organização. Uma injeção pelo README de uma dependência ainda pode abrir um branch; não alcança os outros quarenta repositórios.", "Um agente de suporte com as ferramentas de CRM separadas: read_customer com uma chave somente leitura e update_ticket restrita aos chamados já presentes na conversa. Uma sessão sequestrada pode incomodar um chamado, não exportar a base de clientes.", "Um servidor MCP público cujo catálogo inteiro são getters sobre conteúdo já publicado, apoiado por nenhuma credencial: não há o que revogar porque não há o que vazar." ], "kpis": [ { "metric": "Ferramentas por agente", "note": "O tamanho do catálogo. Crescer sem remover é o sinal de que as concessões se acumulam sem revisão." }, { "metric": "Percentual de ferramentas com escrita", "note": "Quanto do catálogo pode alterar estado. O número que vale a pena levar ao mínimo que a tarefa permitir." }, { "metric": "Idade da ferramenta sem uso mais antiga", "note": "Dias desde a última invocação de uma ferramenta concedida. Uma concessão antiga sem uso é alcance que ninguém precisa e que um atacante herda." }, { "metric": "Cobertura de escopo documentado", "note": "Percentual de ferramentas com escopo escrito e responsável nomeado. Uma ferramenta sem documentação é uma ferramenta sem limite." } ], "failureModes": [ "O token de administrador atrás da ferramenta somente leitura: escopo declarado na camada de ferramenta, ilimitado na camada de credencial.", "Reapontamento de parâmetros: a ferramenta é legítima e o alvo não é, porque nada restringiu o argumento.", "Deputado confuso: estreitar as ferramentas sem estreitar sob qual autoridade elas rodam não muda nada, porque quem chama continua herdando o alcance do agente.", "Deriva do catálogo: as ferramentas adicionadas para um experimento ficam, e o conjunto de permissões revisado já não é o implantado." ], "lessons": [ "Escreva o raio de impacto antes de conceder a ferramenta, não depois do incidente.", "O nome de uma ferramenta não é o escopo dela. Só a credencial do lado servidor é.", "Remover uma ferramenta que ninguém chama é o trabalho de segurança mais barato que existe.", "O privilégio mínimo paga duas vezes: limita ataques e faz o agente escolher melhor as ferramentas." ], "faqs": [ { "q": "O privilégio mínimo impede a injeção de prompts?", "a": "Não, e não é essa a intenção. Ele assume que a injeção às vezes vai funcionar e decide de antemão o que um ataque bem-sucedido consegue realizar. Prevenir e conter são trabalhos diferentes, e só conter está sob o seu controle." }, { "q": "Quão estreito é estreito demais?", "a": "Quando o modelo já não distingue duas ferramentas, ou quando uma tarefa rotineira precisa de quatro chamadas que poderiam com segurança ter sido uma. Dividir melhora até começar a produzir escolhas erradas, e uma chamada errada é uma falha por si só." }, { "q": "Usamos uma única conta de serviço para tudo. É tão ruim assim?", "a": "Significa que cada agente, e cada atacante que alcançar um deles, tem o alcance da tarefa mais ampla que qualquer um deles executa. Uma única conta é a versão deste padrão em que o raio de impacto é “tudo”." } ], "productionEvidence": { "context": "O endpoint MCP público desta base de conhecimento, acessível a qualquer agente na internet.", "scenario": "O corpus é público e somente leitura, então o catálogo é inteiramente de getters. Não há ferramenta que escreva, nenhuma que alcance dados que o site já não publique e nenhuma credencial alcançável a partir de uma ferramenta.", "technology": "JSON-RPC sem estado sobre HTTP em um route handler do Next.js, lista de origens permitidas verificada antes de qualquer handler rodar, limite de taxa por chamador em Redis e log de auditoria estruturado por chamada.", "load": "Tráfego contínuo e não assistido de agentes desde o lançamento, mais rastreadores de registries e verificações de saúde de diretórios.", "results": "Um cliente deste servidor sequestrado por injeção de prompts não obtém nada que não pudesse ter baixado do site público, porque o conjunto alcançável é exatamente o corpus publicado. Não há credencial a revogar nem caminho de escrita a abusar." } }, "fr": { "name": "Outils de moindre privilège", "summary": "Attribuez à un agent l'ensemble d'outils le plus restreint, et à chaque outil la portée la plus étroite, dont la tâche a réellement besoin. Ce modèle accepte le fait que l'injection de prompt réussira parfois et limite ce qu'un agent compromis peut faire — vous ne pouvez pas corriger le modèle, mais vous pouvez décider de ce qu'il est capable d'atteindre.", "definition": "La mise en œuvre d'outils de moindre privilège consiste à restreindre le catalogue d'outils d'un agent, ainsi que les identifiants sous-jacents de chaque outil, au strict minimum requis par la tâche — de sorte que les conséquences d'une attaque réussie ou d'une erreur de modèle soient limitées par conception plutôt que par la conformité du modèle.", "problem": "Un agent doté d'outils et d'identifiants étendus transforme toute injection, jailbreak ou hallucination réussie en une action réelle disposant de toute la portée du compte associé.", "context": "Utilisez ce modèle partout où un agent peut agir — appeler des API, écrire des fichiers, envoyer des messages, transférer de l'argent. Plus l'autonomie est grande et moins il y a de contrôle humain, plus le rayon d'impact doit être défini au niveau de la couche d'autorisation plutôt que dans le prompt.", "solution": [ "Partez de la tâche, pas de la plateforme. Listez les opérations que l'agent doit effectuer et exposez précisément celles-ci. Un catalogue assemblé à partir de « ce que propose l'API » constitue une attribution d'autorisations que personne n'a examinée.", "Séparez la lecture de l'écriture : outils distincts, identifiants distincts, et aucun chemin d'écriture accessible via un argument d'un outil de lecture. Les points de terminaison de « requête » qui peuvent également modifier des données constituent l'escalade silencieuse la plus courante.", "Limitez la portée de l'identifiant, pas seulement de l'outil. Un outil en lecture seule s'appuyant sur un jeton d'administration n'est qu'à un bug près de devenir un outil d'écriture ; émettez des identifiants par outil avec la portée la plus étroite prise en charge par le système amont.", "Limitez les paramètres. Autorisez explicitement (allowlist) les chemins, dépôts, tables, comptes ou destinataires qu'un outil peut cibler, afin qu'un agent compromis ne puisse pas rediriger un outil légitime vers une cible illégitime.", "Faites en sorte que les autorisations expirent et soient réévaluées. Les outils s'accumulent ; supprimez ceux qui ne sont jamais appelés et considérez l'ajout d'un outil comme la modification d'autorisation qu'il représente réellement.", "Enregistrez l'autorisation et l'appel séparément. Ce que l'agent pouvait faire et ce qu'il a fait constituent deux audits d'incidents différents, et la résolution d'un incident nécessite les deux." ], "components": [ "Un catalogue d'outils avec une portée explicite et écrite pour chaque outil.", "Des identifiants par outil émis avec la portée la plus étroite proposée par le système amont.", "Des listes d'autorisation (allowlists) de paramètres pour les cibles qu'un outil peut adresser.", "Une couche de politique qui autorise chaque appel indépendamment du modèle.", "Un journal d'audit couvrant à la fois les autorisations et les appels.", "Un rythme de réévaluation qui supprime les outils qu'aucun élément n'appelle." ], "benefits": [ "Limite les dommages d'une injection réussie sans dépendre du bon comportement du modèle.", "Transforme la question « cet agent est-il sûr ? » en un artefact vérifiable : une liste d'outils, de portées et de propriétaires.", "Améliore la précision de la sélection des outils comme effet secondaire — il est plus facile pour un modèle de choisir parmi des outils moins nombreux et plus précis.", "Rend les incidents analysables, car l'ensemble accessible était connu avant l'incident." ], "risks": [ "Dérive de la portée par commodité : un jeton étendu collé pendant le débogage et jamais restreint par la suite.", "Fragmentation : des dizaines d'outils extrêmement spécifiques que le modèle ne parvient pas à distinguer, troquant un gain de sécurité contre une perte de fiabilité.", "Faux sentiment de sécurité. Le moindre privilège limite les conséquences ; il n'empêche pas l'attaque et ne dit rien sur l'exfiltration via un outil de lecture légitimement autorisé.", "Lenteur des processus : si l'émission d'un identifiant restreint est plus difficile que la réutilisation d'un identifiant étendu, le processus lui-même devient la vulnérabilité." ], "whenNot": [ "Prototypes sur des données synthétiques sans accès à la production, où le formalisme coûte plus cher que le risque qu'il élimine.", "Lorsque la plateforme amont ne peut pas du tout exprimer de portées — le contrôle se déplace alors vers un proxy placé devant elle, plutôt que d'être considéré comme résolu.", "Lorsque restreindre l'agent reviendrait à transférer le travail vers un parcours humain qui est lui-même moins limité et moins audité." ], "examples": [ "Un agent de codage disposant d'un jeton de dépôt limité à un seul dépôt et à un seul préfixe de branche, sans accès en lecture à l'échelle de l'organisation. Une injection via le fichier README d'une dépendance peut toujours ouvrir une branche, mais elle ne peut pas accéder aux quarante autres dépôts.", "Un agent de support dont les outils CRM sont séparés : read_customer avec une clé en lecture seule, et update_ticket restreint aux tickets déjà présents dans la conversation. Une session détournée peut perturber un ticket, mais pas exporter la base de clients.", "Un serveur MCP public dont l'ensemble du catalogue est constitué d'accesseurs (getters) sur du contenu déjà publié, sans aucun identifiant d'accès associé — il n'y a rien à révoquer car il n'y a rien à divulguer." ], "kpis": [ { "metric": "Outils par agent", "note": "La taille du catalogue. Une croissance sans suppressions indique que les autorisations s'accumulent sans être passées en revue." }, { "metric": "Part des outils disposant de droits d'écriture", "note": "La proportion du catalogue capable de modifier l'état. Un indicateur qu'il convient de réduire au strict minimum requis par la tâche." }, { "metric": "Âge de l'outil inutilisé le plus ancien", "note": "Nombre de jours écoulés depuis le dernier appel d'un outil autorisé. Une ancienne autorisation inutilisée représente un accès inutile dont un attaquant pourrait hériter." }, { "metric": "Couverture de la documentation des portées", "note": "Part des outils disposant d'une portée documentée et d'un propriétaire désigné. Un outil non documenté est un outil sans limites." } ], "failureModes": [ "Le jeton d'administration derrière l'outil en lecture seule : portée déclarée au niveau de l'outil, mais illimitée au niveau des identifiants.", "Redirection de paramètre : l'outil est légitime mais la cible ne l'est pas, car rien ne contraignait l'argument.", "Député confus (confused deputy) : restreindre les outils sans restreindre l'autorité sous laquelle ils s'exécutent ne change rien, car l'appelant hérite toujours de la portée de l'agent.", "Dérive du catalogue : les outils ajoutés pour une expérimentation restent en place, et l'ensemble de permissions initialement validé ne correspond plus à celui qui est déployé." ], "lessons": [ "Définissez le rayon d'impact par écrit avant d'autoriser l'outil, et non après l'incident.", "Le nom d'un outil ne définit pas sa portée. Seul l'identifiant côté serveur le fait.", "Supprimer un outil que personne n'appelle est l'action de sécurité la plus économique qui soit.", "Le moindre privilège est doublement rentable : il limite les attaques et permet à l'agent de mieux choisir ses outils." ], "faqs": [ { "q": "Le moindre privilège permet-il d'empêcher l'injection de requêtes (prompt injection) ?", "a": "Non, et ce n'est pas son but. Il part du principe que l'injection réussira parfois et détermine à l'avance ce qu'une attaque réussie peut accomplir. La prévention et le confinement sont deux tâches distinctes ; seul le confinement est sous votre contrôle." }, { "q": "À partir de quand une restriction devient-elle excessive ?", "a": "Lorsque le modèle ne parvient plus à distinguer deux outils, ou lorsqu'une tâche courante nécessite quatre appels qui auraient pu, en toute sécurité, n'en faire qu'un. Diviser améliore la sécurité jusqu'à ce que cela provoque de mauvais choix d'outils, et un appel erroné constitue un échec en soi." }, { "q": "Nous utilisons un seul compte de service pour tout. Est-ce si grave ?", "a": "Cela signifie que chaque agent, et chaque attaquant qui en compromet un, dispose de la portée de la tâche la plus large exécutée par l'un d'eux. Utiliser un compte unique revient à appliquer ce modèle avec un rayon d'impact égal à « l'intégralité du système »." } ], "productionEvidence": { "context": "Le point de terminaison MCP public de cette base de connaissances, accessible par n'importe quel agent sur Internet.", "scenario": "Le corpus étant public et en lecture seule, le catalogue est entièrement composé d'accesseurs (getters). Aucun outil n'effectue d'écriture, aucun outil n'accède à une base de données que le site ne publie pas déjà, et aucun identifiant n'est accessible depuis un outil.", "technology": "JSON-RPC sans état sur HTTP via un gestionnaire de route Next.js, liste d'autorisation d'origine vérifiée avant l'exécution de tout gestionnaire, limitation du débit par appelant dans Redis, journalisation d'audit structurée par appel.", "load": "Trafic continu d'agents autonomes depuis le lancement, ainsi que des robots d'indexation de registres et des vérifications de l'état des répertoires.", "results": "Un client de ce serveur détourné par injection de requêtes ne peut rien obtenir qu'il n'aurait pu récupérer sur le site public, car l'ensemble accessible correspond exactement au corpus publié. Il n'y a aucun identifiant à révoquer ni aucun chemin d'écriture à exploiter." } }, "de": { "name": "Least-Privilege-Tooling", "summary": "Geben Sie einem Agenten die minimal erforderliche Auswahl an Tools und jedem Tool den engsten Scope, den die Aufgabe tatsächlich benötigt. Das Pattern akzeptiert, dass Prompt Injections manchmal erfolgreich sein werden, und begrenzt, was ein gekaperter Agent tun kann – Sie können das Modell nicht patchen, aber Sie können entscheiden, worauf es zugreifen darf.", "definition": "Least-Privilege-Tooling bezeichnet die Praxis, den Tool-Katalog eines Agenten und die den einzelnen Tools zugrunde liegenden Anmeldedaten auf das für die Aufgabe erforderliche Minimum zu beschränken. So werden die Folgen eines erfolgreichen Angriffs oder eines Modellfehlers durch das Systemdesign begrenzt und hängen nicht von der Compliance des Modells ab.", "problem": "Ein Agent mit weitreichenden Tools und Berechtigungen verwandelt jede erfolgreiche Injection, jeden Jailbreak oder jede Halluzination in eine reale Aktion, die den vollen Zugriffsumfang des dahinterstehenden Kontos nutzt.", "context": "Nutzen Sie dieses Pattern überall dort, wo umsetzbare Aktionen ausgeführt werden – beim Aufrufen von APIs, Schreiben von Dateien, Senden von Nachrichten oder Überweisen von Geld. Je mehr Autonomie und je weniger menschliche Überprüfung vorhanden ist, desto dringender muss der Schadensradius auf der Berechtigungsebene statt im Prompt begrenzt werden.", "solution": [ "Gehen Sie von der Aufgabe aus, nicht von der Plattform. Listen Sie die Operationen auf, die der Agent ausführen muss, und geben Sie genau diese frei. Ein Katalog, der einfach aus dem zusammengestellt wird, „was die API bietet“, ist eine Berechtigungserteilung, die niemand überprüft hat.", "Trennen Sie Lese- von Schreibvorgängen: separate Tools, separate Anmeldedaten und kein Schreibpfad, der über ein Argument eines Lese-Tools erreichbar ist. „Query“-Endpunkte, die auch Mutationen durchführen können, sind das häufigste Einfallstor für unbemerkte Rechteausweitung.", "Beschränken Sie die Anmeldedaten, nicht nur das Tool. Ein Nur-Lese-Tool, das mit einem Admin-Token hinterlegt ist, ist nur einen Bug davon entfernt, ein Schreib-Tool zu sein; stellen Sie Anmeldedaten pro Tool mit dem engsten Scope aus, den das vorgeschaltete System unterstützt.", "Begrenzen Sie die Parameter. Setzen Sie Pfade, Repositories, Tabellen, Konten oder Empfänger, die ein Tool ansprechen darf, auf eine Allowlist, damit ein gekaperter Agent ein legitimes Tool nicht auf ein illegitimes Ziel umleiten kann.", "Lassen Sie Berechtigungen ablaufen und überprüfen Sie diese regelmäßig. Tools sammeln sich an; entfernen Sie, was nicht aufgerufen wurde, und behandeln Sie das Hinzufügen eines Tools als die Berechtigungsänderung, die es tatsächlich ist.", "Protokollieren Sie die Berechtigungserteilung und den Aufruf separat. Was der Agent tun durfte und was er tatsächlich getan hat, sind zwei verschiedene Audits – und bei einem Vorfall werden beide benötigt." ], "components": [ "Ein Tool-Katalog mit einem expliziten, schriftlich festgelegten Scope pro Tool.", "Pro Tool ausgestellte Anmeldedaten mit dem engsten Scope, den das vorgeschaltete System bietet.", "Parameter-Allowlists für die Ziele, die ein Tool ansprechen darf.", "Ein Policy-Layer, der jeden Aufruf unabhängig vom Modell autorisiert.", "Ein Audit-Log, das sowohl Berechtigungserteilungen als auch Aufrufe abdeckt.", "Ein Überprüfungszyklus, der Tools entfernt, die nicht aufgerufen werden." ], "benefits": [ "Begrenzt den Schaden einer erfolgreichen Injection, ohne darauf angewiesen zu sein, dass sich das Modell korrekt verhält.", "Verwandelt die Frage „Ist dieser Agent sicher?“ in ein überprüfbares Artefakt: eine Liste von Tools, Scopes und Verantwortlichen.", "Verbessert als Nebeneffekt die Genauigkeit bei der Tool-Auswahl – zwischen weniger, präziser definierten Tools kann ein Modell leichter wählen.", "Macht Vorfälle untersuchbar, da die erreichbare Menge bereits vor dem Vorfall bekannt war." ], "risks": [ "Scope Creep aus Bequemlichkeit: Ein weitreichender Token, der beim Debugging eingefügt und danach nie wieder eingeschränkt wurde.", "Fragmentierung: Dutzende extrem feingliedrige Tools, die das Modell nicht voneinander unterscheiden kann, wodurch ein Sicherheitsgewinn gegen einen Zuverlässigkeitsverlust eingetauscht wird.", "Trügerische Sicherheit. Least Privilege begrenzt die Folgen; es verhindert nicht den Angriff und schützt nicht vor Datenabfluss (Exfiltration) über ein legitim freigegebenes Lese-Tool.", "Prozessverzögerung: Wenn das Ausstellen spezifisch eingeschränkter Anmeldedaten schwieriger ist als die Wiederverwendung weitreichender Daten, wird der Prozess selbst zur Schwachstelle." ], "whenNot": [ "Prototypen auf synthetischen Daten ohne Produktionszugriff, bei denen der Aufwand die damit verringerten Risiken übersteigt.", "Wenn das vorgeschaltete System Scopes überhaupt nicht abbilden kann – in diesem Fall verlagert sich die Kontrolle auf einen vorgeschalteten Proxy, anstatt die Anforderung als erfüllt zu betrachten.", "Wenn die Einschränkung des Agenten die Arbeit auf einen menschlichen Pfad verlagern würde, der selbst weniger begrenzt und weniger auditiert ist." ], "examples": [ "Ein Coding-Agent, der ein Repository-Token erhält, das auf ein einziges Repository und ein einziges Branch-Präfix beschränkt ist, ohne organisationsweiten Lesezugriff. Eine Injection über die README einer Abhängigkeit kann zwar immer noch einen Branch erstellen, aber nicht auf die anderen vierzig Repositories zugreifen.", "Ein Support-Agent, dessen CRM-Tools aufgeteilt sind: `read_customer` mit einem schreibgeschützten Schlüssel und `update_ticket` beschränkt auf Tickets, die sich bereits in der Konversation befinden. Eine gekaperte Sitzung kann ein einzelnes Ticket stören, aber nicht den gesamten Kundenstamm exportieren.", "Ein öffentlicher MCP-Server, dessen gesamter Katalog aus Gettern für bereits veröffentlichte Inhalte besteht und der keinerlei Anmeldedaten benötigt – es gibt nichts zu widerrufen, da nichts durchsickern kann." ], "kpis": [ { "metric": "Tools pro Agent", "note": "Die Größe des Katalogs. Ein Wachstum ohne Bereinigungen ist das Signal dafür, dass sich Berechtigungen ungeprüft ansammeln." }, { "metric": "Anteil schreibberechtigter Tools", "note": "Wie viel des Katalogs den Zustand ändern kann. Der Wert, den man auf das für die Aufgabe erforderliche Minimum reduzieren sollte." }, { "metric": "Alter des ältesten ungenutzten Tools", "note": "Tage seit dem letzten Aufruf eines freigegebenen Tools. Eine alte, ungenutzte Freigabe ist eine Reichweite, die niemand benötigt und die ein Angreifer übernimmt." }, { "metric": "Dokumentationsabdeckung des Scopes", "note": "Anteil der Tools mit schriftlich definiertem Scope und benanntem Owner. Ein undokumentiertes Tool ist ein unbegrenztes Tool." } ], "failureModes": [ "Das Admin-Token hinter dem schreibgeschützten Tool: Der Scope ist auf der Tool-Ebene deklariert, aber auf der Credential-Ebene unbegrenzt.", "Parameter-Repointing: Das Tool ist legitim, das Ziel jedoch nicht, da das Argument durch nichts eingeschränkt wurde.", "Confused Deputy: Das Einschränken der Tools ohne Einschränkung der Autorität, unter der sie ausgeführt werden, ändert nichts, da der Aufrufer weiterhin die Reichweite des Agenten erbt.", "Katalog-Drift: Für ein Experiment hinzugefügte Tools bleiben bestehen, und das überprüfte Berechtigungsset entspricht nicht mehr dem bereitgestellten." ], "lessons": [ "Definieren Sie den Explosionsradius (Blast Radius) vor der Freigabe des Tools, nicht erst nach dem Vorfall.", "Der Name eines Tools ist nicht sein Scope. Das sind nur die serverseitigen Anmeldedaten.", "Das Entfernen eines Tools, das von nichts aufgerufen wird, ist die günstigste Sicherheitsmaßnahme überhaupt.", "Least Privilege zahlt sich doppelt aus: Es begrenzt Angriffe und sorgt dafür, dass der Agent Tools besser auswählt." ], "faqs": [ { "q": "Verhindert Least Privilege Prompt Injection?", "a": "Nein, und das soll es auch nicht. Es setzt voraus, dass Injections manchmal erfolgreich sein werden, und legt im Vorfeld fest, was ein erfolgreicher Angriff ausrichten kann. Prävention und Schadensbegrenzung (Containment) sind unterschiedliche Aufgaben; nur die Schadensbegrenzung liegt in Ihrer Hand." }, { "q": "Wie eng ist zu eng?", "a": "Wenn das Modell zwei Tools nicht mehr voneinander unterscheiden kann oder wenn eine Routineaufgabe vier Aufrufe erfordert, die sicherer in einem hätten zusammengefasst werden können. Die Aufteilung verbessert die Sicherheit nur so lange, bis sie zu falschen Tool-Entscheidungen führt – und ein falscher Aufruf ist ein eigener Fehler." }, { "q": "Wir nutzen ein einziges Dienstkonto für alles. Ist das wirklich so schlimm?", "a": "Das bedeutet, dass jeder Agent – und jeder Angreifer, der einen davon erreicht – die Reichweite der umfangreichsten Aufgabe hat, die einer von ihnen ausführt. Ein einziges Konto ist die Variante dieses Musters, bei der der Explosionsradius „alles“ umfasst." } ], "productionEvidence": { "context": "Der öffentliche MCP-Endpunkt für diese Wissensdatenbank, der für jeden Agenten im Internet erreichbar ist.", "scenario": "Der Korpus ist öffentlich und schreibgeschützt, sodass der Katalog ausschließlich aus Gettern besteht. Es gibt kein Tool, das schreibt, kein Tool, das auf eine Datenbank zugreift, die die Website nicht ohnehin schon veröffentlicht, und keine Anmeldedaten, die von irgendeinem Tool aus erreichbar sind.", "technology": "Zustandsloses JSON-RPC über HTTP auf einem Next.js-Route-Handler, Überprüfung der Origin-Allowlist vor der Ausführung eines Handlers, Rate-Limiting pro Aufrufer in Redis, strukturiertes Audit-Logging pro Aufruf.", "load": "Kontinuierlicher, unbeaufsichtigter Agent-Traffic seit dem Start, plus Registry-Crawler und Directory-Health-Checks.", "results": "Ein Client dieses Servers, der durch Prompt Injection gekapert wird, kann nichts erhalten, was er nicht auch von der öffentlichen Website hätte abrufen können, da die erreichbare Menge genau dem veröffentlichten Korpus entspricht. Es gibt keine Anmeldedaten zu widerrufen und keinen Schreibpfad zu missbrauchen." } }, "ja": { "name": "最小権限ツール", "summary": "エージェントにはタスクが実際に必要とする最も狭いツールのセットを、各ツールには最も狭いスコープを提供します。このパターンは、プロンプトインジェクションが成功することがあるという前提を受け入れ、乗っ取られたエージェントができることを制限します。モデルにパッチを当てることはできませんが、モデルがアクセスできる範囲を決定することはできます。", "definition": "最小権限ツールとは、エージェントのツールカタログと各ツールの基盤となる資格情報を、タスクが必要とする最小限に制限するプラクティスです。これにより、攻撃の成功やモデルのエラーによる影響は、モデルのコンプライアンスではなく、設計によって制限されます。", "problem": "広範なツールと広範な資格情報を与えられたエージェントは、インジェクション、ジェイルブレイク、またはハルシネーションの成功を、その背景にあるアカウントの全権限を伴う実際のアクションに変えてしまいます。", "context": "APIの呼び出し、ファイルの書き込み、メッセージの送信、資金の移動など、エージェントがアクションを実行できるあらゆる場所で使用します。自律性が高く、人間によるレビューが少ないほど、プロンプトではなく権限レイヤーで影響範囲を設定する必要があります。", "solution": [ "プラットフォームからではなく、タスクから始めてください。エージェントが実行する必要がある操作をリストアップし、それらのみを公開します。『APIが提供するもの』から組み立てられたカタログは、誰もレビューしていない権限付与になってしまいます。", "読み取りと書き込みを分割します。ツールを分け、資格情報を分け、読み取りツールの引数からアクセスできる書き込みパスを排除します。データの変更も可能な『クエリ』エンドポイントは、最も一般的な、気付きにくい権限昇格の原因です。", "ツールだけでなく、資格情報もスコープ制限します。管理者トークンに裏打ちされた読み取り専用ツールは、バグが1つあるだけで書き込みツールになり得ます。アップストリームシステムがサポートする最も狭いスコープで、ツールごとの資格情報を発行してください。", "パラメータを制限します。ツールがアクセスできるパス、リポジトリ、テーブル、アカウント、または受信者をホワイトリストに登録し、乗っ取られたエージェントが正当なツールを不正なターゲットに向け直すことができないようにします。", "権限付与に有効期限を設け、レビューを実施します。ツールは蓄積されていくため、呼び出されていないものは削除し、ツールの追加は権限の変更として扱ってください。", "権限付与と呼び出しを個別にログに記録します。エージェントが実行できたことと、実際に実行したことは異なる監査対象であり、インシデント対応にはその両方が必要です。" ], "components": [ "ツールごとに明示的かつ書面で定義されたスコープを持つツールカタログ。", "アップストリームシステムが提供する最も狭いスコープで発行された、ツールごとの資格情報。", "ツールがアクセスできるターゲットのパラメータホワイトリスト。", "モデルとは独立して各呼び出しを認可するポリシーレイヤー。", "権限付与と呼び出しの両方をカバーする監査ログ。", "呼び出されていないツールを削除する定期的なレビュー。" ], "benefits": [ "モデルが適切に動作することに依存せずに、インジェクション成功時の被害を制限します。", "『このエージェントは安全か？』という問いを、ツール、スコープ、所有者のリストというレビュー可能な成果物へと変換します。", "副次的な効果として、ツールの選択精度が向上します。ツールが少なく、役割が明確であるほど、モデルは選択しやすくなります。", "インシデント発生前にアクセス可能な範囲が判明しているため、インシデントの調査が可能になります。" ], "risks": [ "利便性によるスコープの肥大化。デバッグ中に広範なトークンを貼り付け、その後スコープを狭めないまま放置すること。", "断片化。モデルが区別できないほど細分化された多数のツールが存在し、セキュリティ上のメリットと引き換えに信頼性が低下すること。", "誤った安心感。最小権限は影響を制限するだけであり、攻撃を防ぐものではなく、正当に付与された読み取りツールを介した情報漏洩については何も保証しません。", "プロセスの停滞。スコープ制限された資格情報の発行が、広範な資格情報の再利用よりも困難な場合、プロセス自体が脆弱性になります。" ], "whenNot": [ "本番環境へのアクセスがない合成データ上のプロトタイプなど、手続きのコストが排除されるリスクを上回る場合。", "アップストリームプラットフォームがスコープをまったく表現できない場合。この場合、制御は要件を満たしたと宣言するのではなく、その手前にあるプロキシに移動します。", "エージェントの権限を狭めることで、それ自体が制限や監査の不十分な人間のプロセスに作業が押し付けられてしまう場合。" ], "examples": [ "1つのリポジトリと1つのブランチプレフィックスにスコープが限定され、組織全体の読み取り権限を持たないリポジトリトークンを付与されたコーディングエージェント。依存関係のREADMEを介したインジェクションによってブランチが作成される可能性はありますが、他の40のリポジトリにアクセスすることはできません。", "CRMツールが分割されているサポートエージェント：読み取り専用キーを持つ `read_customer` と、すでに会話内にあるチケットに制限された `update_ticket`。セッションが乗っ取られたとしても、1つのチケットに嫌がらせをすることはできますが、顧客ベース全体をエクスポートすることはできません。", "カタログ全体がすでに公開されているコンテンツに対するゲッター（getter）のみで構成され、資格情報を一切持たないパブリックMCPサーバー。漏洩するものが何もないため、失効させるべきものもありません。" ], "kpis": [ { "metric": "エージェントあたりのツール数", "note": "カタログの規模。削除を伴わない増加は、権限がレビューされずに蓄積されている兆候です。" }, { "metric": "書き込み可能なツールの割合", "note": "カタログのうち、状態を変更できるものの割合。タスクが許容する最小限に向けて削減すべき数値です。" }, { "metric": "最も古い未使用ツールの経過日数", "note": "付与されたツールが最後に呼び出されてからの日数。長期間未使用の権限は、誰も必要としないにもかかわらず、攻撃者に引き継がれてしまうアクセス権となります。" }, { "metric": "スコープドキュメントのカバー率", "note": "文書化されたスコープと指名された所有者を持つツールの割合。ドキュメントのないツールは、制限のないツールと同義です。" } ], "failureModes": [ "読み取り専用ツールの背後にある管理者トークン：スコープはツールレイヤーで宣言されているものの、資格情報レイヤーでは制限されていません。", "パラメータの再指定：引数を制限するものが何もないため、ツール自体は正当であっても、ターゲットが不正になります。", "混乱した代理（Confused deputy）：実行権限の主体を絞り込まずにツールだけを絞り込んでも、呼び出し元がエージェントのアクセス権を引き継ぐため、何も変わりません。", "カタログのドリフト：実験のために追加されたツールがそのまま残り、レビューされた権限セットと実際にデプロイされている権限セットが乖離してしまいます。" ], "lessons": [ "インシデントが発生した後ではなく、ツールを付与する前に影響範囲（ブラスト半径）を文書化してください。", "ツールの名前はそのスコープではありません。サーバー側の資格情報のみがスコープを決定します。", "誰からも呼び出されないツールを削除することは、最も低コストで実施できるセキュリティ対策です。", "最小権限は2つのメリットをもたらします。攻撃を制限することと、エージェントによるツールの選択精度を向上させることです。" ], "faqs": [ { "q": "最小権限はプロンプトインジェクションを防げますか？", "a": "いいえ、それを目的としたものではありません。インジェクションは時として成功することを前提とし、成功した場合に何ができるかを事前に制限します。予防と封じ込めは異なる役割であり、制御可能なのは封じ込めだけです。" }, { "q": "どの程度まで絞り込むと狭すぎる（過剰な制限になる）のでしょうか？", "a": "モデルが2つのツールを区別できなくなったとき、または1回で安全に処理できる定型タスクに4回の呼び出しが必要になったときです。分割はセキュリティを向上させますが、ツールの誤選択を招くようになれば逆効果であり、誤った呼び出し自体が失敗の原因となります。" }, { "q": "すべての処理に1つのサービスアカウントを使用しています。それはそんなに悪いことですか？", "a": "それは、すべてのエージェント（およびエージェントに到達したすべての攻撃者）が、実行される最も広範なタスクのアクセス権を持つことを意味します。1つのアカウントを使用することは、このパターンにおいて影響範囲（ブラスト半径）が『すべて』になることを意味します。" } ], "productionEvidence": { "context": "インターネット上のあらゆるエージェントからアクセス可能な、このナレッジベースのパブリックMCPエンドポイント。", "scenario": "コーパスは公開されており読み取り専用であるため、カタログはすべてゲッター（getter）です。書き込みを行うツールや、サイトがすでに公開しているもの以外のデータベースにアクセスするツールはなく、どのツールからもアクセスできる資格情報はありません。", "technology": "Next.jsのルートハンドラー上でのHTTP経由のステートレスJSON-RPC、ハンドラー実行前のオリジン許可リストのチェック、Redisによる呼び出し元ごとのレート制限、呼び出しごとの構造化監査ログの記録。", "load": "ローンチ以来、継続している無人のエージェントトラフィックに加え、レジストリクローラーやディレクトリのヘルスチェック。", "results": "プロンプトインジェクションによってこのサーバーのクライアントが乗っ取られたとしても、アクセス可能な範囲は公開されているコーパスと完全に一致しているため、公開サイトから取得できるもの以外の情報は取得できません。失効させるべき資格情報も、悪用される書き込みパスも存在しません。" } }, "zh": { "name": "最小特权工具化", "summary": "为智能体提供任务实际所需的最窄工具集，并为每个工具赋予最窄的范围。该模式承认提示词注入有时会成功，并限制了被劫持的智能体所能执行的操作——您无法修补模型，但可以决定它能够触及的内容。", "definition": "最小特权工具化是指将智能体的工具目录以及每个工具的底层凭据限制在任务所需的最低限度的实践——这样，成功攻击或模型错误所带来的后果在设计上就是受限的，而不是依赖于模型的合规性。", "problem": "如果赋予智能体广泛的工具和广泛的凭据，任何成功的注入、越狱或幻觉都会转化为真实的行动，并带有其背后账户的全部权限。", "context": "适用于智能体可以执行操作的任何场景——调用 API、写入文件、发送消息、转移资金。自主性越高、人工审查越少，就越需要将爆炸半径设置在权限层，而不是提示词中。", "solution": [ "从任务出发，而不是从平台出发。列出智能体必须执行的操作，并仅公开这些操作。根据“API 提供了什么”来构建目录，无异于授予了未经审查的权限。", "读写分离：独立的工具、独立的凭据，并且不能通过读取工具的参数触及写入路径。同时支持变更的“查询”端点是最常见的隐性越权漏洞。", "限制凭据范围，而不仅仅是工具。由管理员令牌支持的只读工具，只要出现一个 Bug 就会变成写入工具；应在上游系统支持的最窄范围内，为每个工具单独颁发凭据。", "限制参数。将工具可以访问的路径、仓库、表、账户或接收者列入白名单，这样被劫持的智能体就无法将合法的工具重新指向非法的目标。", "使授权可过期并进行审查。工具会不断累积；移除从未被调用过的工具，并将添加工具视为实质上的权限变更。", "分别记录授权和调用。智能体“能做什么”和“做了什么”是两个不同的审计内容，而应对安全事件时两者都需要。" ], "components": [ "一个工具目录，其中明确书写了每个工具的范围。", "在上游系统提供的最窄范围内为每个工具颁发的凭据。", "工具可以访问的目标的参数白名单。", "一个独立于模型对每次调用进行授权的策略层。", "涵盖授权和调用的审计日志。", "定期审查机制，用于移除未被调用的工具。" ], "benefits": [ "在不依赖模型表现良好的情况下，限制成功注入所造成的损害。", "将“这个智能体安全吗？”转化为可审查的产物：工具、范围和所有者的列表。", "顺带提高了工具选择的准确性——更少、更精准的工具更便于模型进行选择。", "使安全事件可调查，因为在事件发生前，可触及的范围就是已知的。" ], "risks": [ "因图方便而导致的范围蔓延：在调试时粘贴了宽泛的令牌，此后从未对其进行收窄。", "碎片化：数十个极细粒度的工具导致模型无法区分，用可靠性的降低换取安全性的提升。", "虚假的安全感。最小特权只是限制了后果；它并不能阻止攻击，也无法防范通过合法授予的读取工具进行的数据外泄。", "流程拖累：如果颁发有范围限制的凭据比复用宽泛的凭据更困难，那么流程本身就会成为漏洞。" ], "whenNot": [ "在不涉及生产环境的合成数据上进行原型设计，此时流程成本高于其消除的风险。", "当上游平台完全无法表达范围时——此时控制权应移至其前置代理，而不是直接声明满足要求。", "当限制智能体反而会将工作推向本身限制更少、审计更少的人工路径时。" ], "examples": [ "一个编码智能体被赋予了仅限于单个代码库和单个分支前缀的仓库 Token，且没有组织范围的读取权限。通过依赖项 README 进行的注入攻击虽然仍能创建分支，但无法触及其他四十个代码库。", "一个支持智能体，其 CRM 工具被拆分：使用只读密钥的 read_customer，以及限制为仅处理已在对话中的工单的 update_ticket。被劫持的会话只能干扰单个工单，而无法导出客户数据库。", "一个公开的 MCP 服务器，其整个目录都是针对已发布内容的 getter（获取器），完全不需要任何凭据——因为没有什么可泄露的，所以也无需撤销任何内容。" ], "kpis": [ { "metric": "每个智能体的工具数", "note": "工具目录的大小。只增不减表明权限正在未经审核地累积。" }, { "metric": "具备写能力的工具占比", "note": "目录中能够改变状态的工具比例。该数值应尽可能降低至任务允许的最小值。" }, { "metric": "最老未使用工具的闲置时长", "note": "自上次调用已授权工具以来的天数。长期未使用的授权属于不必要的权限范围，极易被攻击者利用。" }, { "metric": "范围文档覆盖率", "note": "拥有书面范围定义和明确所有者的工具比例。未记录文档的工具即为未受限的工具。" } ], "failureModes": [ "只读工具背后的管理员 Token：范围仅在工具层声明，但在凭据层未作限制。", "参数重定向：工具本身是合法的，但目标不合法，因为没有任何机制对参数进行约束。", "混淆代理：仅缩减工具而不缩减其运行所依附的权限，无法解决任何问题，因为调用者仍然会继承智能体的权限范围。", "目录漂移：为实验添加的工具被残留，导致经过审核的权限集与实际部署的权限集不一致。" ], "lessons": [ "应在授予工具权限之前明确爆炸半径，而不是在安全事件发生之后。", "工具的名称并不代表其作用范围，只有服务器端的凭据才是。", "移除无人调用的工具是最廉价且有效的安全工作。", "最小特权原则带来双重收益：它既能限制攻击范围，又能让智能体更好地选择工具。" ], "faqs": [ { "q": "最小特权原则能阻止提示词注入吗？", "a": "不能，它也不是为了这个目的而设计的。它假设注入有时会成功，并预先限制成功注入后所能造成的破坏。预防和遏制是不同的工作，而只有遏制是完全在您控制之下的。" }, { "q": "限制到什么程度算过度限制？", "a": "当模型无法再区分两个工具，或者一个常规任务需要四次调用（而这些调用本可以安全地合并为一次）时。拆分工具可以提高安全性，但如果开始导致错误的工具选择，那么错误的调用本身就是一种失败。" }, { "q": "我们所有的操作都使用同一个服务账号。这真的很糟糕吗？", "a": "这意味着每个智能体，以及任何接触到智能体的攻击者，都拥有所有任务中最大任务的权限范围。使用单一账号相当于将该模式下的爆炸半径设为“全部”。" } ], "productionEvidence": { "context": "该知识库的公开 MCP 端点，互联网上的任何智能体均可访问。", "scenario": "语料库是公开且只读的，因此目录完全由 getter（获取器）组成。没有写操作工具，没有工具能访问该网站未公开的数据库，也没有任何工具可以获取凭据。", "technology": "基于 Next.js 路由处理程序的 HTTP 无状态 JSON-RPC，在运行任何处理程序之前检查源白名单，在 Redis 中进行针对每个调用者的速率限制，以及结构化的单次调用审计日志。", "load": "自发布以来持续的无人值守智能体流量，以及注册表爬虫和目录健康检查。", "results": "即使该服务器的客户端因提示词注入而被劫持，攻击者也无法获取公开网站之外的任何内容，因为可访问的范围完全等同于已发布的语料库。这里没有需要撤销的凭据，也没有可以滥用的写入路径。" } } } }, { "slug": "long-term-memory", "category": "retrieval", "updated": "2026-08-25", "version": "1.2", "url": "https://santismm.com/en/patterns/long-term-memory", "api": "https://santismm.com/api/patterns/long-term-memory", "canonical_url": "https://santismm.com/en/patterns/long-term-memory", "api_url": "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", "attributed-memory" ], "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." } ] }, "fr": { "name": "Mémoire à long terme", "summary": "Dotez un agent d'une mémoire persistante d'une session à l'autre afin qu'il se souvienne des faits, des préférences de l'utilisateur et des résultats antérieurs au-delà d'une simple fenêtre de contexte. Un chemin d'écriture décide de ce qu'il faut stocker, le synthétise et supprime les doublons ; un chemin de lecture récupère uniquement les souvenirs pertinents dans le contexte en cas de besoin. Contrairement à la mise en cache sémantique, qui met en cache des réponses entières pour éviter de recalculer, la mémoire à long terme stocke des faits et des états durables et les recompose à chaque fois dans un nouveau raisonnement.", "problem": "La fenêtre de contexte est finie et se réinitialise entre les sessions. Un agent qui ne voit que la conversation en cours oublie les préférences exprimées par l'utilisateur, les décisions prises la semaine précédente et le résultat des tâches antérieures. Intégrer tout l'historique dans chaque invite devient impossible au-delà d'une certaine échelle et dégrade le raisonnement à mesure que la fenêtre se remplit de jetons à faible valeur. Les équipes ont besoin d'un moyen de conserver le petit ensemble de faits importants et de les faire remonter précisément lorsqu'ils sont pertinents.", "context": "Utilisez ce modèle lorsqu'un agent est au service des mêmes utilisateurs ou travaille de manière répétée sur les mêmes tâches de longue durée : assistants qui apprennent les préférences, agents de support qui suivent l'historique d'un client, agents de codage qui mémorisent les conventions d'un projet, ou flux de travail multi-étapes s'étendant sur plusieurs jours. Cela suppose que vous puissiez stocker des données en dehors du modèle (un magasin de vecteurs, une base de données ou un framework de mémoire) et que vous contrôliez à la fois le moment où les souvenirs sont écrits et la manière dont ils sont récupérés dans l'invite.", "solution": [ "Séparez le chemin d'écriture du chemin de lecture. Sur le chemin d'écriture, une fois qu'un tour ou une tâche se termine, une étape d'extraction décide de ce qui mérite d'être mémorisé : des faits stables, des préférences, des engagements et des résultats — et non des échanges éphémères. Les souvenirs potentiels sont synthétisés sous forme d'énoncés compacts et autonomes, comparés aux souvenirs existants pour éliminer les doublons et détecter les contradictions, puis écrits dans un magasin avec des métadonnées : un type de mémoire, un horodatage, une source, et l'utilisateur ou la portée auquel il appartient. L'objectif est d'écrire moins mais d'écrire mieux ; des souvenirs superflus polluent les récupérations ultérieures.\n\nSur le chemin de lecture, avant que l'agent ne raisonne, vous récupérez les souvenirs potentiels pertinents pour la tâche en cours — généralement par similarité sémantique combinée à des filtres sur la portée et la récence —, vous les classez et vous n'injectez que les tout premiers dans le contexte. Traitez la récupération comme un problème de précision : une poignée de souvenirs exacts vaut mieux qu'un grand ensemble vaguement lié. Distinguez les types de mémoire afin de cibler la récupération : épisodique (ce qui s'est passé), sémantique (faits et préférences durables) et procédurale (comment réaliser une tâche récurrente). Consolidez périodiquement et faites expirer les souvenirs pour que le magasin reste de taille réduite, à jour et exempt de contradictions." ], "components": [ "Extracteur de mémoire (chemin d'écriture)", "Déduplication et vérification des contradictions", "Magasin de mémoire", "Récupérateur (chemin de lecture)", "Assembleur de contexte", "Tâche de consolidation et d'expiration" ], "benefits": [ "L'agent se souvient des préférences, des décisions et des résultats des sessions précédentes, évitant ainsi aux utilisateurs de répéter le contexte et garantissant un comportement cohérent de l'agent dans le temps.", "La récupération de quelques souvenirs pertinents permet de concentrer la fenêtre sur des jetons à forte valeur plutôt que d'injecter tout l'historique, ce qui préserve la qualité du raisonnement et réduit les coûts.", "À mesure que les faits stables et les préférences s'accumulent, l'agent adapte ses réponses de manière plus précise à chaque interaction, sans nécessiter de réentraînement du modèle.", "Puisque les souvenirs résident dans un magasin externe doté de métadonnées, vous pouvez inspecter, corriger, exporter et supprimer ce que l'agent sait — un aspect essentiel pour la confiance et la conformité." ], "risks": [ "Sans consolidation ni expiration, le magasin accumule des faits obsolètes et des déclarations contradictoires, et l'agent risque d'agir avec assurance sur la base d'informations erronées.", "La conservation des données utilisateur entraîne des obligations en matière de rétention, de consentement et de contrôle d'accès ; les souvenirs peuvent divulguer des informations sensibles d'une session ou d'un utilisateur à l'autre si la portée n'est pas strictement appliquée.", "Une faible précision injecte des souvenirs non pertinents ou erronés qui faussent le raisonnement ; un faible rappel omet silencieusement le souvenir qui importait, rendant les défaillances difficiles à diagnostiquer.", "Une écriture trop systématique gonfle le magasin, ralentit la récupération, augmente les coûts de stockage et d'intégration (embeddings), et dilue le signal dont dépend la qualité de la récupération." ], "whenNot": [ "Si les sessions sont indépendantes et que rien n'a besoin d'être transmis, la mémoire persistante ajoute de la complexité, des coûts et une surface d'exposition des données personnelles sans aucun avantage.", "Lorsque l'objectif est de réutiliser une réponse précédente pour une requête répétée, la mise en cache sémantique est l'outil approprié ; la mémoire à long terme sert à mémoriser des faits et des états, et non à mettre en cache des sorties.", "Lorsque la réglementation ou les politiques interdisent la conservation des données utilisateur, ne persistez pas les souvenirs ; appuyez-vous sur le contexte de la session ou sur un stockage explicite et délimité contrôlé par l'utilisateur." ], "examples": [ "D'une session à l'autre, il se souvient du ton, des formats, des contacts récurrents et des instructions permanentes, récupérant les quelques éléments qui s'appliquent à la demande en cours au lieu de poser à nouveau la question.", "À chaque contact, il récupère les problèmes antérieurs du client, ses droits et les résolutions associées à ce compte, afin de poursuivre la conversation plutôt que de la recommencer.", "Il stocke des souvenirs procéduraux — commandes de build, règles de nommage, préférences de révision — et les rappelle lorsqu'il travaille sur le même dépôt au fil de nombreuses sessions." ], "productionEvidence": { "context": "Déploiement OpenClaw mono-opérateur et local-first observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des traces de trajectoire de l'agent lui-même.", "scenario": "L'agent persiste les fichiers de mémoire de l'espace de travail et les traces par session pour assurer la continuité entre les tours et les sessions, avec un plugin de rappel sémantique disponible à la demande.", "technology": "Fichiers de mémoire de l'espace de travail (MEMORY.md, IDENTITY.md, SOUL.md, USER.md, HEARTBEAT.md), identifiants de session persistants et événements de cycle de vie, et un plugin de mémoire active (memory_search/get/recall).", "load": "134 fichiers de session persistés sur la fenêtre de 57 jours ; rappel sémantique invoqué une fois.", "results": "La continuité a été maintenue sur 134 sessions persistées pendant 57 jours grâce à la mémoire structurelle de l'espace de travail ; le rappel sémantique explicite a été rarement nécessaire (un seul appel) dans cette charge de travail autonome. Déploiement local-first à opérateur unique." }, "kpis": [ { "metric": "Précision de récupération des souvenirs injectés", "note": "Parmi les souvenirs placés en contexte, la part de ceux qui étaient réellement pertinents. C'est la métrique qui régit le plus directement la qualité des réponses ; un bon résultat signifie que l'ensemble injecté est presque entièrement pertinent, les souvenirs non pertinents étant rares." }, { "metric": "Rappel de récupération sur les tâches dépendantes de la mémoire", "note": "Pour les tâches nécessitant un fait stocké connu, la fréquence à laquelle ce fait est réellement récupéré. Un bon résultat signifie que le bon souvenir remonte de manière fiable ; des échecs persistants indiquent des lacunes d'extraction ou d'indexation." }, { "metric": "Taille et taux de croissance du stockage de mémoire", "note": "Nombre total de souvenirs et vitesse à laquelle ils s'accumulent par utilisateur actif. Un bon résultat signifie que la croissance suit de nouveaux faits durables réels, et non une hausse illimitée — une courbe exponentielle signale une écriture trop zélée." }, { "metric": "Taux d'obsolescence et de contradiction", "note": "Part des souvenirs récupérés qui sont obsolètes ou en conflit avec une vérité plus récente. Un bon résultat correspond à un taux faible et stable, preuve que la consolidation et l'expiration suivent le rythme des changements." } ], "failureModes": [ "Tout écrire transforme le stockage en bruit ; la récupération fait alors remonter des souvenirs de faible valeur ou erronés. Corrigez cela en élevant le niveau d'exigence pour ce qui est écrit et en examinant la qualité de l'extraction.", "Un fait ancien est récupéré et exploité après que la vérité a changé, sans aucun signal indiquant qu'il est obsolète. Atténuez ce problème avec des horodatages, un classement pondéré par la récence et un remplacement explicite lors de l'écriture.", "Un souvenir d'un utilisateur, d'un locataire ou d'un projet est récupéré dans le contexte d'un autre parce que les filtres de portée étaient manquants ou incorrects — un échec à la fois de confidentialité et d'exactitude.", "Pour compenser un mauvais classement, les équipes injectent de nombreux souvenirs, remplissant la fenêtre de jetons marginaux et dégradant le raisonnement même que la mémoire était censée soutenir." ], "lessons": [ "La qualité se décide au moment de choisir ce qu'il faut mémoriser. Un stockage restreint, propre et dédoublonné offre une bien meilleure récupération qu'un grand stockage bruyant.", "Quelques souvenirs corrects sont plus performants que de nombreux souvenirs vaguement liés. Ajustez la pertinence et classez de manière stricte plutôt que de maximiser la quantité injectée.", "Stockez les métadonnées et fournissez des moyens de visualiser, modifier, faire expirer et supprimer les souvenirs. C'est essentiel pour le débogage, la confiance et le respect des obligations de confidentialité.", "Les faits deviennent obsolètes et se contredisent. Intégrez tôt la consolidation, le remplacement et l'expiration ; les adapter ultérieurement à un grand stockage pollué est fastidieux." ], "faqs": [ { "q": "En quoi cela diffère-t-il de la mise en cache sémantique ?", "a": "La mise en cache sémantique stocke et rejoue des réponses entières pour éviter de recalculer des requêtes similaires. La mémoire à long terme stocke des faits durables, des préférences et des résultats, puis les recompose dans un nouveau raisonnement pour chaque nouvelle tâche. L'une réutilise les sorties ; l'autre mémorise l'état." }, { "q": "Que doit réellement mémoriser l'agent ?", "a": "Un signal stable et réutilisable : les préférences de l'utilisateur, les décisions et engagements, les résultats des tâches antérieures et les procédures récurrentes. Évitez les bavardages éphémères et tout ce dont vous ne pouvez justifier la conservation. Écrire moins mais écrire bien est ce qui rend la récupération ultérieure précise." }, { "q": "Comment gérez-vous les PII et la confidentialité ?", "a": "Traitez le stockage comme des données gouvernées : appliquez des limites de portée pour que les souvenirs ne croisent jamais les utilisateurs ou les locataires, minimisez ce que vous persistez, prenez en charge le consentement et la suppression, et définissez des contrôles de rétention et d'accès. L'inspectabilité et une politique d'expiration font partie du respect de ces obligations." } ] }, "de": { "name": "Langzeitgedächtnis", "summary": "Geben Sie einem Agenten ein persistentes Gedächtnis über Sitzungen hinweg, sodass er sich an Fakten, Benutzerpräferenzen und frühere Ergebnisse über ein einzelnes Kontextfenster hinaus erinnert. Ein Schreibpfad entscheidet, was gespeichert wird, fasst es zusammen und dedupliziert es; ein Lesepfad ruft bei Bedarf nur die relevanten Erinnerungen in den Kontext ab. Im Gegensatz zum semantischen Caching, das ganze Antworten zwischenspeichert, um Neuberechnungen zu vermeiden, speichert das Langzeitgedächtnis dauerhafte Fakten und Zustände und setzt diese jedes Mal neu für logische Schlussfolgerungen (Reasoning) zusammen.", "problem": "Das Kontextfenster ist begrenzt und wird zwischen den Sitzungen zurückgesetzt. Ein Agent, der nur die aktuelle Konversation sieht, vergisst die geäußerten Präferenzen eines Benutzers, Entscheidungen aus der Vorwoche und die Ergebnisse früherer Aufgaben. Ab einer bestimmten Größenordnung ist es unmöglich, den gesamten Verlauf in jeden Prompt zu packen, und es verschlechtert das Reasoning, da sich das Fenster mit Token von geringem Wert füllt. Teams benötigen eine Möglichkeit, die wenigen entscheidenden Fakten dauerhaft zu speichern und genau dann bereitzustellen, wenn sie relevant sind.", "context": "Verwenden Sie dies, wenn ein Agent wiederholt dieselben Benutzer bedient oder an denselben langlaufenden Aufgaben arbeitet: Assistenten, die Präferenzen lernen, Support-Agenten, die die Historie eines Kunden verfolgen, Coding-Agenten, die sich an Projektkonventionen erinnern, oder mehrstufige Workflows, die sich über Tage erstrecken. Es setzt voraus, dass Sie Daten außerhalb des Modells speichern können (ein Vektorspeicher, eine Datenbank oder ein Memory-Framework) und dass Sie sowohl den Zeitpunkt des Schreibens von Erinnerungen als auch deren Abruf in den Prompt steuern.", "solution": [ "Trennen Sie den Schreibpfad vom Lesepfad. Auf dem Schreibpfad entscheidet nach Abschluss eines Interaktionsschritts (Turn) oder einer Aufgabe ein Extraktionsschritt, was erinnerungswürdig ist: stabile Fakten, Präferenzen, Zusagen und Ergebnisse – kein flüchtiges Geplauder. Potenzielle Erinnerungen werden in kompakte, in sich geschlossene Aussagen zusammengefasst, mit bestehenden Erinnerungen abgeglichen, um sie zu deduplizieren und Widersprüche zu erkennen, und dann mit Metadaten in einen Speicher geschrieben: einem Erinnerungstyp, einem Zeitstempel, einer Quelle und dem Benutzer oder Scope, zu dem sie gehören. Weniger, aber dafür gut zu schreiben, ist das Ziel; verrauschte Erinnerungen beeinträchtigen den späteren Abruf.\n\nAuf dem Lesepfad rufen Sie, bevor der Agent logische Schlussfolgerungen zieht, potenzielle Erinnerungen ab, die für die aktuelle Aufgabe relevant sind – typischerweise durch semantische Ähnlichkeit plus Filter für Scope und Aktualität –, bewerten diese und fügen nur die wichtigsten in den Kontext ein. Betrachten Sie den Abruf als Präzisionsproblem: Eine Handvoll korrekter Erinnerungen ist besser als eine große, lose zusammenhängende Menge. Unterscheiden Sie Erinnerungstypen, um den Abruf gezielt zu steuern: episodisch (was passiert ist), semantisch (dauerhafte Fakten und Präferenzen) und prozedural (wie eine wiederkehrende Aufgabe auszuführen ist). Konsolidieren Sie Erinnerungen regelmäßig und lassen Sie sie ablaufen, damit der Speicher klein, aktuell und frei von Widersprüchen bleibt." ], "components": [ "Memory-Extraktor (Schreibpfad)", "Deduplizierung und Widerspruchsprüfung", "Memory-Speicher", "Retriever (Lesepfad)", "Kontext-Assembler", "Konsolidierungs- und Ablauf-Job" ], "benefits": [ "Der Agent erinnert sich an Präferenzen, Entscheidungen und Ergebnisse aus früheren Sitzungen, sodass Benutzer den Kontext nicht wiederholen müssen und sich der Agent über die Zeit hinweg konsistent verhält.", "Das Abrufen einiger weniger relevanter Erinnerungen sorgt dafür, dass sich das Fenster auf hochwertige Token konzentriert, anstatt den gesamten Verlauf zu laden. Dies erhält die Qualität des Reasonings und senkt die Kosten.", "Da sich stabile Fakten und Präferenzen ansammeln, passt der Agent seine Antworten mit jeder Interaktion präziser an, ohne dass das Modell neu trainiert werden muss.", "Da Erinnerungen in einem externen Speicher mit Metadaten abgelegt werden, können Sie überprüfen, korrigieren, exportieren und löschen, was der Agent weiß – wichtig für Vertrauen und Compliance." ], "risks": [ "Ohne Konsolidierung und Ablaufdatum sammelt der Speicher veraltete Fakten und widersprüchliche Aussagen an, und der Agent agiert selbstbewusst auf Basis der falschen Informationen.", "Das Speichern von Benutzerdaten bringt Verpflichtungen zur Aufbewahrung, Einwilligung und Zugriffskontrolle mit sich; Erinnerungen können sensible Informationen über Sitzungen oder Benutzer hinweg preisgeben, wenn der Scope nicht erzwungen wird.", "Eine geringe Präzision führt dazu, dass irrelevante oder falsche Erinnerungen eingefügt werden, die das Reasoning in die Irre führen; ein geringer Recall lässt genau die Erinnerung, auf die es ankam, stillschweigend untergehen, was Fehler schwer diagnostizierbar macht.", "Zu eifriges Schreiben bläht den Speicher auf, verlangsamt den Abruf, erhöht die Speicher- und Embedding-Kosten und verwässert das Signal, auf das ein guter Abruf angewiesen ist." ], "whenNot": [ "Wenn Sitzungen unabhängig sind und nichts übertragen werden muss, erhöht ein persistentes Gedächtnis die Komplexität, die Kosten und die Angriffsfläche für den Datenschutz, ohne einen Nutzen zu bringen.", "Wenn das Ziel darin besteht, eine vorherige Antwort für eine wiederholte Anfrage wiederzuverwenden, ist semantisches Caching das richtige Werkzeug; das Langzeitgedächtnis dient dem Erinnern von Fakten und Zuständen, nicht dem Caching von Ausgaben.", "Wo Vorschriften oder Richtlinien die Aufbewahrung von Benutzerdaten verbieten, sollten Sie keine Erinnerungen persistieren; verlassen Sie sich auf den In-Session-Kontext oder einen expliziten, eingegrenzten Speicher, den der Benutzer kontrolliert." ], "examples": [ "Über Sitzungen hinweg erinnert es sich an Tonalität, Formate, wiederkehrende Kontakte und ständige Anweisungen und ruft die wenigen ab, die für die aktuelle Anfrage gelten, anstatt erneut nachzufragen.", "Bei jedem Kontakt ruft es die früheren Probleme, Berechtigungen und Lösungen des Kunden ab, die auf dieses Konto bezogen sind, sodass es die Konversation fortsetzt, anstatt sie neu zu starten.", "Es speichert prozedurale Erinnerungen – Build-Befehle, Namensregeln, Review-Präferenzen – und ruft sie ab, wenn in vielen Sitzungen im selben Repository gearbeitet wird." ], "productionEvidence": { "context": "Single-Operator, Local-First OpenClaw-Bereitstellung, beobachtet über 57 Tage (161 Sitzungen / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Der Agent persistiert Workspace-Memory-Dateien und Traces pro Sitzung für die Kontinuität über Turns und Sitzungen hinweg, wobei bei Bedarf ein Plugin für semantischen Abruf zur Verfügung steht.", "technology": "Workspace-Speicherdateien (MEMORY.md, IDENTITY.md, SOUL.md, USER.md, HEARTBEAT.md), persistente Session-IDs und Lifecycle-Events sowie ein Active-Memory-Plugin (memory_search/get/recall).", "load": "134 persistierte Session-Dateien über das 57-Tage-Fenster; semantischer Abruf (semantic recall) einmal aufgerufen.", "results": "Die Kontinuität blieb über 134 persistierte Sessions hinweg über 57 Tage durch strukturellen Workspace-Speicher erhalten; expliziter semantischer Abruf war in diesem autonomen Workload selten erforderlich (ein Aufruf). Lokale Bereitstellung für einen einzelnen Operator (Local-First)." }, "kpis": [ { "metric": "Retrieval-Präzision (Precision) injizierter Erinnerungen", "note": "Der Anteil der tatsächlich relevanten Erinnerungen unter den in den Kontext eingefügten. Dies ist die Metrik, die die Antwortqualität am direktesten beeinflusst; ein gutes Ergebnis bedeutet, dass die injizierte Menge fast vollständig themenbezogen ist und irrelevante Erinnerungen selten sind." }, { "metric": "Retrieval-Trefferquote (Recall) bei speicherabhängigen Aufgaben", "note": "Bei Aufgaben, die einen bekannten gespeicherten Fakt erfordern, die Häufigkeit, mit der dieser Fakt tatsächlich abgerufen wird. Ein gutes Ergebnis bedeutet, dass die richtige Erinnerung zuverlässig auftaucht; anhaltende Fehlversuche deuten auf Lücken bei der Extraktion oder Indizierung hin." }, { "metric": "Größe und Wachstumsrate des Speichers", "note": "Gesamtzahl der Erinnerungen und wie schnell sie sich pro aktivem Benutzer ansammeln. Ein gutes Ergebnis bedeutet, dass das Wachstum tatsächlich neue, dauerhafte Fakten widerspiegelt und keinen unbegrenzten Anstieg – eine exponentielle Kurve signalisiert ein zu eifriges Schreiben." }, { "metric": "Veraltungs- und Widerspruchsrate", "note": "Anteil der abgerufenen Erinnerungen, die veraltet sind oder im Widerspruch zu einer neueren Wahrheit stehen. Ein gutes Ergebnis bedeutet eine niedrige und stabile Rate, was beweist, dass Konsolidierung und Ablaufdatum mit den Änderungen Schritt halten." } ], "failureModes": [ "Das Schreiben von allem verwandelt den Speicher in Rauschen; der Abruf liefert dann minderwertige oder falsche Erinnerungen. Beheben Sie dies, indem Sie die Hürde für das Schreiben erhöhen und die Extraktionsqualität überprüfen.", "Ein alter Fakt wird abgerufen und verarbeitet, nachdem sich die Wahrheit geändert hat, ohne dass ein Signal für die Veraltung vorliegt. Mildern Sie dies durch Zeitstempel, nach Aktualität gewichtetes Ranking und explizites Überschreiben beim Schreiben.", "Eine Erinnerung eines Benutzers, Mandanten oder Projekts wird in den Kontext eines anderen abgerufen, weil Scope-Filter fehlten oder fehlerhaft waren – ein gleichzeitiger Verstoß gegen Datenschutz und Korrektheit.", "Um ein schlechtes Ranking zu kompensieren, injizieren Teams viele Erinnerungen, wodurch das Kontextfenster mit marginalen Tokens gefüllt und genau die Argumentation beeinträchtigt wird, die der Speicher eigentlich unterstützen sollte." ], "lessons": [ "Die Qualität entscheidet sich bei der Auswahl dessen, was erinnert werden soll. Ein kleiner, sauberer, deduplizierter Speicher liefert weitaus bessere Abrufergebnisse als ein großer, verrauschter Speicher.", "Einige wenige korrekte Erinnerungen übertreffen viele lose zusammenhängende. Optimieren Sie auf Relevanz und ranken Sie streng, anstatt die Menge der injizierten Daten zu maximieren.", "Speichern Sie Metadaten und bieten Sie Möglichkeiten zum Anzeigen, Bearbeiten, Ablaufenlassen und Löschen von Erinnerungen. Dies ist unerlässlich für das Debugging, das Vertrauen und die Erfüllung von Datenschutzpflichten.", "Fakten veralten und widersprechen sich. Implementieren Sie Konsolidierung, Überschreiben und Ablaufdaten frühzeitig; diese nachträglich in einen großen, verunreinigten Speicher einzubauen, ist mühsam." ], "faqs": [ { "q": "Wie unterscheidet sich dies von semantischem Caching?", "a": "Semantisches Caching speichert und gibt ganze Antworten wieder, um die Neuberechnung ähnlicher Anfragen zu vermeiden. Langzeitgedächtnis speichert dauerhafte Fakten, Präferenzen und Ergebnisse und setzt diese dann für jede neue Aufgabe zu neuen logischen Schlüssen zusammen. Das eine verwendet Ausgaben wieder, das andere merkt sich den Zustand." }, { "q": "Was sollte sich der Agent tatsächlich merken?", "a": "Stabile, wiederverwendbare Signale: Benutzerpräferenzen, Entscheidungen und Zusagen, Ergebnisse früherer Aufgaben und wiederkehrende Abläufe. Vermeiden Sie flüchtigen Smalltalk und alles, dessen Aufbewahrung Sie nicht rechtfertigen können. Weniger, aber dafür gut zu schreiben, macht den späteren Abruf präzise." }, { "q": "Wie gehen Sie mit personenbezogenen Daten (PII) und Datenschutz um?", "a": "Behandeln Sie den Speicher als regulierte Daten: Setzen Sie Scopes durch, damit Erinnerungen niemals Benutzer oder Mandanten überschreiten, minimieren Sie die Persistierung, unterstützen Sie Einwilligung und Löschung und legen Sie Aufbewahrungs- und Zugriffskontrollen fest. Überprüfbarkeit und eine Richtlinie zum Ablauf von Daten sind Teil der Erfüllung dieser Pflichten." } ] }, "ja": { "name": "長期記憶（Long-Term Memory）", "summary": "エージェントにセッション間で永続する記憶を提供し、単一のコンテキストウィンドウを超えて事実、ユーザーの好み、過去の結果を記憶できるようにします。書き込みパスは保存すべき内容を決定し、要約して重複を排除します。読み取りパスは、必要なときにのみ関連する記憶をコンテキストに取得します。再計算をスキップするために回答全体をキャッシュするセマンティックキャッシュとは異なり、長期記憶は永続的な事実と状態を保存し、毎回それらを新しい推論に再構成します。", "problem": "コンテキストウィンドウは有限であり、セッション間でリセットされます。現在の会話しか見えないエージェントは、ユーザーが指定した好み、先週下された決定、過去のタスクの結果を忘れてしまいます。すべての履歴をすべてのプロンプトに詰め込むことは、一定の規模を超えると不可能になり、ウィンドウが価値の低いトークンで満たされるため推論の質が低下します。開発チームは、重要な少数の事実を永続化し、それらが関連するタイミングで正確に提示する方法を必要としています。", "context": "エージェントが同じユーザーに対応したり、同じ長期的なタスクを繰り返し実行したりする場合に使用します。好みを学習するアシスタント、顧客の履歴を追跡するサポートエージェント、プロジェクトの規約を記憶するコーディングエージェント、数日間にわたるマルチステップのワークフローなどが該当します。これは、モデルの外部（ベクトルストア、データベース、またはメモリフレームワーク）にデータを保存できること、および記憶が書き込まれるタイミングとプロンプトに取得される方法の両方を制御できることを前提としています。", "solution": [ "書き込みパスと読み取りパスを分離します。書き込みパスでは、ターンまたはタスクの完了後に、抽出ステップによって記憶に値するもの（一時的な雑談ではなく、不変の事実、好み、約束、結果など）を決定します。記憶の候補は、コンパクトで自己完結した記述に要約され、既存の記憶と照合されて重複や矛盾が検出された後、メモリタイプ、タイムスタンプ、ソース、所属するユーザーまたはスコープなどのメタデータとともにストアに書き込まれます。少なく、かつ質高く書き込むことが目標です。ノイズの多い記憶は、その後の取得プロセスを阻害します。\\n\\n読み取りパスでは、エージェントが推論を行う前に、現在のタスクに関連する記憶の候補を（通常はセマンティック類似度に加え、スコープや新しさのフィルターを用いて）取得し、ランク付けして、上位の数件のみをコンテキストに注入します。取得は適合率（プレシジョン）の問題として捉えてください。関連性の薄い大量の記憶よりも、少数の正確な記憶の方が効果的です。取得をターゲット化できるように、記憶のタイプを区別します。エピソード記憶（何が起きたか）、意味記憶（永続的な事実や好み）、手続き記憶（繰り返し発生するタスクの実行方法）などです。定期的に記憶を整理（集約）および期限切れにすることで、ストアを小さく、最新の状態に保ち、矛盾を排除します。" ], "components": [ "メモリ抽出器（書き込みパス）", "重複排除および矛盾チェック", "メモリストア", "リトリーバー（読み取りパス）", "コンテキストアセンブラー", "集約および期限切れジョブ" ], "benefits": [ "エージェントが過去のセッションからの好み、決定、結果を思い出すため、ユーザーがコンテキストを繰り返す必要がなくなり、エージェントは長期にわたって一貫した動作を維持できます。", "いくつかの関連する記憶のみを取得することで、履歴全体をダンプする代わりに、ウィンドウを価値の高いトークンに集中させることができます。これにより、推論の質が維持され、コストが削減されます。", "不変の事実や好みが蓄積されるにつれて、モデルを再学習させることなく、インタラクションを重ねるごとにエージェントはより正確にパーソナライズされた応答を返せるようになります。", "記憶はメタデータとともに外部ストアに保存されるため、エージェントが知っている内容を検査、修正、エクスポート、削除できます。これは信頼性とコンプライアンスにおいて重要です。" ], "risks": [ "集約と期限切れの処理を行わないと、ストアに古い事実や矛盾する記述が蓄積され、エージェントが誤った情報に基づいて自信満々に行動してしまう可能性があります。", "ユーザーデータを永続化すると、保持、同意、アクセス制御の義務が生じます。スコープが強制されていない場合、記憶によってセッション間やユーザー間で機密情報が漏洩する可能性があります。", "適合率（プレシジョン）が低いと、無関係な記憶や誤った記憶が注入されて推論が誤った方向に導かれます。再現率（リコール）が低いと、重要な記憶が暗黙的にドロップされ、失敗の診断が困難になります。", "過剰に書き込みを行うと、ストアが肥大化し、取得が遅くなり、ストレージと埋め込み（embedding）のコストが上昇し、優れた取得の前提となるシグナルが希薄化します。" ], "whenNot": [ "セッションが独立しており、引き継ぐべき情報がない場合、永続メモリはメリットをもたらさず、複雑さ、コスト、プライバシーのリスクを増大させるだけです。", "繰り返されるクエリに対して以前の回答を再利用することが目的である場合は、セマンティックキャッシュが適切なツールです。長期記憶は事実や状態を記憶するためのものであり、出力をキャッシュするためのものではありません。", "規制やポリシーによってユーザーデータの保持が禁止されている場合は、記憶を永続化しないでください。セッション内のコンテキストや、ユーザーが制御する明示的でスコープ限定されたストレージに依存してください。" ], "examples": [ "セッションをまたいでトーン、フォーマット、頻繁に連絡する相手、常時指示を記憶し、再質問する代わり現在のリクエストに適用される少数の指示を取得します。", "コンタクトのたびに、そのアカウントにスコープされた顧客の過去の課題、資格、解決策を取得するため、会話を最初からやり直すのではなく、継続することができます。", "手続き記憶（ビルドコマンド、命名規則、レビューの好みなど）を保存し、多くのセッションにわたって同じリポジトリで作業する際にそれらを呼び出します。" ], "productionEvidence": { "context": "57日間（161セッション / 2,776ターン）にわたって観察された、シングルオペレーター、ローカルファーストのOpenClawデプロイメント。エージェント自身のトラジェクトリトレースから集計。", "scenario": "エージェントは、ターン間およびセッション間の継続性のためにワークスペースメモリファイルとセッションごとのトレースを永続化し、オンデマンドでセマンティックリコールプラグインを利用できるようにします。", "technology": "ワークスペースメモリファイル（MEMORY.md、IDENTITY.md、SOUL.md、USER.md、HEARTBEAT.md）、永続的なセッションIDとライフサイクルイベント、およびアクティブメモリプラグイン（memory_search/get/recall）。", "load": "57日間のウィンドウ全体で134の永続化されたセッションファイル。セマンティックリコールは1回呼び出されました。", "results": "構造化されたワークスペースメモリにより、57日間にわたる134の永続セッション全体で継続性が維持されました。この自律的なワークロードにおいて、明示的なセマンティックリコールはほとんど必要ありませんでした（呼び出しは1回）。単一オペレーターによるローカルファーストのデプロイメント。" }, "kpis": [ { "metric": "注入されたメモリの検索適合率（Precision）", "note": "コンテキストに配置されたメモリのうち、実際に関連していたものの割合。これは回答の品質を最も直接的に左右する指標です。良好な状態とは、注入されたメモリセットがほぼ完全にトピックに沿っており、無関係なメモリがほとんどない状態を指します。" }, { "metric": "メモリ依存タスクにおける検索再現率（Recall）", "note": "既知の保存された事実を必要とするタスクにおいて、その事実が実際に検索される頻度。良好な状態とは、適切なメモリが確実に表面化することです。継続的な検索漏れは、抽出またはインデックス作成のギャップを示しています。" }, { "metric": "メモリストアのサイズと成長率", "note": "総メモリ数と、アクティブユーザーあたりの蓄積速度。良好な状態とは、制限のない増加ではなく、真に新しい永続的な事実に追従して成長することです。制御不能な急上昇曲線は、過剰な書き込みが行われていることを示します。" }, { "metric": "陳腐化および矛盾の発生率", "note": "検索されたメモリのうち、古くなっているか、より新しい事実と矛盾しているものの割合。良好な状態とは、この割合が低く安定していることであり、整理（consolidation）と有効期限切れ（expiry）の処理が変化に追いついている証拠です。" } ], "failureModes": [ "すべてを書き込むとストアがノイズ化し、検索時に価値の低いメモリや誤ったメモリが表面化します。書き込む情報の基準を引き上げ、抽出品質を見直すことで解決します。", "事実が変更された後、それが古くなっているというシグナルがないまま、古い事実が検索されて実行されてしまいます。タイムスタンプ、新しさを重視した重み付けランキング、および書き込み時の明示的な上書き（supersession）によって軽減します。", "スコープフィルターの欠落や誤りにより、あるユーザー、テナント、またはプロジェクトのメモリが別のコンテキストに検索されてしまいます。これはプライバシーと正確性の両方における重大な障害です。", "ランキング精度の低さを補うために、チームが多数のメモリを注入してしまい、コンテキストウィンドウが重要度の低いトークンで埋め尽くされ、メモリが本来サポートすべき推論能力自体が低下します。" ], "lessons": [ "品質は、何を記憶するかを選択する時点で決まります。重複が排除された、小さくクリーンなストアは、ノイズの多い巨大なストアよりもはるかに優れた検索精度を発揮します。", "少数の正確なメモリは、緩やかに関連する多数 of メモリよりも優れたパフォーマンスを発揮します。注入する量を最大化するのではなく、関連性を調整し、厳密にランク付けしてください。", "メタデータを保存し、メモリの表示、編集、期限切れ、削除を行う方法を提供してください。これは、デバッグ、信頼性の確保、およびプライバシー義務の遵守に不可欠です。", "事実は陳腐化し、互いに矛盾するようになります。整理、上書き、および有効期限切れの仕組みを早期に構築してください。汚染された大規模なストアにこれらを後から組み込むのは極めて困難です。" ], "faqs": [ { "q": "セマンティックキャッシュとはどのように違うのですか？", "a": "セマンティックキャッシュは、同様のリクエストの再計算を避けるために、回答全体を保存して再利用します。長期メモリは、永続的な事実、好み、および結果を保存し、新しいタスクごとにそれらを再構成して新たな推論を行います。一方は出力を再利用し、他方は状態を記憶します。" }, { "q": "エージェントは実際に何を記憶すべきですか？", "a": "ユーザーの好み、決定とコミットメント、以前のタスクの結果、繰り返し発生する手順など、安定して再利用可能なシグナルです。一時的な雑談や、保持する正当な理由がないものは避けてください。書き込み量を抑え、質の高い書き込みを行うことが、後の検索精度を高める鍵となります。" }, { "q": "PII（個人特定情報）とプライバシーはどのように処理しますか？", "a": "ストアをガバナンス対象データとして扱います。メモリがユーザーやテナントをまたぐことがないようスコープを強制し、永続化するデータを最小限に抑え、同意と削除をサポートし、保持期間とアクセス制御を設定します。監査可能性と有効期限ポリシーは、これらの義務を果たすための要素です。" } ] }, "zh": { "name": "长期记忆", "summary": "为智能体提供跨会话的持久化记忆，使其能够在单个上下文窗口之外记住事实、用户偏好和先前的结果。写入路径决定存储什么、对其进行摘要并去重；读取路径在需要时仅将相关的记忆检索到上下文中。与缓存完整答案以跳过重复计算的语义缓存不同，长期记忆存储持久的事实和状态，并在每次进行新的推理时重新组合它们。", "problem": "上下文窗口是有限的，并且会在会话之间重置。仅关注当前对话的智能体会遗忘用户声明的偏好、上周做出的决定以及先前任务的结果。在超过一定规模后，将所有历史记录塞进每个提示词中是不可能的，而且随着窗口被低价值 Token 填满，推理质量也会下降。团队需要一种方法来持久化存储少数关键事实，并在它们相关时精准地呈现出来。", "context": "当智能体需要重复服务相同的用户或处理相同的长期运行任务时，请使用此模式：例如学习偏好的助手、跟踪客户历史记录的支持智能体、记住项目规范的编码智能体，或跨越数天的多步骤工作流。它假设您可以在模型外部存储数据（向量存储、数据库或记忆框架），并且您可以控制何时写入记忆以及如何将记忆检索到提示词中。", "solution": [ "将写入路径与读取路径分离。在写入路径上，在单轮对话或任务完成后，提取步骤会决定哪些内容值得记住：稳定的事实、偏好、承诺和结果——而不是瞬时的闲聊。候选记忆会被总结为紧凑、自包含的陈述，并与现有记忆进行比对以去重和检测冲突，然后写入带有元数据（记忆类型、时间戳、来源以及所属的用户或范围）的存储中。目标是少写但写好，嘈杂的记忆会污染后续的检索。\n\n在读取路径上，在智能体进行推理之前，您需要检索与当前任务相关的候选记忆（通常通过语义相似度加上范围和时效性过滤器），对其进行排序，并仅将前几个注入到上下文中。将检索视为一个精度问题：少数正确的记忆胜过大量松散相关的记忆。区分记忆类型以便进行有针对性的检索：情景记忆（发生了什么）、语义记忆（持久的事实和偏好）和程序记忆（如何执行循环任务）。定期合并和过期记忆，以保持存储的小型化、最新性且无冲突。" ], "components": [ "记忆提取器（写入路径）", "去重与冲突检查", "记忆存储", "检索器（读取路径）", "上下文装配器", "合并与过期任务" ], "benefits": [ "智能体能够召回先前会话中的偏好、决定和结果，因此用户无需重复提供上下文，且智能体随时间推移表现出一致的行为。", "仅检索少数相关的记忆可以使窗口专注于高价值 Token，而不是倾倒全部历史记录，从而保证了推理质量并降低了成本。", "随着稳定事实和偏好的积累，智能体在每次交互中都能更准确地定制回复，而无需重新训练模型。", "由于记忆保存在带有元数据的外部存储中，您可以检查、纠正、导出和删除智能体所知的内容——这对于信任和合规性至关重要。" ], "risks": [ "如果没有合并和过期机制，存储中会积累过时的事实和相互冲突的陈述，导致智能体自信地基于错误的信息采取行动。", "持久化用户数据会增加数据保留、同意和访问控制方面的义务；如果未强制执行范围限制，记忆可能会跨会话或跨用户泄露敏感信息。", "低精准度会注入无关或错误的记忆，从而误导推理；低召回率会默默丢弃关键记忆，使故障难以诊断。", "过度频繁的写入会使存储膨胀、减慢检索速度、增加存储和嵌入成本，并稀释高质量检索所依赖的信号。" ], "whenNot": [ "如果会话是独立的且不需要传递任何内容，持久化记忆只会增加复杂性、成本和隐私风险，而不会带来任何好处。", "当目标是为重复的查询重用以前的答案时，语义缓存是正确的工具；长期记忆用于记住事实和状态，而不是缓存输出。", "在法规或政策禁止保留用户数据的情况下，请勿持久化记忆；应依赖会话内上下文或用户控制的、有明确范围限制的显式存储。" ], "examples": [ "跨会话记住语气、格式、常用联系人和现行指令，仅检索适用于当前请求的少数内容，而不是重新询问。", "在每次联系时，它会检索该账户范围内的客户先前问题、权益和解决方案，从而继续对话而不是重新开始。", "它存储程序记忆——构建命令、命名规则、评审偏好——并在跨多个会话在同一个代码库中工作时召回它们。" ], "productionEvidence": { "context": "在 57 天（161 个会话 / 2,776 轮）内观察到的单操作员、本地优先的 OpenClaw 部署，数据从智能体自身的轨迹追踪中聚合而来。", "scenario": "智能体持久化工作区记忆文件和每个会话的追踪，以实现跨轮次和跨会话的连续性，并可根据需要使用语义召回插件。", "technology": "工作区记忆文件（MEMORY.md、IDENTITY.md、SOUL.md、USER.md、HEARTBEAT.md）、持久化会话 ID 和生命周期事件，以及活动记忆插件（memory_search/get/recall）。", "load": "在 57 天的窗口期内共有 134 个持久化会话文件；语义召回被调用了一次。", "results": "通过结构化工作区记忆，在 57 天内的 134 个持久化会话中保持了连续性；在此自主工作负载中，极少需要显式语义召回（仅调用一次）。单操作员本地优先部署。" }, "kpis": [ { "metric": "注入记忆的检索精准率", "note": "在放入上下文的记忆中，实际相关的比例。这是最直接决定回答质量的指标；表现良好意味着注入的记忆集几乎完全切题，极少出现无关记忆。" }, { "metric": "依赖记忆的任务的检索召回率", "note": "在需要已知存储事实的任务中，该事实实际被检索到的频率。表现良好意味着正确的记忆能够可靠地呈现；持续遗漏则表明存在提取或索引差距。" }, { "metric": "记忆库大小和增长率", "note": "总记忆量以及每个活跃用户的累积速度。表现良好意味着增长与真正新增的持久事实保持同步，而不是无限制地攀升——失控的曲线表明写入过于频繁。" }, { "metric": "陈旧率和冲突率", "note": "检索到的记忆中已过时或与更新的事实相冲突的比例。表现良好意味着该比例低且稳定，这证明整合和过期机制跟上了变化的速度。" } ], "failureModes": [ "记录所有内容会导致记忆库充斥噪音；检索时就会呈现低价值或错误的记忆。解决方法是提高写入内容的门槛，并审查提取质量。", "在事实发生变化后，检索并执行了旧的事实，且没有任何其已过时的信号。通过时间戳、基于新鲜度权重的排序以及在写入时显式更替来缓解此问题。", "由于缺少或错误的范围过滤器，导致某个用户、租户或项目的记忆被检索到了另一个的上下文中——这同时属于隐私和正确性故障。", "为了弥补排序不佳的问题，团队注入了大量记忆，导致窗口中充斥着边缘 Token，从而降低了记忆本应支持的推理能力。" ], "lessons": [ "质量取决于你选择记住什么。一个小型、干净、去重的记忆库，其检索效果远好于一个庞大且嘈杂的记忆库。", "少数正确的记忆胜过大量弱相关的记忆。应针对相关性进行微调并严格排序，而不是最大化注入量。", "存储元数据并提供查看、编辑、过期和删除记忆的方法。这对于调试、建立信任以及履行隐私义务至关重要。", "事实会变陈旧并相互冲突。尽早构建整合、更替和过期机制；在已被污染的大型记忆库上进行后期改造会非常痛苦。" ], "faqs": [ { "q": "这与语义缓存有什么不同？", "a": "语义缓存存储并重放完整的回答，以避免重复计算相似的请求。长期记忆则存储持久的事实、偏好和结果，然后针对每个新任务将它们重新组合成全新的推理。前者重用输出，后者记住状态。" }, { "q": "智能体实际上应该记住什么？", "a": "稳定、可重用的信号：用户偏好、决策与承诺、先前任务的结果以及循环往复的流程。避免记录瞬时的闲聊以及任何无法证明保留合理性的内容。写得少但写得好，才能保证后续检索的精准。" }, { "q": "如何处理 PII 和隐私？", "a": "将记忆库视为受治理的数据：强制执行范围限制，确保记忆绝不跨用户或租户，尽量减少持久化的内容，支持知情同意 and 删除，并设置保留和访问控制。可检查性和过期策略是履行这些义务的一部分。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/orchestrator-workers", "api_url": "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." } ] }, "fr": { "name": "Orchestrateur-Workers", "summary": "Un LLM orchestrateur décompose dynamiquement une tâche en sous-tâches, délègue chacune à un LLM worker, et synthétise les résultats. Contrairement à la parallélisation fixe, l'orchestrateur décide des sous-tâches au moment de l'exécution — ce qui le rend adapté aux tâches complexes dont la décomposition n'est pas connue à l'avance.", "problem": "Certaines tâches sont trop complexes pour un seul appel et ne peuvent pas être décomposées à l'avance, car les sous-tâches nécessaires dépendent de l'entrée.", "context": "Utilisez le modèle orchestrateur-workers lorsqu'une tâche nécessite une décomposition dynamique — le nombre et la nature des sous-tâches variant selon l'entrée — et qu'un modèle de coordination peut planifier et intégrer le travail.", "solution": [ "Un modèle principal (orchestrateur) analyse la tâche, décide des sous-tâches nécessaires et délègue chacune à un modèle worker (souvent spécialisé). Il collecte et synthétise ensuite les sorties des workers en un résultat final.", "Il s'agit de la généralisation agentique de la parallélisation : la décomposition est décidée au moment de l'exécution plutôt que codée en dur, ce qui ajoute de la flexibilité au prix d'une coordination accrue et d'une plus grande imprévisibilité." ], "components": [ "Modèle orchestrateur (principal)", "Modèles workers", "Logique de délégation", "Synthétiseur", "État partagé / outils" ], "benefits": [ "Gère les tâches complexes avec une décomposition dynamique.", "Les workers peuvent être spécialisés par sous-tâche.", "S'adapte à des entrées variées sans étapes codées en dur." ], "risks": [ "Surcharge de coordination, latence et coût en jetons.", "Plus difficile à prédire et à déboguer que les flux de travail fixes.", "L'orchestrateur peut mal planifier ou boucler sans limites." ], "whenNot": [ "Lorsque la décomposition est connue à l'avance — utilisez le chaînage ou la parallélisation fixe.", "Pour les tâches simples qu'un seul appel peut traiter.", "Lorsque la prévisibilité et un contrôle strict des coûts sont primodiaux." ], "examples": [ "Une tâche de codage où le lead décide quels fichiers modifier et délègue les éditions.", "Une tâche de recherche divisée en sous-questions, chacune faisant l'objet de recherches puis d'une synthèse.", "Un rapport complexe assemblé à partir de sections choisies dynamiquement." ], "productionEvidence": { "context": "Déploiement OpenClaw local-first à opérateur unique observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des propres traces de trajectoire de l'agent.", "scenario": "Le travail planifié s'exécute dans des sessions de workers isolées et uniques, dupliquées (forked) depuis le parent, avec une délimitation des capacités et des limites d'enfants/profondeur.", "technology": "Runtime d'agent isolé Cron, duplication de session (forkSessionFromParent), un couloir et registre de sous-agents, et limites d'enfants/profondeur par agent.", "load": "57 sessions de workers isolées par cron sur la fenêtre (l'outil explicite sessions.spawn n'a pas été utilisé).", "results": "57 sessions de workers isolées ont fonctionné sans interférence entre sessions ; l'isolation par duplication de session (forked-session) a été le modèle de worker dominant, tandis que l'outil explicite spawn est resté inutilisé dans cette fenêtre. Déploiement local-first à opérateur unique." }, "kpis": [ { "metric": "Taux de réussite des tâches de bout en bout", "note": "Part des tâches orchestrées qui se terminent correctement sur l'ensemble des sous-tâches ; l'orchestrateur est responsable du résultat global." }, { "metric": "Facteur de division (fan-out) et coût des workers", "note": "Nombre d'appels de workers par tâche et leur coût combiné en jetons ; l'orchestration peut faire exploser les dépenses si la décomposition est bâclée." }, { "metric": "Latence du chemin critique", "note": "Temps réel de la chaîne dépendante la plus longue, et non la somme des workers — cela limite la réactivité." }, { "metric": "Taux d'erreur des sous-tâches", "note": "Fréquence à laquelle les workers individuels échouent ou renvoient des résultats inutilisables, entraînant des tentatives de réessai et de récupération." } ], "failureModes": [ "Mauvaise décomposition : l'orchestrateur divise mal la tâche, de sorte que des workers corrects produisent tout de même un résultat global erroné.", "Perte de contexte entre l'orchestrateur et les workers, provoquant des résultats partiels incohérents ou contradictoires.", "Explosion des coûts due à la création de trop nombreux workers ou à une imbrication profonde sans limites de budget.", "Point de défaillance unique : si l'orchestrateur évalue mal la situation, l'ensemble de la tâche échoue malgré des workers sains." ], "lessons": [ "Investissez dans la logique de décomposition — la plupart des échecs proviennent de la manière dont le travail a été divisé, et non des workers.", "Transmettez explicitement aux workers le contexte minimal dont ils ont besoin pour éviter les dérives et les contradictions.", "Définissez un budget et une limite de profondeur ; l'orchestration sans limites est la cause de l'envolée des coûts des agents.", "Rendez le plan de l'orchestrateur inspectable afin que les échecs puissent être attribués à une sous-tâche spécifique." ], "faqs": [ { "q": "En quoi cela diffère-t-il de la parallélisation ?", "a": "La parallélisation utilise une division fixe et prédéfinie. Orchestrator-workers décide des sous-tâches de manière dynamique au moment de l'exécution, ce qui lui permet de gérer des tâches dont la forme varie selon l'entrée." }, { "q": "S'agit-il d'un système multi-agent ?", "a": "Oui — c'est un modèle multi-agent courant. Utilisez-le uniquement lorsqu'une tâche bénéficie réellement de sous-tâches dynamiques et séparables." }, { "q": "Comment éviter qu'il ne devienne incontrôlable ?", "a": "Définissez des budgets, des limites d'étapes et des conditions d'arrêt, et ajoutez de l'observabilité afin de pouvoir visualiser et limiter la planification de l'orchestrateur." } ] }, "de": { "name": "Orchestrator-Workers", "summary": "Ein Orchestrator-LLM zerlegt eine Aufgabe dynamisch in Teilaufgaben, delegiert diese jeweils an ein Worker-LLM und führt die Ergebnisse zusammen. Im Gegensatz zur festen Parallelisierung entscheidet der Orchestrator zur Laufzeit über die Teilaufgaben – was ihn für komplexe Aufgaben eignet, deren Zerlegung im Vorfeld nicht bekannt ist.", "problem": "Einige Aufgaben sind zu komplex für einen einzelnen Aufruf und können nicht im Vorfeld zerlegt werden, da die benötigten Teilaufgaben von der Eingabe abhängen.", "context": "Verwenden Sie das Orchestrator-Workers-Muster, wenn eine Aufgabe eine dynamische Zerlegung erfordert – die Anzahl und Art der Teilaufgaben variieren je nach Eingabe – und ein koordinierendes Modell die Arbeit planen und integrieren kann.", "solution": [ "Ein führendes Modell (Orchestrator) analysiert die Aufgabe, entscheidet, welche Teilaufgaben erforderlich sind, und delegiert diese jeweils an ein (oft spezialisiertes) Worker-Modell. Anschließend sammelt und synthetisiert es die Ausgaben der Worker zu einem Endergebnis.", "Es ist die agentenbasierte Generalisierung der Parallelisierung: Die Zerlegung wird zur Laufzeit entschieden und nicht fest codiert, was Flexibilität auf Kosten von mehr Koordination und Unvorhersehbarkeit bringt." ], "components": [ "Orchestrator-Modell (Lead)", "Worker-Modelle", "Delegationslogik", "Synthesizer", "Gemeinsamer Zustand / Tools" ], "benefits": [ "Bewältigt komplexe Aufgaben mit dynamischer Zerlegung.", "Worker können pro Teilaufgabe spezialisiert werden.", "Skaliert für unterschiedliche Eingaben ohne fest codierte Schritte." ], "risks": [ "Koordinationsaufwand, Latenz und Token-Kosten.", "Schwerer vorherzusagen und zu debuggen als feste Workflows.", "Der Orchestrator kann Fehlplanungen vornehmen oder in Endlosschleifen geraten." ], "whenNot": [ "Wenn die Zerlegung im Vorfeld bekannt ist – verwenden Sie Chaining oder feste Parallelisierung.", "Für einfache Aufgaben, die mit einem einzigen Aufruf erledigt werden können.", "Wenn Vorhersehbarkeit und strenge Kostenkontrolle im Vordergrund stehen." ], "examples": [ "Eine Programmieraufgabe, bei der das Lead-Modell entscheidet, welche Dateien geändert werden sollen, und die Bearbeitungen delegiert.", "Eine Forschungsaufgabe, die in Teilfragen aufgeteilt wird, die jeweils untersucht und anschließend synthetisiert werden.", "Ein komplexer Bericht, der aus dynamisch ausgewählten Abschnitten zusammengestellt wird." ], "productionEvidence": { "context": "Lokale Bereitstellung für einen einzelnen Operator (Local-First) von OpenClaw, beobachtet über 57 Tage (161 Sessions / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Geplante Arbeiten laufen in isolierten, einmaligen Worker-Sessions, die vom übergeordneten Prozess geforkt wurden, mit Berechtigungseinschränkungen (Capability Scoping) sowie Limits für Child-Prozesse und Tiefe.", "technology": "Cron-isolierte Agenten-Laufzeitumgebung, Session-Forking (forkSessionFromParent), eine Subagenten-Lane und -Registry sowie Child-/Tiefenlimits pro Agent.", "load": "57 Cron-isolierte Worker-Sessions über das Zeitfenster (das explizite Tool sessions.spawn wurde nicht verwendet).", "results": "57 isolierte Worker-Sessions liefen ohne gegenseitige Beeinflussung; die Isolation durch geforkte Sessions war das dominierende Worker-Muster, während das explizite Spawn-Tool in diesem Zeitfenster ungenutzt blieb. Lokale Bereitstellung für einen einzelnen Operator (Local-First)." }, "kpis": [ { "metric": "End-to-End-Aufgabenerfüllungsrate", "note": "Anteil der orchestrierten Jobs, die über alle Teilaufgaben hinweg korrekt abgeschlossen werden; der Orchestrator trägt die Verantwortung für das Gesamtergebnis." }, { "metric": "Worker-Fan-out & Kosten", "note": "Anzahl der Worker-Aufrufe pro Job und deren kombinierte Token-Kosten; die Orchestrierung kann die Ausgaben explodieren lassen, wenn die Zerlegung ungenau ist." }, { "metric": "Latenz des kritischen Pfads", "note": "Tatsächliche Laufzeit (Wall-clock) der längsten abhängigen Kette, nicht die Summe der Worker – dies begrenzt die Reaktionsfähigkeit." }, { "metric": "Fehlerrate der Teilaufgaben", "note": "Wie oft einzelne Worker fehlschlagen oder unbrauchbare Ergebnisse liefern, was zu Wiederholungsversuchen und Fehlerbehebungen führt." } ], "failureModes": [ "Fehlerhafte Zerlegung: Der Orchestrator teilt die Aufgabe falsch auf, sodass korrekt arbeitende Worker dennoch ein falsches Gesamtergebnis liefern.", "Kontextverlust zwischen Orchestrator und Workern, was zu inkonsistenten oder widersprüchlichen Teilergebnissen führt.", "Kostenexplosion durch das Erzeugen zu vieler Worker oder tiefe Verschachtelung ohne Budgetgrenzen.", "Single Point of Failure: Wenn sich der Orchestrator verschätzt, schlägt der gesamte Job trotz funktionierender Worker fehl." ], "lessons": [ "Investieren Sie in die Zerlegungslogik – die meisten Fehler lassen sich darauf zurückführen, wie die Arbeit aufgeteilt wurde, nicht auf die Worker.", "Übergeben Sie Workern explizit nur den minimal benötigten Kontext, um Abweichungen und Widersprüche zu vermeiden.", "Legen Sie ein Budget und ein Tiefenlimit fest; eine grenzenlose Orchestrierung lässt die Agenten-Kosten explodieren.", "Machen Sie den Plan des Orchestrators einsehbar, damit Fehler auf eine bestimmte Teilaufgabe zurückgeführt werden können." ], "faqs": [ { "q": "Wie unterscheidet sich dies von der Parallelisierung?", "a": "Die Parallelisierung nutzt eine feste, vordefinierte Aufteilung. Orchestrator-Workers entscheidet über die Teilaufgaben dynamisch zur Laufzeit und bewältigt so Aufgaben, deren Struktur je nach Eingabe variiert." }, { "q": "Handelt es sich hierbei um ein Multi-Agenten-System?", "a": "Ja – es ist ein gängiges Multi-Agenten-Muster. Verwenden Sie es nur, wenn eine Aufgabe tatsächlich von dynamischen, trennbaren Teilaufgaben profitiert." }, { "q": "Wie verhindere ich, dass es außer Kontrolle gerät?", "a": "Legen Sie Budgets, Schrittbegrenzungen und Abbruchbedingungen fest und fügen Sie Observability hinzu, damit Sie die Planung des Orchestrators einsehen und eingrenzen können." } ] }, "ja": { "name": "オーケストレーター・ワーカー（Orchestrator-Workers）", "summary": "オーケストレーターLLMがタスクを動的にサブタスクに分割し、それぞれをワーカーLLMに委譲して、結果を統合します。固定された並列化とは異なり、オーケストレーターは実行時にサブタスクを決定するため、事前に分解方法がわからない複雑なタスクに適しています。", "problem": "一部のタスクは1回の呼び出しで処理するには複雑すぎて、必要なサブタスクが入力に依存するため、事前に分解することができません。", "context": "タスクに動的な分解が必要な場合（サブタスクの数や性質が入力によって異なる場合）、および調整モデルが作業を計画して統合できる場合に、オーケストレーター・ワーカーを使用します。", "solution": [ "リード（オーケストレーター）モデルがタスクを分析し、必要なサブタスクを決定して、それぞれを（多くの場合、特化した）ワーカーモデルに委譲します。その後、ワーカーの出力を収集して最終結果に統合します。", "これは並列化のエージェント的汎用化です。分解はハードコードされるのではなく実行時に決定されるため、柔軟性が向上する一方で、調整コストと予測不可能性が増加します。" ], "components": [ "オーケストレーター（リード）モデル", "ワーカーモデル", "委譲ロジック", "シンセサイザー（統合器）", "共有状態 / ツール" ], "benefits": [ "動的な分解を伴う複雑なタスクを処理できます。", "サブタスクごとにワーカーを特化させることができます。", "ハードコードされたステップなしで、多様な入力に対応してスケールします。" ], "risks": [ "調整のオーバーヘッド、レイテンシー、およびトークンコスト。", "固定されたワークフローよりも予測やデバッグが困難です。", "オーケストレーターが計画を誤ったり、制限なくループしたりする可能性があります。" ], "whenNot": [ "分解方法が事前にわかっている場合。チェーニングまたは固定の並列化を使用してください。", "1回の呼び出しで処理できるシンプルなタスクの場合。", "予測可能性と厳格なコスト管理が最優先される場合。" ], "examples": [ "リードが変更すべきファイルを決定し、編集を委譲するコーディングタスク。", "調査タスクをサブ質問に分割し、それぞれを調査した後に統合するケース。", "動的に選択されたセクションから組み立てられる複雑なレポート。" ], "productionEvidence": { "context": "57日間にわたり観察された単一オペレーター、ローカルファーストのOpenClawデプロイメント（161セッション / 2,776ターン）。エージェント自身のトラジェクトリトレースから集計。", "scenario": "スケジュールされたワークは、親からフォークされた隔離されたワンショットのワーカーセッションで実行され、機能スコープおよび子/深度の制限が適用されます。", "technology": "Cron隔離エージェントランタイム、セッションフォーク（forkSessionFromParent）、サブエージェントレーンおよびレジストリ、エージェントごとの子/深度制限。", "load": "対象期間中に57のCron隔離ワーカーセッション（明示的なsessions.spawnツールは実行されませんでした）。", "results": "57の隔離されたワーカーセッションがセッション間の干渉なしに実行されました。フォークされたセッションの隔離が主要なワーカーパターンであり、この期間中、明示的なspawnツールは未使用のままでした。単一オペレーターによるローカルファーストのデプロイメント。" }, "kpis": [ { "metric": "エンドツーエンドのタスク完了率", "note": "オーケストレーションされたジョブのうち、すべてのサブタスクにわたって正しく完了した割合。オーケストレーターが結果全体に責任を持ちます。" }, { "metric": "ワーカーのファンアウトとコスト", "note": "ジョブあたりのワーカー呼び出し回数と、それらの合計トークンコスト。分解が不十分な場合、オーケストレーションによって支出が爆発的に増加する可能性があります。" }, { "metric": "クリティカルパスのレイテンシー", "note": "ワーカーの合計時間ではなく、最も長い依存チェーンの実時間（ウォールクロック時間）。これが応答性の限界を決定します。" }, { "metric": "サブタスクのエラー率", "note": "個々のワーカーが失敗するか、使用不可能な結果を返す頻度。これにより再試行やリカバリが発生します。" } ], "failureModes": [ "不適切な分解：オーケストレーターがタスクを誤って分割するため、個々のワーカーが正しく動作しても、全体として誤った結果が生成されます。", "オーケストレーターとワーカー間のコンテキスト喪失。これにより、一貫性のない、または矛盾する部分的な結果が生じます。", "予算制限なしに多数のワーカーを生成したり、深いネストを行ったりすることによるコストの爆発的増加。", "単一障害点：オーケストレーターが判断を誤ると、ワーカーが正常であってもジョブ全体が失敗します。" ], "lessons": [ "分解ロジックに投資してください。ほとんどの失敗は、ワーカーではなく、作業の分割方法に起因しています。", "乖離や矛盾を避けるために、ワーカーには必要な最小限のコンテキストを明示的に渡してください。", "予算と深度の上限を設定してください。制限のないオーケストレーションは、エージェントコストが急上昇する原因になります。", "失敗を特定のサブタスクまで追跡できるように、オーケストレーターの計画を検査可能にしてください。" ], "faqs": [ { "q": "並列化とはどのように違うのですか？", "a": "並列化は、固定された事前定義済みの分割を使用します。オーケストレーター・ワーカーは実行時に動的にサブタスクを決定するため、入力によって形状が変化するタスクを処理できます。" }, { "q": "これはマルチエージェントシステムですか？", "a": "はい。これは一般的なマルチエージェントパターンです。タスクが動的で分離可能なサブタスクから真に恩恵を受ける場合にのみ使用してください。" }, { "q": "暴走を防ぐにはどうすればよいですか？", "a": "予算、ステップ制限、停止条件を設定し、オブザーバビリティ（可観測性）を追加することで、オーケストレーターの計画を可視化し、制限できるようにします。" } ] }, "zh": { "name": "编排器-工作器", "summary": "编排器 LLM 动态地将任务分解为子任务，将每个子任务委派给工作器 LLM，并综合结果。与固定的并行化不同，编排器在运行时决定子任务，这使其适用于无法提前预知如何分解的复杂任务。", "problem": "某些任务过于复杂，无法通过单次调用完成，且无法提前分解，因为所需的子任务取决于输入。", "context": "当任务需要动态分解（子任务的数量和性质因输入而异），且协调模型能够规划和整合工作时，请使用编排器-工作器模式。", "solution": [ "主导（编排器）模型分析任务，决定需要哪些子任务，并将每个子任务委派给工作器模型（通常是专门的）。然后，它收集并综合工作器的输出以生成最终结果。", "它是并行化在智能体（Agentic）层面的泛化：分解是在运行时决定的，而不是硬编码的，这增加了灵活性，但代价是更多的协调工作和不可预测性。" ], "components": [ "编排器（主导）模型", "工作器模型", "委派逻辑", "综合器", "共享状态 / 工具" ], "benefits": [ "处理具有动态分解特征的复杂任务。", "工作器可以针对每个子任务进行专门化。", "无需硬编码步骤即可扩展以适应各种输入。" ], "risks": [ "协调开销、延迟和 Token 成本。", "比固定工作流更难预测和调试。", "编排器可能会规划失误或进行无限循环。" ], "whenNot": [ "当分解方式提前已知时——使用链式调用或固定并行化。", "适用于单次调用即可处理的简单任务。", "当可预测性和严格的成本控制至关重要时。" ], "examples": [ "一个编码任务，其中主导模型决定要修改哪些文件并委派编辑工作。", "一个研究任务，被拆分为若干子问题，每个子问题分别进行研究然后进行综合。", "一份由动态选择的章节组装而成的复杂报告。" ], "productionEvidence": { "context": "在 57 天内（161 个会话 / 2,776 个轮次）观察到的单操作员、本地优先 OpenClaw 部署，数据自智能体自身的轨迹追踪聚合而来。", "scenario": "计划的工作在从父会话派生的隔离、一次性工作器会话中运行，并具有能力范围限制以及子会话/深度限制。", "technology": "Cron 隔离智能体运行时、会话派生（forkSessionFromParent）、子智能体通道与注册表，以及每个智能体的子会话/深度限制。", "load": "在窗口期内共有 57 个 Cron 隔离的工作器会话（未调用显式的 sessions.spawn 工具）。", "results": "57 个隔离的工作器会话在没有跨会话干扰的情况下运行；派生会话隔离是主要的工作器模式，而显式的 spawn 工具在此窗口期内保持未使用状态。单操作员本地优先部署。" }, "kpis": [ { "metric": "端到端任务完成率", "note": "在所有子任务中正确完成的编排作业比例；编排器对整个结果负责。" }, { "metric": "工作器扇出与成本", "note": "每个作业的工作器调用次数及其合并的 Token 成本；如果分解过于草率，编排可能会导致开销激增。" }, { "metric": "关键路径延迟", "note": "最长依赖链的实际耗时，而不是工作器耗时的总和——这限制了响应速度。" }, { "metric": "子任务错误率", "note": "单个工作器失败或返回不可用结果的频率，这会触发重试和恢复。" } ], "failureModes": [ "糟糕的分解：编排器错误地拆分了任务，导致即使工作器正确执行，最终仍产生错误的结果。", "编排器与工作器之间丢失上下文，导致部分结果不一致或相互矛盾。", "由于在没有预算限制的情况下生成过多工作器或进行深层嵌套，导致成本激增。", "单点故障：如果编排器判断失误，尽管工作器运行正常，整个作业仍会失败。" ], "lessons": [ "投入精力优化分解逻辑——大多数失败都可以追溯到工作是如何拆分的，而不是工作器本身的问题。", "显式地向工作器传递其所需的最小上下文，以避免偏差和矛盾。", "设置预算和深度上限；无限制的编排是智能体成本失控的根源。", "使编排器的计划具有可检查性，以便将失败追溯到特定的子任务。" ], "faqs": [ { "q": "这与并行化有什么不同？", "a": "并行化使用固定的、预定义的拆分方式。而编排器-工作者（Orchestrator-workers）模式在运行时动态决定子任务，因此它能够处理其形态随输入而变化的任务。" }, { "q": "这是一个多智能体系统吗？", "a": "是的——这是一个常见的多智能体模式。只有当任务确实能从动态、可拆分的子任务中获益时，才应使用它。" }, { "q": "我该如何防止它失控运行？", "a": "设置预算、步骤限制和终止条件，并增加可观测性，以便您能够查看并限制编排器的规划。" } ] } } }, { "slug": "output-boundary-encoding", "category": "safety", "updated": "2026-08-25", "version": "1.0", "url": "https://santismm.com/en/patterns/output-boundary-encoding", "api": "https://santismm.com/api/patterns/output-boundary-encoding", "canonical_url": "https://santismm.com/en/patterns/output-boundary-encoding", "api_url": "https://santismm.com/api/patterns/output-boundary-encoding", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "medium", "sourceType": [ "industry_observation", "paper" ] }, "technologies": [ "Context-aware output encoders", "Markdown renderers with raw HTML disabled", "Parameterised queries and ORM bindings", "argv-array process execution", "URL and egress allowlists", "JSON Schema validation of tool-call arguments" ], "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "OWASP LLM01 — Prompt Injection (the paired risk)", "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/" }, { "title": "MITRE ATLAS — adversarial techniques against AI systems", "url": "https://atlas.mitre.org/" }, { "title": "NIST AI Risk Management Framework", "url": "https://www.nist.gov/itl/ai-risk-management-framework" }, { "title": "EU AI Act — Article 15 (accuracy, robustness and cybersecurity)", "url": "https://artificialintelligenceact.eu/article/15/" } ], "related": [ "egress-allowlist", "least-privilege-tooling", "sandboxed-execution", "human-approval-gate", "attributed-memory" ], "locales": { "en": { "name": "Output Boundary Encoding", "summary": "Treat everything the model emits as hostile input to whatever consumes it. Encode and validate at each destination — renderer, shell, query, downstream agent — using that destination's own rules. One global sanitiser cannot do this: escaping that is correct for HTML is meaningless for a shell.", "definition": "Output boundary encoding is the practice of applying destination-specific encoding and validation to model output at every point where it crosses into a system that will interpret it, rather than filtering it once, generically, on the way out of the model. Its absence is the weakness OWASP names as improper output handling.", "problem": "Teams harden the input side against prompt injection and leave the output side open. The model's text then reaches a renderer, a shell, a database or another agent's context, where it is interpreted as instruction rather than displayed as data. The attacker never has to reach the model directly.", "context": "Any agent whose output reaches something that parses it: a chat interface rendering markdown, a coding agent running a suggested command, a tool call built from generated arguments, a summary fed into a second agent's prompt, or a webhook that forwards the text onward.", "solution": [ "Enumerate the destinations before writing any filter. Every place model output lands and is interpreted — HTML renderer, shell, query, file path, URL fetcher, another agent's context, a downstream webhook — is a distinct boundary with distinct rules.", "Encode at the destination, not at the source. HTML-escape for the renderer, parameterise for the query, pass an argv array to the process. The encoding belongs where the interpretation happens, because only there do you know what will be interpreted.", "Prefer structured output over prose you have to parse back. A tool call with typed arguments has a schema to validate against; a sentence you regex for a filename does not.", "Validate the value, not only the syntax. An encoded path is still a path: check it resolves inside the directory you meant before opening it.", "Treat outbound URLs as a destination of their own. Rendered images and links cause a fetch with no click, so they carry data out; allowlist the hosts a rendered link may reach.", "Make the boundary the only route. If any code path can consume raw model output without passing a destination encoder, the control is advisory rather than real." ], "components": [ "A destination inventory: every consumer of model output, with the encoder each one requires.", "Per-destination encoders — HTML, process argv, query parameters, path resolution, URL allowlist — rather than one shared sanitiser.", "Schema-validated structured output for tool calls, so arguments are typed rather than parsed out of prose.", "An egress allowlist covering the hosts reachable from rendered links and images.", "Contract tests that emit a payload per destination and assert it is neutralised at the boundary.", "Logging when an encoder neutralises something, so the boundary can tell you it is on the path." ], "benefits": [ "Breaks the injection chain where it matters: even a fully persuaded model cannot make a downstream system act, because that system never interprets its text.", "Independent of model behaviour. It keeps working across model upgrades, new jailbreaks and prompt changes, because it does not depend on the model refusing anything.", "Testable. Each destination has a payload and a pass or fail, so the control produces evidence rather than assurance.", "Cheap when applied early. Adding an encoder is a boundary change; retrofitting one after the destination is everywhere is a refactor." ], "risks": [ "One sanitiser for every destination. It feels like a control, satisfies the checklist, and is wrong at every boundary except the one it was written for.", "Encoding that breaks the product: over-escaping turns legitimate markdown, code blocks and non-Latin text into noise, and the pressure to loosen it lands on the encoder rather than on the destination list.", "A destination inventory that ages. New integrations add consumers, and nothing fails when one is missed.", "Confusing detection with encoding. Scanning output for suspicious strings catches last year's payloads; encoding does not need to recognise the attack at all." ], "whenNot": [ "Output that is never interpreted — a score, an enum, a boolean the caller compares. Constrain the type instead; an encoder on a closed value set is ceremony.", "Fully local single-user tools with no rendering and no process execution, where the only consumer is a person reading text.", "Where the destination already parameterises by construction, such as an ORM binding or a template engine that escapes by default. A second encoder gains nothing and can double-encode." ], "examples": [ "A support agent summarises a ticket whose body contains a markdown image pointing at an attacker's host. The console renders it, the browser fetches the URL, and the conversation leaks with nobody clicking anything. Disabling raw HTML and allowlisting image hosts closes it.", "A coding agent proposes a shell command. The runner passes the string to a shell, so a filename containing a command separator executes. Passing an argv array instead removes the shell's parsing step entirely.", "One agent's summary is placed into a second agent's prompt. The summary contained instructions, and the second agent followed them. Fencing the untrusted span and labelling it as data is the boundary in that case." ], "kpis": [ { "metric": "Destination coverage", "note": "Share of known model-output consumers with an encoder at the boundary. Below 100% the control has a specific hole, and naming the destination is more useful than a percentage that averages it away." }, { "metric": "Payload neutralisation rate", "note": "Share of per-destination test payloads neutralised at the boundary. The target is 100%: anything else names a destination to fix rather than a number to improve." }, { "metric": "Time to cover a new destination", "note": "How long from a new integration going live to its encoder existing. Measures whether the inventory keeps up with the product rather than whether it was right once." }, { "metric": "Boundary trigger volume", "note": "How often encoders neutralise something in production. A flat zero usually means the encoder is not on the path, not that nothing hostile is arriving." } ], "failureModes": [ "Silent exfiltration through rendered markup: an image or link causes a fetch without a click, so data leaves with no user action and no error anyone would notice.", "Second-order injection: output encoded correctly for the console is stored and later rendered somewhere else — a log viewer, a ticket, a digest email — where that encoding does not apply.", "The encoder that only sits on the happy path. Error branches, retries and fallbacks emit the same text through a different code path with nothing on it.", "Double encoding. Two layers each escape correctly, users see escaped entities in the product, and the fix removes the wrong layer." ], "lessons": [ "Enumerate destinations before writing filters. Almost every real failure here is a consumer nobody listed, not an encoder that was written wrong.", "The destination you forget is rarely a screen. It is a webhook, a log viewer, an export or a digest email — somewhere the output goes without anyone thinking of it as a render.", "Encoding beats detection because encoding does not need to recognise the attack. A payload blocklist is a description of the attacks that were already public.", "Do not let a single sanitise() become the answer. The name suggests completeness and the behaviour is correct for exactly one destination." ], "faqs": [ { "q": "Isn't this the same as filtering inputs for prompt injection?", "a": "No — they defend opposite ends. Input filtering tries to stop the model from being persuaded, which depends on the model. This assumes persuasion already succeeded and stops the output from being acted on, which does not depend on the model at all. A system with only the first fails the moment a new jailbreak appears." }, { "q": "Isn't this just output sanitization? Why not one sanitiser for everything?", "a": "Because encoding is contextual. Escaping a quote protects an HTML renderer and does nothing for a shell; shell-quoting protects a shell and corrupts displayed text. A shared function has to choose one context, is wrong in the others, and looks like coverage while being a single point of failure." }, { "q": "The model is ours and the prompt is fixed. Do we still need this?", "a": "Yes, if any content the model reads comes from outside: a fetched page, a user file, a tool result, a memory record. The instruction does not have to arrive through your prompt — it arrives through whatever the model reads, and your prompt being fixed does not constrain that." } ] }, "es": { "name": "Codificación en la frontera de salida", "summary": "Trata todo lo que el modelo emite como entrada hostil para quien lo consuma. Codifica y valida en cada destino —renderizador, shell, consulta, agente aguas abajo— con las reglas de ese destino. Un saneador global no puede hacerlo: el escapado correcto para HTML no significa nada para un shell.", "definition": "La codificación en la frontera de salida es la práctica de aplicar codificación y validación específicas de cada destino a la salida del modelo en todo punto donde cruza hacia un sistema que va a interpretarla, en lugar de filtrarla una sola vez, de forma genérica, al salir del modelo. Su ausencia es la debilidad que OWASP llama improper output handling: manejo indebido de la salida.", "problem": "Los equipos endurecen el lado de la entrada contra la inyección de prompts y dejan abierto el de la salida. El texto del modelo llega entonces a un renderizador, un shell, una base de datos o el contexto de otro agente, donde se interpreta como instrucción en vez de mostrarse como dato. El atacante no necesita llegar al modelo directamente. Dicho de otro modo: la salida del modelo hay que tratarla como entrada no confiable.", "context": "Cualquier agente cuya salida llegue a algo que la parsea: una interfaz de chat que renderiza markdown, un agente de código que ejecuta un comando sugerido, una llamada a herramienta construida con argumentos generados, un resumen que se inyecta en el prompt de un segundo agente, o un webhook que reenvía el texto.", "solution": [ "Enumera los destinos antes de escribir ningún filtro. Cada sitio donde aterriza la salida del modelo y se interpreta —renderizador HTML, shell, consulta, ruta de fichero, descargador de URLs, contexto de otro agente, webhook aguas abajo— es una frontera distinta con reglas distintas.", "Codifica en el destino, no en el origen. Escapa HTML para el renderizador, parametriza la consulta, pasa un array argv al proceso. La codificación pertenece a donde ocurre la interpretación, porque solo ahí sabes qué se va a interpretar.", "Prefiere salida estructurada antes que prosa que luego hay que volver a parsear. Una llamada a herramienta con argumentos tipados tiene un esquema contra el que validar; una frase a la que le aplicas una expresión regular para sacar un nombre de fichero, no.", "Valida el valor, no solo la sintaxis. Una ruta codificada sigue siendo una ruta: comprueba que resuelve dentro del directorio que querías antes de abrirla.", "Trata las URLs salientes como un destino propio. Las imágenes y los enlaces renderizados provocan una petición sin que nadie pulse, así que sacan datos; pon en lista de permitidos los hosts que puede alcanzar un enlace renderizado.", "Haz que la frontera sea el único camino. Si alguna ruta de código puede consumir salida cruda del modelo sin pasar por un codificador de destino, el control es orientativo, no real." ], "components": [ "Un inventario de destinos: cada consumidor de la salida del modelo, con el codificador que necesita cada uno.", "Codificadores por destino —HTML, argv de proceso, parámetros de consulta, resolución de rutas, lista de URLs permitidas— en lugar de un saneador compartido.", "Salida estructurada validada contra esquema para las llamadas a herramientas, de modo que los argumentos estén tipados y no extraídos de la prosa.", "Una lista de egreso permitido que cubra los hosts alcanzables desde enlaces e imágenes renderizados.", "Pruebas de contrato que emiten un payload por destino y comprueban que se neutraliza en la frontera.", "Registro de cuándo un codificador neutraliza algo, para que la frontera pueda decirte que está en el camino." ], "benefits": [ "Rompe la cadena de inyección donde importa: ni un modelo completamente persuadido puede hacer que un sistema aguas abajo actúe, porque ese sistema nunca interpreta su texto.", "Independiente del comportamiento del modelo. Sigue funcionando entre versiones, jailbreaks nuevos y cambios de prompt, porque no depende de que el modelo se niegue a nada.", "Comprobable. Cada destino tiene un payload y un resultado de pasa o falla, así que el control produce evidencia en vez de garantías.", "Barato si se aplica pronto. Añadir un codificador es un cambio de frontera; ponerlo cuando el destino ya está por todas partes es una refactorización." ], "risks": [ "Un solo saneador para todos los destinos. Parece un control, satisface la lista de verificación y está mal en todas las fronteras menos en aquella para la que se escribió.", "Codificación que rompe el producto: escapar de más convierte markdown legítimo, bloques de código y texto no latino en ruido, y la presión por aflojar recae sobre el codificador en vez de sobre la lista de destinos.", "Un inventario de destinos que envejece. Cada integración nueva añade consumidores, y no falla nada cuando se olvida uno.", "Confundir detección con codificación. Escanear la salida buscando cadenas sospechosas caza los payloads del año pasado; la codificación no necesita reconocer el ataque." ], "whenNot": [ "Salida que nunca se interpreta: una puntuación, un enum, un booleano que el llamante compara. Restringe el tipo en su lugar; un codificador sobre un conjunto cerrado de valores es ceremonia.", "Herramientas locales de un solo usuario, sin renderizado ni ejecución de procesos, donde el único consumidor es una persona leyendo texto.", "Donde el destino ya parametriza por construcción, como el binding de un ORM o un motor de plantillas que escapa por defecto. Un segundo codificador no aporta nada y puede provocar doble codificación." ], "examples": [ "Un agente de soporte resume un ticket cuyo cuerpo contiene una imagen markdown apuntando al host de un atacante. La consola la renderiza, el navegador pide la URL, y la conversación se filtra sin que nadie pulse nada. Deshabilitar HTML crudo y permitir solo ciertos hosts de imagen lo cierra.", "Un agente de código propone un comando de shell. El ejecutor pasa la cadena a un shell, así que un nombre de fichero con un separador de comandos se ejecuta. Pasar un array argv elimina por completo el paso de parseo del shell.", "El resumen de un agente se coloca en el prompt de un segundo agente. El resumen contenía instrucciones y el segundo las siguió. Delimitar el fragmento no confiable y etiquetarlo como dato es la frontera en ese caso." ], "kpis": [ { "metric": "Cobertura de destinos", "note": "Proporción de consumidores conocidos de la salida del modelo con codificador en la frontera. Por debajo del 100% el control tiene un agujero concreto, y nombrar el destino sirve más que un porcentaje que lo promedia." }, { "metric": "Tasa de neutralización de payloads", "note": "Proporción de payloads de prueba por destino neutralizados en la frontera. El objetivo es 100%: cualquier otra cifra nombra un destino que arreglar, no un número que mejorar." }, { "metric": "Tiempo hasta cubrir un destino nuevo", "note": "Cuánto pasa desde que una integración entra en producción hasta que existe su codificador. Mide si el inventario sigue el ritmo del producto, no si acertó una vez." }, { "metric": "Volumen de disparos en la frontera", "note": "Con qué frecuencia los codificadores neutralizan algo en producción. Un cero plano suele significar que el codificador no está en el camino, no que no llegue nada hostil." } ], "failureModes": [ "Exfiltración silenciosa por marcado renderizado: una imagen o un enlace provocan una petición sin pulsar, así que los datos salen sin acción del usuario y sin ningún error que alguien fuera a notar.", "Inyección de segundo orden: la salida se codifica bien para la consola, se almacena y luego se renderiza en otro sitio —un visor de logs, un ticket, un correo resumen— donde esa codificación no aplica.", "El codificador que solo está en el camino feliz. Las ramas de error, los reintentos y los repliegues emiten el mismo texto por otra ruta de código que no lleva nada.", "Doble codificación. Dos capas escapan correctamente, los usuarios ven entidades escapadas en el producto, y el arreglo quita la capa equivocada." ], "lessons": [ "Enumera destinos antes de escribir filtros. Casi todo fallo real aquí es un consumidor que nadie listó, no un codificador mal escrito.", "El destino que se olvida rara vez es una pantalla. Es un webhook, un visor de logs, una exportación o un correo resumen: algún sitio al que va la salida sin que nadie lo piense como un renderizado.", "La codificación gana a la detección porque no necesita reconocer el ataque. Una lista negra de payloads es una descripción de los ataques que ya eran públicos.", "No dejes que un único sanitize() se convierta en la respuesta. El nombre sugiere completitud y el comportamiento es correcto para exactamente un destino." ], "faqs": [ { "q": "¿No es lo mismo que filtrar entradas contra la inyección de prompts?", "a": "No: defienden extremos opuestos. El filtrado de entrada intenta que no persuadan al modelo, y eso depende del modelo. Esto asume que ya lo persuadieron e impide que se actúe sobre la salida, y eso no depende del modelo en absoluto. Un sistema que solo tenga lo primero falla en cuanto aparece un jailbreak nuevo." }, { "q": "¿Esto no es simplemente sanitization de la salida, con un saneador único para todo?", "a": "Porque la codificación es contextual. Escapar una comilla protege un renderizador HTML y no hace nada por un shell; entrecomillar para shell protege el shell y corrompe el texto mostrado. Una función compartida tiene que elegir un contexto, está mal en los demás, y parece cobertura mientras es un punto único de fallo." }, { "q": "El modelo es nuestro y el prompt está fijado. ¿Aun así hace falta?", "a": "Sí, si algo de lo que el modelo lee viene de fuera: una página descargada, un fichero del usuario, el resultado de una herramienta, un registro de memoria. La instrucción no tiene que llegar por tu prompt: llega por lo que el modelo lea, y que tu prompt esté fijado no restringe eso." } ] }, "pt": { "name": "Codificação na fronteira de saída", "summary": "Trate tudo o que o modelo emite como entrada hostil para quem o consome. Codifique e valide em cada destino — renderizador, shell, consulta, agente a jusante — com as regras desse destino. Um sanitizador global não dá conta: o escape correto para HTML não significa nada para um shell.", "definition": "A codificação na fronteira de saída é a prática de aplicar codificação e validação específicas de cada destino à saída do modelo em todo ponto onde ela cruza para um sistema que vai interpretá-la, em vez de filtrá-la uma única vez, de forma genérica, ao sair do modelo. Sua ausência é a fraqueza que a OWASP chama de improper output handling: tratamento indevido da saída.", "problem": "As equipes endurecem o lado da entrada contra injeção de prompt e deixam o lado da saída aberto. O texto do modelo então chega a um renderizador, a um shell, a um banco de dados ou ao contexto de outro agente, onde é interpretado como instrução em vez de exibido como dado. O atacante nunca precisa alcançar o modelo diretamente. Dito de outro modo: a saída do modelo tem de ser tratada como entrada não confiável.", "context": "Qualquer agente cuja saída chegue a algo que a analisa: uma interface de chat que renderiza markdown, um agente de código que executa um comando sugerido, uma chamada de ferramenta construída com argumentos gerados, um resumo injetado no prompt de um segundo agente, ou um webhook que encaminha o texto adiante.", "solution": [ "Enumere os destinos antes de escrever qualquer filtro. Cada lugar onde a saída do modelo aterrissa e é interpretada — renderizador HTML, shell, consulta, caminho de arquivo, buscador de URLs, contexto de outro agente, webhook a jusante — é uma fronteira distinta com regras distintas.", "Codifique no destino, não na origem. Escape HTML para o renderizador, parametrize a consulta, passe um array argv ao processo. A codificação pertence ao lugar onde ocorre a interpretação, porque só ali se sabe o que será interpretado.", "Prefira saída estruturada a prosa que depois é preciso analisar de volta. Uma chamada de ferramenta com argumentos tipados tem um esquema contra o qual validar; uma frase da qual você extrai um nome de arquivo com expressão regular, não.", "Valide o valor, não só a sintaxe. Um caminho codificado continua sendo um caminho: verifique que ele resolve dentro do diretório pretendido antes de abri-lo.", "Trate as URLs de saída como um destino próprio. Imagens e links renderizados provocam uma requisição sem clique, portanto levam dados para fora; permita apenas os hosts que um link renderizado pode alcançar.", "Faça da fronteira o único caminho. Se alguma rota de código puder consumir saída crua do modelo sem passar por um codificador de destino, o controle é orientativo, não real." ], "components": [ "Um inventário de destinos: cada consumidor da saída do modelo, com o codificador exigido por cada um.", "Codificadores por destino — HTML, argv de processo, parâmetros de consulta, resolução de caminhos, lista de URLs permitidas — em vez de um sanitizador compartilhado.", "Saída estruturada validada por esquema para as chamadas de ferramentas, de modo que os argumentos sejam tipados e não extraídos da prosa.", "Uma lista de egresso permitido cobrindo os hosts alcançáveis a partir de links e imagens renderizados.", "Testes de contrato que emitem um payload por destino e verificam que ele é neutralizado na fronteira.", "Registro de quando um codificador neutraliza algo, para que a fronteira consiga dizer que está no caminho." ], "benefits": [ "Rompe a cadeia de injeção onde importa: nem um modelo completamente persuadido consegue fazer um sistema a jusante agir, porque esse sistema nunca interpreta o texto dele.", "Independente do comportamento do modelo. Continua funcionando entre versões, novos jailbreaks e mudanças de prompt, porque não depende de o modelo recusar nada.", "Verificável. Cada destino tem um payload e um resultado de passa ou falha, então o controle produz evidência em vez de garantia.", "Barato quando aplicado cedo. Adicionar um codificador é uma mudança de fronteira; colocá-lo depois que o destino já está em toda parte é uma refatoração." ], "risks": [ "Um único sanitizador para todos os destinos. Parece um controle, satisfaz a lista de verificação e está errado em todas as fronteiras menos naquela para a qual foi escrito.", "Codificação que quebra o produto: escapar demais transforma markdown legítimo, blocos de código e texto não latino em ruído, e a pressão por afrouxar recai sobre o codificador em vez de sobre a lista de destinos.", "Um inventário de destinos que envelhece. Cada nova integração acrescenta consumidores, e nada falha quando um é esquecido.", "Confundir detecção com codificação. Varrer a saída em busca de cadeias suspeitas pega os payloads do ano passado; a codificação não precisa reconhecer o ataque." ], "whenNot": [ "Saída que nunca é interpretada: uma pontuação, um enum, um booleano que o chamador compara. Restrinja o tipo em vez disso; um codificador sobre um conjunto fechado de valores é cerimônia.", "Ferramentas locais de um só usuário, sem renderização e sem execução de processos, onde o único consumidor é uma pessoa lendo texto.", "Onde o destino já parametriza por construção, como o binding de um ORM ou um motor de templates que escapa por padrão. Um segundo codificador não acrescenta nada e pode causar dupla codificação." ], "examples": [ "Um agente de suporte resume um chamado cujo corpo contém uma imagem markdown apontando para o host de um atacante. O console a renderiza, o navegador busca a URL, e a conversa vaza sem que ninguém clique em nada. Desabilitar HTML cru e permitir apenas certos hosts de imagem fecha isso.", "Um agente de código propõe um comando de shell. O executor passa a string a um shell, então um nome de arquivo com um separador de comandos é executado. Passar um array argv elimina por completo a etapa de análise do shell.", "O resumo de um agente é colocado no prompt de um segundo agente. O resumo continha instruções e o segundo as seguiu. Delimitar o trecho não confiável e rotulá-lo como dado é a fronteira nesse caso." ], "kpis": [ { "metric": "Cobertura de destinos", "note": "Proporção de consumidores conhecidos da saída do modelo com codificador na fronteira. Abaixo de 100% o controle tem um buraco concreto, e nomear o destino serve mais do que uma porcentagem que o dilui na média." }, { "metric": "Taxa de neutralização de payloads", "note": "Proporção de payloads de teste por destino neutralizados na fronteira. O alvo é 100%: qualquer outro número nomeia um destino a corrigir, não um número a melhorar." }, { "metric": "Tempo até cobrir um novo destino", "note": "Quanto tempo passa desde que uma integração entra em produção até que o codificador dela exista. Mede se o inventário acompanha o produto, não se ele acertou uma vez." }, { "metric": "Volume de disparos na fronteira", "note": "Com que frequência os codificadores neutralizam algo em produção. Um zero constante costuma significar que o codificador não está no caminho, não que nada hostil esteja chegando." } ], "failureModes": [ "Exfiltração silenciosa por marcação renderizada: uma imagem ou um link provocam uma requisição sem clique, então os dados saem sem ação do usuário e sem nenhum erro que alguém fosse notar.", "Injeção de segunda ordem: a saída é codificada corretamente para o console, é armazenada e depois renderizada em outro lugar — um visualizador de logs, um chamado, um e-mail de resumo — onde essa codificação não se aplica.", "O codificador que só está no caminho feliz. Ramos de erro, novas tentativas e fallbacks emitem o mesmo texto por outra rota de código, sem nada nela.", "Dupla codificação. Duas camadas escapam corretamente, os usuários veem entidades escapadas no produto, e a correção remove a camada errada." ], "lessons": [ "Enumere destinos antes de escrever filtros. Quase toda falha real aqui é um consumidor que ninguém listou, não um codificador escrito errado.", "O destino que se esquece raramente é uma tela. É um webhook, um visualizador de logs, uma exportação ou um e-mail de resumo: algum lugar para onde a saída vai sem que ninguém o pense como renderização.", "A codificação vence a detecção porque não precisa reconhecer o ataque. Uma lista de bloqueio de payloads é uma descrição dos ataques que já eram públicos.", "Não deixe um único sanitize() virar a resposta. O nome sugere completude e o comportamento está correto para exatamente um destino." ], "faqs": [ { "q": "Isso não é o mesmo que filtrar entradas contra injeção de prompt?", "a": "Não: defendem extremos opostos. O filtro de entrada tenta impedir que o modelo seja persuadido, e isso depende do modelo. Isto aqui assume que a persuasão já ocorreu e impede que se aja sobre a saída, e isso não depende do modelo em nada. Um sistema que só tenha o primeiro falha assim que surge um novo jailbreak." }, { "q": "Isto não é simplesmente sanitization da saída, com um sanitizador único para tudo?", "a": "Porque a codificação é contextual. Escapar uma aspa protege um renderizador HTML e não faz nada por um shell; aspas de shell protegem o shell e corrompem o texto exibido. Uma função compartilhada precisa escolher um contexto, está errada nos demais, e parece cobertura enquanto é um ponto único de falha." }, { "q": "O modelo é nosso e o prompt é fixo. Ainda assim é preciso?", "a": "Sim, se algo que o modelo lê vem de fora: uma página buscada, um arquivo do usuário, o resultado de uma ferramenta, um registro de memória. A instrução não precisa chegar pelo seu prompt: chega por aquilo que o modelo lê, e o seu prompt ser fixo não restringe isso." } ] }, "fr": { "name": "Encodage aux limites de sortie", "summary": "Traitez tout ce que le modèle émet comme une entrée hostile pour tout ce qui la consomme. Encodez et validez au niveau de chaque destination — moteur de rendu, shell, requête, agent en aval — en utilisant les règles propres à cette destination. Un outil d'assainissement global unique ne peut pas faire cela : un échappement correct pour HTML n'a aucun sens pour un shell.", "definition": "L'encodage aux limites de sortie consiste à appliquer un encodage et une validation spécifiques à la destination sur la sortie du modèle à chaque point de passage vers un système qui l'interprétera, plutôt que de la filtrer une seule fois de manière générique à la sortie du modèle. Son absence constitue la vulnérabilité que l'OWASP qualifie de traitement incorrect des sorties (improper output handling).", "problem": "Les équipes sécurisent le côté entrée contre l'injection de requêtes (prompt injection) et laissent le côté sortie ouvert. Le texte du modèle atteint alors un moteur de rendu, un shell, une base de données ou le contexte d'un autre agent, où il est interprété comme une instruction plutôt que d'être affiché comme une donnée. L'attaquant n'a jamais besoin d'atteindre directement le modèle.", "context": "Tout agent dont la sortie atteint un élément qui l'analyse : une interface de chat affichant du markdown, un agent de codage exécutant une commande suggérée, un appel d'outil construit à partir d'arguments générés, un résumé injecté dans l'invite d'un second agent, ou un webhook qui transmet le texte plus loin.", "solution": [ "Énumérez les destinations avant d'écrire le moindre filtre. Chaque endroit où la sortie du modèle atterrit et est interprétée — moteur de rendu HTML, shell, requête, chemin de fichier, récupérateur d'URL, contexte d'un autre agent, webhook en aval — constitue une limite distincte avec des règles distinctes.", "Encodez à la destination, pas à la source. Échappez le HTML pour le moteur de rendu, paramétrez pour la requête, passez un tableau `argv` au processus. L'encodage doit se faire là où l'interprétation a lieu, car c'est seulement à cet endroit que vous savez ce qui sera interprété.", "Privilégiez les sorties structurées plutôt que de la prose que vous devez analyser a posteriori. Un appel d'outil avec des arguments typés dispose d'un schéma de validation ; une phrase dans laquelle vous recherchez un nom de fichier par expression régulière n'en a pas.", "Validez la valeur, pas seulement la syntaxe. Un chemin encodé reste un chemin : vérifiez qu'il se résout bien à l'intérieur du répertoire prévu avant de l'ouvrir.", "Traitez les URL sortantes comme une destination à part entière. Les images et les liens affichés provoquent une requête de récupération sans clic, exfiltrant ainsi des données ; autorisez uniquement (via une liste d'autorisation) les hôtes qu'un lien affiché peut atteindre.", "Faites de la limite l'unique voie de passage. Si un chemin de code peut consommer la sortie brute du modèle sans passer par un encodeur de destination, le contrôle est indicatif plutôt que réel." ], "components": [ "Un inventaire des destinations : chaque consommateur de la sortie du modèle, avec l'encodeur requis pour chacun.", "Des encodeurs par destination — HTML, `argv` de processus, paramètres de requête, résolution de chemin, liste d'autorisation d'URL — plutôt qu'un seul outil d'assainissement partagé.", "Des sorties structurées validées par schéma pour les appels d'outils, afin que les arguments soient typés plutôt qu'extraits de la prose.", "Une liste d'autorisation de sortie couvrant les hôtes accessibles depuis les liens et images affichés.", "Des tests de contrat qui émettent une charge utile (payload) par destination et vérifient qu'elle est neutralisée à la limite.", "La journalisation lorsqu'un encodeur neutralise un élément, afin que la limite puisse vous signaler qu'elle est bien sur le chemin." ], "benefits": [ "Brise la chaîne d'injection là où cela compte : même un modèle entièrement manipulé ne peut pas faire agir un système en aval, car ce système n'interprète jamais son texte.", "Indépendant du comportement du modèle. Cela continue de fonctionner malgré les mises à niveau du modèle, les nouveaux jailbreaks et les modifications d'invites, car cela ne dépend pas du refus du modèle.", "Testable. Chaque destination a une charge utile et un résultat de réussite ou d'échec, de sorte que le contrôle produit des preuves plutôt que de simples assurances.", "Peu coûteux s'il est appliqué tôt. Ajouter un encodeur est une modification de limite ; en intégrer un après coup, une fois que la destination est partout, relève de la refonte." ], "risks": [ "Un seul outil d'assainissement pour toutes les destinations. Cela donne l'impression d'un contrôle, valide la liste de contrôle, mais s'avère incorrect à chaque limite, sauf celle pour laquelle il a été écrit.", "Un encodage qui altère le produit : un sur-échappement transforme le markdown légitime, les blocs de code et le texte non latin en bruit, et la pression pour l'assouplir pèse sur l'encodeur plutôt que sur la liste des destinations.", "Un inventaire des destinations qui vieillit. Les nouvelles intégrations ajoutent des consommateurs, et rien ne signale d'erreur lorsqu'un consommateur est oublié.", "Confondre la détection et l'encodage. Analyser la sortie à la recherche de chaînes suspectes permet de détecter les charges utiles de l'année dernière ; l'encodage n'a pas du tout besoin de reconnaître l'attaque." ], "whenNot": [ "Une sortie qui n'est jamais interprétée — un score, une énumération, un booléen comparé par l'appelant. Contraignez plutôt le type ; un encodeur sur un ensemble de valeurs fermé est superflu.", "Des outils mono-utilisateur entièrement locaux, sans rendu ni exécution de processus, où le seul consommateur est une personne lisant du texte.", "Lorsque la destination applique déjà un paramétrage par construction, comme une liaison ORM ou un moteur de template qui échappe par défaut. Un second encodeur n'apporte rien et peut provoquer un double encodage." ], "examples": [ "Un agent de support résume un ticket dont le corps contient une image markdown pointant vers l'hôte d'un attaquant. La console l'affiche, le navigateur récupère l'URL et la conversation est divulguée sans que personne n'ait cliqué sur quoi que ce soit. Désactiver le HTML brut et autoriser uniquement certains hôtes d'images permet de résoudre ce problème.", "Un agent de codage propose une commande shell. L'exécuteur transmet la chaîne à un shell, de sorte qu'un nom de fichier contenant un séparateur de commande est exécuté. Passer un tableau `argv` à la place supprime complètement l'étape d'analyse du shell.", "Le résumé d'un agent est placé dans l'invite d'un second agent. Le résumé contenait des instructions, et le second agent les a suivies. Encadrer la zone non approuvée et la marquer comme donnée constitue la limite dans ce cas." ], "kpis": [ { "metric": "Couverture des destinations", "note": "Part des consommateurs connus de la sortie du modèle disposant d'un encodeur à la limite. En dessous de 100 %, le contrôle présente une faille spécifique, et nommer la destination est plus utile qu'un pourcentage qui masque la réalité par une moyenne." }, { "metric": "Taux de neutralisation des charges utiles", "note": "Part des charges utiles de test par destination neutralisées à la limite. L'objectif est de 100 % : tout autre résultat désigne une destination à corriger plutôt qu'un chiffre à améliorer." }, { "metric": "Délai de couverture d'une nouvelle destination", "note": "Temps écoulé entre la mise en production d'une nouvelle intégration et la création de son encodeur. Permet de mesurer si l'inventaire suit l'évolution du produit plutôt que de savoir s'il a été correct à un instant T." }, { "metric": "Volume de déclenchement aux limites", "note": "Fréquence à laquelle les encodeurs neutralisent un élément en production. Un zéro absolu signifie généralement que l'encodeur n'est pas sur le chemin, et non qu'aucun élément hostile n'arrive." } ], "failureModes": [ "Exfiltration silencieuse via un balisage affiché : une image ou un lien provoque une requête de récupération sans clic, de sorte que les données s'échappent sans action de l'utilisateur et sans erreur visible.", "Injection de second ordre : une sortie encodée correctement pour la console est stockée puis affichée ailleurs — un visualiseur de journaux, un ticket, un e-mail récapitulatif — là où cet encodage ne s'applique pas.", "L'encodeur qui ne se trouve que sur le chemin nominal (happy path). Les branches d'erreur, les tentatives et les solutions de repli émettent le même texte via un chemin de code différent dépourvu de tout contrôle.", "Double encodage. Deux couches effectuent chacune un échappement correct, les utilisateurs voient des entités échappées dans le produit, et la correction supprime la mauvaise couche." ], "lessons": [ "Énumérez les destinations avant d'écrire des filtres. Presque chaque défaillance réelle ici provient d'un consommateur que personne n'a répertorié, et non d'un encodeur mal écrit.", "La destination que vous oubliez est rarement un écran. Il s'agit d'un webhook, d'un visualiseur de journaux, d'un export ou d'un e-mail récapitulatif — un endroit où la sortie est envoyée sans que personne ne l'assimile à un rendu.", "L'encodage l'emporte sur la détection car il n'a pas besoin de reconnaître l'attaque. Une liste de blocage de charges utiles n'est qu'une description des attaques déjà publiques.", "Ne laissez pas une unique fonction `sanitise()` devenir la solution. Son nom suggère l'exhaustivité alors que son comportement n'est correct que pour une seule et unique destination." ], "faqs": [ { "q": "N'est-ce pas la même chose que de filtrer les entrées contre l'injection de requêtes (prompt injection) ?", "a": "Non — ils défendent des extrémités opposées. Le filtrage des entrées tente d'empêcher le modèle d'être manipulé, ce qui dépend du modèle. Cette approche suppose que la manipulation a déjà réussi et empêche l'exécution de la sortie, ce qui ne dépend pas du tout du modèle. Un système doté uniquement de la première protection échoue dès qu'un nouveau jailbreak apparaît." }, { "q": "Ne s'agit-il pas simplement d'un assainissement des sorties ? Pourquoi ne pas utiliser un seul outil d'assainissement pour tout ?", "a": "Parce que l'encodage est contextuel. Échapper un guillemet protège un moteur de rendu HTML mais ne fait rien pour un shell ; l'échappement pour shell protège un shell mais corrompt le texte affiché. Une fonction partagée doit choisir un contexte unique, s'avère incorrecte dans les autres, et donne l'illusion d'une couverture tout en constituant un point de défaillance unique." }, { "q": "Le modèle nous appartient et l'invite est fixe. En avons-nous tout de même besoin ?", "a": "Oui, si un contenu lu par le modèle provient de l'extérieur : une page récupérée, un fichier utilisateur, un résultat d'outil, un enregistrement de mémoire. L'instruction n'a pas besoin d'arriver via votre prompt — elle arrive via tout ce que le modèle lit, et le fait que votre prompt soit fixe ne limite pas cela." } ] }, "de": { "name": "Output-Boundary-Encoding", "summary": "Behandeln Sie alles, was das Modell ausgibt, als feindliche Eingabe für das nachfolgende System. Codieren und validieren Sie an jedem Ziel – Renderer, Shell, Query, nachgelagerter Agent – unter Verwendung der spezifischen Regeln dieses Ziels. Ein einziger globaler Sanitizer kann dies nicht leisten: Ein Escaping, das für HTML korrekt ist, ist für eine Shell bedeutungslos.", "definition": "Output-Boundary-Encoding ist die Praxis, zielspezifische Codierung und Validierung auf die Modellausgabe an jedem Punkt anzuwenden, an dem sie in ein System übergeht, das sie interpretiert, anstatt sie einmal generisch beim Verlassen des Modells zu filtern. Ihr Fehlen entspricht der Schwachstelle, die OWASP als unzureichende Ausgabeverarbeitung (Improper Output Handling) bezeichnet.", "problem": "Teams härten die Eingabeseite gegen Prompt Injection ab und lassen die Ausgabeseite offen. Der Text des Modells gelangt dann in einen Renderer, eine Shell, eine Datenbank oder den Kontext eines anderen Agenten, wo er als Anweisung interpretiert statt als Daten angezeigt wird. Der Angreifer muss das Modell so niemals direkt erreichen.", "context": "Jeder Agent, dessen Ausgabe ein System erreicht, das sie parst: eine Chat-Schnittstelle, die Markdown rendert, ein Coding-Agent, der einen vorgeschlagenen Befehl ausführt, ein Tool-Aufruf, der aus generierten Argumenten erstellt wird, eine Zusammenfassung, die in den Prompt eines zweiten Agenten einfließt, oder ein Webhook, der den Text weiterleitet.", "solution": [ "Listen Sie alle Ziele auf, bevor Sie Filter schreiben. Jeder Ort, an dem die Modellausgabe landet und interpretiert wird – HTML-Renderer, Shell, Query, Dateipfad, URL-Fetcher, Kontext eines anderen Agenten, nachgelagerter Webhook – ist eine eigene Grenze mit eigenen Regeln.", "Codieren Sie am Ziel, nicht an der Quelle. Nutzen Sie HTML-Escaping für den Renderer, parametrisieren Sie Queries, übergeben Sie ein argv-Array an den Prozess. Die Codierung gehört dorthin, wo die Interpretation stattfindet, da nur dort bekannt ist, was interpretiert wird.", "Bevorzugen Sie strukturierten Output gegenüber Fließtext, den Sie wieder parsen müssen. Ein Tool-Aufruf mit typisierten Argumenten verfügt über ein Schema, gegen das validiert werden kann; ein Satz, den Sie per Regex nach einem Dateinamen durchsuchen, nicht.", "Validieren Sie den Wert, nicht nur die Syntax. Ein codierter Pfad ist immer noch ein Pfad: Überprüfen Sie vor dem Öffnen, ob er sich innerhalb des beabsichtigten Verzeichnisses auflösen lässt.", "Behandeln Sie ausgehende URLs als eigenständiges Ziel. Gerenderte Bilder und Links führen zu einem Abruf ohne Klick und transportieren so Daten nach außen; setzen Sie die Hosts, die ein gerenderter Link erreichen darf, auf eine Allowlist.", "Machen Sie die Grenze zum einzigen Pfad. Wenn irgendein Codepfad rohe Modellausgaben konsumieren kann, ohne einen zielspezifischen Encoder zu durchlaufen, ist die Schutzmaßnahme eher theoretischer Natur." ], "components": [ "Ein Zielinventar: jeder Konsument von Modellausgaben zusammen mit dem jeweils erforderlichen Encoder.", "Zielspezifische Encoder – HTML, Prozess-argv, Query-Parameter, Pfadauflösung, URL-Allowlist – anstelle eines einzigen gemeinsamen Sanitizers.", "Schemavalidierter strukturierter Output für Tool-Aufrufe, sodass Argumente typisiert sind, anstatt aus Fließtext herausgeparst zu werden.", "Eine Egress-Allowlist für die Hosts, die über gerenderte Links und Bilder erreichbar sind.", "Contract-Tests, die ein Payload pro Ziel senden und sicherstellen, dass dieses an der Grenze neutralisiert wird.", "Protokollierung, wenn ein Encoder etwas neutralisiert, damit die Grenze signalisieren kann, dass sie aktiv im Pfad liegt." ], "benefits": [ "Unterbricht die Injection-Kette an der entscheidenden Stelle: Selbst ein vollständig manipuliertes Modell kann ein nachgelagertes System nicht zum Handeln zwingen, da dieses System seinen Text niemals interpretiert.", "Unabhängig vom Modellverhalten. Es funktioniert auch bei Modell-Upgrades, neuen Jailbreaks und Prompt-Änderungen weiterhin, da es nicht darauf angewiesen ist, dass das Modell eine Anfrage verweigert.", "Testbar. Jedes Ziel hat ein Payload und ein klares Ergebnis (Erfolg oder Fehlschlag), sodass die Schutzmaßnahme Belege statt bloßer Zusicherungen liefert.", "Kostengünstig bei frühzeitiger Implementierung. Das Hinzufügen eines Encoders ist eine Änderung an der Grenze; das nachträgliche Hinzufügen, wenn das Ziel bereits überall verteilt ist, erfordert ein Refactoring." ], "risks": [ "Ein einziger Sanitizer für alle Ziele. Es fühlt sich wie eine Schutzmaßnahme an, erfüllt die Checkliste, ist aber an jeder Grenze falsch, außer an derjenigen, für die er geschrieben wurde.", "Eine Codierung, die das Produkt unbrauchbar macht: Übermäßiges Escaping verwandelt legitimes Markdown, Codeblöcke und nicht-lateinischen Text in Zeichensalat, und der Druck, dies zu lockern, lastet dann auf dem Encoder statt auf der Zielliste.", "Ein veraltendes Zielinventar. Neue Integrationen fügen Konsumenten hinzu, und es kommt zu keinem Fehler, wenn einer übersehen wird.", "Verwechslung von Erkennung mit Codierung. Das Scannen von Ausgaben nach verdächtigen Zeichenketten fängt die Payloads des letzten Jahres ab; Codierung muss den Angriff überhaupt nicht erkennen." ], "whenNot": [ "Ausgaben, die niemals interpretiert werden – ein Score, ein Enum, ein Boolean, den der Aufrufer vergleicht. Schränken Sie stattdessen den Typ ein; ein Encoder auf einer geschlossenen Wertemenge ist reine Formsache.", "Vollständig lokale Single-User-Tools ohne Rendering und ohne Prozessausführung, bei denen der einzige Konsument eine Person ist, die den Text liest.", "Wenn das Ziel bereits konstruktionsbedingt parametrisiert, wie z. B. ein ORM-Binding oder eine Template-Engine, die standardmäßig escapet. Ein zweiter Encoder bringt keinen Gewinn und kann zu doppelter Codierung führen." ], "examples": [ "Ein Support-Agent fasst ein Ticket zusammen, dessen Text ein Markdown-Bild enthält, das auf den Host eines Angreifers verweist. Die Konsole rendert es, der Browser ruft die URL ab und die Konversation fließt ab, ohne dass jemand auf etwas klickt. Das Deaktivieren von rohem HTML und das Setzen von Bild-Hosts auf eine Allowlist schließt diese Lücke.", "Ein Coding-Agent schlägt einen Shell-Befehl vor. Der Runner übergibt den String an eine Shell, sodass ein Dateiname, der ein Befehlstrennzeichen enthält, ausgeführt wird. Die Übergabe eines argv-Arrays stattdessen eliminiert den Parsing-Schritt der Shell vollständig.", "Die Zusammenfassung eines Agenten wird in den Prompt eines zweiten Agenten eingefügt. Die Zusammenfassung enthielt Anweisungen, und der zweite Agent hat diese befolgt. Das Eingrenzen (Fencing) des nicht vertrauenswürdigen Bereichs und dessen Kennzeichnung als Daten stellt in diesem Fall die Grenze dar." ], "kpis": [ { "metric": "Zielabdeckung", "note": "Anteil der bekannten Konsumenten von Modellausgaben mit einem Encoder an der Grenze. Unter 100 % weist die Schutzmaßnahme eine konkrete Lücke auf, und die Benennung des Ziels ist nützlicher als ein Prozentsatz, der diese Lücke wegrechnet." }, { "metric": "Payload-Neutralisierungsrate", "note": "Anteil der zielspezifischen Test-Payloads, die an der Grenze neutralisiert wurden. Das Ziel liegt bei 100 %: Alles andere benennt ein zu behebendes Ziel und nicht eine zu verbessernde Zahl." }, { "metric": "Zeit bis zur Abdeckung eines neuen Ziels", "note": "Zeitspanne vom Livegang einer neuen Integration bis zur Existenz ihres Encoders. Misst, ob das Inventar mit dem Produkt Schritt hält, und nicht, ob es einmalig korrekt war." }, { "metric": "Auslösungsvolumen an den Grenzen", "note": "Wie oft Encoder in der Produktion etwas neutralisieren. Eine glatte Null bedeutet meist, dass der Encoder nicht im Pfad liegt, und nicht, dass keine feindlichen Daten eingehen." } ], "failureModes": [ "Stille Exfiltration durch gerendertes Markup: Ein Bild oder Link führt zu einem Abruf ohne Klick, sodass Daten ohne Benutzeraktion und ohne einen für jemanden bemerkbaren Fehler abfließen.", "Second-Order-Injection: Eine für die Konsole korrekt codierte Ausgabe wird gespeichert und später an anderer Stelle gerendert – einem Log-Viewer, einem Ticket, einer Digest-E-Mail –, wo diese Codierung nicht greift.", "Der Encoder, der sich nur auf dem Happy Path befindet. Fehlerzweige, Retries und Fallbacks geben denselben Text über einen anderen Codepfad aus, auf dem sich keine Schutzmaßnahme befindet.", "Doppelte Codierung. Zwei Schichten escapen jeweils korrekt, Benutzer sehen gecodete Entities im Produkt, und die Behebung entfernt die falsche Schicht." ], "lessons": [ "Listen Sie Ziele auf, bevor Sie Filter schreiben. Fast jeder reale Fehler hier ist ein Konsument, den niemand aufgeführt hat, und kein falsch geschriebener Encoder.", "Das Ziel, das Sie vergessen, ist selten ein Bildschirm. Es ist ein Webhook, ein Log-Viewer, ein Export oder eine Digest-E-Mail – ein Ort, an den die Ausgabe gelangt, ohne dass jemand an ein Rendering denkt.", "Codierung schlägt Erkennung, da Codierung den Angriff nicht erkennen muss. Eine Payload-Blocklist ist lediglich eine Beschreibung der Angriffe, die bereits öffentlich waren.", "Lassen Sie nicht zu, dass ein einzelnes sanitise() zur Universallösung wird. Der Name suggeriert Vollständigkeit, und das Verhalten ist für genau ein Ziel korrekt." ], "faqs": [ { "q": "Ist das nicht dasselbe wie das Filtern von Eingaben gegen Prompt Injection?", "a": "Nein – sie sichern entgegengesetzte Enden ab. Die Eingabefilterung versucht zu verhindern, dass das Modell manipuliert wird, was vom Modell abhängt. Dieser Ansatz setzt voraus, dass die Manipulation bereits erfolgreich war, und verhindert, dass die Ausgabe ausgeführt wird, was überhaupt nicht vom Modell abhängt. Ein System, das nur Ersteres nutzt, scheitert in dem Moment, in dem ein neuer Jailbreak auftaucht." }, { "q": "Ist das nicht einfach Output-Sanitization? Warum nicht ein einziger Sanitizer für alles?", "a": "Weil Codierung kontextabhängig ist. Das Escaping eines Anführungszeichens schützt einen HTML-Renderer, bewirkt aber nichts für eine Shell; Shell-Quoting schützt eine Shell und zerstört angezeigten Text. Eine gemeinsam genutzte Funktion muss sich für einen Kontext entscheiden, ist in den anderen falsch und erweckt den Anschein von Abdeckung, während sie einen Single Point of Failure darstellt." }, { "q": "Das Modell gehört uns und der Prompt ist fest vorgegeben. Benötigen wir das trotzdem?", "a": "Ja, wenn Inhalte, die das Modell liest, von außen stammen: eine abgerufene Seite, eine Benutzerdatei, ein Tool-Ergebnis, ein Speichereintrag. Die Anweisung muss nicht über Ihren Prompt erfolgen – sie erfolgt über alles, was das Modell liest, und die Tatsache, dass Ihr Prompt fest vorgegeben ist, schränkt dies nicht ein." } ] }, "ja": { "name": "出力境界エンコーディング", "summary": "モデルが出力するすべてのものを、それを消費するシステムに対する敵対的な入力として扱います。レンダラー、シェル、クエリ、下流のエージェントなど、各宛先において、その宛先独自のルールを使用してエンコードと検証を行います。単一のグローバルなサニタイザーではこれを行うことはできません。HTMLにとって正しいエスケープ処理は、シェルにとっては無意味だからです。", "definition": "出力境界エンコーディングとは、モデルの出力がそれを解釈するシステムに渡されるすべてのポイントにおいて、モデルの出力時に一度だけ汎用的なフィルタリングを行うのではなく、宛先固有のエンコードと検証を適用するプラティスです。これが欠如している状態は、OWASPが「不適切な出力処理（improper output handling）」と呼ぶ脆弱性に該当します。", "problem": "開発チームはプロンプトインジェクションに対して入力側を堅牢化する一方で、出力側を無防備なままにしがちです。その結果、モデルのテキストがレンダラー、シェル、データベース、または別のエージェントのコンテキストに到達し、データとして表示されるのではなく、命令として解釈されてしまいます。攻撃者はモデルに直接アクセスする必要すらありません。", "context": "出力がそれを解析（パース）する何らかの対象に到達するすべてのエージェントが該当します。例えば、Markdownをレンダリングするチャットインターフェース、提案されたコマンドを実行するコーディングエージェント、生成された引数から構築されるツール呼び出し、2番目のエージェントのプロンプトに投入される要約、あるいはテキストを前方に転送するWebhookなどです。", "solution": [ "フィルターを作成する前に、宛先を列挙します。モデルの出力が到達し、解釈されるすべての場所（HTMLレンダラー、シェル、クエリ、ファイルパス、URLフェッチャー、別のエージェントのコンテキスト、下流のWebhookなど）は、それぞれ異なるルールを持つ個別の境界です。", "送信元ではなく、宛先でエンコードします。HTML-escapeはレンダラー向けに行い、クエリ向けにはパラメータ化し、プロセスにはargv配列を渡します。エンコードは解釈が行われる場所で実施すべきです。なぜなら、そこで初めて何が解釈されるのかが分かるからです。", "パースし直す必要のある自然文よりも、構造化された出力を優先します。型定義された引数を持つツール呼び出しには検証用のスキーマがありますが、正規表現でファイル名を抽出するような文章にはスキーマがありません。", "構文だけでなく、値も検証します。エンコードされたパスであってもパスであることに変わりはありません。ファイルを開く前に、意図したディレクトリ内で解決されるかを確認してください。", "外部へのURLは、それ自体を独自の宛先として扱います。レンダリングされた画像やリンクは、クリックしなくてもフェッチを発生させるため、データを外部に持ち出す可能性があります。レンダリングされたリンクが到達できるホストをホワイトリストに登録してください。", "境界を唯一のルートにします。宛先エンコーダーを通さずに生のモデル出力を消費できるコードパスが1つでも存在する場合、その制御は形骸化しており、実質的な効果はありません。" ], "components": [ "宛先インベントリ：モデル出力を消費するすべてのシステムと、それぞれが必要とするエンコーダーの一覧。", "共有された1つのサニタイザーではなく、宛先ごとのエンコーダー（HTML、プロセスargv、クエリパラメータ、パス解決、URLホワイトリストなど）。", "ツール呼び出しのためのスキーマ検証済み構造化出力。これにより、引数は自然文からパースされるのではなく、型定義されます。", "レンダリングされたリンクや画像から到達可能なホストをカバーする、送信（エグレス）ホワイトリスト。", "宛先ごとにペイロードを送信し、それが境界で無害化されていることをアサートする契約（コントラクト）テスト。", "エンコーダーが何かを無害化した際のロギング。これにより、境界が処理経路上で機能していることを確認できます。" ], "benefits": [ "重要なポイントでインジェクションの連鎖を断ち切ります。モデルが完全に誘導されてしまったとしても、下流のシステムがそのテキストを解釈することはないため、下流のシステムを動作させることはできません。", "モデルの挙動に依存しません。モデルが拒否することに依存しないため、モデルのアップグレード、新しいジェイルブレイク（脱獄）、プロンプトの変更を経ても機能し続けます。", "テスト可能です。各宛先にはペイロードと合否（パス/フェイル）が存在するため、この制御は単なる安心感ではなく、確実な証拠をもたらします。", "早期に適用すれば低コストで済みます。エンコーダーの追加は境界の変更ですが、宛先がいたるところに存在した後に後付けするのは大規模なリファクタリングになります。" ], "risks": [ "すべての宛先に対して1つのサニタイザーを使用すること。これは制御が行われているように感じられ、チェックリストを満たしますが、それが想定して書かれた境界以外のすべての境界において誤った処理となります。", "プロダクトを破損させるエンコーディング：過剰なエスケープ処理により、正当なMarkdown、コードブロック、非ラテン文字テキストがノイズに変わってしまいます。そして、それを緩和しようとする圧力は、宛先リストではなくエンコーダーにかかることになります。", "陳腐化する宛先インベントリ。新しい連携によって消費システムが追加されても、それを見落としたときにエラーが発生することはありません。", "検知とエンコーディングの混同。不審な文字列がないか出力をスキャンすることは、過去のペイロードを捉えるのには役立ちますが、エンコーディングは攻撃をまったく認識する必要がありません。" ], "whenNot": [ "出力が一切解釈されない場合（スコア、列挙型、呼び出し元が比較するブール値など）。代わりに型を制約してください。閉じられた値のセットに対してエンコーダーを適用するのは、形式的な手続きにすぎません。", "レンダリングもプロセス実行も行わず、唯一の消費者がテキストを読む人間だけである、完全にローカルなシングルユーザー向けツールのケース。", "ORMバインディングや、デフォルトでエスケープを行うテンプレートエンジンなど、宛先が構造上すでにパラメータ化されている場合。2つ目のエンコーダーを導入しても何も得られず、二重エンコードが発生する可能性があります。" ], "examples": [ "サポートエージェントが、攻撃者のホストを指すMarkdown画像が本文に含まれるチケットを要約します。コンソールがそれをレンダリングし、ブラウザがそのURLをフェッチするため、誰も何もクリックしていないにもかかわらず会話が漏洩します。生のHTMLを無効化し、画像ホストをホワイトリストに登録することで、この問題を解決できます。", "コーディングエージェントがシェルコマンドを提案します。ランナーがその文字列をシェルに渡すため、コマンド区切り文字を含むファイル名が実行されてしまいます。代わりにargv配列を渡すことで、シェルのパースステップを完全に排除できます。", "あるエージェントの要約が、2番目のエージェントのプロンプトに配置されます。要約に指示が含まれており、2番目のエージェントがそれに従いました。この場合、信頼できないスパンをフェンスで囲み、データとしてラベル付けすることが境界となります。" ], "kpis": [ { "metric": "宛先カバー率", "note": "境界にエンコーダーが設置されている、既知のモデル出力消費システムの割合。100%未満の場合、制御に特定の抜け穴が存在することになります。平均化されたパーセンテージを示すよりも、具体的な宛先を特定する方が有用です。" }, { "metric": "ペイロード無害化率", "note": "境界で無害化された宛先ごとのテストペイロードの割合。目標は100%です。それ以外の数値は、改善すべき数値というよりも、修正すべき宛先を示しています。" }, { "metric": "新規宛先のカバーに要する時間", "note": "新しい連携が本番稼働してから、そのエンコーダーが用意されるまでの期間。インベントリが一度正しかったかどうかではなく、プロダクトの進化に追従できているかを測定します。" }, { "metric": "境界トリガー数", "note": "本番環境でエンコーダーが何かを無害化した頻度。完全にゼロである場合は、敵対的な入力が届いていないのではなく、通常はエンコーダーが処理経路上に存在しないことを意味します。" } ], "failureModes": [ "レンダリングされたマークアップを介したサイレントな情報漏洩：画像やリンクがクリックなしでフェッチを発生させるため、ユーザーの操作なしに、また誰も気づかないようなエラーも発生せずにデータが外部に流出します。", "二次インジェクション：コンソール向けに正しくエンコードされた出力が保存され、その後、そのエンコーディングが適用されない別の場所（ログビューア、チケット、ダイジェストメールなど）でレンダリングされます。", "正常系パスにしか存在しないエンコーダー。エラー分岐、再試行、フォールバックが、何も対策が施されていない別のコードパスを介して同じテキストを出力してしまいます。", "二重エンコード。2つのレイヤーがそれぞれ正しくエスケープ処理を行い、ユーザーにはプロダクト内でエスケープされた実体参照が表示され、その修正において誤ったレイヤーが削除されてしまいます。" ], "lessons": [ "フィルターを作成する前に宛先を列挙します。ここでの実際の失敗のほぼすべては、エンコーダーの書き間違いではなく、誰もリストアップしていなかった消費システムが存在することに起因します。", "忘れがちな宛先が画面であることは稀です。それはWebhook、ログビューア、エクスポート、またはダイジェストメールなど、レンダリングであると誰も意識しないまま出力が送られる場所です。", "エンコーディングは検知よりも優れています。なぜなら、エンコーディングは攻撃を認識する必要がないからです。ペイロードのブラックリストは、すでに公開されている攻撃の記述にすぎません。", "単一の `sanitise()` を解決策にしないでください。その名前は完全性を連想させますが、その挙動は正確には1つの宛先に対してのみ正しいものです。" ], "faqs": [ { "q": "これはプロンプトインジェクション対策として入力をフィルタリングすることと同じではないのですか？", "a": "いいえ、これらは相反する両端を防御するものです。入力フィルタリングはモデルが誘導されるのを防ごうとするもので、モデルに依存します。一方、出力境界エンコーディングは、誘導がすでに成功したと仮定した上で、出力が実行されるのを防ぐものであり、モデルには一切依存しません。前者のみを備えたシステムは、新しいジェイルブレイク（脱獄）が現れた瞬間に破綻します。" }, { "q": "これは単なる出力サニタイズではないのですか？なぜすべてに対して1つのサニタイザーではいけないのですか？", "a": "エンコーディングは文脈に依存するからです。引用符のエスケープはHTMLレンダラーを保護しますが、シェルに対しては何の効果もありません。シェルクォーティングはシェルを保護しますが、表示されるテキストを破損させます。共有関数は1つの文脈を選択せざるを得ず、他の文脈では誤った処理となり、カバーできているように見えて単一障害点になってしまいます。" }, { "q": "モデルは自社のものであり、プロンプトも固定されています。それでもこれが必要ですか？", "a": "はい。モデルが読み込むコンテンツが、取得したページ、ユーザーファイル、ツールの実行結果、メモリレコードなど、外部から提供されるものである場合は該当します。指示はプロンプトから直接与えられる必要はありません。モデルが読み込むあらゆるコンテンツを介して指示が入り込むため、プロンプトが固定されているからといって、それを防げるわけではありません。" } ] }, "zh": { "name": "输出边界编码", "summary": "将模型输出的所有内容都视为对其消费端的恶意输入。在每个目标端（渲染器、shell、查询、下游智能体）使用该目标端自身的规则进行编码和验证。单一的全局净化器无法做到这一点：对 HTML 正确的转义对 shell 来说毫无意义。", "definition": "输出边界编码是指在模型输出跨入将对其进行解析的系统的每一个节点上，应用针对特定目标端的编码和验证，而不是在输出模型时进行一次通用的过滤。缺少这一实践即是 OWASP 所称的“不当输出处理”漏洞。", "problem": "团队往往会针对提示词注入对输入端进行加固，却让输出端处于不设防状态。随后，模型的文本到达渲染器、shell、数据库或其他智能体的上下文，并在那里被解析为指令而非作为数据展示。攻击者根本不需要直接接触模型。", "context": "任何其输出会到达对其进行解析的系统的智能体：例如渲染 markdown 的聊天界面、运行建议命令的编码智能体、根据生成的参数构建的工具调用、输入到第二个智能体提示词中的摘要，或者向前转发文本的 webhook。", "solution": [ "在编写任何过滤器之前，先列举所有的目标端。模型输出落地并被解析的每个地方——HTML 渲染器、shell、查询、文件路径、URL 获取器、另一个智能体的上下文、下游 webhook——都是一个具有不同规则的独立边界。", "在目标端进行编码，而不是在源端。为渲染器进行 HTML 转义，为查询进行参数化，向进程传递 argv 数组。编码应当发生在解析发生的地方，因为只有在那里你才知道什么将被解析。", "优先选择结构化输出，而不是需要重新解析的自然语言。带有类型化参数的工具调用具有可用于验证的 schema；而你用正则表达式提取文件名的句子则没有。", "不仅要验证语法，还要验证值。编码后的路径仍然是路径：在打开它之前，请检查它是否解析在你预期的目录内。", "将出站 URL 视为一个独立的目标端。渲染的图片和链接会在无需点击的情况下触发获取请求，从而将数据带出；请将渲染链接可以访问的主机加入白名单。", "使该边界成为唯一的路径。如果任何代码路径可以在不经过目标端编码器的情况下消费原始模型输出，那么这种控制只是建议性的，而非实质性的。" ], "components": [ "目标端清单：模型输出的每个消费者，以及它们各自所需的编码器。", "针对每个目标端的编码器（HTML、进程 argv、查询参数、路径解析、URL 白名单），而不是一个共享的净化器。", "针对工具调用的、经过 schema 验证的结构化输出，从而使参数具有类型，而不是从自然语言中解析出来。", "一个出口白名单，涵盖渲染的链接和图片可访问的主机。", "契约测试，针对每个目标端发送有效载荷，并断言其在边界处已被中和。", "在编码器中和某些内容时记录日志，以便边界能够告知您它正在发挥作用。" ], "benefits": [ "在关键环节切断注入链：即使模型被完全说服，也无法让下游系统执行操作，因为该系统绝不会解析其文本。", "独立于模型行为。它在模型升级、新的越狱和提示词更改时依然有效，因为它不依赖于模型拒绝任何内容。", "可测试。每个目标端都有一个有效载荷以及通过或失败的结果，因此该控制措施产生的是证据而非口头保证。", "尽早应用成本较低。添加编码器属于边界变更；而在目标端无处不在之后再进行补救则属于重构。" ], "risks": [ "对所有目标端使用同一个净化器。这看起来像是一种控制措施，满足了检查清单的要求，但除了它专门针对的那个边界之外，在其他所有边界上都是错误的。", "编码破坏了产品：过度转义会将合法的 markdown、代码块和非拉丁文本变成噪音，而放宽限制的压力最终会落在编码器上，而不是目标端清单上。", "目标端清单老化。新的集成增加了消费者，而当遗漏某个消费者时，系统并不会报错。", "混淆检测与编码。扫描输出中的可疑字符串只能捕获去年的有效载荷；而编码根本不需要识别攻击。" ], "whenNot": [ "绝不会被解析的输出——例如调用者进行比较的分数、枚举或布尔值。此时应限制其类型；在封闭的值集上使用编码器只是流于形式。", "完全本地的单用户工具，没有渲染，也没有进程执行，唯一的消费者是阅读文本的人。", "目标端在构建时已经进行了参数化，例如 ORM 绑定或默认进行转义的模板引擎。第二个编码器不会带来任何好处，反而可能导致双重编码。" ], "examples": [ "支持智能体对工单进行摘要，该工单正文中包含一个指向攻击者主机的 markdown 图片。控制台渲染了该图片，浏览器获取了该 URL，于是在无人点击任何内容的情况下，对话内容泄露了。禁用原始 HTML 并将图片主机加入白名单可以解决此问题。", "编码智能体建议了一条 shell 命令。运行器将该字符串传递给 shell，导致包含命令分隔符的文件名被执行。改为传递 argv 数组则可以完全省去 shell 的解析步骤。", "一个智能体的摘要被放入第二个智能体的提示词中。该摘要包含指令，而第二个智能体执行了这些指令。在这种情况下，隔离不可信的跨度并将其标记为数据就是其边界。" ], "kpis": [ { "metric": "目标端覆盖率", "note": "在边界处设有编码器的已知模型输出消费者的比例。低于 100% 意味着控制措施存在特定的漏洞，指明具体的目标端比用一个平均百分比将其掩盖更有用。" }, { "metric": "有效载荷中和率", "note": "在边界处被中和的每个目标端测试有效载荷的比例。目标是 100%：任何其他结果都意味着需要指出待修复的目标端，而不是需要提高的数字。" }, { "metric": "覆盖新目标端所需的时间", "note": "从新集成上线到其编码器就绪所需的时间。这衡量的是清单是否能跟上产品的步伐，而不是它是否曾经正确过。" }, { "metric": "边界触发量", "note": "编码器在生产环境中中和内容的频率。完全为零通常意味着编码器未处于路径上，而不是没有恶意内容到达。" } ], "failureModes": [ "通过渲染的标记进行静默外传：图片或链接在无需点击的情况下触发获取请求，从而在没有用户操作且无人会注意到的错误的情况下将数据带出。", "二阶注入：针对控制台正确编码的输出被存储，随后在其他地方（日志查看器、工单、摘要邮件）进行渲染，而那里的编码并不适用。", "仅存在于正常路径（happy path）上的编码器。错误分支、重试和回退通过一条没有任何防护的、不同的代码路径发送相同的文本。", "双重编码。两层都进行了正确的转义，用户在产品中看到了转义后的实体，而修复措施却移除了错误的一层。" ], "lessons": [ "在编写过滤器之前，先列举所有的目标端。这里几乎所有实际的失败都是因为存在无人列出的消费者，而不是因为编码器写错了。", "你遗忘的目标端很少是屏幕。它通常是 webhook、日志查看器、导出或摘要邮件——即输出所流向的、但没人会将其视为渲染的某个地方。", "编码优于检测，因为编码不需要识别攻击。有效载荷黑名单只是对已经公开的攻击的描述。", "不要让单一的 `sanitise()` 成为解决方案。这个名字暗示了完整性，但其行为仅对恰好一个目标端是正确的。" ], "faqs": [ { "q": "这与针对提示词注入过滤输入不是一回事吗？", "a": "不——它们防御的是相反的两端。输入过滤试图阻止模型被说服，这取决于模型。而本方法假设说服已经成功，并阻止输出被执行，这完全不依赖于模型。仅具有前者的系统在出现新的越狱手段时就会失效。" }, { "q": "这不就是输出净化吗？为什么不使用一个通用的净化器呢？", "a": "因为编码是与上下文相关的。转义引号可以保护 HTML 渲染器，但对 shell 毫无作用；shell 引号转义可以保护 shell，但会破坏显示的文本。共享函数必须选择一种上下文，在其他上下文中则是错误的，这看起来实现了覆盖，实则是一个单点故障。" }, { "q": "模型是我们的，提示词也是固定的。我们还需要这个吗？", "a": "是的，只要模型读取的任何内容来自外部：获取的页面、用户文件、工具结果、内存记录。指令不一定非要通过你的提示词传入——它可以通过模型读取的任何内容传入，而你的提示词是固定的并不能约束这一点。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/parallelization", "api_url": "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." } ] }, "fr": { "name": "Parallélisation", "summary": "La parallélisation exécute plusieurs appels de LLM en même temps et agrège les résultats. Deux variantes : le sectionnement (diviser une tâche en sous-tâches indépendantes exécutées en parallèle) et le vote (exécuter la même tâche plusieurs fois pour améliorer la fiabilité ou la couverture). Elle réduit la latence et peut améliorer la qualité.", "problem": "Exécuter des sous-tâches indépendantes les unes après les autres fait perdre du temps, et un échantillon unique d'une tâche difficile peut s'avérer peu fiable.", "context": "Utilisez la parallélisation lorsque les sous-tâches sont indépendantes (sectionnement), ou lorsque plusieurs tentatives pour une même tâche améliorent la confiance ou la couverture (vote).", "solution": [ "Sectionnement : diviser le travail en parties indépendantes, les exécuter simultanément et combiner les résultats. Vote : exécuter le même prompt plusieurs fois (ou avec des variantes) et agréger par majorité, union ou via un juge.", "Les deux approches réduisent le temps d'exécution réel par rapport à une exécution séquentielle ; le vote permet en outre d'échanger un coût supplémentaire contre une plus grande fiabilité sur les tâches où un échantillon unique est risqué." ], "components": [ "Diviseur de tâche", "Workers concurrents", "Agrégateur (fusion / vote / juge)" ], "benefits": [ "Latence réduite en exécutant les appels de manière concurrente.", "Le vote améliore la fiabilité et la couverture.", "Chaque appel parallèle reste simple et ciblé." ], "risks": [ "Le vote multiplie le coût en jetons.", "La logique d'agrégation peut être difficile à mettre au point.", "Des sous-tâches supposées indépendantes peuvent en réalité interagir." ], "whenNot": [ "Lorsque les sous-tâches dépendent du résultat les unes des autres — enchaînez-les.", "Lorsque le budget est serré et qu'un seul appel suffit.", "Lorsque les résultats ne peuvent pas être agrégés de manière significative." ], "examples": [ "Résumer plusieurs documents à la fois, puis fusionner les résumés.", "Exécuter un contrôle de sécurité en parallèle de la réponse principale.", "Échantillonner une réponse plusieurs fois et retenir la majorité." ], "kpis": [ { "metric": "Réduction de la latence par rapport au séquentiel", "note": "Temps réel économisé en exécutant les appels de manière concurrente ; c'est tout l'intérêt de ce pattern." }, { "metric": "Qualité de l'agrégation", "note": "Le fait que la fusion des résultats parallèles préserve ou non l'exactitude — la difficulté réside dans la jointure, pas dans la distribution (fan-out)." }, { "metric": "Coût de la concurrence", "note": "Total des jetons sur l'ensemble des branches parallèles ; vous échangez de l'argent contre de la vitesse, surveillez donc le multiplicateur." }, { "metric": "Taux de dépassement des limites de requêtes (rate-limit / throttle)", "note": "Fréquence à laquelle les appels parallèles atteignent les limites de requêtes du fournisseur, ce qui les sérialise silencieusement ou les fait échouer." } ], "failureModes": [ "Erreurs d'agrégation : les résultats parallèles sont corrects individuellement mais mal combinés (double comptage, contradictions).", "La limitation du débit (rate limiting) transforme la parallélisation prévue en appels séquentiels lents.", "Surprise sur les coûts : N branches parallèles coûtent N fois plus cher, même si un seul résultat est utilisé.", "Gestion des échecs partiels : une branche échoue et l'agrégateur bloque ou l'ignore silencieusement." ], "lessons": [ "Concevez d'abord l'étape d'agrégation — bien combiner les résultats est plus difficile que de diviser le travail.", "Respectez les limites de requêtes du fournisseur avec du traitement par lots (batching) ou du backoff, sous peine de voir la parallélisation s'évaporer.", "Ne parallélisez que les sous-tâches indépendantes ; les dépendances imposent de toute façon un enchaînement séquentiel.", "Décidez explicitement de la manière dont les échecs partiels sont gérés avant qu'ils ne surviennent en production." ], "faqs": [ { "q": "Quelle est la différence entre le sectionnement et le vote ?", "a": "Le sectionnement divise une tâche en différentes sous-tâches indépendantes ; le vote exécute la même tâche plusieurs fois afin d'agréger les résultats pour plus de fiabilité." }, { "q": "Le vote améliore-t-il toujours la qualité ?", "a": "Souvent, sur les tâches où les échantillons varient, mais cela multiplie les coûts. Réservez-le aux étapes à enjeux élevés où un échantillon unique est risqué." }, { "q": "Comment combiner les résultats parallèles ?", "a": "Selon le cas : concaténer les sections, procéder à un vote majoritaire, unir les résultats ou utiliser un modèle juge pour faire la synthèse." } ] }, "de": { "name": "Parallelisierung", "summary": "Parallelisierung führt mehrere LLM-Aufrufe gleichzeitig aus und aggregiert die Ergebnisse. Zwei Varianten: Sektionierung (Aufteilen einer Aufgabe in unabhängige, parallel ausgeführte Teilaufgaben) und Voting (mehrfaches Ausführen derselben Aufgabe zur Verbesserung der Zuverlässigkeit oder Abdeckung). Sie verringert die Latenz und kann die Qualität steigern.", "problem": "Das nacheinander Ausführen unabhängiger Teilaufgaben verschwendet Zeit, und ein einzelner Durchlauf einer schwierigen Aufgabe kann unzuverlässig sein.", "context": "Nutzen Sie Parallelisierung, wenn Teilaufgaben unabhängig sind (Sektionierung) oder wenn mehrere Versuche bei derselben Aufgabe das Vertrauen oder die Abdeckung verbessern (Voting).", "solution": [ "Sektionierung: Teilen Sie die Arbeit in unabhängige Teile auf, führen Sie diese gleichzeitig aus und kombinieren Sie die Ausgaben. Voting: Führen Sie denselben Prompt mehrmals (oder mit Variationen) aus und aggregieren Sie die Ergebnisse per Mehrheitsentscheid, Vereinigung oder durch ein Judge-Modell.", "Beide Ansätze reduzieren die tatsächliche Laufzeit im Vergleich zur sequenziellen Ausführung; Voting tauscht zudem zusätzliche Kosten gegen eine höhere Zuverlässigkeit bei Aufgaben ein, bei denen ein einzelner Durchlauf riskant ist." ], "components": [ "Task-Splitter", "Gleichzeitige Worker", "Aggregator (Zusammenführung / Voting / Bewertung)" ], "benefits": [ "Geringere Latenz durch gleichzeitiges Ausführen von Aufrufen.", "Voting verbessert die Zuverlässigkeit und Abdeckung.", "Jeder parallele Aufruf bleibt einfach und fokussiert." ], "risks": [ "Voting vervielfacht die Token-Kosten.", "Die Aggregationslogik kann in der korrekten Umsetzung knifflig sein.", "Teilaufgaben, von denen angenommen wird, dass sie unabhängig sind, können sich tatsächlich gegenseitig beeinflussen." ], "whenNot": [ "Wenn Teilaufgaben von den Ausgaben der jeweils anderen abhängen – verketten Sie diese.", "Wenn das Budget knapp ist und ein einzelner Aufruf ausreicht.", "Wenn Ergebnisse nicht sinnvoll aggregiert werden können." ], "examples": [ "Gleichzeitiges Zusammenfassen vieler Dokumente und anschließendes Zusammenführen der Zusammenfassungen.", "Paralleles Ausführen einer Sicherheitsprüfung zur Hauptantwort.", "Mehrfaches Generieren einer Antwort und Auswahl der Mehrheit." ], "kpis": [ { "metric": "Latenzreduktion im Vergleich zu sequenziell", "note": "Eingesparte tatsächliche Laufzeit durch gleichzeitiges Ausführen von Aufrufen; der eigentliche Zweck dieses Musters." }, { "metric": "Aggregationsqualität", "note": "Ob das Zusammenführen der parallelen Ausgaben die Korrektheit bewahrt – der schwierige Teil ist der Join, nicht der Fan-out." }, { "metric": "Parallelitätskosten", "note": "Gesamte Token über alle parallelen Zweige hinweg; Sie tauschen Geld gegen Geschwindigkeit, achten Sie also auf den Multiplikator." }, { "metric": "Rate-Limit- / Drosselungsrate", "note": "Wie oft parallele Aufrufe an die Rate-Limits des Anbieters stoßen, was sie unbemerkt serialisiert oder fehlschlagen lässt." } ], "failureModes": [ "Aggregationsfehler: Parallele Ergebnisse sind einzeln korrekt, werden aber falsch kombiniert (Doppelzählung, Widersprüche).", "Rate-Limiting verwandelt die beabsichtigte Parallelität wieder in langsame, sequenzielle Aufrufe.", "Kostenüberraschung: N parallele Zweige kosten das N-Fache, selbst wenn nur ein Ergebnis verwendet wird.", "Umgang mit Teilausfällen: Ein Zweig schlägt fehl und der Aggregator blockiert entweder oder verwirft ihn stillschweigend." ], "lessons": [ "Entwerfen Sie zuerst den Aggregationsschritt – das gute Kombinieren von Ergebnissen ist schwieriger als das Aufteilen der Arbeit.", "Beachten Sie die Rate-Limits des Anbieters durch Batching oder Backoff, da die Parallelität sonst verpufft.", "Parallelisieren Sie nur unabhängige Teilaufgaben; Abhängigkeiten erzwingen ohnehin eine Sequenz.", "Entscheiden Sie explizit, wie mit Teilausfällen umgegangen wird, bevor sie in der Produktion auftreten." ], "faqs": [ { "q": "Was ist der Unterschied zwischen Sektionierung und Voting?", "a": "Sektionierung teilt eine Aufgabe in verschiedene unabhängige Teilaufgaben auf; Voting führt dieselbe Aufgabe mehrfach aus, um die Ergebnisse für eine höhere Zuverlässigkeit zu aggregieren." }, { "q": "Verbessert Voting immer die Qualität?", "a": "Oft bei Aufgaben, bei denen die Ergebnisse variieren, aber es vervielfacht die Kosten. Reservieren Sie es für kritische Schritte, bei denen ein einzelner Durchlauf riskant ist." }, { "q": "Wie kombiniere ich parallele Ergebnisse?", "a": "Je nach Fall: Verketten Sie Abschnitte, führen Sie einen Mehrheitsentscheid durch, vereinigen Sie die Ergebnisse oder nutzen Sie ein Judge-Modell zur Synthese." } ] }, "ja": { "name": "並列化", "summary": "並列化は、複数のLLM呼び出しを同時に実行し、その結果を集約します。これには2つのパターンがあります。セクショニング（タスクを独立したサブタスクに分割して並列実行する）と、ボーティング（信頼性やカバレッジを向上させるために同じタスクを複数回実行する）です。これにより、レイテンシが短縮され、品質が向上します。", "problem": "独立したサブタスクを順次実行すると時間が無駄になり、また、難易度の高いタスクを1回だけ試行した結果は信頼性に欠ける場合があります。", "context": "サブタスクが独立している場合（セクショニング）、または同じタスクを複数回試行することで確信度やカバレッジが向上する場合（ボーティング）に、並列化を使用します。", "solution": [ "セクショニング：作業を独立した部分に分割し、それらを並行して実行し、出力を結合します。ボーティング：同じプロンプト（またはバリエーション）を複数回実行し、多数決、和集合、または判定モデルによって集約します。", "どちらの方法も、順次実行と比較して実時間（ウォールクロックタイム）を短縮します。さらにボーティングは、1回の試行ではリスクが伴うタスクにおいて、追加のコストと引き換えに高い信頼性を得ることができます。" ], "components": [ "タスクスプリッター", "並行ワーカー", "アグリゲーター（マージ / ボーティング / 判定）" ], "benefits": [ "呼び出しを並行して実行することで、レイテンシを短縮します。", "ボーティングにより、信頼性とカバレッジが向上します。", "個々の並列呼び出しをシンプルかつ焦点を絞った状態に維持できます。" ], "risks": [ "ボーティングにより、トークンコストが倍増します。", "集約ロジックを正しく構築するのが難しい場合があります。", "独立していると想定されたサブタスクが、実際には相互に影響を及ぼし合う可能性があります。" ], "whenNot": [ "サブタスクが互いの出力に依存している場合（この場合はチェーニングを行います）。", "コストに余裕がなく、1回の呼び出しで十分な場合。", "結果を有意義に集約できない場合。" ], "examples": [ "多数のドキュメントを一度に要約し、その後、要約をマージする。", "メインの応答と並行して安全性チェックを実行する。", "回答を複数回サンプリングし、多数決をとる。" ], "kpis": [ { "metric": "順次実行と比較したレイテンシ削減率", "note": "呼び出しを並行して実行することで節約される実時間。このパターンの本質です。" }, { "metric": "集約品質", "note": "並列出力をマージしても正確性が維持されるかどうか。難しいのはファンアウトではなく、結合（ジョイン）の部分です。" }, { "metric": "並行実行コスト", "note": "すべての並列ブランチにおける総トークン数。速度と引き換えにコストを支払うことになるため、倍率に注意してください。" }, { "metric": "レート制限 / スロットリング発生率", "note": "並列呼び出しがプロバイダーのレート制限に達する頻度。制限に達すると、暗黙的に順次実行に切り替わるか、呼び出しが失敗します。" } ], "failureModes": [ "集約エラー：個々の並列結果は正しいものの、結合方法が誤っている（二重カウント、矛盾など）。", "レート制限により、意図した並列処理が低速な順次呼び出しに戻ってしまう。", "予期せぬコスト：1つの結果しか使用しない場合でも、N個の並列ブランチにはN倍のコストがかかります。", "部分的な失敗の処理：1つのブランチが失敗した際に、アグリゲーターが処理をブロックするか、あるいはエラーを暗黙的に無視してドロップしてしまう。" ], "lessons": [ "最初に集約ステップを設計してください。作業を分割することよりも、結果を適切に結合することの方が困難です。", "バッチ処理やバックオフを使用してプロバイダーのレート制限を遵守してください。さもないと、並列処理のメリットが失われます。", "独立したサブタスクのみを並列化してください。依存関係がある場合は、いずれにせよ順次実行せざるを得なくなります。", "本番環境で発生する前に、部分的な失敗をどのように処理するかを明示的に決定しておいてください。" ], "faqs": [ { "q": "セクショニングとボーティングの違いは何ですか？", "a": "セクショニングは1つのタスクを異なる独立したサブタスクに分割します。ボーティングは、信頼性を高めるために同じタスクを複数回実行して集約します。" }, { "q": "ボーティングを行えば、常に品質が向上しますか？", "a": "試行結果にばらつきが生じるタスクでは向上することが多いですが、コストが倍増します。1回の試行ではリスクが伴う、極めて重要なステップに限定して使用してください。" }, { "q": "並列処理の結果はどのように結合すればよいですか？", "a": "ユースケースに応じて、セクションを結合する、多数決をとる、検出結果の和集合をとる、または判定モデルを使用して統合します。" } ] }, "zh": { "name": "并行化", "summary": "并行化同时运行多个 LLM 调用并汇总结果。它有两种形式：分段（将任务拆分为独立子任务并并行运行）和投票（多次运行同一任务以提高可靠性或覆盖率）。它能降低延迟并提高质量。", "problem": "依次运行独立的子任务会浪费时间，而且对困难任务进行单次采样可能不可靠。", "context": "当子任务相互独立时（分段），或者当对同一任务进行多次尝试可以提高置信度或覆盖率时（投票），请使用并行化。", "solution": [ "分段：将工作拆分为独立的部分，并发运行它们，然后合并输出。投票：多次运行相同的提示词（或带有变体），并通过多数票、并集或裁判模型进行汇总。", "与顺序执行相比，两者都能减少实际运行时间；此外，在单次采样存在风险的任务中，投票通过增加额外成本来换取更高的可靠性。" ], "components": [ "任务拆分器", "并发工作器", "聚合器（合并/投票/裁判）" ], "benefits": [ "通过并发运行调用来降低延迟。", "投票可以提高可靠性和覆盖率。", "每个并行调用都保持简单和专注。" ], "risks": [ "投票会成倍增加 Token 成本。", "聚合逻辑可能很难处理得当。", "假设独立的子任务实际上可能会相互影响。" ], "whenNot": [ "当子任务依赖于彼此的输出时——请使用链式调用。", "当预算紧张且单次调用已足够时。", "当结果无法进行有意义的聚合时。" ], "examples": [ "同时总结多个文档，然后合并这些摘要。", "与主响应并行运行安全检查。", "对一个回答进行多次采样并取多数意见。" ], "kpis": [ { "metric": "相比顺序执行的延迟降低幅度", "note": "通过并发运行调用节省的实际运行时间；这是该模式的核心意义。" }, { "metric": "聚合质量", "note": "合并并行输出是否能保持正确性——难点在于合并，而不是分发。" }, { "metric": "并发成本", "note": "所有并行分支的总 Token 数；这是用资金换取速度，因此需要注意倍数效应。" }, { "metric": "速率限制/限流率", "note": "并行调用触发服务商速率限制的频率，这会默默地将调用转为串行或导致失败。" } ], "failureModes": [ "聚合错误：并行结果单独来看是正确的，但合并方式错误（如重复计算、相互矛盾）。", "速率限制将预期的并行执行重新变回缓慢的串行调用。", "意外的成本：即使只使用一个结果，N 个并行分支也会产生 N 倍的成本。", "部分失败处理：某个分支失败，导致聚合器阻塞或默默丢弃该分支。" ], "lessons": [ "优先设计聚合步骤——良好地合并结果比拆分工作更难。", "通过批处理或退避机制来遵守服务商的速率限制，否则并行性将不复存在。", "仅对独立的子任务进行并行化；存在依赖关系的任务无论如何都必须按顺序执行。", "在生产环境中发生部分失败之前，明确决定如何处理它们。" ], "faqs": [ { "q": "分段和投票有什么区别？", "a": "分段将一个任务拆分为不同的独立子任务；投票则多次运行同一任务并进行聚合以提高可靠性。" }, { "q": "投票总能提高质量吗？", "a": "在样本存在差异的任务中通常如此，但它会成倍增加成本。请将其保留用于单次采样存在风险的高风险步骤。" }, { "q": "如何合并并行结果？", "a": "视具体情况而定：拼接各段内容、采用多数票、取结果的并集，或使用裁判模型进行综合。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/prompt-chaining", "api_url": "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." } ] }, "fr": { "name": "Enchaînement de prompts", "summary": "L'enchaînement de prompts décompose une tâche en une séquence fixe d'appels de LLM, où chaque étape travaille sur le résultat de la précédente. Il échange un peu de latence contre une précision et un contrôle bien plus élevés, et constitue le pattern de workflow le plus simple : utilisez-le dès qu'une tâche se divise clairement en sous-tâches ordonnées.", "problem": "Un prompt unique auquel on demande de faire plusieurs choses à la fois produit un résultat de moindre qualité, plus difficile à contrôler, et s'avère complexe à déboguer en cas de problème.", "context": "Utilisez l'enchaînement de prompts lorsqu'une tâche se décompose en une séquence claire et ordonnée de sous-tâches — par exemple, faire un plan, puis rédiger, puis éditer — et que chaque étape bénéficie du résultat de la précédente.", "solution": [ "Divisez la tâche en étapes distinctes et effectuez un appel de LLM par étape, en transmettant chaque résultat au suivant. Ajoutez éventuellement des contrôles programmatiques (portes de validation) entre les étapes pour valider les résultats intermédiaires avant de continuer.", "Chaque appel ayant une tâche ciblée, les prompts sont plus simples, les résultats plus fiables, et les échecs sont localisés à une étape spécifique que vous pouvez inspecter et corriger." ], "components": [ "Étapes ordonnées", "Prompt par étape", "Portes de validation / contrôles entre les étapes", "État transmis entre les étapes" ], "benefits": [ "Précision accrue en attribuant à chaque appel une tâche ciblée.", "Plus facile à déboguer — les échecs sont localisés à une étape précise.", "Les portes de validation peuvent intercepter les erreurs entre les étapes." ], "risks": [ "Latence totale plus élevée en raison des appels séquentiels.", "Les erreurs peuvent s'accumuler tout au long de la chaîne si elles ne sont pas contrôlées.", "Un trop grand nombre d'étapes augmente le coût et la fragilité." ], "whenNot": [ "Lorsque la tâche est suffisamment simple pour un seul appel.", "Lorsque les sous-tâches sont indépendantes — parallélisez plutôt.", "Lorsque le chemin n'est pas connu à l'avance — utilisez une boucle d'agent." ], "examples": [ "Générer un plan, puis rédiger chaque section, puis réviser le ton.", "Extraire des champs structurés, puis les valider, puis résumer.", "Traduire un document, puis vérifier la traduction par rapport à la source." ], "kpis": [ { "metric": "Taux de réussite de bout en bout", "note": "Part des chaînes qui produisent un résultat final correct ; les erreurs s'accumulent au fil des étapes." }, { "metric": "Taux d'erreur par étape", "note": "Taux d'échec à chaque maillon — une étape fiable à 95 % enchaînée cinq fois donne environ 77 % de réussite de bout en bout." }, { "metric": "Latence et coût totaux", "note": "Somme de tous les appels de la chaîne ; plus d'étapes signifie une augmentation de ces deux facteurs." }, { "metric": "Taux de récupération", "note": "Fréquence à laquelle une étape intermédiaire défaillante est interceptée et corrigée plutôt que propagée silencieusement." } ], "failureModes": [ "Propagation des erreurs : une erreur au début de la chaîne corrompt toutes les étapes en aval.", "Accumulation de la latence et des coûts à mesure que la chaîne s'allonge.", "Passages de relais fragiles lorsque le format de sortie d'une étape ne correspond pas à l'entrée attendue de l'étape suivante.", "Perte de contexte entre les étapes, de sorte que les maillons ultérieurs oublient les contraintes définies précédemment." ], "lessons": [ "Validez ou effectuez des contrôles d'accès (gate-checks) entre les étapes afin que les erreurs soient interceptées avant de se propager.", "Gardez les chaînes aussi courtes que la tâche le permet ; chaque étape supplémentaire multiplie la probabilité d'échec.", "Figez le contrat de sortie de chaque étape afin que les passages de relais ne se cassent pas silencieusement.", "Utilisez l'enchaînement pour les travaux véritablement séquentiels ; parallélisez plutôt les étapes indépendantes." ], "faqs": [ { "q": "En quoi l'enchaînement de prompts diffère-t-il d'un agent ?", "a": "L'enchaînement de prompts suit une séquence fixe et prédéfinie. Un agent décide de ses propres étapes de manière dynamique. Privilégiez l'enchaînement lorsque le chemin est connu à l'avance." }, { "q": "Quand dois-je ajouter des portes de validation entre les étapes ?", "a": "Chaque fois qu'un résultat intermédiaire doit remplir une condition avant de continuer — cela empêche les erreurs de se propager tout au long de la chaîne." }, { "q": "Le chaînage augmente-t-il le coût ?", "a": "Oui, modestement — plus d'appels signifie plus de jetons et de latence — mais le gain de fiabilité l'emporte généralement pour les tâches en plusieurs parties." } ] }, "de": { "name": "Prompt Chaining", "summary": "Prompt Chaining zerlegt eine Aufgabe in eine feste Sequenz von LLM-Aufrufen, bei der jeder Schritt auf der Ausgabe des vorherigen aufbaut. Es tauscht ein wenig Latenz gegen eine deutlich höhere Genauigkeit und Kontrolle ein und ist das einfachste Workflow-Muster: Nutzen Sie es immer dann, wenn sich eine Aufgabe sauber in geordnete Teilaufgaben aufteilen lässt.", "problem": "Ein einzelner Prompt, der mehrere Dinge gleichzeitig erledigen soll, liefert eine qualitativ minderwertigere, schwerer zu kontrollierende Ausgabe und ist bei Fehlern nur schwer zu debuggen.", "context": "Nutzen Sie Prompt Chaining, wenn sich eine Aufgabe in eine klare, geordnete Sequenz von Teilaufgaben zerlegen lässt – zum Beispiel Gliederung, dann Entwurf, dann Bearbeitung – und jeder Schritt vom Ergebnis des vorherigen Schritts profitiert.", "solution": [ "Teilen Sie die Aufgabe in diskrete Schritte auf und führen Sie einen LLM-Aufruf pro Schritt aus, wobei jede Ausgabe an den nächsten übergeben wird. Fügen Sie optional programmatische Prüfungen (Gates) zwischen den Schritten hinzu, um Zwischenergebnisse zu validieren, bevor Sie fortfahren.", "Da jeder Aufruf eine fokussierte Aufgabe hat, sind die Prompts einfacher, die Ausgaben zuverlässiger und Fehler auf einen bestimmten Schritt eingegrenzt, den Sie überprüfen und beheben können." ], "components": [ "Geordnete Schritte", "Prompt pro Schritt", "Gates / Validierung zwischen den Schritten", "Zwischen den Schritten übergebener Zustand" ], "benefits": [ "Höhere Genauigkeit, da jeder Aufruf eine fokussierte Aufgabe hat.", "Einfacheres Debugging – Fehler lassen sich auf einen Schritt eingrenzen.", "Validierungs-Gates können Fehler zwischen den Schritten abfangen." ], "risks": [ "Höhere Gesamtlatenz durch sequenzielle Aufrufe.", "Fehler können sich entlang der Kette aufschaukeln, wenn sie nicht überprüft werden.", "Zu viele Schritte erhöhen die Kosten und die Fehleranfälligkeit." ], "whenNot": [ "Wenn die Aufgabe einfach genug für einen einzelnen Aufruf ist.", "Wenn Teilaufgaben unabhängig sind – parallelisieren Sie stattdessen.", "Wenn der Pfad im Vorfeld unbekannt ist – nutzen Sie einen Agent-Loop." ], "examples": [ "Erstellen einer Gliederung, anschließendes Schreiben jedes Abschnitts und abschließendes Überarbeiten des Tonfalls.", "Extrahieren strukturierter Felder, anschließendes Validieren dieser Felder und abschließendes Zusammenfassen.", "Übersetzen eines Dokuments und anschließendes Abgleichen der Übersetzung mit der Quelle." ], "kpis": [ { "metric": "End-to-End-Erfolgsquote", "note": "Anteil der Ketten, die ein korrektes Endergebnis liefern; Fehler summieren sich über die Schritte hinweg." }, { "metric": "Fehlerrate pro Schritt", "note": "Ausfallrate bei jedem Glied – ein zu 95 % zuverlässiger Schritt, der fünfmal verkettet wird, führt zu einer End-to-End-Zuverlässigkeit von ca. 77 %." }, { "metric": "Gesamtlatenz und -kosten", "note": "Summe über jeden Aufruf in der Kette; mehr Schritte bedeuten eine Erhöhung von beidem." }, { "metric": "Recovery-Rate", "note": "Wie oft ein fehlgeschlagener Zwischenschritt abgefangen und korrigiert wird, anstatt stillschweigend weitergegeben zu werden." } ], "failureModes": [ "Fehlerfortpflanzung: Ein Fehler zu Beginn der Kette beeinträchtigt jeden nachfolgenden Schritt.", "Akkumulation von Latenz und Kosten, je länger die Kette wird.", "Fehleranfällige Übergaben, wenn das Ausgabeformat eines Schritts nicht mit der erwarteten Eingabe des nächsten Schritts übereinstimmt.", "Kontextverlust über Schritte hinweg, sodass spätere Glieder früher festgelegte Einschränkungen vergessen." ], "lessons": [ "Validieren oder prüfen Sie Zwischenschritte mit Gates, damit Fehler abgefangen werden, bevor sie sich fortpflanzen.", "Halten Sie Ketten so kurz wie möglich; jeder zusätzliche Schritt multipliziert die Ausfallwahrscheinlichkeit.", "Legen Sie den Ausgabe-Vertrag (Output Contract) jedes Schritts fest, damit Übergaben nicht unbemerkt fehlschlagen.", "Nutzen Sie Chaining für wirklich sequenzielle Aufgaben; parallelisieren Sie stattdessen unabhängige Schritte." ], "faqs": [ { "q": "Wie unterscheidet sich Prompt Chaining von einem Agenten?", "a": "Prompt Chaining folgt einer festen, vordefinierten Sequenz. Ein Agent entscheidet seine Schritte dynamisch selbst. Bevorzugen Sie Chaining, wenn der Pfad im Voraus bekannt ist." }, { "q": "Wann sollte ich Gates zwischen den Schritten hinzufügen?", "a": "Immer dann, wenn ein Zwischenergebnis eine Bedingung erfüllen muss, bevor es weitergeht – dies verhindert, dass sich Fehler in der Kette fortpflanzen." }, { "q": "Erhöht Chaining die Kosten?", "a": "Ja, in geringem Maße – mehr Aufrufe bedeuten mehr Token und Latenz –, aber der Gewinn an Zuverlässigkeit überwiegt dies bei mehrteiligen Aufgaben meist." } ] }, "ja": { "name": "プロンプトチェーニング", "summary": "プロンプトチェーニングは、タスクを固定された一連のLLM呼び出しに分解し、各ステップで前のステップの出力を処理します。わずかなレイテンシと引き換えに、精度と制御性を大幅に向上させることができます。これは最もシンプルなワークフローパターンであり、タスクを順序付けられたサブタスクに明確に分割できる場合は常に使用すべきです。", "problem": "1つのプロンプトで同時に複数のことを実行しようとすると、出力の品質が低下し、制御が難しくなります。また、問題が発生した際のデバッグも困難になります。", "context": "タスクが明確で順序付けられた一連のサブタスク（例：アウトライン作成、ドラフト作成、編集など）に分解でき、各ステップが前のステップの結果を利用できる場合に、プロンプトチェーニングを使用します。", "solution": [ "タスクを個別のステップに分割し、ステップごとに1回のLLM呼び出しを実行して、各出力を次のステップに渡します。オプションとして、ステップ間にプログラムによるチェック（ゲート）を追加し、処理を継続する前に中間結果を検証することもできます。", "各呼び出しの役割が1つに絞られるため、プロンプトがシンプルになり、出力の信頼性が向上します。また、失敗が特定のステップに限定されるため、そのステップを調査して修正することが容易になります。" ], "components": [ "順序付けられたステップ", "ステップごとのプロンプト", "ステップ間のゲート / 検証", "ステップ間で渡される状態（ステート）" ], "benefits": [ "各呼び出しの役割を1つに絞ることで、精度が向上します。", "デバッグが容易になります。失敗が特定のステップに限定されるためです。", "検証ゲートにより、ステップ間のエラーをキャッチできます。" ], "risks": [ "順次呼び出しを行うため、全体のレイテンシが増加します。", "チェックを行わないと、チェーンの下流に進むにつれてエラーが蓄積・増幅する可能性があります。", "ステップ数が多すぎると、コストが増加し、システムが脆弱になります。" ], "whenNot": [ "タスクが十分にシンプルで、1回の呼び出しで済む場合。", "サブタスクが独立している場合（この場合は並列化を行います）。", "事前に実行経路が不明な場合（この場合はエージェントループを使用します）。" ], "examples": [ "アウトラインを生成し、次に各セクションを執筆し、最後にトーンを修正する。", "構造化されたフィールドを抽出し、それらを検証し、最後に要約する。", "ドキュメントを翻訳し、次に翻訳結果を原文と照らし合わせてチェックする。" ], "kpis": [ { "metric": "エンドツーエンドの成功率", "note": "最終的に正しい結果を出力できたチェーンの割合。エラーはステップをまたいで蓄積されます。" }, { "metric": "ステップごとのエラー率", "note": "各リンクにおける失敗率。信頼性95%のステップを5回連結すると、エンドツーエンドの信頼性は約77%になります。" }, { "metric": "総レイテンシと総コスト", "note": "チェーン内のすべての呼び出しの合計。ステップ数が増えるほど、レイテンシとコストの両方が増加します。" }, { "metric": "リカバリ率", "note": "失敗した中間ステップが、暗黙的に伝播されることなく、キャッチされて修正される頻度。" } ], "failureModes": [ "エラーの伝播：チェーンの初期段階での誤りが、下流のすべてのステップを損なう。", "チェーンが長くなるにつれて、レイテンシとコストが累積する。", "あるステップの出力フォーマットが、次のステップで想定されている入力フォーマットと一致しない場合に、連携が破綻しやすい。", "ステップ間でコンテキストが失われ、後続のリンクが以前に設定された制約を忘れてしまう。" ], "lessons": [ "エラーが伝播する前にキャッチできるよう、ステップ間で検証またはゲートチェックを行ってください。", "タスクが許す限りチェーンを短く保ってください。ステップが1つ増えるごとに出力失敗の確率が倍増します。", "連携が暗黙的に破綻しないよう、各ステップの出力仕様（コントラクト）を固定してください。", "真に順次実行が必要な作業にのみチェーニングを使用してください。独立したステップは代わりに並列化します。" ], "faqs": [ { "q": "プロンプトチェーニングはエージェントとどう違うのですか？", "a": "プロンプトチェーニングは、事前に定義された固定の順序に従います。一方、エージェントは自身のステップを動的に決定します。実行経路が事前に分かっている場合は、チェーニングを優先してください。" }, { "q": "ステップ間にゲートを追加すべきなのはどのような場合ですか？", "a": "処理を進める前に中間結果が特定の条件を満たす必要がある場合は常に、ゲートを追加すべきです。これにより、エラーがチェーンの下流に伝播するのを防ぐことができます。" }, { "q": "チェーニングによってコストは増加しますか？", "a": "はい、わずかに増加します。呼び出し回数が増えることは、トークン数とレイテンシの増加を意味します。しかし、複数のパートからなるタスクにおいては、通常、信頼性の向上がそのコストを上回ります。" } ] }, "zh": { "name": "提示词链式调用", "summary": "提示词链式调用（Prompt Chaining）将任务分解为固定的 LLM 调用序列，其中每一步都基于上一步的输出进行处理。它以少许延迟为代价换取极高的准确性和控制力，是最简单的流式工作流模式：只要任务可以清晰地拆分为有序的子任务，即可使用该模式。", "problem": "要求单个提示词同时完成多项任务会导致输出质量下降、难以控制，且在出错时难以调试。", "context": "当任务可以分解为清晰、有序的子任务序列（例如：先列大纲，再起草，最后编辑），且每一步都受益于上一步的结果时，请使用提示词链式调用。", "solution": [ "将任务拆分为离散的步骤，每步运行一次 LLM 调用，并将每次的输出传递给下一步。可以选择在步骤之间添加程序化检查（网关），以便在继续之前验证中间结果。", "由于每次调用都专注于一项工作，提示词会更简单，输出更可靠，且失败会被定位到特定步骤，便于检查和修复。" ], "components": [ "有序步骤", "每步提示词", "步骤间网关/验证", "步骤间传递的状态" ], "benefits": [ "通过让每次调用专注于一项工作来提高准确性。", "更易于调试——失败会被定位到具体步骤。", "验证网关可以捕获步骤之间的错误。" ], "risks": [ "顺序调用会导致更高的总延迟。", "如果不进行检查，错误可能会在链条中向下累积。", "步骤过多会增加成本和脆弱性。" ], "whenNot": [ "当任务足够简单，单次调用即可完成时。", "当子任务相互独立时——请改用并行化。", "当执行路径无法预先确定时——请使用智能体循环（agent loop）。" ], "examples": [ "生成大纲，然后撰写每个章节，最后修改语气。", "提取结构化字段，然后对其进行验证，最后进行总结。", "翻译文档，然后对照原文检查译文。" ], "kpis": [ { "metric": "端到端成功率", "note": "产生正确最终结果的链条比例；错误会在各个步骤之间累积。" }, { "metric": "单步错误率", "note": "每个环节的失败率——一个可靠性为 95% 的步骤在链式调用五次后，端到端可靠性约为 77%。" }, { "metric": "总延迟与成本", "note": "链条中每次调用的总和；步骤越多，两者的消耗就越大。" }, { "metric": "恢复率", "note": "失败的中间步骤被捕获并纠正（而不是默默向下传播）的频率。" } ], "failureModes": [ "错误传播：链条前期的错误会破坏所有下游步骤。", "随着链条变长，延迟和成本不断累积。", "当某一步的输出格式与下一步预期的输入不匹配时，会导致脆弱的交接。", "跨步骤丢失上下文，导致后面的环节忘记了前面设置的约束。" ], "lessons": [ "在步骤之间进行验证或网关检查，以便在错误传播之前将其捕获。", "在任务允许的范围内尽可能缩短链条；每增加一个步骤都会使失败概率成倍增加。", "固定每一步的输出契约，以免交接过程默默中断。", "将链式调用用于真正的顺序工作；对于独立的步骤，请改用并行化。" ], "faqs": [ { "q": "提示词链式调用与智能体（agent）有什么区别？", "a": "提示词链式调用遵循固定的、预定义的顺序。而智能体则动态决定自己的步骤。当执行路径预先已知时，优先选择链式调用。" }, { "q": "我应该在什么时候在步骤之间添加网关？", "a": "每当中间结果在继续之前必须满足某个条件时——这可以防止错误在链条中向下传播。" }, { "q": "链式调用会增加成本吗？", "a": "是的，会略微增加——更多的调用意味着更多的 Token 和延迟——但对于多步骤任务，可靠性的提升通常利大于弊。" } ] } } }, { "slug": "recovery-strategy", "category": "reliability", "updated": "2026-08-25", "version": "1.1", "url": "https://santismm.com/en/patterns/recovery-strategy", "api": "https://santismm.com/api/patterns/recovery-strategy", "canonical_url": "https://santismm.com/en/patterns/recovery-strategy", "api_url": "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", "correlated-run-trace" ], "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." } ] }, "fr": { "name": "Stratégie de récupération", "summary": "Donnez à l'agent un plan explicite en cas de panne. Détectez les défaillances en validant les sorties et en interceptant les erreurs des outils ; puis réessayez avec ajustement, basculez vers un chemin alternatif, annulez les actions partielles ou escaladez. Limitez les tentatives pour éviter les boucles infinies et les coûts, rendez les actions idempotentes et distinguez les défaillances transitoires des défaillances permanentes. L'objectif est une dégradation progressive plutôt que des plantages ou des résultats silencieusement erronés.", "problem": "Les agents échouent constamment : les outils expirent, les API renvoient des erreurs, les modèles émettent des sorties malformées, les plans se retrouvent dans des impasses et les flux de travail multi-étapes laissent derrière eux des effets secondaires partiels. Sans chemin de récupération explicite, un agent soit plante à la première erreur, soit — pire encore — continue sur la base de données erronées et produit silencieusement des résultats faux avec assurance. Les boucles de tentative naïves aggravent la situation, pilonnant une dépendance défaillante, consommant des jetons et tournant indéfiniment. Le plus difficile n'est pas d'intercepter une erreur, mais de déterminer de quel type de défaillance il s'agit et quelle réponse est sûre.", "context": "Utilisez ce modèle dans tout agent qui appelle des outils externes, exécute des plans multi-étapes ou effectue des actions importantes où une exécution partielle est possible. Il est particulièrement crucial pour les flux de travail autonomes ou de longue durée qu'aucun humain ne surveille en temps réel, et pour les actions ayant des effets secondaires (paiements, écritures, e-mails) où une tentative aveugle pourrait dupliquer le travail. Il suppose que vous pouvez valider les sorties par rapport à un contrat et qu'au moins certaines opérations peuvent être rendues idempotentes ou compensées. Il est moins pertinent pour les prompts ponctuels, en lecture seule et à faibles enjeux.", "solution": [ "Traisez la récupération comme une boucle de contrôle de premier ordre superposée à l'exécution normale de l'agent. Chaque appel d'outil et chaque sortie de modèle passe par une barrière de validation : interceptez les exceptions et les expirations de délai, et vérifiez les sorties par rapport à un schéma ou un contrat avant de leur faire confiance. En cas d'échec, classifiez-le. Les défaillances transitoires (expirations, limites de débit, 5xx) font l'objet d'une tentative limitée avec un backoff exponentiel et du jitter, idéalement sur une opération idempotente pour qu'une requête dupliquée soit sans danger. Les défaillances permanentes (arguments invalides, erreurs d'authentification, violations de contrat) ignorent les tentatives et passent directement à une alternative : un outil différent, un plan plus simple ou une réponse de secours.\n\nLorsque la progression est importante, sauvegardez l'état (checkpoint) afin que l'agent puisse reprendre à partir de la dernière étape valide plutôt que de redémarrer. Lorsqu'une étape a déjà produit des effets secondaires et ne peut pas continuer, exécutez des actions de compensation pour annuler — annuler la commande, supprimer le brouillon, rembourser le débit. Enveloppez l'ensemble de la boucle dans des budgets stricts : nombre maximal de tentatives, temps d'exécution maximal et plafond de coût, plus un disjoncteur (circuit breaker) qui cesse d'appeler une dépendance qui échoue continuellement. Lorsque toutes les options de récupération sont épuisées, escaladez proprement — remontez la défaillance à un humain ou à un agent superviseur avec suffisamment de contexte pour agir, plutôt que de deviner." ], "components": [ "Barrière de validation", "Classificateur de défaillances", "Tentative limitée avec backoff", "Routeur de secours", "Stockage de checkpoints", "Gestionnaire de compensation" ], "benefits": [ "L'agent produit un résultat partiel ou de secours et un statut clair au lieu de planter ou de renvoyer des données aberrantes avec assurance.", "Les limites strictes de tentatives, de temps et de coût empêchent les boucles de tentative infinies de consommer le budget sur une dépendance défaillante.", "Les actions de compensation et les checkpoints maintiennent la cohérence des systèmes externes et de l'état des tâches lorsqu'un flux de travail s'arrête à mi-parcours.", "En cas d'échec de la récupération, l'agent passe la main avec suffisamment de contexte pour qu'un humain ou un superviseur puisse agir, plutôt que de deviner." ], "risks": [ "Des tentatives agressives contre une dépendance en difficulté augmentent la charge et peuvent transformer une brève anomalie en une panne en cascade.", "Réessayer une action non idempotente peut entraîner une double facturation, un double envoi ou une double écriture si des clés de requête ne sont pas utilisées.", "Des solutions de secours trop zélées peuvent masquer des défaillances systématiques, de sorte qu'un outil en panne semble sain tout en dégradant discrètement chaque résultat.", "La logique d'annulation est souvent incomplète ou échoue elle-même, laissant les systèmes dans un état incohérent difficile à détecter." ], "whenNot": [ "Pour les prompts à faibles enjeux, sans effets secondaires et sans plan multi-étapes, une simple logique de tentative ou d'échec suffit ; un mécanisme complet de récupération est superflu.", "Lorsqu'une défaillance signifie que la tâche est réellement impossible (autorisation manquante, API obsolète), les tentatives et les solutions de secours ne font que perdre du temps — échouez rapidement et escaladez.", "Si un effet secondaire est irréversible et ne peut pas être rendu idempotent, ne lancez pas de tentative automatique ; exigez plutôt une confirmation ou une approbation humaine." ], "examples": [ "L'outil de recherche d'un agent de recherche renvoie une erreur 503 ; l'agent réessaie avec un backoff, réussit à la troisième tentative et continue sans faire planter l'exécution.", "Un agent de code génère du JSON qui échoue à la validation du schéma ; la barrière de validation le rejette et relance le prompt avec l'erreur, au lieu de transmettre des données malformées en aval.", "Un agent de réservation réserve un vol mais l'étape de l'hôtel échoue définitivement ; le gestionnaire de compensation annule la réservation et escalade plutôt que de laisser un voyage à moitié réservé." ], "productionEvidence": { "context": "Déploiement OpenClaw mono-opérateur, local-first, observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des traces de trajectoire de l'agent lui-même.", "scenario": "Les erreurs, les abandons et les expirations de délai pendant les tours autonomes sont absorbés par des tentatives/backoffs et une chaîne de secours de modèles (model-fallback) afin que l'agent continue de fonctionner.", "technology": "retryAsync avec backoff exponentiel et jitter, runWithModelFallback, propagation d'abandon et autoprotection cron contre les boucles de redéclenchement.", "load": "2 942 tours terminaux ; 52 erreurs, 126 abandons, 120 expirations de délai et 31 erreurs de prompt observées.", "results": "Un taux d'erreur terminale de 1,77 % sur 2 942 tours ; les primitives de récupération ont absorbé les défaillances transitoires et le déploiement a maintenu un taux de réussite de session de 98,8 %. Déploiement mono-opérateur local-first." }, "kpis": [ { "metric": "Taux de réussite de la récupération", "note": "Part des défaillances résolues automatiquement par tentative ou secours sans intervention humaine ; une valeur saine est élevée et stable, sans dérive descendante silencieuse." }, { "metric": "Nombre moyen de tentatives par tâche réussie", "note": "Nombre de tentatives nécessaires pour réussir ; surveillez toute augmentation progressive, qui signale une dégradation de dépendance plutôt qu'une véritable récupération." }, { "metric": "Taux de boucle infinie / dépassement de budget", "note": "Fréquence à laquelle les exécutions atteignent les plafonds de tentative, de temps ou de coût ; cela devrait être rare, et les pics signifient que les limites ou la classification doivent être ajustées." }, { "metric": "Complétude de la compensation", "note": "Fraction des flux de travail multi-étapes échoués qui se terminent dans un état cohérent ; l'objectif est une annulation complète sans effets secondaires orphelins." } ], "failureModes": [ "Des limites de tentatives manquantes ou trop élevées permettent à l'agent de réessayer indéfiniment une défaillance permanente, ce qui engendre des coûts sans jamais progresser.", "Traiter une erreur permanente comme transitoire gaspille des tentatives ; traiter une erreur transitoire comme permanente conduit à abandonner trop tôt et déclenche des solutions de secours inutiles.", "Un chemin de secours renvoie une réponse plausible mais erronée sans signaler qu'une récupération a eu lieu, de sorte que les consommateurs en aval font confiance à une mauvaise sortie.", "L'agent échoue après une écriture ou une action externe mais avant l'exécution de la compensation, laissant des enregistrements en double ou orphelins." ], "lessons": [ "La décision de tenter, de basculer ou d'escalader repose sur la distinction entre transitoire et permanent ; investissez dans une classification claire avant d'ajuster les courbes de backoff.", "Les clés d'idempotence transforment une tentative risquée en une tentative sûre ; concevez-les dès le départ plutôt que d'ajouter une déduplication après coup.", "Les limites strictes sur les tentatives, le temps et le coût sont non négociables ; un agent qui en est dépourvu finira par trouver un moyen de s'exécuter indéfiniment.", "Enregistrez chaque tentative, solution de secours et compensation afin qu'une dégradation silencieuse apparaisse sous forme de métrique plutôt que comme un incident surprise." ], "faqs": [ { "q": "En quoi cela diffère-t-il de l'ajout d'un bloc try/except et d'une boucle de tentative ?", "a": "Le bloc try/except gère une seule erreur ; une stratégie de récupération détermine le type de défaillance et choisit entre la tentative, la solution de secours, l'annulation et l'escalade sous des budgets stricts. C'est la logique de contrôle et l'idempotence qui en constituent l'essence, et non la gestion des exceptions." }, { "q": "Combien de tentatives dois-je autoriser ?", "a": "Peu — généralement une petite limite fixe avec un backoff exponentiel et du jitter, plus des plafonds de temps et de coût distincts. Le nombre exact dépend de la dépendance, mais la boucle doit toujours se terminer, et les défaillances permanentes ne doivent pas faire l'objet de tentatives." }, { "q": "Que se passe-t-il si une action ne peut pas être annulée ou rendue idempotente ?", "a": "Ne lancez pas de tentative automatique sur cette action. Créez un checkpoint avant l'étape irréversible et, en cas d'échec, escaladez vers un humain ou un agent superviseur plutôt que de deviner. L'irréversibilité est un signal pour ralentir, pas pour insister davantage." } ] }, "de": { "name": "Recovery-Strategie", "summary": "Geben Sie dem Agenten einen expliziten Plan für den Fall, dass Fehler auftreten. Erkennen Sie Fehler, indem Sie Ausgaben validieren und Tool-Fehler abfangen; führen Sie dann einen erneuten Versuch mit Anpassungen durch, weichen Sie auf einen alternativen Pfad aus, machen Sie Teilaktionen rückgängig oder eskalieren Sie. Begrenzen Sie die Anzahl der Versuche, um unkontrollierte Schleifen und Kosten zu vermeiden, machen Sie Aktionen idempotent und unterscheiden Sie zwischen vorübergehenden und dauerhaften Fehlern. Das Ziel ist ein kontrollierter Funktionsabbau (Graceful Degradation) anstelle von Abstürzen oder unbemerkt fehlerhaften Ergebnissen.", "problem": "Agenten fallen ständig aus: Tools laufen in Timeouts, APIs geben Fehler zurück, Modelle liefern fehlerhafte Ausgaben, Pläne geraten in Sackgassen und mehrstufige Workflows hinterlassen unvollständige Nebeneffekte. Ohne einen expliziten Recovery-Pfad stürzt ein Agent entweder beim ersten Fehler ab oder – was noch schlimmer ist – arbeitet mit fehlerhaften Daten weiter und liefert unbemerkt, aber mit scheinbarer Gewissheit falsche Ergebnisse. Naive Wiederholungsschleifen verschlimmern das Problem, indem sie eine fehlerhafte Abhängigkeit überlasten, Token verbrauchen und endlos laufen. Die Schwierigkeit liegt nicht darin, einen einzelnen Fehler abzufangen, sondern zu entscheiden, um welche Art von Fehler es sich handelt und welche Reaktion sicher ist.", "context": "Verwenden Sie dieses Pattern bei jedem Agenten, der externe Tools aufruft, mehrstufige Pläne ausführt oder folgenschwere Aktionen durchführt, bei denen ein unvollständiger Abschluss möglich ist. Es ist besonders wichtig für langlebige oder autonome Workflows, die von keinem Menschen in Echtzeit überwacht werden, sowie für Aktionen mit Nebeneffekten (Zahlungen, Schreibvorgänge, E-Mails), bei denen ein blinder Wiederholungsversuch zu doppelter Arbeit führen könnte. Es setzt voraus, dass Sie Ausgaben anhand eines Kontrakts validieren können und dass zumindest einige Operationen idempotent gestaltet oder kompensiert werden können. Für einmalige, schreibgeschützte Prompts mit geringem Risiko ist es weniger relevant.", "solution": [ "Behandeln Sie Recovery als erstklassigen Kontrollkreis (Control Loop), der um die normale Ausführung des Agenten gelegt wird. Jeder Tool-Aufruf und jede Modellausgabe durchläuft ein Validierungs-Gate: Fangen Sie Exceptions und Timeouts ab und prüfen Sie Ausgaben anhand eines Schemas oder Kontrakts, bevor Sie ihnen vertrauen. Klassifizieren Sie den Fehler im Fall eines Fehlschlags. Vorübergehende Fehler (Timeouts, Ratenbegrenzungen, 5xx) erhalten eine begrenzte Anzahl von Wiederholungsversuchen mit exponentiellem Backoff und Jitter, idealerweise bezogen auf eine idempotente Operation, sodass eine doppelte Anfrage harmlos ist. Dauerhafte Fehler (ungültige Argumente, Authentifizierungsfehler, Kontraktverletzungen) überspringen Wiederholungsversuche und führen direkt zu einer Alternative: einem anderen Tool, einem einfacheren Plan oder einer Fallback-Antwort.\n\nWenn der Fortschritt entscheidend ist, speichern Sie den Zustand über Checkpoints, damit der Agent beim letzten erfolgreichen Schritt fortfahren kann, anstatt neu zu starten. Wenn ein Schritt bereits Nebeneffekte erzeugt hat und nicht fortgesetzt werden kann, führen Sie kompensierende Aktionen aus, um den Zustand zurückzusetzen – stornieren Sie die Bestellung, löschen Sie den Entwurf, buchen Sie die Gebühr zurück. Schließen Sie die gesamte Schleife in harte Budgets ein: maximale Versuche, maximale Echtzeit (Wall-Clock Time) und eine Kostenobergrenze, ergänzt durch einen Circuit Breaker, der Aufrufe an eine dauerhaft fehlerhafte Abhängigkeit stoppt. Wenn alle Recovery-Optionen ausgeschöpft sind, eskalieren Sie sauber – leiten Sie den Fehler an einen Menschen oder einen überwachenden Agenten mit ausreichend Kontext weiter, anstatt Vermutungen anzustellen." ], "components": [ "Validierungs-Gate", "Fehler-Klassifizierer", "Begrenzter Wiederholungsversuch mit Backoff", "Fallback-Router", "Checkpoint-Speicher", "Kompensations-Handler" ], "benefits": [ "Der Agent liefert ein unvollständiges Ergebnis oder ein Fallback-Ergebnis sowie einen klaren Status, anstatt abzustürzen oder mit scheinbarer Gewissheit unbrauchbare Daten zurückzugeben.", "Harte Limits für Versuche, Zeit und Kosten verhindern, dass unkontrollierte Wiederholungsschleifen Budget für eine fehlerhafte Abhängigkeit verbrauchen.", "Kompensierende Aktionen und Checkpoints halten externe Systeme und den Aufgabenstatus konsistent, wenn ein Workflow mittendrin abbricht.", "Wenn die Recovery fehlschlägt, übergibt der Agent die Aufgabe mit ausreichend Kontext, damit ein Mensch oder ein Supervisor handeln kann, anstatt Vermutungen anzustellen." ], "risks": [ "Aggressive Wiederholungsversuche bei einer überlasteten Abhängigkeit erhöhen die Last und können eine kurze Störung in einen kaskadierenden Ausfall verwandeln.", "Der Wiederholungsversuch einer nicht-idempotenten Aktion kann zu doppelten Abbuchungen, doppeltem Senden oder doppelten Schreibvorgängen führen, wenn keine Request-Keys verwendet werden.", "Zu voreilige Fallbacks können systematische Fehler verbergen, sodass ein defektes Tool fehlerfrei erscheint, während es im Hintergrund jedes Ergebnis verschlechtert.", "Rollback-Logik ist oft unvollständig oder schlägt selbst fehl, was Systeme in einem inkonsistenten Zustand hinterlässt, der schwer zu erkennen ist." ], "whenNot": [ "Bei risikoarmen Prompts ohne Nebeneffekte und ohne mehrstufigen Plan reicht ein einfaches Wiederholen-oder-Abbrechen aus; eine vollständige Recovery-Infrastruktur bedeutet hier nur unnötigen Overhead.", "Wenn ein Fehler bedeutet, dass die Aufgabe tatsächlich unmöglich ist (fehlende Berechtigung, veraltete API), verschwenden Wiederholungsversuche und Fallbacks nur Zeit – brechen Sie schnell ab (Fail-Fast) und eskalieren Sie.", "Wenn ein Nebeneffekt unumkehrbar ist und nicht idempotent gemacht werden kann, führen Sie keine automatischen Wiederholungsversuche durch; fordern Sie stattdessen eine Bestätigung oder eine menschliche Freigabe an." ], "examples": [ "Das Such-Tool eines Recherche-Agenten gibt einen 503-Fehler zurück; der Agent versucht es mit Backoff erneut, ist beim dritten Versuch erfolgreich und fährt fort, ohne den Durchlauf abzubrechen.", "Ein Code-Agent generiert JSON, das die Schema-Validierung nicht besteht; das Validierungs-Gate lehnt es ab und fordert das Modell unter Angabe des Fehlers erneut auf (Re-Prompt), anstatt fehlerhafte Daten an nachgelagerte Systeme weiterzugeben.", "Ein Buchungs-Agent reserviert einen Flug, aber der Schritt für das Hotel schlägt dauerhaft fehl; der Kompensations-Handler storniert die Reservierung und eskaliert, anstatt eine halb gebuchte Reise zu hinterlassen." ], "productionEvidence": { "context": "Lokale OpenClaw-Bereitstellung (Single-Operator), beobachtet über 57 Tage (161 Sitzungen / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Fehler, Abbrüche und Timeouts während autonomer Turns werden durch Retry/Backoff und eine Modell-Fallback-Kette abgefangen, sodass der Agent weiterläuft.", "technology": "retryAsync mit exponentiellem Backoff und Jitter, runWithModelFallback, Abort-Propagierung und Cron-Selbstschutz gegen wiederholte Auslöseschleifen.", "load": "2.942 Terminal-Turns; 52 Fehler, 126 Abbrüche, 120 Timeouts und 31 Prompt-Fehler beobachtet.", "results": "Eine Terminal-Fehlerrate von 1,77 % bei 2.942 Turns; Recovery-Primitive fingen vorübergehende Fehler ab und die Bereitstellung hielt eine Sitzungserfolgsquote von 98,8 %. Lokale Bereitstellung (Single-Operator)." }, "kpis": [ { "metric": "Recovery-Erfolgsquote", "note": "Anteil der Fehler, die automatisch durch Wiederholungsversuche oder Fallbacks ohne menschliche Hilfe behoben wurden; ein gesunder Wert ist hoch und stabil, ohne unbemerkt abfallenden Trend." }, { "metric": "Mittlere Anzahl der Versuche pro erfolgreicher Aufgabe", "note": "Wie viele Versuche für einen Erfolg nötig sind; achten Sie auf einen schleichenden Anstieg, der eher auf eine sich verschlechternde Abhängigkeit als auf eine echte Recovery hindeutet." }, { "metric": "Quote unbegrenzter Schleifen / Budgetüberschreitungen", "note": "Wie oft Durchläufe an Wiederholungs-, Zeit- oder Kostenobergrenzen stoßen; dies sollte selten vorkommen, und Spitzen deuten darauf hin, dass Limits oder die Klassifizierung angepasst werden müssen." }, { "metric": "Vollständigkeit der Kompensation", "note": "Anteil fehlgeschlagener mehrstufiger Workflows, die in einem konsistenten Zustand enden; das Ziel ist ein vollständiges Rollback ohne verwaiste Nebeneffekte." } ], "failureModes": [ "Fehlende oder zu hohe Obergrenzen für Versuche führen dazu, dass der Agent einen dauerhaften Fehler endlos wiederholt, was Kosten verursacht und keinen Fortschritt bringt.", "Die Behandlung eines dauerhaften Fehlers als vorübergehend verschwendet Wiederholungsversuche; die Behandlung eines vorübergehenden Fehlers als dauerhaft führt zu einem zu frühen Aufgeben und löst unnötige Fallbacks aus.", "Ein Fallback-Pfad gibt eine plausible, aber falsche Antwort zurück, ohne zu signalisieren, dass eine Recovery stattgefunden hat, sodass nachgelagerte Konsumenten fehlerhaften Ausgaben vertrauen.", "Der Agent fällt nach einem Schreibvorgang oder einer externen Aktion aus, aber bevor die Kompensation ausgeführt wird, was zu doppelten oder verwaisten Datensätzen führt." ], "lessons": [ "Die Entscheidung zwischen Wiederholungsversuch, Fallback und Eskalation hängt von der Unterscheidung zwischen vorübergehenden und dauerhaften Fehlern ab; investieren Sie in eine klare Klassifizierung, bevor Sie Backoff-Kurven optimieren.", "Idempotenz-Keys machen aus einem riskanten Wiederholungsversuch einen sicheren; planen Sie dies von Anfang an ein, anstatt später eine Deduplizierung dranzuflanschen.", "Harte Obergrenzen für Versuche, Zeit und Kosten sind nicht verhandelbar; ein Agent ohne diese Limits wird irgendwann einen Weg finden, endlos zu laufen.", "Protokollieren Sie jeden Wiederholungsversuch, jedes Fallback und jede Kompensation, damit eine unbemerkte Verschlechterung als Metrik sichtbar wird und nicht als überraschender Vorfall." ], "faqs": [ { "q": "Wie unterscheidet sich dies vom einfachen Hinzufügen von try/except und einer Wiederholungsschleife?", "a": "Try/except behandelt einen einzelnen Fehler; eine Recovery-Strategie entscheidet, um welche Art von Fehler es sich handelt, und wählt unter harten Budgets zwischen Wiederholungsversuch, Fallback, Rollback und Eskalation. Der Kern liegt in der Kontrolllogik und der Idempotenz, nicht in der Ausnahmebehandlung." }, { "q": "Wie viele Wiederholungsversuche sollte ich zulassen?", "a": "Wenige – typischerweise eine niedrige, feste Obergrenze mit exponentiellem Backoff und Jitter, plus separate Zeit- und Kostenobergrenzen. Die genaue Anzahl hängt von der Abhängigkeit ab, aber die Schleife muss immer enden, und dauerhafte Fehler sollten überhaupt nicht wiederholt werden." }, { "q": "Was passiert, wenn eine Aktion nicht rückgängig gemacht oder idempotent gestaltet werden kann?", "a": "Führen Sie darüber hinweg keine automatischen Wiederholungsversuche aus. Setzen Sie vor dem unumkehrbaren Schritt einen Checkpoint und eskalieren Sie bei einem Fehler an einen Menschen oder einen überwachenden Agenten, anstatt Vermutungen anzustellen. Unumkehrbarkeit ist ein Signal, langsamer vorzugehen, nicht, es noch intensiver zu versuchen." } ] }, "ja": { "name": "リカバリ戦略", "summary": "エージェントに対して、問題が発生した際の明示的な計画を提供します。出力の検証やツールのエラーのキャッチによって失敗を検出し、調整を伴う再試行、代替パスへのフォールバック、部分的なアクションのロールバック、またはエスカレーションを行います。無限ループやコストの急増を防ぐために再試行回数を制限し、アクションを冪等（べきとう）にし、一時的な失敗と永続的な失敗を区別します。目標は、クラッシュやサイレントな誤り（誤った結果をそのまま出力すること）を避け、段階的に機能を縮小（グレースフルデグラデーション）させることです。", "problem": "エージェントは常に失敗に直面します。ツールのタイムアウト、APIのエラー、モデルによる不正な形式の出力、計画の行き詰まり、そして複数ステップのワークフローによる部分的な副作用の残存などです。明示的なリカバリパスがなければ、エージェントは最初のエラーでクラッシュするか、さらに悪いことには、不正なデータに基づいて処理を強行し、自信ありげに誤った結果をサイレントに出力してしまいます。単純な再試行ループは状況を悪化させ、失敗している依存先に負荷をかけ続け、トークンを浪費し、無限に回り続けます。難しいのは、単一のエラーをキャッチすることではなく、それがどのような種類の失敗であるかを判断し、どのアクションをとるのが安全かを決定することです。", "context": "このパターンは、外部ツールの呼び出し、複数ステップの計画の実行、または部分的な完了が発生し得る重要なアクションを実行するすべてのエージェントで使用します。これは、人間がリアルタイムで監視しない長期実行型または自律型のワークフローや、盲目的な再試行によって処理が重複する可能性がある副作用を伴うアクション（支払い、書き込み、メール送信など）において最も重要です。このパターンは、何らかの規約（コントラクト）に照らして出力を検証できること、および少なくとも一部の操作を冪等にできるか、または補償トランザクションを実行できることを前提としています。1回限りの読み取り専用で、リスクの低いプロンプトにはあまり適していません。", "solution": [ "リカバリを、エージェントの通常の実行を囲むレイヤーとして、第一級の制御ループとして扱います。すべてのツール呼び出しとモデル出力は検証ゲートを通過します。例外やタイムアウトをキャッチし、出力を信頼する前にスキーマや規約（コントラクト）に照らしてチェックします。失敗した場合は、それを分類します。一時的な失敗（タイムアウト、レート制限、5xxエラーなど）に対しては、指数バックオフとジッターを伴う制限付きの再試行を行います。これは、重複リクエストが無害になるよう、理想的には冪等な操作に対して行います。永続的な失敗（無効な引数、認証エラー、規約違反など）は、再試行をスキップして、別のツール、よりシンプルな計画、またはフォールバック回答などの代替手段に直接移行します。\\n\\n進捗が重要な場合は、状態のチェックポイントを作成し、エージェントが最初からやり直すのではなく、最後に正常だったステップから再開できるようにします。あるステップですでに副作用が発生しており、それ以上進められない場合は、補償アクションを実行してロールバックします（注文のキャンセル、下書きの削除、課金の取り消しなど）。ループ全体を、最大試行回数、最大実時間、コスト上限などの厳格な予算（バジェット）で囲み、失敗し続ける依存先への呼び出しを停止するサーキットブレーカーも導入します。すべてのリカバリ手段が尽きた場合は、推測で動くのではなく、対応に必要な十分なコンテキストとともに、人間または監視エージェントに失敗を明確にエスカレーションします。" ], "components": [ "検証ゲート", "失敗分類器", "バックオフを伴う制限付き再試行", "フォールバックルーター", "チェックポイントストア", "補償ハンドラー" ], "benefits": [ "エージェントは、クラッシュしたり自信ありげにゴミデータを返したりする代わりに、部分的な結果やフォールバック結果、および明確なステータスを出力します。", "試行回数、時間、コストに対する厳格な制限により、制御不能な再試行ループが失敗している依存先に対して予算を浪費するのを防ぎます。", "補償アクションとチェックポイントにより、ワークフローが途中で停止した場合でも、外部システムとタスクの状態の一貫性が維持されます。", "リカバリに失敗した場合、エージェントは推測で動くのではなく、人間や監視者が対応するために十分なコンテキストを提供して引き継ぎます。" ], "risks": [ "負荷がかかっている依存先に対する過剰な再試行は負荷を増大させ、一時的な不具合を連鎖的なシステム障害へと発展させる可能性があります。", "リクエストキーを使用しない場合、冪等ではないアクションを再試行すると、二重課金、二重送信、または二重書き込みが発生する可能性があります。", "性急すぎるフォールバックはシステム的な障害を隠蔽してしまうため、壊れたツールが正常に動作しているように見えながら、裏ですべての結果の品質を低下させる原因になります。", "ロールバックロジックは不完全であることが多く、それ自体が失敗することもあるため、検出が困難な不整合な状態にシステムが取り残される可能性があります。" ], "whenNot": [ "副作用がなく、複数ステップの計画もない低リスクのプロンプトの場合、単純な「再試行または失敗」で十分であり、完全なリカバリ機構はオーバーヘッドになります。", "失敗の原因がタスクの実行が本質的に不可能であること（権限不足、非推奨のAPIなど）である場合、再試行やフォールバックは時間の無駄です。速やかに失敗（フェイルファスト）させ、エスカレーションしてください。", "副作用が不可逆であり、冪等にできない場合は、それをまたぐ自動再試行は行わないでください。代わりに、確認や人間の承認を求めるようにします。" ], "examples": [ "調査エージェントの検索ツールが503エラーを返した際、エージェントはバックオフを伴う再試行を行い、3回目の試行で成功し、実行をクラッシュさせることなく処理を継続します。", "コード生成エージェントがスキーマ検証に失敗するJSONを生成した際、検証ゲートはそれを拒否し、不正な形式のデータを後続の処理に渡す代わりに、エラー内容を含めて再プロンプトを実行します。", "予約エージェントがフライトを予約したものの、ホテルの予約ステップで永続的な失敗が発生した際、補償ハンドラーは中途半端な予約状態のまま放置するのではなく、フライトの予約をキャンセルしてエスカレーションします。" ], "productionEvidence": { "context": "57日間にわたり観察されたシングルオペレーター、ローカルファーストのOpenClawデプロイメント（161セッション / 2,776ターン）。エージェント自身のトラジェクトリトレースから集計。", "scenario": "自律的なターンにおけるエラー、中断、タイムアウトは、再試行/バックオフおよびモデルフォールバックチェーンによって吸収され、エージェントは実行を継続します。", "technology": "指数バックオフとジッターを伴う retryAsync、runWithModelFallback、中断（abort）の伝播、および再実行ループに対するcron自己保護。", "load": "2,942回のターミナルターン。52件のエラー、126件の中断、120件のタイムアウト、31件のプロンプトエラーを観測。", "results": "2,942ターン全体で1.77%のターミナルエラー率。リカバリプリミティブが一時的な失敗を吸収し、デプロイメントは98.8%のセッション成功率を維持しました。シングルオペレーター、ローカルファーストのデプロイメント。" }, "kpis": [ { "metric": "リカバリ成功率", "note": "人間の介入なしに、再試行またはフォールバックによって自動的に解決された失敗の割合。健全な状態では、この値は高く安定しており、気づかないうちに低下することはありません。" }, { "metric": "成功タスクあたりの平均試行回数", "note": "成功するまでに必要な試行回数。この値の増加に注意してください。増加している場合は、真のリカバリではなく、依存先の品質低下を示唆しています。" }, { "metric": "無限ループ/予算超過率", "note": "実行が再試行、時間、またはコストの上限に達する頻度。これは稀であるべきであり、急増している場合は制限値や分類の調整が必要です。" }, { "metric": "補償完了率", "note": "失敗した複数ステップのワークフローのうち、一貫した状態で終了した割合。目標は、孤立した副作用を残さない完全なロールバックです。" } ], "failureModes": [ "試行回数の上限がない、または高すぎる場合、エージェントは永続的な失敗を無限に再試行し続け、コストを浪費して一向に進捗が得られなくなります。", "永続的なエラーを一時的なものとして扱うと再試行が無駄になり、一時的なエラーを永続的なものとして扱うと、早期に諦めすぎて不要なフォールバックを誘発します。", "フォールバックパスが、リカバリが発生したというシグナルなしに、もっともらしいが誤った回答を返すと、後続のコンシューマーがその不正な出力を信頼してしまいます。", "書き込みや外部アクションの後、補償処理が実行される前にエージェントが失敗し、重複したレコードや宙に浮いたレコードが残ってしまいます。" ], "lessons": [ "再試行、フォールバック、エスカレーションの決定は、一時的なものか永続的なものかによって決まります。バックオフ曲線を調整する前に、明確な分類に投資してください。", "冪等性キーは、リスクのある再試行を安全なものに変えます。後から重複排除を付け足すのではなく、最初からそれを考慮して設計してください。", "試行回数、時間、コストに対する厳格な上限設定は必須です。これらがないエージェントは、最終的に無限に実行され続ける方法を見つけ出してしまいます。", "すべての再試行、フォールバック、補償処理をログに記録し、サイレントな品質低下が突然のインシデントではなく、メトリクスとして表面化するようにします。" ], "faqs": [ { "q": "単に try/except と再試行ループを追加することと、何が違うのですか？", "a": "Try/except は単一のエラーを処理します。一方、リカバリ戦略は、失敗の種類を判断し、厳格な予算制限のもとで再試行、フォールバック、ロールバック、エスカレーションの中から選択します。本質は例外処理ではなく、制御ロジックと冪等性にあります。" }, { "q": "再試行は何回まで許可すべきですか？", "a": "少数です。通常は、指数バックオフとジッターを伴う小さな固定上限を設定し、それとは別に時間とコストの上限を設けます。正確な回数は依存先によって異なりますが、ループは必ず終了する必要があり、永続的な失敗に対しては一切再試行すべきではありません。" }, { "q": "アクションを取り消すことも、冪等にすることもできない場合はどうすればよいですか？", "a": "そのアクションをまたぐ自動再試行は行わないでください。不可逆なステップの前にチェックポイントを設定し、失敗した場合は推測で動くのではなく、人間または監視エージェントにエスカレーションします。不可逆性とは、再試行を強化するのではなく、処理を慎重に進めるべきというシグナルです。" } ] }, "zh": { "name": "恢复策略", "summary": "为智能体提供明确的应对故障的计划。通过验证输出和捕获工具错误来检测故障；然后通过调整进行重试、回退到备用路径、回滚部分操作或进行升级。限制重试次数以避免失控循环和成本超支，使操作具备幂等性，并区分瞬态故障与永久故障。其目标是实现优雅降级，而不是崩溃或产生隐蔽的错误结果。", "problem": "智能体经常发生故障：工具超时、API 返回错误、模型输出格式错误、计划陷入死胡同，以及多步骤工作流留下部分副作用。如果没有明确的恢复路径，智能体要么在遇到第一个错误时崩溃，要么（更糟糕的是）继续使用错误的数据，并默默地产生看似笃定实则错误的输出。幼稚的重试循环会让情况变得更糟，不断冲击发生故障的依赖项、消耗 Token 并陷入无限循环。难点不在于捕获单个错误，而在于判断故障的类型以及采取何种应对措施才是安全的。", "context": "在任何调用外部工具、运行多步骤计划或执行可能部分完成的重要操作的智能体中，都可以使用此模式。它对于无人实时监控的长期运行或自主工作流，以及具有副作用的操作（支付、写入、发送电子邮件，其中盲目重试可能会导致重复工作）最为重要。它假设您可以根据某种契约验证输出，并且至少某些操作可以实现幂等或得到补偿。对于单次、只读、低风险的提示词，该模式的关联性较低。", "solution": [ "将恢复视为围绕智能体正常执行构建的一等控制循环。每次工具调用和模型输出都要通过验证门：捕获异常和超时，并在信任输出之前根据 Schema 或契约对其进行检查。发生故障时，对其进行分类。瞬态故障（超时、速率限制、5xx 错误）将通过指数退避和抖动进行有界重试，最好是针对幂等操作，这样重复请求就是无害的。永久故障（无效参数、身份验证错误、契约违规）则跳过重试，直接转向备用方案：不同的工具、更简单的计划或回退答案。\\n\\n当进度至关重要时，对状态进行检查点记录，以便智能体可以从上一个正常步骤恢复，而不是重新启动。当某个步骤已经产生副作用且无法继续时，运行补偿操作以进行回滚——取消订单、删除草稿、撤销收费。将整个循环封装在硬性预算中：最大尝试次数、最大实际运行时间以及成本上限，外加一个熔断器，用于停止调用持续失败的依赖项。当所有恢复选项都耗尽时，进行干净的升级——将故障呈现给人类或主管智能体，并提供足够的上下文以便其采取行动，而不是凭空猜测。" ], "components": [ "验证门", "故障分类器", "带退避的有界重试", "回退路由", "检查点存储", "补偿处理器" ], "benefits": [ "智能体会产生部分或回退结果以及清晰的状态，而不是崩溃或返回看似笃定实则是垃圾的信息。", "硬性的尝试次数、时间和成本限制可以阻止失控的重试循环在发生故障的依赖项上烧掉预算。", "当工作流中途停止时，补偿操作和检查点可以保持外部系统和任务状态的一致性。", "当恢复失败时，智能体在移交工作时会提供足够的上下文，以便人类或主管采取行动，而不是凭空猜测。" ], "risks": [ "对处于困境的依赖项进行激进的重试会增加负载，并可能将短暂的波动演变成级联故障。", "如果不使用请求 Key，重试非幂等操作可能会导致重复收费、重复发送或重复写入。", "过于急切的回退可能会掩盖系统性故障，使损坏的工具看起来正常，同时却在悄悄降低每个结果的质量。", "回滚逻辑通常不完整，或者其自身也会失败，从而使系统处于难以检测的不一致状态。" ], "whenNot": [ "对于没有副作用且没有多步骤计划的低风险提示词，简单的“重试或失败”就足够了；完整的恢复机制反而是额外开销。", "当故障意味着任务确实无法完成时（例如缺少权限、API 已弃用），重试和回退只会浪费时间——应快速失败并进行升级。", "如果某种副作用是不可逆的，且无法实现幂等，请勿跨越该步骤进行自动重试；相反，应要求确认或人工审批。" ], "examples": [ "研究智能体的搜索工具返回 503 错误；智能体通过退避进行重试，在第三次尝试时成功，并在不导致运行崩溃的情况下继续执行。", "代码智能体生成的 JSON 未通过 Schema 验证；验证门将其拒绝，并带上错误信息重新进行提示，而不是将格式错误的数据传递给下游。", "预订智能体预订了机票，但酒店预订步骤发生永久性失败；补偿处理器会取消机票预订并进行升级，而不是留下一个只预订了一半的行程。" ], "productionEvidence": { "context": "在 57 天内（161 个会话 / 2,776 轮）观察到的单操作员、本地优先的 OpenClaw 部署，数据从智能体自身的轨迹追踪中聚合而来。", "scenario": "自主轮次期间的错误、中止和超时会被重试/退避和模型回退链吸收，从而使智能体保持运行。", "technology": "具有指数退避和抖动的 retryAsync、runWithModelFallback、中止传播以及针对重复触发循环的 cron 自我保护。", "load": "观察到 2,942 个终端轮次；其中包含 52 个错误、126 个中止、120 个超时和 31 个提示词错误。", "results": "在 2,942 轮中，终端错误率为 1.77%；恢复原语吸收了瞬态故障，部署保持了 98.8% 的会话成功率。单操作员本地优先部署。" }, "kpis": [ { "metric": "恢复成功率", "note": "在没有人工帮助的情况下，通过重试或回退自动解决的故障比例；健康的值应当较高且稳定，没有无声的下降趋势。" }, { "metric": "每个成功任务的平均尝试次数", "note": "成功需要尝试多少次；注意观察次数的攀升，这通常预示着依赖项性能下降，而非真正的恢复。" }, { "metric": "无限循环/预算超支率", "note": "运行达到重试、时间或成本上限的频率；这应该是罕见的，出现峰值意味着限制或分类需要调整。" }, { "metric": "补偿完整性", "note": "以一致状态结束的失败多步骤工作流的比例；目标是完全回滚，不留下孤立的副作用。" } ], "failureModes": [ "缺失或过高的尝试次数上限会导致智能体无限期地重试永久性故障，从而烧掉成本且永远无法取得进展。", "将永久性错误视为瞬态错误会浪费重试次数；将瞬态错误视为永久性错误则会过早放弃并触发不必要的回退。", "回退路径返回了一个看似合理但错误的答案，且没有发出已发生恢复的信号，导致下游使用者信任了错误的输出。", "智能体在写入或执行外部操作之后、但在运行补偿之前发生故障，从而留下重复或悬空的记录。" ], "lessons": [ "重试/回退/升级的决策取决于故障是瞬态的还是永久性的；在调整退避曲线之前，应先投入精力进行清晰的分类。", "幂等 Key 可以将高风险的重试转化为安全的重试；应在前期进行设计，而不是在后期才强行加入去重机制。", "对尝试次数、时间和成本的硬性限制是不可妥协的；没有这些限制的智能体最终总会找到一种无限运行下去的方法。", "记录每一次重试、回退和补偿，以便将隐蔽的降级转化为可见的指标，而不是突发的意外事件。" ], "faqs": [ { "q": "这与仅仅添加 try/except 和重试循环有什么区别？", "a": "Try/except 只能处理单个错误；而恢复策略则负责判断故障的类型，并在硬性预算下在重试、回退、回滚和升级之间做出选择。其实质在于控制逻辑和幂等性，而非异常处理本身。" }, { "q": "我应该允许多少次重试？", "a": "很少——通常是一个较小的固定上限，配合指数退避和抖动，外加独立的时间和成本上限。确切的次数取决于依赖项，但循环必须始终能够终止，且根本不应该对永久性故障进行重试。" }, { "q": "如果某个操作无法撤销或无法实现幂等怎么办？", "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", "canonical_url": "https://santismm.com/en/patterns/reflection", "api_url": "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." } ] }, "fr": { "name": "Réflexion", "summary": "La réflexion consiste à faire critiquer par un modèle sa propre sortie, puis à la réviser en utilisant cette critique comme retour d'expérience. C'est un moyen léger, basé sur un seul modèle, de détecter les erreurs et d'améliorer la qualité des tâches de raisonnement, de codage et de rédaction — au coût d'appels supplémentaires.", "definition": "La réflexion est un modèle dans lequel un modèle examine et critique sa propre sortie par rapport à des critères explicites, puis la révise, échangeant une inférence supplémentaire contre une qualité supérieure.", "problem": "Les modèles produisent souvent une première réponse imparfaite qu'ils pourraient améliorer si on les invitait à revoir leur propre travail, mais une seule passe ne leur en donne pas l'occasion.", "context": "Utilisez la réflexion lorsqu'une étape d'auto-examen améliore de manière mesurable la sortie et que vous souhaitez une alternative plus simple à une boucle d'évaluation à deux modèles — ce qui est courant dans les tâches de raisonnement et de codage.", "solution": [ "Après avoir généré une réponse, demandez au même modèle de la critiquer par rapport à l'objectif (et à tout retour d'outil tel que des résultats de tests ou des erreurs), puis de produire une réponse révisée tenant compte de cette critique. Répétez l'opération pour un nombre limité d'itérations.", "La réflexion fonctionne mieux lorsqu'elle s'appuie sur des signaux réels — erreurs d'exécution, résultats de tests, faits récupérés — plutôt que sur une simple auto-évaluation, qui peut être trop confiante." ], "components": [ "Génération initiale", "Étape d'auto-critique", "Signal d'ancrage (erreurs / tests / faits)", "Révision", "Budget d'itérations" ], "benefits": [ "Améliore la qualité avec un seul modèle — pas de second système.", "Efficace lorsqu'elle s'appuie sur les retours d'outils ou de tests.", "Simple à ajouter à un appel existant." ], "risks": [ "L'auto-critique peut être trop confiante ou passer à côté de ses propres erreurs.", "Les appels supplémentaires ajoutent de la latence et des coûts.", "Sans ancrage, les gains sont limités." ], "whenNot": [ "Lorsque vous disposez d'un contrôle externe objectif — utilisez l'évaluateur-optimiseur.", "Lorsqu'un seul passage atteint déjà le niveau requis.", "Lorsque les budgets de latence sont très serrés." ], "examples": [ "Un agent de codage lisant les échecs de tests et corrigeant son propre correctif.", "Une tâche de raisonnement où le modèle vérifie à nouveau ses étapes avant de répondre.", "Un brouillon que le modèle examine pour y déceler des lacunes avant de le finaliser." ], "productionEvidence": { "context": "Tâches où la qualité des résultats importe plus que la latence ou le coût — rédaction, génération de code, analyse — et où les erreurs sont détectables lors de la révision.", "scenario": "Après avoir produit une première réponse, le modèle (ou un critique distinct) l'évalue par rapport à des critères concrets et produit une version révisée ; la boucle est limitée à un ou deux passages.", "technology": "Une chaîne de prompts critique-puis-révision, idéalement soutenue par des signaux externes (tests, outils, évaluateur distinct) pour les tâches à enjeux élevés.", "load": "Chaque passage de réflexion double au moins les appels, il est donc appliqué de manière sélective aux résultats qui justifient ce surcoût.", "results": "Modèle observé : la réflexion améliore la qualité lorsque le modèle peut réellement détecter ses propres erreurs, mais elle peut sur-réviser des réponses correctes et double au moins le coût. Mesurez l'amélioration de la qualité par rapport à un ensemble d'évaluation avant de lui faire confiance, et privilégiez les signaux externes lorsque les enjeux sont élevés." }, "kpis": [ { "metric": "Amélioration de la qualité grâce à la réflexion", "note": "Amélioration mesurée de la qualité des résultats avec l'étape de réflexion par rapport à une exécution sans ; si elle n'est pas mesurable, l'étape ne justifie pas son coût." }, { "metric": "Taux d'auto-correction", "note": "Part des erreurs réelles que le modèle détecte et corrige lors de la révision — distincte des modifications cosmétiques." }, { "metric": "Latence et coût supplémentaires", "note": "La réflexion double au moins les appels ; suivez le surcoût par rapport à la qualité qu'elle apporte." }, { "metric": "Taux de sur-révision", "note": "Fréquence à laquelle la réflexion dégrade une réponse déjà satisfaisante en la remettant en question." } ], "failureModes": [ "Angles morts de l'auto-évaluation : un modèle ne voit souvent pas ses propres erreurs, de sorte que la réflexion passe à côté.", "Sur-révision : le modèle « corrige » une réponse correcte pour en faire une moins bonne.", "Le coût et la latence doublent (ou plus) pour un gain de qualité marginal ou nul.", "Fausse confiance : le modèle affirme que le résultat est désormais correct alors qu'il ne l'est pas." ], "lessons": [ "Mesurez l'amélioration ; la réflexion n'en vaut la peine que lorsqu'elle améliore manifestement la qualité.", "Privilégiez les signaux externes (tests, outils, évaluateur distinct) à la simple auto-critique lorsque les enjeux sont élevés.", "Limitez la réflexion à un ou deux passages — les rendements diminuent rapidement et les coûts s'accumulent.", "Donnez à l'étape de réflexion des critères concrets, et non une consigne vague comme « améliore ceci »." ], "faqs": [ { "q": "Réflexion ou évaluateur-optimiseur ?", "a": "La réflexion utilise un seul modèle pour s'auto-critiquer (plus simple) ; l'évaluateur-optimiseur utilise un évaluateur distinct (plus précis, moins biaisé). Choisissez en fonction de la fiabilité de l'auto-évaluation pour votre tâche." }, { "q": "La réflexion est-elle toujours utile ?", "a": "Elle est surtout utile lorsqu'elle s'appuie sur des retours réels tels que des résultats de tests ou des erreurs. Une simple auto-évaluation peut être trop confiante et apporter peu." }, { "q": "Combien de cycles de réflexion ?", "a": "Limitez-les — souvent un ou deux. Les rendements décroissants et l'augmentation des coûts font que les boucles longues en valent rarement la peine." } ] }, "de": { "name": "Reflection", "summary": "Bei Reflection kritisiert ein Modell seine eigene Ausgabe und überarbeitet sie anschließend, wobei es die Kritik als Feedback nutzt. Es ist eine leichtgewichtige Methode für ein einzelnes Modell, um Fehler zu finden und die Qualität bei Denk-, Codierungs- und Schreibaufgaben zu verbessern – auf Kosten zusätzlicher Aufrufe.", "definition": "Reflection ist ein Pattern, bei dem ein Modell seine eigene Ausgabe anhand expliziter Kriterien überprüft, kritisiert und anschließend überarbeitet, wobei zusätzliche Inferenz für eine höhere Qualität in Kauf genommen wird.", "problem": "Modelle liefern oft eine fehlerhafte erste Antwort, die sie verbessern könnten, wenn sie aufgefordert würden, ihre eigene Arbeit zu überprüfen. Ein einziger Durchlauf gibt ihnen jedoch keine Gelegenheit dazu.", "context": "Verwenden Sie Reflection, wenn ein Selbstüberprüfungsschritt die Ausgabe messbar verbessert und Sie eine einfachere Alternative zu einer Evaluator-Schleife mit zwei Modellen suchen – was bei Denk- und Codierungsaufgaben häufig der Fall ist.", "solution": [ "Fordern Sie dasselbe Modell nach der Generierung einer Antwort auf, diese im Hinblick auf das Ziel (und jegliches Tool-Feedback wie Testergebnisse oder Fehler) zu kritisieren und anschließend eine überarbeitete Antwort auf Basis dieser Kritik zu erstellen. Wiederholen Sie dies für eine begrenzte Anzahl von Iterationen.", "Reflection funktioniert am besten, wenn sie auf realen Signalen basiert – Ausführungsfehlern, Testausgaben, abgerufenen Fakten – und nicht auf reiner Selbsteinschätzung, die zu übermäßigem Vertrauen (Overconfidence) neigen kann." ], "components": [ "Initiale Generierung", "Schritt der Selbstkritik", "Grounding-Signal (Fehler / Tests / Fakten)", "Überarbeitung", "Iterationsbudget" ], "benefits": [ "Verbessert die Qualität mit einem einzigen Modell – kein zweites System erforderlich.", "Effektiv, wenn auf Tool- oder Test-Feedback gestützt.", "Einfach in einen bestehenden Aufruf zu integrieren." ], "risks": [ "Selbstkritik kann zu optimistisch sein oder eigene Fehler übersehen.", "Zusätzliche Aufrufe erhöhen Latenz und Kosten.", "Ohne Grounding sind die Qualitätsgewinne begrenzt." ], "whenNot": [ "Wenn Sie eine objektive externe Prüfung haben – nutzen Sie Evaluator-Optimizer.", "Wenn ein einziger Durchlauf die Anforderungen bereits erfüllt.", "Wenn das Latenzbudget sehr knapp bemessen ist." ], "examples": [ "Ein Coding-Agent, der Testfehler liest und seinen eigenen Patch korrigiert.", "Eine Denkaufgabe (Reasoning), bei der das Modell seine Schritte vor der Antwort nochmals überprüft.", "Ein Entwurf, den das Modell vor der Fertigstellung auf Lücken überprüft." ], "productionEvidence": { "context": "Aufgaben, bei denen die Ausgabequalität wichtiger ist als Latenz oder Kosten – wie Entwurfserstellung, Codegenerierung, Analyse – und bei denen Fehler bei der Überprüfung erkennbar sind.", "scenario": "Nach der Erstellung einer ersten Antwort bewertet das Modell (oder ein separater Kritiker) diese anhand konkreter Kriterien und erstellt eine überarbeitete Version; die Schleife ist auf ein oder zwei Durchläufe begrenzt.", "technology": "Eine Prompt-Kette nach dem Prinzip „Kritik, dann Überarbeitung“, idealerweise gestützt durch externe Signale (Tests, Tools, ein separater Evaluator) für kritische Aufgaben.", "load": "Jeder Reflection-Durchlauf verdoppelt mindestens die Anzahl der Aufrufe, weshalb er gezielt nur auf Ausgaben angewendet wird, die diesen Mehraufwand rechtfertigen.", "results": "Beobachtetes Muster: Reflection steigert die Qualität dort, wo das Modell seine eigenen Fehler tatsächlich erkennen kann, kann jedoch korrekte Antworten übermäßig überarbeiten (Over-Revision) und verdoppelt mindestens die Kosten. Messen Sie die Qualitätssteigerung anhand eines Evaluierungs-Sets, bevor Sie darauf vertrauen, und bevorzugen Sie bei kritischen Aufgaben externe Signale." }, "kpis": [ { "metric": "Qualitätssteigerung durch Reflection", "note": "Gemessene Verbesserung der Ausgabequalität mit dem Reflection-Schritt im Vergleich zu ohne; wenn sie nicht messbar ist, rechtfertigt der Schritt seine Kosten nicht." }, { "metric": "Selbstkorrekturrate", "note": "Anteil echter Fehler, die das Modell bei der Überprüfung erkennt und behebt – im Unterschied zu rein kosmetischen Bearbeitungen." }, { "metric": "Zusätzliche Latenz & Kosten", "note": "Reflection verdoppelt mindestens die Anzahl der Aufrufe; stellen Sie den Mehraufwand der gewonnenen Qualität gegenüber." }, { "metric": "Over-Revision-Rate", "note": "Wie oft Reflection eine bereits gute Antwort durch nachträgliches Zweifeln verschlechtert." } ], "failureModes": [ "Blinde Flecken bei der Selbsteinschätzung: Ein Modell kann seine eigenen Fehler oft nicht erkennen, sodass Reflection diese übersieht.", "Over-Revision: Das Modell „korrigiert“ eine richtige Antwort und verschlechtert sie dadurch.", "Kosten und Latenz verdoppeln sich (oder mehr) bei nur geringem oder gar keinem Qualitätsgewinn.", "Falsches Vertrauen: Das Modell behauptet, die Ausgabe sei nun korrekt, obwohl sie es nicht ist." ], "lessons": [ "Messen Sie die Steigerung; Reflection lohnt sich nur dort, wo sie die Qualität nachweislich verbessert.", "Bevorzugen Sie bei kritischen Aufgaben externe Signale (Tests, Tools, einen separaten Evaluator) gegenüber reiner Selbstkritik.", "Begrenzen Sie Reflection auf ein oder zwei Durchläufe – der Nutzen nimmt schnell ab und die Kosten summieren sich.", "Geben Sie dem Reflection-Schritt konkrete Kriterien an die Hand, statt eines vagen „Verbessere dies“." ], "faqs": [ { "q": "Reflection oder Evaluator-Optimizer?", "a": "Reflection nutzt ein einziges Modell zur Selbstkritik (einfacher); Evaluator-Optimizer nutzt einen separaten Evaluator (präziser, weniger voreingenommen). Wählen Sie danach aus, wie zuverlässig die Selbsteinschätzung für Ihre Aufgabe ist." }, { "q": "Hilft Reflection immer?", "a": "Sie hilft am meisten, wenn sie auf realem Feedback wie Testergebnissen oder Fehlern basiert. Reine Selbsteinschätzung kann zu optimistisch sein und bringt oft wenig Mehrwert." }, { "q": "Wie viele Reflection-Runden sind sinnvoll?", "a": "Halten Sie es in Grenzen – oft ein oder zwei. Aufgrund abnehmender Erträge und steigender Kosten lohnen sich lange Schleifen selten." } ] }, "ja": { "name": "リフレクション", "summary": "リフレクションは、モデルに自身の出力を批判（レビュー）させ、その批判をフィードバックとして使用して修正させる手法です。これは、追加の呼び出しコストと引き換えに、推論、コーディング、執筆タスクにおける誤りを検出し、品質を向上させるための、単一モデルによる軽量なアプローチです。", "definition": "リフレクションは、モデルが明示的な基準に照らして自身の出力をレビューおよび批判し、それを修正するパターンであり、追加の推論コストと引き換えに、より高い品質を得る手法です。", "problem": "モデルは、自身の成果物をレビューするように促されれば改善できるような、欠陥のある初期回答を出力しがちですが、1回のパス（シングルパス）だけではその機会がありません。", "context": "自己レビューのステップによって出力が測定可能なほど改善され、2つのモデルを使用するエバリュエーター（評価者）ループに代わるよりシンプルな方法を求めるときに、リフレクションを使用します。これは推論やコーディングのタスクで一般的です。", "solution": [ "回答を生成した後、同じモデルに対して、目標（およびテスト結果やエラーなどのツールからのフィードバック）に照らし合わせてそれを批判し、その批判を踏まえて修正された回答を生成するようにプロンプトを提示します。これを制限された回数だけ繰り返します。", "リフレクション（自己省察）は、過信につながるおそれのある純粋な自己評価よりも、実行エラー、テスト出力、取得された事実などの実際のシグナルに基づいている場合に最も効果的に機能します。" ], "components": [ "初期生成", "自己批判ステップ", "グラウンディングシグナル（エラー / テスト / 事実）", "修正", "イテレーションバジェット" ], "benefits": [ "単一のモデルで品質を向上させることができます。第2のシステムは不要です。", "ツールやテストのフィードバックに基づいている場合に効果的です。", "既存の呼び出しに簡単に追加できます。" ], "risks": [ "自己批判は過信に陥ったり、自身の誤りを見落としたりすることがあります。", "追加の呼び出しにより、レイテンシーとコストが増加します。", "グラウンディングがない場合、得られる効果は限定的です。" ], "whenNot": [ "客観的な外部チェックがある場合：evaluator-optimizer（評価者-最適化者）パターンを使用してください。", "1回のパスで既に基準を満たしている場合。", "レイテンシーバジェットが非常に厳しい場合。" ], "examples": [ "テストの失敗を読み取り、自身のパッチを修正するコーディングエージェント。", "回答する前にモデルが自身のステップを再確認する推論タスク。", "最終化する前に、モデルがギャップがないかレビューする下書き。" ], "productionEvidence": { "context": "レイテンシーやコストよりも出力品質が重視され（下書き作成、コード生成、分析など）、レビュー時にエラーを検出できるタスク。", "scenario": "最初の回答を生成した後、モデル（または別の批判者）が具体的な基準に照らし合わせてそれを評価し、修正版を生成します。このループは1回または2回のパスに制限されます。", "technology": "批判した後に修正するプロンプトチェーン。重要な業務においては、外部シグナル（テスト、ツール、別の評価者）に裏付けられていることが理想的です。", "load": "リフレクションのパスを実行するたびに呼び出し回数が少なくとも2倍になるため、オーバーヘッドに見合う出力に対してのみ選択的に適用されます。", "results": "観察されたパターン：リフレクションは、モデルが実際に自身の誤りを検出できる場合に品質を向上させますが、正しい回答を過剰に修正してしまう可能性があり、コストは少なくとも2倍になります。信頼する前に評価セットに対して品質の向上を測定し、リスクが高い場合は外部シグナルを優先してください。" }, "kpis": [ { "metric": "リフレクションによる品質向上", "note": "リフレクションステップがある場合とない場合での出力品質の測定された改善度。測定できない場合、そのステップはコストに見合っていません。" }, { "metric": "自己修正率", "note": "モデルがレビュー時に検出し、修正した本質的なエラーの割合（表面的な編集とは区別されます）。" }, { "metric": "追加のレイテンシーとコスト", "note": "リフレクションは呼び出し回数を少なくとも2倍にします。得られる品質に対してオーバーヘッドを追跡してください。" }, { "metric": "過剰修正率", "note": "リフレクションが、すでに優れた回答を疑うことによって、かえって品質を低下させてしまう頻度。" } ], "failureModes": [ "自己評価の盲点：モデルは自身の誤りに気づかないことが多く、リフレクションでそれらを見落とします。", "過剰修正：モデルが正しい回答を「修正」して、より悪いものにしてしまいます。", "品質の向上がわずかであるか、まったくないにもかかわらず、コストとレイテンシーが2倍（またはそれ以上）になります。", "誤った自信：出力が正しくないにもかかわらず、モデルが「正しくなった」と主張します。" ], "lessons": [ "向上度を測定すること。リフレクションは、品質が明らかに向上する場合にのみ価値があります。", "リスクが高い場合は、純粋な自己批判よりも外部シグナル（テスト、ツール、別の評価者）を優先してください。", "リフレクションは1回または2回のパスに制限すること。収益は急速に減少し、コストは累積します。", "リフレクションステップには、曖昧な「これを改善して」ではなく、具体的な基準を与えてください。" ], "faqs": [ { "q": "リフレクションとevaluator-optimizerのどちらを選ぶべきですか？", "a": "リフレクションは1つのモデルを使用して自己批判を行います（よりシンプル）。evaluator-optimizerは別の評価者を使用します（より鋭く、偏りが少ない）。タスクにおける自己評価の信頼性に基づいて選択してください。" }, { "q": "リフレクションは常に役立ちますか？", "a": "テスト結果やエラーなどの実際のフィードバックに基づいている場合に最も役立ちます。純粋な自己評価は過信につながりやすく、ほとんど効果がありません。" }, { "q": "リフレクションは何回行うべきですか？", "a": "回数を制限してください。通常は1回または2回です。収穫逓減とコストの増加により、長いループが価値に見合うことはほとんどありません。" } ] }, "zh": { "name": "反思", "summary": "反思让模型批判自己的输出，然后以该批判作为反馈进行修改。这是一种轻量级的、单模型的方法，用于在推理、编码和写作任务中发现错误并提高质量，代价是需要额外的调用。", "definition": "反思是一种模式，其中模型根据明确的标准审查和批判自己的输出，然后对其进行修改，以额外的推理换取更高的质量。", "problem": "模型往往会产生有缺陷的初步答案，如果提示它们审查自己的工作，它们本可以改进这些答案，但单次生成让它们没有机会这样做。", "context": "当自我审查步骤能够显著改善输出，且您希望使用一种比双模型评估器循环更简单的替代方案时，可以使用反思——这在推理和编码任务中很常见。", "solution": [ "在生成答案后，提示同一个模型根据目标（以及任何工具反馈，如测试结果或错误）对其进行批判，然后根据该批判生成修改后的答案。重复此过程，限制迭代次数。", "当反思基于真实信号（执行错误、测试输出、检索到的事实）而非纯粹的自我评估时，效果最好，因为纯粹的自我评估可能会过度自信。" ], "components": [ "初始生成", "自我批判步骤", "依据信号（错误/测试/事实）", "修改", "迭代预算" ], "benefits": [ "使用单个模型即可提高质量——无需第二个系统。", "当基于工具或测试反馈时非常有效。", "易于添加到现有的调用中。" ], "risks": [ "自我批判可能会过度自信，或者遗漏自身的错误。", "额外的调用会增加延迟和成本。", "如果没有依据，收益会很有限。" ], "whenNot": [ "当您有客观的外部检查时——使用评估器-优化器。", "当单次运行已达到标准时。", "当延迟预算非常紧张时。" ], "examples": [ "一个编码智能体读取测试失败信息并修复自己的补丁。", "一个推理任务，模型在回答前重新检查其步骤。", "模型在定稿前审查草稿是否存在漏洞。" ], "productionEvidence": { "context": "输出质量比延迟或成本更重要的任务（如起草、代码生成、分析），且在审查时可以检测到错误。", "scenario": "在生成第一个答案后，模型（或单独的批判器）根据具体标准对其进行评估，并生成修改后的版本；该循环限制在一次或两次运行内。", "technology": "一个“先批判后修改”的提示词链，对于高风险工作，最好有外部信号（测试、工具、单独的评估器）的支持。", "load": "每次反思运行至少会使调用次数翻倍，因此它被选择性地应用于那些值得付出此开销的输出。", "results": "观察到的模式：在模型确实能够检测到自身错误的情况下，反思可以提升质量，但它可能会对正确的答案进行过度修改，并且至少会使成本翻倍。在信任它之前，先根据评估集衡量质量提升，并在高风险情况下优先选择外部信号。" }, "kpis": [ { "metric": "反思带来的质量提升", "note": "衡量有反思步骤与没有反思步骤时输出质量的改进；如果无法衡量，则该步骤不值得其成本。" }, { "metric": "自我纠正率", "note": "模型在审查中捕获并修复的真实错误的比例——这与表面上的修改不同。" }, { "metric": "增加的延迟与成本", "note": "反思至少会使调用次数翻倍；跟踪该开销与它所换取的质量之间的关系。" }, { "metric": "过度修改率", "note": "反思因自我怀疑而降低原本优秀的答案质量的频率。" } ], "failureModes": [ "自我评估盲区：模型通常无法发现自己的错误，因此反思会遗漏这些错误。", "过度修改：模型将正确的答案“修复”成更差的答案。", "成本和延迟翻倍（或更多），而质量提升微乎其微或根本没有。", "盲目自信：模型在输出并不正确时，却断言其现在是正确的。" ], "lessons": [ "衡量提升幅度；只有在反思能明显提高质量的情况下，它才值得使用。", "在高风险情况下，优先选择外部信号（测试、工具、单独的评估器），而非纯粹的自我批判。", "将反思限制在一次或两次运行内——收益递减很快，且成本会成倍增加。", "为反思步骤提供具体的标准，而不是模糊的“改进这个”。" ], "faqs": [ { "q": "反思还是评估器-优化器？", "a": "反思使用一个模型进行自我批判（更简单）；评估器-优化器使用单独的评估器（更敏锐、偏见更少）。根据自我评估对您的任务有多可靠来做出选择。" }, { "q": "反思总是有效吗？", "a": "当基于测试结果或错误等真实反馈时，它的帮助最大。纯粹的自我评估可能会过度自信，且收效甚微。" }, { "q": "需要多少轮反思？", "a": "保持次数受限——通常是一到两轮。收益递减和成本上升使得长循环很少值得。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/routing", "api_url": "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." } ] }, "fr": { "name": "Routage", "summary": "Le routage classifie une entrée et la dirige vers le gestionnaire, le prompt ou le modèle spécialisé le plus approprié. Il améliore la qualité en permettant d'optimiser chaque chemin pour son cas d'usage, et maîtrise les coûts en envoyant les requêtes simples vers des modèles économiques et les requêtes complexes vers des modèles performants.", "definition": "Le routage est un modèle de conception (pattern) qui classifie chaque requête entrante et l'oriente vers le gestionnaire ou le modèle le plus approprié, de sorte que les entrées simples utilisent des chemins économiques et les entrées complexes des chemins performants.", "problem": "Un prompt ou un modèle unique traitant tous les types d'entrées est moins performant sur chacun d'eux, et utiliser un modèle coûteux pour tout gaspille de l'argent sur les requêtes simples.", "context": "Utilisez le routage lorsque les entrées se répartissent en catégories distinctes qui bénéficient d'un traitement différent — prompts, outils, modèles ou workflows différents — et que ces catégories peuvent être classifiées de manière fiable.", "solution": [ "Un classificateur léger (un appel LLM ou un modèle) étiquette l'entrée, puis un routeur l'envoie au gestionnaire en aval correspondant. Chaque gestionnaire est spécialisé et optimisé pour sa catégorie.", "Le routage permet également une hiérarchisation coût-performance : orientez les requêtes simples vers un modèle rapide et économique, et les requêtes complexes vers un modèle de raisonnement plus puissant, afin de ne payer pour la performance que lorsque c'est nécessaire." ], "components": [ "Classificateur", "Logique de routage", "Gestionnaires spécialisés", "Route de secours / par défaut" ], "benefits": [ "Chaque chemin est optimisé pour son cas d'usage, ce qui améliore la qualité.", "Contrôle des coûts en adaptant les modèles à la difficulté.", "La séparation des préoccupations permet de garder chaque gestionnaire simple." ], "risks": [ "Une mauvaise classification envoie les entrées sur le mauvais chemin.", "Le classificateur ajoute une étape et de la latence.", "La dérive des catégories au fil du temps dégrade la précision du routage." ], "whenNot": [ "Lorsque les entrées sont homogènes — un seul gestionnaire suffit.", "Lorsque les catégories ne peuvent pas être classifiées de manière fiable.", "Lorsque l'étape de classification ajoutée ne vaut pas le gain obtenu." ], "examples": [ "Routage des tickets de support vers des gestionnaires de facturation, techniques ou commerciaux.", "Envoi de questions simples à un petit modèle et de questions complexes à un modèle de raisonnement.", "Orientation de différents types de documents vers des extracteurs spécifiques au type." ], "productionEvidence": { "context": "Déploiement OpenClaw mono-opérateur, local-first, observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des traces de trajectoire de l'agent.", "scenario": "Les messages des canaux entrants et les réveils autonomes sont routés vers un agent via des points d'entrée distincts, les liaisons canal/pair/rôle sélectionnant la session.", "technology": "Liaison + registre de routes (resolveAgentRoute), clés de session par canal et cache de routes résolues.", "load": "3 canaux (Telegram, chat web, WhatsApp) et 4 types de déclencheurs (utilisateur, heartbeat, cron, mémoire).", "results": "Le routage a fonctionné sur les trois canaux et les quatre types de déclencheurs, sans qu'aucun mauvais routage ne se traduise par un échec (98,8 % de réussite globale des sessions). Déploiement mono-opérateur local-first — une référence fonctionnelle, pas un benchmark d'échelle." }, "kpis": [ { "metric": "Précision du routage", "note": "Part des entrées envoyées au bon gestionnaire/modèle ; la métrique unique qui définit la valeur du modèle de conception." }, { "metric": "Économies de coûts par rapport au meilleur modèle systématique", "note": "Argent économisé en routant les entrées simples vers des modèles moins chers au lieu d'utiliser le meilleur modèle pour tout." }, { "metric": "Coût d'un mauvais routage", "note": "Les dommages en aval des mauvaises routes — un mauvais routage peut coûter bien plus cher que les économies recherchées." }, { "metric": "Surcoût de latence du routeur", "note": "Temps que la décision de routage elle-même ajoute avant que le travail réel ne commence." } ], "failureModes": [ "Mauvaise classification : le routeur envoie une entrée vers le mauvais modèle ou chemin, dégradant la réponse.", "Entrées ambiguës qui ne correspondent clairement à aucune route et se retrouvent forcées dans une route inadaptée.", "Le routeur devient un goulot d'étranglement ou un point de défaillance unique pour chaque requête.", "Dérive : la distribution des entrées évolue au fil du temps et les catégories du routeur deviennent obsolètes." ], "lessons": [ "Optimisez pour le coût d'une erreur d'aiguillage, pas seulement pour la précision du routage — certains mauvais aiguillages coûtent beaucoup plus cher que d'autres.", "Ajoutez une route par défaut / de secours pour les entrées qui ne correspondent bien à rien.", "Gardez le routeur économique et rapide ; s'il coûte aussi cher que le travail lui-même, cela va à l'encontre du but recherché.", "Surveillez la dérive des entrées et réajustez les routes à mesure que la distribution change." ], "faqs": [ { "q": "Qu'est-ce qui classifie l'entrée ?", "a": "Généralement un appel LLM léger ou un modèle de classification dédié ; pour les cas évidents, des règles déterministes peuvent effectuer le routage sans modèle." }, { "q": "Comment le routage permet-il de réduire les coûts ?", "a": "Par la hiérarchisation : les requêtes simples vont vers des modèles économiques et rapides, et seules les requêtes complexes atteignent les modèles de raisonnement coûteux, de sorte que vous ne payez pour la performance que lorsque c'est nécessaire." }, { "q": "Que se passe-t-il si le classificateur se trompe ?", "a": "Prévoyez une route par défaut cohérente et surveillez les erreurs d'aiguillage ; un gestionnaire de secours et une bonne observabilité limitent l'impact d'une mauvaise classification." } ] }, "de": { "name": "Routing", "summary": "Routing klassifiziert eine Eingabe und leitet sie an den am besten geeigneten spezialisierten Handler, Prompt oder das passende Modell weiter. Es verbessert die Qualität, indem jeder Pfad für seinen spezifischen Fall optimiert werden kann, und kontrolliert die Kosten, indem einfache Anfragen an günstige Modelle und komplexe an leistungsfähigere Modelle gesendet werden.", "definition": "Routing ist ein Pattern, das jede eingehende Anfrage klassifiziert und an den am besten geeigneten Handler oder das passende Modell weiterleitet, sodass einfache Eingaben kostengünstige Pfade nutzen und komplexe Eingaben leistungsfähigere Modelle beanspruchen.", "problem": "Wenn ein einziger Prompt oder ein einziges Modell jede Art von Eingabe verarbeitet, führt dies zu schlechteren Ergebnissen bei den einzelnen Aufgaben. Zudem verschwendet der Einsatz eines teuren Modells für alles Geld bei einfachen Anfragen.", "context": "Nutzen Sie Routing, wenn Eingaben in eindeutige Kategorien fallen, die von einer unterschiedlichen Handhabung profitieren – verschiedene Prompts, Tools, Modelle oder Workflows – und sich diese Kategorien zuverlässig klassifizieren lassen.", "solution": [ "Ein leichtgewichtiger Klassifizierer (ein LLM-Aufruf oder ein Modell) kennzeichnet die Eingabe, woraufhin ein Router sie an den passenden nachgelagerten Handler sendet. Jeder Handler ist auf seine Kategorie spezialisiert und optimiert.", "Routing ermöglicht zudem ein Preis-Leistungs-Tiering: Leiten Sie einfache Abfragen an ein schnelles, günstiges Modell und komplexe an ein stärkeres Reasoning-Modell weiter, sodass Sie nur dann für Leistung bezahlen, wenn sie tatsächlich benötigt wird." ], "components": [ "Klassifizierer", "Routing-Logik", "Spezialisierte Handler", "Fallback- / Standard-Route" ], "benefits": [ "Jeder Pfad ist für seinen Fall optimiert, was die Qualität steigert.", "Kostenkontrolle durch Staffelung der Modelle nach Schwierigkeitsgrad.", "Die Trennung von Zuständigkeiten (Separation of Concerns) hält jeden Handler einfach." ], "risks": [ "Fehlklassifizierungen leiten Eingaben auf den falschen Pfad.", "Der Klassifizierer fügt einen zusätzlichen Schritt und Latenz hinzu.", "Kategoriendrift im Laufe der Zeit verschlechtert die Routing-Genauigkeit." ], "whenNot": [ "Wenn die Eingaben homogen sind – ein einziger Handler reicht aus.", "Wenn Kategorien nicht zuverlässig klassifiziert werden können.", "Wenn der zusätzliche Klassifizierungsschritt den Gewinn nicht wert ist." ], "examples": [ "Routing von Support-Tickets an Abrechnungs-, Technik- oder Vertriebs-Handler.", "Senden einfacher Fragen an ein kleines Modell und komplexer Fragen an ein Reasoning-Modell.", "Leiten verschiedener Dokumenttypen an typspezifische Extraktoren." ], "productionEvidence": { "context": "Single-Operator, Local-First OpenClaw-Bereitstellung, beobachtet über 57 Tage (161 Sessions / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Eingehende Kanalnachrichten und autonome Aktivierungen werden über verschiedene Einstiegspunkte an einen Agenten geleitet, wobei Kanal-/Peer-/Rollenbindungen die Session auswählen.", "technology": "Binding + Route-Registry (resolveAgentRoute), Session-Keys pro Kanal und ein Cache für aufgelöste Routen.", "load": "3 Kanäle (Telegram, Web-Chat, WhatsApp) und 4 Trigger-Arten (User, Heartbeat, Cron, Memory).", "results": "Das Routing funktionierte über alle drei Kanäle und vier Trigger-Typen hinweg, ohne dass eine Fehlleitung als Fehler auftrat (98,8 % Session-Erfolgsquote insgesamt). Single-Operator, Local-First-Bereitstellung – eine funktionierende Referenz, kein Skalierungs-Benchmark." }, "kpis": [ { "metric": "Routing-Genauigkeit", "note": "Anteil der Eingaben, die an den korrekten Handler/das korrekte Modell gesendet wurden; die entscheidende Metrik, die den Wert des Patterns definiert." }, { "metric": "Kosteneinsparungen im Vergleich zu „Immer das beste Modell“", "note": "Eingespartes Geld durch das Routing einfacher Eingaben an günstigere Modelle, anstatt für alles das Spitzenmodell zu nutzen." }, { "metric": "Fehlrouting-Kosten", "note": "Der nachgelagerte Schaden durch falsche Routen – ein Fehlrouting kann weitaus mehr kosten als die angestrebten Einsparungen." }, { "metric": "Latenz-Overhead des Routers", "note": "Zeit, die die Routing-Entscheidung selbst beansprucht, bevor die eigentliche Arbeit beginnt." } ], "failureModes": [ "Fehlklassifizierung: Der Router sendet eine Eingabe an das falsche Modell oder den falschen Pfad, was die Antwortqualität verschlechtert.", "Mehrdeutige Eingaben, die in keine Route sauber hineinpassen und in eine ungeeignete Route gezwungen werden.", "Der Router wird zum Engpass (Bottleneck) oder Single Point of Failure für jede Anfrage.", "Drift: Die Verteilung der Eingaben verschiebt sich im Laufe der Zeit und die Kategorien des Routers veralten." ], "lessons": [ "Optimieren Sie für die Kosten einer Fehlleitung, nicht nur für die Routing-Genauigkeit – manche falschen Routen sind weitaus kostspieliger als andere.", "Fügen Sie eine Standard-/Fallback-Route für Eingaben hinzu, die auf nichts gut passen.", "Halten Sie den Router kostengünstig und schnell; wenn er so viel kostet wie die eigentliche Arbeit, verfehlt er seinen Zweck.", "Überwachen Sie den Input-Drift und passen Sie die Routen an, wenn sich die Verteilung ändert." ], "faqs": [ { "q": "Was klassifiziert die Eingabe?", "a": "In der Regel ein leichtgewichtiger LLM-Aufruf oder ein dediziertes Klassifikatormodell; bei eindeutigen Fällen können deterministische Regeln das Routing auch ohne Modell übernehmen." }, { "q": "Wie spart Routing Kosten?", "a": "Durch Tiering: Einfache Anfragen gehen an günstige, schnelle Modelle, und nur komplexe Anfragen erreichen teure Reasoning-Modelle. So zahlen Sie nur dann für Leistungsfähigkeit, wenn sie tatsächlich benötigt wird." }, { "q": "Was passiert, wenn der Klassifikator falsch liegt?", "a": "Bieten Sie eine sinnvolle Standardroute und überwachen Sie Fehlleitungen; ein Fallback-Handler und gute Observability begrenzen die Auswirkungen von Fehlklassifizierungen." } ] }, "ja": { "name": "ルーティング", "summary": "ルーティングは、入力を分類し、最も適切な専用のハンドラー、プロンプト、またはモデルに転送します。各パスをそのケースに合わせて最適化できるようにすることで品質を向上させ、簡単なリクエストは安価なモデルに、難しいリクエストは能力の高いモデルに送信することでコストを制御します。", "definition": "ルーティングは、入ってくる各リクエストを分類し、最も適切なハンドラーまたはモデルにディスパッチするパターンです。これにより、簡単な入力には安価なパスを使用し、難しい入力には能力の高いパスを使用します。", "problem": "単一のプロンプトやモデルですべての種類の入力を処理すると、それぞれの処理品質が低下します。また、すべてに1つの高価なモデルを使用すると、簡単なリクエストに対して無駄なコストが発生します。", "context": "入力が、異なる処理（異なるプロンプト、ツール、モデル、またはワークフロー）から恩恵を受ける明確なカテゴリに分類され、かつそれらのカテゴリを高い信頼性で分類できる場合にルーティングを使用します。", "solution": [ "軽量な分類器（LLM呼び出しまたはモデル）が入力にラベルを付け、ルーターがそれを対応するダウンストリームのハンドラーに送信します。各ハンドラーはそのカテゴリに特化し、最適化されています。", "ルーティングは、コストパフォーマンスの階層化（ティアリング）も可能にします。単純なクエリは高速で安価なモデルにルーティングし、複雑なクエリはより強力な推論モデルにルーティングすることで、必要なときにのみ能力に対してコストを支払うことができます。" ], "components": [ "分類器", "ルーティングロジック", "専用ハンドラー", "フォールバック / デフォルトルート" ], "benefits": [ "各パスがそのケースに合わせて最適化され、品質が向上します。", "難易度に応じてモデルを階層化することによるコスト制御。", "関心の分離により、各ハンドラーをシンプルに保つことができます。" ], "risks": [ "誤分類により、入力が誤ったパスに送信されます。", "分類器によってステップが追加され、一定のレイテンシーが発生します。", "時間の経過に伴うカテゴリのドリフトにより、ルーティングの精度が低下します。" ], "whenNot": [ "入力が均一である場合：1つのハンドラーで十分です。", "カテゴリを高い信頼性で分類できない場合。", "追加される分類ステップが、得られる効果に見合わない場合。" ], "examples": [ "サポートチケットを請求、技術、または営業のハンドラーにルーティングする。", "単純な質問は小規模なモデルに、難しい質問は推論モデルに送信する。", "異なるドキュメントタイプを、タイプ固有の抽出器に転送する。" ], "productionEvidence": { "context": "エージェント自身のトラジェクトリトレースから集計された、57日間にわたる（161セッション / 2,776ターン）シングルオペレーター、ローカルファーストのOpenClawデプロイメントの観察結果。", "scenario": "インバウンドチャネルのメッセージと自律的な起動は、異なるエントリポイントを介して1つのエージェントにルーティングされ、チャネル/ピア/ロールのバインディングによってセッションが選択されます。", "technology": "バインディング + ルートレジストリ（resolveAgentRoute）、チャネルごとのセッションキー、および解決済みルートキャッシュ。", "load": "3つのチャネル（Telegram、Webチャット、WhatsApp）と4つのトリガータイプ（ユーザー、ハートビート、cron、メモリ）。", "results": "ルーティングは3つのチャネルすべてと4つのトリガータイプすべてで維持され、障害として表面化するような誤ルーティングはありませんでした（全体で98.8%のセッション成功率）。シングルオペレーター、ローカルファーストのデプロイメントであり、スケールベンチマークではなく、動作するリファレンスです。" }, "kpis": [ { "metric": "ルーティング精度", "note": "正しいハンドラー/モデルに送信された入力の割合。このパターンの価値を定義する唯一のメトリックです。" }, { "metric": "常に最良 of モデルを使用した場合と比較したコスト削減", "note": "すべてに最上位のモデルを使用する代わりに、簡単な入力をより安価なモデルにルーティングすることによって節約されたコスト。" }, { "metric": "誤ルーティングコスト", "note": "誤ったルートによるダウンストリームへの被害。誤ルーティングは、追求した削減コストをはるかに上回るコストを伴う可能性があります。" }, { "metric": "ルーターのレイテンシーオーバーヘッド", "note": "実際の処理が開始される前に、ルーティングの決定自体によって追加される時間。" } ], "failureModes": [ "誤分類：ルーターが誤ったモデルまたはパスに入力を送信し、回答の品質を低下させます。", "どのルートにも明確に適合せず、不適切なルートに強制的に割り当てられてしまう曖昧な入力。", "ルーターがすべてのリクエストのボトルネックまたは単一障害点になります。", "ドリフト：時間の経過とともに入力の分布が変化し、ルーターのカテゴリが陳腐化します。" ], "lessons": [ "ルーティングの正確性だけでなく、誤ルーティングのコストを最適化します。一部の誤ったルートは、他のルートよりもはるかにコストが高くなります。", "いずれにもうまく一致しない入力に対して、デフォルト/フォールバックルートを追加します。", "ルーターは安価かつ高速に保ちます。ルーターのコストが実際の処理と同等になってしまっては、本末転倒です。", "入力のドリフトを監視し、分布の変化に応じてルートを再調整します。" ], "faqs": [ { "q": "入力はどのように分類されますか？", "a": "通常は軽量なLLM呼び出しや専用の分類モデルを使用します。明確なケースでは、モデルを使用せずに決定論的なルールでルーティングすることも可能です。" }, { "q": "ルーティングによってどのようにコストを削減できますか？", "a": "階層化（ティアリング）によるものです。簡単なリクエストは安価で高速なモデルに送り、困難なリクエストのみを高価な推論モデルに送ることで、必要なときにだけ機能に対するコストを支払うようにします。" }, { "q": "分類器が誤っていた場合はどうなりますか？", "a": "適切なデフォルトルートを用意し、誤ルーティングを監視します。フォールバックハンドラーと優れたオブザーバビリティにより、誤分類の影響を抑えることができます。" } ] }, "zh": { "name": "路由", "summary": "路由对输入进行分类，并将其引导至最合适的专用处理器、提示词或模型。它通过让每条路径针对其具体情况进行优化来提高质量，并通过将简单的请求发送给便宜的模型、将困难的请求发送给能力更强的模型来控制成本。", "definition": "路由是一种对每个传入请求进行分类并将其分发到最合适的处理器或模型的模式，从而使简单的输入使用便宜的路径，而困难的输入使用能力更强的路径。", "problem": "由单个提示词或模型处理每种输入会导致每种情况的效果都变差，而对所有事情都使用一个昂贵的模型会在简单的请求上浪费资金。", "context": "当输入属于不同的类别，且这些类别能从不同的处理方式（不同的提示词、工具、模型或工作流）中受益，并且这些类别可以被可靠地分类时，请使用路由。", "solution": [ "轻量级分类器（LLM 调用或模型）对输入进行标记，然后路由器将其发送到匹配的下游处理器。每个处理器都针对其类别进行了专门化和优化。", "路由还支持性价比分层：将简单的查询路由到快速、便宜的模型，将复杂的查询路由到更强大的推理模型，仅在需要时才为高能力付费。" ], "components": [ "分类器", "路由逻辑", "专用处理器", "后备/默认路由" ], "benefits": [ "每条路径都针对其具体情况进行了优化，从而提高了质量。", "通过根据难度对模型进行分层来控制成本。", "关注点分离使每个处理器保持简单。" ], "risks": [ "错误分类会导致输入走向错误的路径。", "分类器增加了一个步骤和一些延迟。", "随着时间的推移，类别漂移会降低路由准确性。" ], "whenNot": [ "当输入是同质的——一个处理器就足够了。", "当类别无法被可靠地分类时。", "当增加的分类步骤不值得其带来的收益时。" ], "examples": [ "将支持工单路由到计费、技术或销售处理器。", "将简单的问题发送给小模型，将困难的问题发送给推理模型。", "将不同的文档类型引导至特定类型的提取器。" ], "productionEvidence": { "context": "在 57 天内（161 个会话/2,776 轮）观察到的单操作员、本地优先的 OpenClaw 部署，数据从智能体自身的轨迹追踪中聚合而来。", "scenario": "入站通道消息和自主唤醒通过不同的入口点路由到同一个智能体，并通过通道/对等体/角色绑定来选择会话。", "technology": "绑定 + 路由注册表（resolveAgentRoute）、每通道会话密钥以及已解析路由缓存。", "load": "3 个通道（Telegram、网页聊天、WhatsApp）和 4 种触发类型（用户、心跳、cron、内存）。", "results": "路由在所有三个通道和四种触发类型中均保持正常，没有出现因路由错误导致的失败（整体会话成功率为 98.8%）。单操作员本地优先部署——这是一个可运行的参考，而非规模基准。" }, "kpis": [ { "metric": "路由准确性", "note": "发送到正确处理器/模型的输入比例；这是定义该模式价值的唯一指标。" }, { "metric": "相比于“始终使用最佳模型”所节省的成本", "note": "通过将简单的输入路由到更便宜的模型，而不是对所有内容都使用顶级模型所节省的资金。" }, { "metric": "路由错误成本", "note": "错误路由带来的下游损害——一次路由错误所付出的代价可能远远超过其试图节省的成本。" }, { "metric": "路由器延迟开销", "note": "在任何实际工作开始之前，路由决策本身所增加的时间。" } ], "failureModes": [ "错误分类：路由器将输入发送到错误的模型或路径，从而降低回答质量。", "模糊的输入无法清晰地适应任何路由，从而被强行归入不佳的路由。", "路由器成为每个请求的瓶颈或单点故障。", "漂移：输入分布随着时间的推移而发生偏移，导致路由器的类别过时。" ], "lessons": [ "针对误路由的成本进行优化，而不仅仅是路由准确率——某些错误的路由路径其代价远比其他路径高昂。", "为无法良好匹配任何路径的输入添加默认/备用路由。", "保持路由器廉价且快速；如果路由本身的开销与实际工作的开销相当，那就失去了路由的意义。", "监控输入漂移，并在分布发生变化时重新调整路由。" ], "faqs": [ { "q": "由什么来对输入进行分类？", "a": "通常是轻量级的 LLM 调用或专用的分类器模型；对于界限清晰的情况，确定性规则可以在无需模型的情况下进行路由。" }, { "q": "路由是如何节省成本的？", "a": "通过分层：简单的请求流向便宜、快速的模型，只有复杂的请求才会到达昂贵的推理模型，从而实现仅在需要时才为高能力付费。" }, { "q": "如果分类器出错怎么办？", "a": "提供合理的默认路由并监控误路由；备用处理器和良好的可观测性可以限制误分类的影响。" } ] } } }, { "slug": "sandboxed-execution", "category": "safety", "updated": "2026-08-22", "version": "1.0", "url": "https://santismm.com/en/patterns/sandboxed-execution", "api": "https://santismm.com/api/patterns/sandboxed-execution", "canonical_url": "https://santismm.com/en/patterns/sandboxed-execution", "api_url": "https://santismm.com/api/patterns/sandboxed-execution", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "personal_experience", "paper" ] }, "technologies": [ "Containers", "microVMs (Firecracker / gVisor)", "Ephemeral workspaces", "Resource quotas and timeouts", "Scoped secret injection" ], "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems", "url": "https://atlas.mitre.org/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "least-privilege-tooling", "egress-allowlist", "recovery-strategy", "human-approval-gate" ], "locales": { "en": { "name": "Sandboxed Execution", "summary": "Run everything an agent generates or invokes inside a disposable, isolated environment with no ambient credentials, a bounded filesystem, controlled egress and hard resource caps. The sandbox is not there because the agent is malicious; it is there because the agent's input can be.", "definition": "Sandboxed execution is the practice of running agent-generated code and agent-invoked actions inside an isolated, ephemeral environment whose filesystem, network, credentials and resources are bounded by the host rather than by the agent, so that a hijacked or mistaken agent cannot affect anything outside it.", "problem": "An agent that executes code on the host inherits the host: its credentials, its filesystem, its network position. One successful injection or one confidently wrong command is then indistinguishable from a compromise of the machine.", "context": "Use it whenever an agent runs code, executes shell commands, installs packages or processes untrusted files. The threshold is low: if the agent can cause execution, the execution belongs in a sandbox.", "solution": [ "Make it ephemeral. Create the environment per task, destroy it after, and never carry state forward that the next task did not ask for. Persistence is how a one-off compromise becomes a foothold.", "Remove ambient credentials. Nothing in the environment should be usable simply because it is present; inject only the narrowly scoped secrets the task needs, for its duration.", "Bound the filesystem to the working set. Mount the repository or the input, nothing else, and mount read-only whatever does not need writing.", "Constrain egress inside the sandbox, not around it. The isolation and the network policy are the same control from the attacker's point of view, and a sandbox with open network is a jail with a phone.", "Cap resources — CPU, memory, disk, wall-clock, process count. Runaway consumption is the failure mode that arrives first and most often, usually without any adversary at all.", "Log what crossed the boundary: which files came in, which came out, which destinations were reached. The boundary is only useful if you can see what passed through it." ], "components": [ "An isolation primitive: container, microVM or equivalent, chosen for the strength the workload needs.", "Ephemeral lifecycle management, with destruction as the default rather than a cleanup step.", "A secret-injection path scoped to the task and its duration.", "A network policy applied inside the sandbox boundary.", "Resource quotas and timeouts, enforced by the host.", "Boundary logging: inputs, outputs and destinations." ], "benefits": [ "Converts 'the agent ran something bad' from an incident into a discarded container.", "Makes it safe to give an agent genuine execution ability, which is often what makes it useful at all.", "Bounds honest mistakes as well as attacks — the same control catches an infinite loop and an injected payload.", "Gives a clean place to observe: everything the task touched crossed one boundary." ], "risks": [ "Isolation weaker than assumed: a shared kernel is not a security boundary against determined escape, and treating a container as a microVM is a category error.", "Credentials smuggled in for convenience — one mounted config file undoes the whole pattern.", "Sandboxes that quietly become persistent because rebuilding is slow, so the ephemerality that carried the guarantee is gone.", "Escape via the shared surface that remains: mounted volumes, the orchestrator API, or the network the sandbox still reaches." ], "whenNot": [ "Read-only agents with no execution capability, where there is nothing to isolate and the cost buys nothing.", "Latency-critical inline paths where environment startup dominates the task and a narrower control — a restricted interpreter, a pure function — fits better.", "When the sandbox would need the very credentials it exists to withhold, which is a sign the task should be split rather than isolated." ], "examples": [ "A coding agent that clones into a fresh container per task, with the repository mounted, no cloud credentials present and egress limited to the package registry. A malicious dependency install destroys a container and nothing else.", "A data-analysis agent executing generated Python in a microVM with the input dataset mounted read-only, no network at all and a wall-clock cap. The generated code can be wrong; it cannot be expensive or exfiltrating.", "A document-processing agent that opens untrusted PDFs inside a disposable environment, because a parser exploit in an uploaded file is a real path to the host and the file arrived from outside." ], "kpis": [ { "metric": "Share of executions sandboxed", "note": "The coverage number. Anything running outside the sandbox is the actual security posture, regardless of what the sandboxed share does." }, { "metric": "Sandbox lifetime", "note": "How long environments live. Rising lifetimes mean ephemerality is eroding into persistence." }, { "metric": "Resource-cap hits", "note": "Tasks stopped by a quota or timeout. A useful mix of runaway generations and genuine limits set too tight." }, { "metric": "Secrets present at runtime", "note": "Count of credentials reachable inside the environment. The target is the minimum the task needs, and often zero." } ], "failureModes": [ "The convenience mount: a home directory, a credentials file or a socket mounted in so a task would stop failing.", "Persistent reuse: the environment stops being per-task because rebuilding costs too much, so state and compromise both survive.", "Open egress inside the boundary: strong isolation with a free network is containment against the filesystem only.", "Orchestrator reachability: the sandbox can call the API that manages sandboxes, which is escape by design rather than by exploit." ], "lessons": [ "Isolate execution before you trust generation. The sandbox is what makes it reasonable to let an agent run code at all.", "Ephemeral is the security property; isolation alone only postpones the problem.", "The credential that is not present cannot be stolen — and it is the only control that holds after an escape.", "Most sandbox activations are honest mistakes, not attacks. That is the pattern working, not evidence it was unnecessary." ], "faqs": [ { "q": "Is a container enough, or do I need a microVM?", "a": "It depends on what runs inside. For your own code with an injection risk, a hardened container with no credentials and constrained egress is usually proportionate. For arbitrary code from untrusted sources, assume the shared kernel can be escaped and use a microVM." }, { "q": "How does this differ from least-privilege tooling?", "a": "Least privilege bounds what the agent may ask for; the sandbox bounds what happens when something runs anyway. One governs the request, the other the environment it executes in, and agents that run code need both." }, { "q": "The sandbox slows everything down. Is it worth it?", "a": "Compare against the alternative cost, not against zero. Most of the latency is environment startup, which pools and pre-warmed images largely remove; the failure it prevents is a compromise of the host that runs the agent." } ] }, "es": { "name": "Ejecución en Sandbox", "summary": "Ejecuta todo lo que un agente genera o invoca dentro de un entorno aislado y desechable, sin credenciales ambientales, con sistema de ficheros acotado, salida controlada y límites duros de recursos. El sandbox no está porque el agente sea malicioso, sino porque su entrada puede serlo.", "definition": "La ejecución en sandbox es la práctica de correr el código generado por el agente y las acciones que invoca dentro de un entorno aislado y efímero cuyo sistema de ficheros, red, credenciales y recursos los acota el anfitrión y no el agente, de forma que un agente secuestrado o equivocado no pueda afectar a nada fuera de él.", "problem": "Un agente que ejecuta código en el anfitrión hereda el anfitrión: sus credenciales, su sistema de ficheros, su posición de red. Una inyección con éxito o un comando confiadamente equivocado pasan entonces a ser indistinguibles de un compromiso de la máquina.", "context": "Úsala siempre que un agente ejecute código, corra comandos de shell, instale paquetes o procese ficheros no confiables. El umbral es bajo: si el agente puede provocar ejecución, la ejecución va en un sandbox.", "solution": [ "Hazlo efímero. Crea el entorno por tarea, destrúyelo al terminar y no arrastres estado que la siguiente tarea no haya pedido. La persistencia es cómo un compromiso puntual se convierte en punto de apoyo.", "Elimina las credenciales ambientales. Nada del entorno debería ser utilizable solo por estar presente; inyecta únicamente los secretos acotados que la tarea necesita, durante lo que dure.", "Acota el sistema de ficheros al conjunto de trabajo. Monta el repositorio o la entrada y nada más, y monta en solo lectura todo lo que no necesite escritura.", "Restringe la salida dentro del sandbox, no alrededor. Desde el punto de vista del atacante el aislamiento y la política de red son el mismo control, y un sandbox con red abierta es una celda con teléfono.", "Limita recursos: CPU, memoria, disco, tiempo de reloj, número de procesos. El consumo desbocado es el modo de fallo que llega primero y más a menudo, normalmente sin ningún adversario.", "Registra lo que cruzó la frontera: qué ficheros entraron, cuáles salieron, a qué destinos se llegó. La frontera solo sirve si puedes ver qué pasó por ella." ], "components": [ "Una primitiva de aislamiento: contenedor, microVM o equivalente, elegida por la fuerza que la carga necesita.", "Gestión de ciclo de vida efímero, con la destrucción como comportamiento por defecto y no como paso de limpieza.", "Una vía de inyección de secretos acotada a la tarea y a su duración.", "Una política de red aplicada dentro de la frontera del sandbox.", "Cuotas de recursos y timeouts aplicados por el anfitrión.", "Registro de frontera: entradas, salidas y destinos." ], "benefits": [ "Convierte «el agente ejecutó algo malo» de incidente en contenedor descartado.", "Hace seguro dar a un agente capacidad real de ejecución, que suele ser justo lo que lo hace útil.", "Acota los errores honestos igual que los ataques: el mismo control atrapa un bucle infinito y un payload inyectado.", "Da un buen sitio donde observar: todo lo que la tarea tocó cruzó una única frontera." ], "risks": [ "Aislamiento más débil de lo supuesto: un kernel compartido no es una frontera de seguridad frente a un escape decidido, y tratar un contenedor como una microVM es un error de categoría.", "Credenciales coladas por comodidad: un solo fichero de configuración montado deshace el patrón entero.", "Sandboxes que se vuelven persistentes en silencio porque reconstruir es lento, y con ello desaparece la efimeridad que sostenía la garantía.", "Escape por la superficie compartida que queda: volúmenes montados, la API del orquestador o la red a la que el sandbox sigue llegando." ], "whenNot": [ "Agentes de solo lectura sin capacidad de ejecución, donde no hay nada que aislar y el coste no compra nada.", "Rutas en línea críticas en latencia donde el arranque del entorno domina la tarea y encaja mejor un control más estrecho: un intérprete restringido, una función pura.", "Cuando el sandbox necesitaría justo las credenciales que existe para retener, que es señal de que la tarea hay que partirla en lugar de aislarla." ], "examples": [ "Un agente de programación que clona en un contenedor nuevo por tarea, con el repositorio montado, sin credenciales de nube presentes y con salida limitada al registro de paquetes. Una instalación de dependencia maliciosa destruye un contenedor y nada más.", "Un agente de análisis de datos que ejecuta Python generado en una microVM con el dataset montado en solo lectura, sin red alguna y con límite de tiempo de reloj. El código generado puede estar mal; no puede salir caro ni exfiltrar.", "Un agente de procesamiento documental que abre PDFs no confiables dentro de un entorno desechable, porque un exploit del parser en un fichero subido es una vía real al anfitrión y el fichero vino de fuera." ], "kpis": [ { "metric": "Porcentaje de ejecuciones en sandbox", "note": "El número de cobertura. Lo que corre fuera del sandbox es la postura de seguridad real, diga lo que diga la parte que sí está dentro." }, { "metric": "Vida del sandbox", "note": "Cuánto duran los entornos. Vidas crecientes significan que la efimeridad se está erosionando hacia la persistencia." }, { "metric": "Choques con límites de recursos", "note": "Tareas detenidas por una cuota o un timeout. Una mezcla útil de generaciones desbocadas y límites legítimos puestos demasiado estrechos." }, { "metric": "Secretos presentes en ejecución", "note": "Número de credenciales alcanzables dentro del entorno. El objetivo es el mínimo que la tarea necesite, y a menudo cero." } ], "failureModes": [ "El montaje por comodidad: un directorio home, un fichero de credenciales o un socket montados para que una tarea dejara de fallar.", "Reutilización persistente: el entorno deja de ser por tarea porque reconstruir cuesta demasiado, así que sobreviven el estado y el compromiso.", "Salida abierta dentro de la frontera: aislamiento fuerte con red libre es contención solo frente al sistema de ficheros.", "Alcance al orquestador: el sandbox puede llamar a la API que gestiona sandboxes, lo que es escapar por diseño y no por exploit." ], "lessons": [ "Aísla la ejecución antes de confiar en la generación. El sandbox es lo que hace razonable dejar que un agente ejecute código.", "Lo efímero es la propiedad de seguridad; el aislamiento por sí solo únicamente aplaza el problema.", "La credencial que no está presente no se puede robar, y es el único control que aguanta después de un escape.", "La mayoría de activaciones del sandbox son errores honestos, no ataques. Eso es el patrón funcionando, no la prueba de que sobraba." ], "faqs": [ { "q": "¿Basta un contenedor o necesito una microVM?", "a": "Depende de qué corre dentro. Para código propio con riesgo de inyección, un contenedor endurecido sin credenciales y con salida acotada suele ser proporcionado. Para código arbitrario de origen no confiable, asume que el kernel compartido se puede escapar y usa una microVM." }, { "q": "¿En qué se diferencia del mínimo privilegio en herramientas?", "a": "El mínimo privilegio acota lo que el agente puede pedir; el sandbox acota lo que ocurre cuando algo se ejecuta igualmente. Uno gobierna la petición y el otro el entorno donde se ejecuta, y un agente que corre código necesita ambos." }, { "q": "El sandbox lo ralentiza todo, ¿compensa?", "a": "Compáralo con el coste de la alternativa, no con cero. Casi toda la latencia es el arranque del entorno, que los pools y las imágenes precalentadas eliminan en buena parte; el fallo que evita es un compromiso del anfitrión que ejecuta el agente." } ] }, "pt": { "name": "Execução em Sandbox", "summary": "Execute tudo o que um agente gera ou invoca dentro de um ambiente isolado e descartável, sem credenciais ambientais, com sistema de arquivos limitado, saída controlada e limites rígidos de recursos. O sandbox não existe porque o agente seja malicioso, mas porque a entrada dele pode ser.", "definition": "Execução em sandbox é a prática de rodar o código gerado pelo agente e as ações que ele invoca dentro de um ambiente isolado e efêmero cujo sistema de arquivos, rede, credenciais e recursos são limitados pelo host e não pelo agente, de modo que um agente sequestrado ou equivocado não afete nada fora dele.", "problem": "Um agente que executa código no host herda o host: suas credenciais, seu sistema de arquivos, sua posição de rede. Uma injeção bem-sucedida ou um comando confiantemente errado passam a ser indistinguíveis de um comprometimento da máquina.", "context": "Use sempre que um agente executar código, rodar comandos de shell, instalar pacotes ou processar arquivos não confiáveis. O limiar é baixo: se o agente pode provocar execução, a execução vai para um sandbox.", "solution": [ "Torne-o efêmero. Crie o ambiente por tarefa, destrua ao final e não carregue estado que a próxima tarefa não pediu. A persistência é como um comprometimento pontual vira ponto de apoio.", "Remova as credenciais ambientais. Nada no ambiente deveria ser utilizável só por estar presente; injete apenas os segredos restritos de que a tarefa precisa, pelo tempo dela.", "Limite o sistema de arquivos ao conjunto de trabalho. Monte o repositório ou a entrada e nada mais, e monte como somente leitura tudo o que não precisa de escrita.", "Restrinja a saída dentro do sandbox, não em volta dele. Do ponto de vista do atacante, o isolamento e a política de rede são o mesmo controle, e um sandbox com rede aberta é uma cela com telefone.", "Limite recursos: CPU, memória, disco, tempo de relógio, número de processos. O consumo descontrolado é o modo de falha que chega primeiro e com mais frequência, normalmente sem adversário algum.", "Registre o que cruzou a fronteira: quais arquivos entraram, quais saíram, quais destinos foram alcançados. A fronteira só é útil se você puder ver o que passou por ela." ], "components": [ "Uma primitiva de isolamento: contêiner, microVM ou equivalente, escolhida pela força que a carga exige.", "Gestão de ciclo de vida efêmero, com a destruição como comportamento padrão e não como etapa de limpeza.", "Um caminho de injeção de segredos restrito à tarefa e à duração dela.", "Uma política de rede aplicada dentro da fronteira do sandbox.", "Cotas de recursos e timeouts aplicados pelo host.", "Registro de fronteira: entradas, saídas e destinos." ], "benefits": [ "Converte “o agente executou algo ruim” de incidente em contêiner descartado.", "Torna seguro dar a um agente capacidade real de execução, que costuma ser justamente o que o torna útil.", "Limita erros honestos tanto quanto ataques: o mesmo controle pega um laço infinito e um payload injetado.", "Dá um bom lugar para observar: tudo o que a tarefa tocou cruzou uma única fronteira." ], "risks": [ "Isolamento mais fraco do que o suposto: um kernel compartilhado não é fronteira de segurança contra um escape determinado, e tratar um contêiner como microVM é um erro de categoria.", "Credenciais contrabandeadas por conveniência: um único arquivo de configuração montado desfaz o padrão inteiro.", "Sandboxes que ficam persistentes em silêncio porque reconstruir é lento, e com isso some a efemeridade que sustentava a garantia.", "Escape pela superfície compartilhada que resta: volumes montados, a API do orquestrador ou a rede que o sandbox ainda alcança." ], "whenNot": [ "Agentes somente leitura sem capacidade de execução, onde não há o que isolar e o custo não compra nada.", "Caminhos em linha críticos em latência onde a inicialização do ambiente domina a tarefa e um controle mais estreito cabe melhor: um interpretador restrito, uma função pura.", "Quando o sandbox precisaria justamente das credenciais que ele existe para reter, o que é sinal de que a tarefa deve ser dividida em vez de isolada." ], "examples": [ "Um agente de programação que clona em um contêiner novo por tarefa, com o repositório montado, sem credenciais de nuvem presentes e com saída limitada ao registry de pacotes. Uma instalação de dependência maliciosa destrói um contêiner e nada mais.", "Um agente de análise de dados que executa Python gerado em uma microVM com o dataset montado somente leitura, sem rede alguma e com limite de tempo de relógio. O código gerado pode estar errado; não pode sair caro nem exfiltrar.", "Um agente de processamento de documentos que abre PDFs não confiáveis dentro de um ambiente descartável, porque um exploit de parser em um arquivo enviado é um caminho real até o host e o arquivo veio de fora." ], "kpis": [ { "metric": "Percentual de execuções em sandbox", "note": "O número de cobertura. O que roda fora do sandbox é a postura de segurança real, independentemente do que a parte de dentro faça." }, { "metric": "Tempo de vida do sandbox", "note": "Quanto duram os ambientes. Vidas crescentes significam que a efemeridade está erodindo para persistência." }, { "metric": "Batidas em limites de recursos", "note": "Tarefas interrompidas por cota ou timeout. Uma mistura útil de gerações descontroladas e limites legítimos apertados demais." }, { "metric": "Segredos presentes em execução", "note": "Número de credenciais alcançáveis dentro do ambiente. O alvo é o mínimo de que a tarefa precisa, e muitas vezes zero." } ], "failureModes": [ "A montagem por conveniência: um diretório home, um arquivo de credenciais ou um socket montados para que uma tarefa parasse de falhar.", "Reutilização persistente: o ambiente deixa de ser por tarefa porque reconstruir custa demais, então estado e comprometimento sobrevivem.", "Saída aberta dentro da fronteira: isolamento forte com rede livre é contenção apenas contra o sistema de arquivos.", "Alcance ao orquestrador: o sandbox consegue chamar a API que gerencia sandboxes, o que é escapar por design e não por exploit." ], "lessons": [ "Isole a execução antes de confiar na geração. O sandbox é o que torna razoável deixar um agente rodar código.", "O efêmero é a propriedade de segurança; o isolamento sozinho apenas adia o problema.", "A credencial que não está presente não pode ser roubada — e é o único controle que resiste depois de um escape.", "A maioria das ativações do sandbox são erros honestos, não ataques. Isso é o padrão funcionando, não prova de que era desnecessário." ], "faqs": [ { "q": "Um contêiner basta ou preciso de microVM?", "a": "Depende do que roda dentro. Para código próprio com risco de injeção, um contêiner endurecido sem credenciais e com saída limitada costuma ser proporcional. Para código arbitrário de origem não confiável, assuma que o kernel compartilhado pode ser escapado e use uma microVM." }, { "q": "Em que difere de ferramentas com privilégio mínimo?", "a": "O privilégio mínimo limita o que o agente pode pedir; o sandbox limita o que acontece quando algo executa mesmo assim. Um governa a requisição, o outro o ambiente em que ela roda, e agentes que executam código precisam dos dois." }, { "q": "O sandbox deixa tudo mais lento. Compensa?", "a": "Compare com o custo da alternativa, não com zero. Quase toda a latência é a inicialização do ambiente, que pools e imagens pré-aquecidas removem em boa parte; a falha que ele evita é um comprometimento do host que roda o agente." } ] }, "fr": { "name": "Exécution en bac à sable", "summary": "Exécutez tout ce qu'un agent génère ou invoque au sein d'un environnement isolé et jetable, sans identifiants ambiants, avec un système de fichiers restreint, une sortie contrôlée et des limites strictes de ressources. Le bac à sable n'est pas là parce que l'agent est malveillant, mais parce que les entrées de l'agent peuvent l'être.", "definition": "L'exécution en bac à sable consiste à exécuter le code généré par l'agent et les actions invoquées par celui-ci au sein d'un environnement isolé et éphémère dont le système de fichiers, le réseau, les identifiants et les ressources sont limités par l'hôte plutôt que par l'agent, afin qu'un agent compromis ou erroné ne puisse rien affecter en dehors de cet environnement.", "problem": "Un agent qui exécute du code sur l'hôte hérite de cet hôte : ses identifiants, son système de fichiers, sa position réseau. Une seule injection réussie ou une seule commande erronée mais exécutée avec assurance devient alors impossible à distinguer d'une compromission de la machine.", "context": "Utilisez-le dès qu'un agent exécute du code, lance des commandes shell, installe des paquets ou traite des fichiers non approuvés. Le seuil est bas : si l'agent peut déclencher une exécution, cette exécution doit se faire dans un bac à sable.", "solution": [ "Rendez-le éphémère. Créez l'environnement par tâche, détruisez-le ensuite, et ne transmettez jamais un état que la tâche suivante n'a pas demandé. C'est par la persistance qu'une compromission ponctuelle devient un point d'ancrage.", "Supprimez les identifiants ambiants. Rien dans l'environnement ne devrait être utilisable simplement parce qu'il s'y trouve ; n'injectez que les secrets strictement nécessaires à la tâche, pour sa seule durée.", "Limitez le système de fichiers à l'ensemble de travail. Montez le dépôt ou l'entrée, rien d'autre, et montez en lecture seule tout ce qui n'a pas besoin d'être écrit.", "Contraignez les flux de sortie à l'intérieur du bac à sable, pas autour. L'isolation et la politique réseau représentent le même contrôle du point de vue de l'attaquant, et un bac à sable avec un réseau ouvert est une prison avec un téléphone.", "Limitez les ressources — CPU, mémoire, disque, temps d'exécution réel, nombre de processus. La consommation incontrôlée est le mode de défaillance qui survient en premier et le plus souvent, généralement sans le moindre adversaire.", "Journalisez ce qui a franchi la limite : quels fichiers sont entrés, lesquels sont sortis, quelles destinations ont été atteintes. La limite n'est utile que si vous pouvez voir ce qui l'a traversée." ], "components": [ "Une primitive d'isolation : conteneur, microVM ou équivalent, choisie selon le niveau de robustesse requis par la charge de travail.", "Une gestion du cycle de vie éphémère, avec la destruction comme comportement par défaut plutôt que comme simple étape de nettoyage.", "Un mécanisme d'injection de secrets limité à la tâche et à sa durée.", "Une politique réseau appliquée à l'intérieur des limites du bac à sable.", "Des quotas de ressources et des délais d'expiration (timeouts), appliqués par l'hôte.", "Une journalisation aux limites : entrées, sorties et destinations." ], "benefits": [ "Transforme l'événement « l'agent a exécuté quelque chose de malveillant » d'un incident grave en un conteneur jeté.", "Permet de donner en toute sécurité une véritable capacité d'exécution à un agent, ce qui est souvent indispensable pour le rendre utile.", "Limite aussi bien les erreurs involontaires que les attaques — le même contrôle intercepte une boucle infinie et une charge utile injectée.", "Offre un espace d'observation clair : tout ce que la tâche a touché a franchi une seule et unique limite." ], "risks": [ "Une isolation plus faible que prévu : un noyau partagé ne constitue pas une barrière de sécurité contre une évasion déterminée, et traiter un conteneur comme une microVM est une erreur de catégorie.", "Des identifiants introduits en douce par commodité — un seul fichier de configuration monté annule tout l'intérêt du modèle.", "Des bacs à sable qui deviennent discrètement persistants parce que la reconstruction est lente, faisant ainsi disparaître le caractère éphémère qui garantissait la sécurité.", "Une évasion via la surface partagée restante : volumes montés, API de l'orchestrateur ou réseau que le bac à sable peut encore atteindre." ], "whenNot": [ "Les agents en lecture seule sans capacité d'exécution, où il n'y a rien à isoler et où le coût n'apporte aucun bénéfice.", "Les parcours en ligne critiques en termes de latence, où le démarrage de l'environnement domine la tâche et où un contrôle plus restreint — un interpréteur limité, une fonction pure — est plus adapté.", "Lorsque le bac à sable aurait besoin des identifiants mêmes qu'il a pour but de retenir, ce qui indique que la tâche devrait être divisée plutôt qu'isolée." ], "examples": [ "Un agent de codage qui clone un dépôt dans un conteneur neuf par tâche, avec le dépôt monté, aucun identifiant cloud présent et des flux de sortie limités au registre de paquets. L'installation d'une dépendance malveillante détruit le conteneur et rien d'autre.", "Un agent d'analyse de données exécutant du code Python généré dans une microVM avec le jeu de données d'entrée monté en lecture seule, aucun réseau et une limite de temps d'exécution réel. Le code généré peut être erroné ; il ne peut pas être coûteux ni exfiltrer de données.", "Un agent de traitement de documents qui ouvre des PDF non approuvés dans un environnement jetable, car une faille d'analyseur dans un fichier téléversé constitue une véritable voie d'accès à l'hôte et le fichier provient de l'extérieur." ], "kpis": [ { "metric": "Part des exécutions exécutées en bac à sable", "note": "Le taux de couverture. Tout ce qui s'exécute en dehors du bac à sable représente la posture de sécurité réelle, indépendamment de ce que fait la part exécutée en bac à sable." }, { "metric": "Durée de vie du bac à sable", "note": "La durée de vie des environnements. Des durées de vie croissantes signifient que le caractère éphémère s'érode au profit de la persistance." }, { "metric": "Dépassements des limites de ressources", "note": "Tâches arrêtées par un quota ou un délai d'expiration. Un indicateur utile mêlant générations incontrôlées et limites réelles définies de manière trop stricte." }, { "metric": "Secrets présents au moment de l'exécution", "note": "Nombre d'identifiants accessibles à l'intérieur de l'environnement. L'objectif est le strict minimum requis par la tâche, et souvent zéro." } ], "failureModes": [ "Le montage de commodité : un répertoire personnel, un fichier d'identifiants ou un socket monté pour qu'une tâche cesse d'échouer.", "La réutilisation persistante : l'environnement cesse d'être propre à chaque tâche car la reconstruction coûte trop cher, de sorte que l'état et la compromission survivent tous deux.", "Flux de sortie ouverts à l'intérieur de la limite : une isolation forte avec un réseau libre n'est qu'un confinement limité au système de fichiers.", "Accessibilité de l'orchestrateur : le bac à sable peut appeler l'API qui gère les bacs à sable, ce qui constitue une évasion par conception plutôt que par faille." ], "lessons": [ "Isolez l'exécution avant de faire confiance à la génération. C'est le bac à sable qui permet de laisser un agent exécuter du code de manière raisonnable.", "Le caractère éphémère est la véritable propriété de sécurité ; l'isolation seule ne fait que différer le problème.", "L'identifiant qui n'est pas présent ne peut pas être volé — et c'est le seul contrôle qui tient après une évasion.", "La plupart des activations de bac à sable sont des erreurs involontaires, pas des attaques. C'est la preuve que le modèle fonctionne, et non qu'il était inutile." ], "faqs": [ { "q": "Un conteneur est-il suffisant ou ai-je besoin d'une microVM ?", "a": "Cela dépend de ce qui s'y exécute. Pour votre propre code présentant un risque d'injection, un conteneur durci sans identifiants et avec des flux de sortie restreints est généralement proportionné. Pour du code arbitraire provenant de sources non approuvées, partez du principe que le noyau partagé peut être contourné et utilisez une microVM." }, { "q": "En quoi cela diffère-t-il des outils de moindre privilège ?", "a": "Le moindre privilège limite ce que l'agent peut demander ; le bac à sable limite ce qui se passe lorsque quelque chose s'exécute malgré tout. L'un régit la requête, l'autre régit l'environnement dans lequel elle s'exécute, et les agents qui exécutent du code ont besoin des deux." }, { "q": "Le bac à sable ralentit tout. Est-ce que cela en vaut la peine ?", "a": "Comparez par rapport au coût de l'alternative, pas par rapport à zéro. La majeure partie de la latence provient du démarrage de l'environnement, ce que les pools et les images préchauffées éliminent en grande partie ; la défaillance qu'il prévient est une compromission de l'hôte qui exécute l'agent." } ] }, "de": { "name": "Sandbox-Ausführung", "summary": "Führen Sie alles, was ein Agent generiert oder aufruft, in einer verworfenen, isolierten Umgebung ohne implizite Anmeldedaten (Ambient Credentials), mit einem begrenzten Dateisystem, kontrolliertem Egress und harten Ressourcenlimits aus. Die Sandbox existiert nicht, weil der Agent bösartig ist, sondern weil es die Eingaben des Agenten sein können.", "definition": "Sandbox-Ausführung bezeichnet die Praxis, von Agenten generierten Code und von Agenten aufgerufene Aktionen in einer isolierten, flüchtigen (ephemeren) Umgebung auszuführen, deren Dateisystem, Netzwerk, Anmeldedaten und Ressourcen durch den Host statt durch den Agenten begrenzt sind, sodass ein gekaperter oder fehlerhafter Agent nichts außerhalb dieser Umgebung beeinflussen kann.", "problem": "Ein Agent, der Code auf dem Host ausführt, erbt dessen Umgebung: seine Anmeldedaten, sein Dateisystem und seine Netzwerkposition. Eine einzige erfolgreiche Injection oder ein einziger selbstbewusst falscher Befehl ist dann nicht mehr von einer Kompromittierung des Systems zu unterscheiden.", "context": "Nutzen Sie dies immer dann, wenn ein Agent Code ausführt, Shell-Befehle ausführt, Pakete installiert oder nicht vertrauenswürdige Dateien verarbeitet. Die Hürde ist niedrig: Wenn der Agent eine Ausführung bewirken kann, gehört diese Ausführung in eine Sandbox.", "solution": [ "Machen Sie es flüchtig (ephemer). Erstellen Sie die Umgebung pro Task, zerstören Sie sie danach und übertragen Sie niemals einen Zustand, der vom nächsten Task nicht angefordert wurde. Persistenz ist der Weg, wie aus einer einmaligen Kompromittierung ein dauerhafter Zugang wird.", "Entfernen Sie implizite Anmeldedaten (Ambient Credentials). Nichts in der Umgebung sollte nutzbar sein, nur weil es vorhanden ist; injizieren Sie nur die eng begrenzten Secrets, die der Task für seine Dauer benötigt.", "Begrenzen Sie das Dateisystem auf das Working Set. Mounten Sie das Repository oder den Input und nichts anderes, und mounten Sie alles schreibgeschützt (read-only), was nicht beschrieben werden muss.", "Beschränken Sie den Egress innerhalb der Sandbox, nicht um sie herum. Die Isolation und die Netzwerkrichtlinie sind aus Sicht des Angreifers dieselbe Kontrollmaßnahme, und eine Sandbox mit offenem Netzwerk ist wie ein Gefängnis mit Telefon.", "Begrenzen Sie die Ressourcen – CPU, Arbeitsspeicher, Festplatte, Laufzeit (Wall-Clock), Prozessanzahl. Unkontrollierter Ressourcenverbrauch ist das Fehlerszenario, das zuerst und am häufigsten auftritt, meist ganz ohne Angreifer.", "Protokollieren Sie, was die Grenze überschritten hat: Welche Dateien kamen hinein, welche gingen heraus, welche Ziele wurden erreicht. Die Grenze ist nur dann nützlich, wenn Sie sehen können, was sie passiert hat." ], "components": [ "Ein Isolations-Primitiv: Container, MicroVM oder Ähnliches, ausgewählt nach der für den Workload erforderlichen Stärke.", "Ephemeres Lifecycle-Management, bei dem die Zerstörung der Standardzustand und nicht nur ein Bereinigungsschritt ist.", "Ein Pfad zur Secret-Injektion, der auf den Task und dessen Dauer begrenzt ist.", "Eine Netzwerkrichtlinie, die innerhalb der Sandbox-Grenze angewendet wird.", "Ressourcen-Quotas und Timeouts, die vom Host erzwungen werden.", "Grenzprotokollierung (Boundary Logging): Eingaben, Ausgaben und Ziele." ], "benefits": [ "Verwandelt das Szenario „Der Agent hat etwas Schädliches ausgeführt“ von einem Sicherheitsvorfall in einen verworfenen Container.", "Ermöglicht es, einem Agenten echte Ausführungsfähigkeiten zu geben, was ihn oft überhaupt erst nützlich macht.", "Begrenzt sowohl ehrliche Fehler als auch Angriffe – dieselbe Kontrollmaßnahme fängt eine Endlosschleife ebenso ab wie ein injiziertes Payload.", "Bietet einen sauberen Ort für die Beobachtung: Alles, was der Task berührt hat, hat genau eine Grenze überschritten." ], "risks": [ "Schwächere Isolation als angenommen: Ein gemeinsam genutzter Kernel ist keine Sicherheitsgrenze gegen einen entschlossenen Ausbruch (Escape), und einen Container wie eine MicroVM zu behandeln, ist ein Kategorienfehler.", "Aus Bequemlichkeit eingeschmuggelte Anmeldedaten – eine einzige gemountete Konfigurationsdatei macht das gesamte Pattern zunichte.", "Sandboxes, die unbemerkt persistent werden, weil der Neuaufbau zu langsam ist, wodurch die Flüchtigkeit (Ephemerality), die die Garantie bot, verloren geht.", "Ausbruch über die verbleibende gemeinsame Schnittstelle: gemountete Volumes, die Orchestrator-API oder das Netzwerk, das die Sandbox noch erreicht." ], "whenNot": [ "Read-only-Agenten ohne Ausführungsfähigkeit, bei denen es nichts zu isolieren gibt und die Kosten keinen Nutzen bringen.", "Latenzkritische Inline-Pfade, bei denen der Start der Umgebung den Task dominiert und eine engere Kontrolle – wie ein eingeschränkter Interpreter oder eine reine Funktion – besser geeignet ist.", "Wenn die Sandbox genau die Anmeldedaten benötigen würde, die sie eigentlich vorenthalten soll – was ein Zeichen dafür ist, dass der Task eher aufgeteilt als isoliert werden sollte." ], "examples": [ "Ein Coding-Agent, der für jeden Task in einen frischen Container klont, wobei das Repository gemountet ist, keine Cloud-Anmeldedaten vorhanden sind und der Egress auf die Paketregistrierung beschränkt ist. Die Installation einer bösartigen Abhängigkeit zerstört lediglich den Container und sonst nichts.", "Ein Datenanalyse-Agent, der generierten Python-Code in einer MicroVM ausführt, wobei der Eingabedatensatz schreibgeschützt gemountet ist, keinerlei Netzwerkverbindung besteht und ein Laufzeitlimit (Wall-Clock Cap) gilt. Der generierte Code kann fehlerhaft sein; er kann jedoch weder teuer sein noch Daten exfiltrieren.", "Ein Dokumentenverarbeitungs-Agent, der nicht vertrauenswürdige PDFs in einer Einwegumgebung öffnet, da ein Parser-Exploit in einer hochgeladenen Datei ein realer Pfad zum Host ist und die Datei von außen stammt." ], "kpis": [ { "metric": "Anteil der in einer Sandbox ausgeführten Prozesse", "note": "Die Abdeckungsrate. Alles, was außerhalb der Sandbox läuft, bestimmt das tatsächliche Sicherheitsniveau, unabhängig davon, was der in der Sandbox ausgeführte Anteil tut." }, { "metric": "Lebensdauer der Sandbox", "note": "Wie lange Umgebungen existieren. Steigende Lebensdauern bedeuten, dass die Flüchtigkeit (Ephemerality) schleichend in Persistenz übergeht." }, { "metric": "Erreichen von Ressourcenlimits", "note": "Tasks, die durch ein Kontingent oder ein Timeout gestoppt wurden. Eine nützliche Mischung aus unkontrollierten Generierungen und tatsächlich zu eng gesetzten Limits." }, { "metric": "Zur Laufzeit vorhandene Secrets", "note": "Anzahl der innerhalb der Umgebung erreichbaren Anmeldedaten. Das Ziel ist das für den Task erforderliche Minimum, oft null." } ], "failureModes": [ "Das Bequemlichkeits-Mounting: Ein Home-Verzeichnis, eine Anmeldedatendatei oder ein Socket, die gemountet werden, damit ein Task nicht mehr fehlschlägt.", "Persistente Wiederverwendung: Die Umgebung wird nicht mehr pro Task erstellt, weil der Neuaufbau zu viel kostet, sodass sowohl der Zustand als auch eine Kompromittierung überdauern.", "Offener Egress innerhalb der Grenze: Eine starke Isolation bei freiem Netzwerkzugriff schützt lediglich das Dateisystem.", "Erreichbarkeit des Orchestrators: Die Sandbox kann die API aufrufen, die die Sandboxes verwaltet – was ein systembedingter Ausbruch (Escape by Design) statt eines Exploits ist." ], "lessons": [ "Isolieren Sie die Ausführung, bevor Sie der Generierung vertrauen. Erst die Sandbox macht es überhaupt vertretbar, einen Agenten Code ausführen zu lassen.", "Flüchtigkeit (Ephemerality) ist die eigentliche Sicherheitseigenschaft; Isolation allein verschiebt das Problem nur nach hinten.", "Anmeldedaten, die nicht vorhanden sind, können nicht gestohlen werden – und das ist die einzige Kontrollmaßnahme, die nach einem Ausbruch noch greift.", "Die meisten Sandbox-Aktivierungen sind ehrliche Fehler, keine Angriffe. Das zeigt, dass das Pattern funktioniert, und ist kein Beweis dafür, dass es unnötig war." ], "faqs": [ { "q": "Reicht ein Container aus oder benötige ich eine MicroVM?", "a": "Das hängt davon ab, was darin ausgeführt wird. Für eigenen Code mit einem Injection-Risiko ist ein gehärteter Container ohne Anmeldedaten und mit eingeschränktem Egress meist verhältnismäßig. Für beliebigen Code aus nicht vertrauenswürdigen Quellen sollten Sie davon ausgehen, dass aus dem gemeinsam genutzten Kernel ausgebrochen werden kann, und eine MicroVM verwenden." }, { "q": "Wie unterscheidet sich dies von Least-Privilege-Tooling?", "a": "Least Privilege (das Prinzip der minimalen Rechte) begrenzt, was der Agent anfordern darf; die Sandbox begrenzt, was passiert, wenn dennoch etwas ausgeführt wird. Das eine regelt die Anfrage, das andere die Umgebung, in der sie ausgeführt wird – und Agenten, die Code ausführen, benötigen beides." }, { "q": "Die Sandbox verlangsamt alles. Lohnt sich das?", "a": "Vergleichen Sie dies mit den Alternativkosten, nicht mit null. Der Großteil der Latenz entsteht beim Starten der Umgebung, was durch Pools und vorgewärmte Images weitgehend vermieden werden kann. Der Fehler, den sie verhindert, ist eine Kompromittierung des Hosts, auf dem der Agent läuft." } ] }, "ja": { "name": "サンドボックス実行", "summary": "エージェントが生成または呼び出すものはすべて、環境固有の資格情報（ambient credentials）を持たず、制限されたファイルシステム、制御された送信（egress）、および厳格なリソース制限を備えた、使い捨ての隔離環境内で実行します。サンドボックスが存在するのは、エージェントが悪意を持っているからではなく、エージェントへの入力が悪意を持っている可能性があるからです。", "definition": "サンドボックス実行とは、エージェントが生成したコードやエージェントが呼び出したアクションを、隔離されたエフェメラル（一時的）な環境内で実行する手法です。そのファイルシステム、ネットワーク、資格情報、およびリソースは、エージェントではなくホストによって制限されるため、乗っ取られたり誤動作したりしたエージェントが外部に影響を与えるのを防ぐことができます。", "problem": "ホスト上でコードを実行するエージェントは、ホストの資格情報、ファイルシステム、ネットワーク上の位置などをそのまま継承します。そのため、インジェクションが1回成功したり、自信満々に間違ったコマンドが1回実行されたりするだけで、マシン全体の侵害と区別がつかなくなります。", "context": "エージェントがコードを実行したり、シェルコマンドを実行したり、パッケージをインストールしたり、信頼できないファイルを処理したりする場合は、常にこれを使用します。基準は低く設定すべきです。エージェントが実行を引き起こす可能性があるなら、その実行はサンドボックス内で行われるべきです。", "solution": [ "エフェメラル（一時的）にします。タスクごとに環境を作成し、終了後に破棄します。次のタスクが要求していない状態（ステート）は決して引き継がないでください。永続化こそが、単発の侵害を足がかりへと変えてしまう原因です。", "環境固有の資格情報（ambient credentials）を排除します。環境内に存在するからという理由だけで利用できるものは何もない状態にすべきです。タスクが必要とする、範囲を厳密に限定したシークレットのみを、その実行期間中だけ注入します。", "ファイルシステムを作業セットに制限します。リポジトリや入力のみをマウントし、それ以外はマウントしません。また、書き込みが不要なものはすべて読み取り専用でマウントします。", "サンドボックスの周囲ではなく、サンドボックスの「内部」で送信（egress）を制限します。攻撃者の視点からは、隔離とネットワークポリシーは同一のコントロールであり、ネットワークが開放されたサンドボックスは「電話のある刑務所」と同じです。", "リソース（CPU、メモリ、ディスク、実時間、プロセス数）に上限を設けます。リソースの暴走消費は、攻撃者がいなくても、最も早く、最も頻繁に発生する障害モードです。", "境界を越えたもの（どのファイルが入り、どのファイルが出ていき、どの宛先にアクセスしたか）をログに記録します。境界は、そこを通過したものを可視化できて初めて役に立ちます。" ], "components": [ "隔離プリミティブ：ワークロードが必要とする強度に応じて選択された、コンテナ、microVM、またはそれと同等のもの。", "クリーンアップステップとしてではなく、デフォルトで破棄を行うエフェメラルなライフサイクル管理。", "タスクとその実行期間にスコープを限定したシークレット注入パス。", "サンドボックスの境界内部に適用されるネットワークポリシー。", "ホストによって強制されるリソースクォータとタイムアウト。", "境界ログ：入力、出力、およびアクセス先。" ], "benefits": [ "「エージェントが悪質なものを実行した」という事態を、インシデントから「破棄されたコンテナ」へと変換します。", "エージェントに本物の実行能力を安全に付与できるようにします。これこそが、多くの場合においてエージェントを真に有用なものにする要素です。", "攻撃だけでなく、悪意のない誤りも制限します。同一のコントロールで、無限ループとインジェクションされたペイロードの両方を捕捉できます。", "観察のための明確な場所を提供します。タスクが触れたものはすべて、単一の境界を越えるためです。" ], "risks": [ "想定よりも隔離が弱いこと：共有カーネルは、執拗なエスケープに対するセキュリティ境界にはならず、コンテナをmicroVMのように扱うのはカテゴリーエラーです。", "利便性のために資格情報が持ち込まれること：マウントされた設定ファイルが1つあるだけで、このパターン全体が台無しになります。", "再構築が遅いためにサンドボックスが密かに永続化し、安全性を担保していたエフェメラル（一時的）な性質が失われること。", "残された共有サーフェス（マウントされたボリューム、オーケストレーターAPI、またはサンドボックスが依然として到達できるネットワーク）を介したエスケープ。" ], "whenNot": [ "実行能力を持たない読み取り専用のエージェント。隔離すべき対象がなく、コストに見合うメリットが得られません。", "環境の起動時間がタスクの大部分を占める、レイテンシーが極めて重要なインラインパス。この場合は、制限されたインタプリタや純粋関数など、より限定的なコントロールの方が適しています。", "サンドボックスが、本来は与えないために存在するはずの資格情報を必要とする場合。これは、タスクを隔離するのではなく、分割すべきであるという兆候です。" ], "examples": [ "タスクごとに新しいコンテナにクローンを作成するコーディングエージェント。リポジトリはマウントされ、クラウドの資格情報は存在せず、送信（egress）はパッケージレジストリに制限されています。悪意のある依存関係がインストールされても、破棄されるのはそのコンテナだけであり、それ以外に影響はありません。", "入力データセットを読み取り専用でマウントし、ネットワーク接続を一切持たず、実行時間の上限を設定したmicroVM内で、生成されたPythonを実行するデータ分析エージェント。生成されたコードが誤っている可能性はありますが、高コストになったり、データを外部に流出させたりすることはありません。", "信頼できないPDFを使い捨て環境内で開く文書処理エージェント。アップロードされたファイル内のパーサーの脆弱性を突くエクスプロイトは、ホストへの現実的な侵入経路であり、そのファイルは外部から届いたものだからです。" ], "kpis": [ { "metric": "サンドボックス化された実行の割合", "note": "カバレッジの数値。サンドボックス化された割合がどうであれ、サンドボックスの外で実行されているものこそが、実際のセキュリティ体制を示します。" }, { "metric": "サンドボックスの生存期間", "note": "環境が存続する期間。生存期間が長くなっている場合は、エフェメラル（一時的）な性質が失われ、永続化へと侵食されていることを意味します。" }, { "metric": "リソース上限への到達回数", "note": "クォータやタイムアウトによって停止されたタスク。暴走した生成と、厳しすぎる実際の上限設定の両方が混在する、有用な指標です。" }, { "metric": "実行時に存在するシークレット数", "note": "環境内でアクセス可能な資格情報の数。目標はタスクが必要とする最小限であり、多くの場合ゼロです。" } ], "failureModes": [ "利便性のためのマウント：タスクのエラーを解消するために、ホームディレクトリ、資格情報ファイル、またはソケットをマウントしてしまうこと。", "永続的な再利用：再構築コストが高すぎるために環境がタスクごとのものではなくなり、状態と侵害の両方が存続してしまうこと。", "境界内部での送信（egress）の開放：強力に隔離されていてもネットワークが自由であれば、それはファイルシステムに対してのみ機能する封じ込めにすぎません。", "オーケストレーターへの到達可能性：サンドボックスがサンドボックスを管理するAPIを呼び出せる状態。これはエクスプロイトによるものではなく、設計上のエスケープです。" ], "lessons": [ "生成を信頼する前に、実行を隔離します。サンドボックスこそが、エージェントにコードを実行させることを妥当にする要素です。", "エフェメラル（一時的）であることがセキュリティ特性です。隔離だけでは問題を先送りするにすぎません。", "存在しない資格情報は盗まれません。そして、それこそがエスケープが発生した後に機能する唯一のコントロールです。", "サンドボックスが作動する原因のほとんどは、攻撃ではなく悪意のない誤りです。それはこのパターンが機能している証拠であり、不要であったことを示すものではありません。" ], "faqs": [ { "q": "コンテナで十分ですか、それともmicroVMが必要ですか？", "a": "内部で何を実行するかによって異なります。インジェクションのリスクがある自社コードの場合、資格情報を持たず、送信（egress）を制限した堅牢なコンテナで通常は十分です。信頼できないソースからの任意のコードを実行する場合は、共有カーネルからエスケープされる可能性があると想定し、microVMを使用してください。" }, { "q": "最小権限のツール設定とはどのように異なりますか？", "a": "最小権限はエージェントが要求できるものを制限し、サンドボックスは何かを実行したときに起こることを制限します。一方はリクエストを管理し、もう一方はそれが実行される環境を管理します。コードを実行するエージェントにはその両方が必要です。" }, { "q": "サンドボックスを導入すると動作が遅くなります。それだけの価値はありますか？", "a": "ゼロと比較するのではなく、代替コストと比較してください。レイテンシーの大部分は環境の起動によるものですが、これはプールや事前ウォームアップされたイメージによって大幅に削減できます。サンドボックスが防ぐ障害は、エージェントを実行するホストの侵害です。" } ] }, "zh": { "name": "沙箱化执行", "summary": "在一次性的隔离环境中运行智能体生成或调用的所有内容，该环境不提供环境凭据，具有受限的文件系统、受控的出站流量和严格的资源上限。引入沙箱并不是因为智能体本身具有恶意，而是因为智能体的输入可能具有恶意。", "definition": "沙箱化执行是指在隔离的临时环境中运行智能体生成的代码和智能体调用的操作。该环境的文件系统、网络、凭据和资源由宿主机而非智能体进行限制，从而确保被劫持或出错的智能体不会影响到沙箱外部的任何内容。", "problem": "在宿主机上执行代码的智能体会继承宿主机的属性：其凭据、文件系统和网络位置。此时，一次成功的注入或一个极其自信的错误命令，其后果与整台机器被攻破无异。", "context": "每当智能体运行代码、执行 Shell 命令、安装包或处理不可信文件时，都应使用此模式。门槛很低：只要智能体能够触发执行，该执行就应当在沙箱中进行。", "solution": [ "使其具备临时性。为每个任务创建独立环境，并在任务结束后将其销毁，绝不传递下一个任务未要求的状态。持久化是单次攻破演变为长期据点的原因。", "移除环境凭据。环境中的任何内容都不应仅仅因为存在即可被使用；仅在任务执行期间注入该任务所需的、范围严格受限的机密信息。", "将文件系统限制在工作集内。仅挂载代码仓库或输入，不挂载其他任何内容，并将不需要写入的所有内容挂载为只读。", "在沙箱内部限制出站流量，而不是在沙箱外围。从攻击者的角度来看，隔离和网络策略是同一种控制手段，而一个网络开放的沙箱就像是一个配有电话的监狱。", "限制资源——CPU、内存、磁盘、实际运行时间（wall-clock）和进程数。资源失控消耗是最先且最常出现的失效模式，而且通常在没有任何对手攻击的情况下就会发生。", "记录跨越边界的行为：哪些文件进入、哪些文件输出、访问了哪些目标地址。只有当您能看清什么通过了边界时，边界才是有用的。" ], "components": [ "隔离原语：容器、microVM 或同等技术，根据工作负载所需的强度进行选择。", "临时生命周期管理，将销毁作为默认操作，而非作为清理步骤。", "限定于任务及其执行期间的机密注入路径。", "在沙箱边界内部应用的网络策略。", "由宿主机强制执行的资源配额和超时限制。", "边界日志记录：输入、输出和目标地址。" ], "benefits": [ "将“智能体运行了恶意内容”这一安全事件转化为一个被废弃的容器。", "使得赋予智能体真正的执行能力变得安全，而这往往是其发挥作用的关键所在。", "既能限制无意的错误，也能防御恶意的攻击——同一种控制手段既能捕获死循环，也能拦截注入的有效载荷（payload）。", "提供了一个干净的观测场所：任务所触及的一切都跨越了同一个边界。" ], "risks": [ "隔离性弱于预期：共享内核并不是防范蓄意逃逸的安全边界，将容器等同于 microVM 是一种概念性错误。", "为了方便而暗中引入凭据——一个挂载的配置文件就会让整个模式功亏一篑。", "由于重建缓慢，沙箱悄然变得持久化，从而失去了作为安全保障的临时性。", "通过残留的共享界面逃逸：挂载的卷、编排器 API，或沙箱仍可访问的网络。" ], "whenNot": [ "无执行能力的只读智能体，此时无需隔离，且引入沙箱无法带来任何收益。", "对延迟极其敏感的内联路径，此时环境启动时间占用了任务的大部分时间，而更窄范围的控制（如受限的解释器、纯函数）会更合适。", "当沙箱需要其本应扣留的凭据时，这表明该任务应该被拆分，而不是被隔离。" ], "examples": [ "一个编码智能体，为每个任务克隆到一个全新的容器中，挂载代码仓库，不提供云凭据，且出站流量限制在包注册表。恶意依赖项的安装只会销毁该容器，而不会产生其他影响。", "一个数据分析智能体，在 microVM 中执行生成的 Python 代码，输入数据集挂载为只读，完全断网，并设有实际运行时间上限。生成的代码可能会出错，但绝不会产生高昂开销或泄露数据。", "一个文档处理智能体，在一次性环境中打开不可信的 PDF 文件，因为上传文件中的解析器漏洞是通往宿主机的真实路径，且该文件来自外部。" ], "kpis": [ { "metric": "沙箱化执行的比例", "note": "覆盖率指标。无论沙箱化部分的表现如何，在沙箱外运行的任何内容才代表了实际的安全态势。" }, { "metric": "沙箱生命周期", "note": "环境存活的时间。生命周期的延长意味着临时性正在向持久化侵蚀。" }, { "metric": "触及资源上限的次数", "note": "因配额或超时而停止的任务。这有助于识别失控的生成内容以及设置过紧的实际限制。" }, { "metric": "运行时存在的机密数量", "note": "环境中可访问的凭据数量。目标是任务所需的最小值，通常为零。" } ], "failureModes": [ "便利性挂载：为了让任务不再报错而挂载用户主目录、凭据文件或套接字（socket）。", "持久化复用：由于重建成本过高，环境不再针对每个任务独立创建，导致状态和安全漏洞得以存留。", "边界内开放出站流量：在网络自由开放的情况下，强隔离仅仅是对文件系统的限制。", "编排器可达性：沙箱可以调用管理沙箱的 API，这属于设计上的逃逸，而非通过漏洞利用实现的逃逸。" ], "lessons": [ "在信任生成内容之前，先隔离执行。沙箱是允许智能体运行代码的合理前提。", "临时性才是安全属性；单靠隔离只能延缓问题的发生。", "不存在的凭据无法被窃取——这也是发生逃逸后唯一有效的控制手段。", "大多数沙箱的触发都是无意的错误，而非恶意攻击。这恰恰证明了该模式正在发挥作用，而不是它没有必要。" ], "faqs": [ { "q": "容器足够安全吗，还是我需要使用 microVM？", "a": "这取决于内部运行的内容。对于存在注入风险的自有代码，一个无凭据且限制出站流量的加固容器通常是相称的。对于来自不可信来源的任意代码，应假定共享内核可以被逃逸，并使用 microVM。" }, { "q": "这与最小特权工具有何不同？", "a": "最小特权限制了智能体可以请求的内容；而沙箱限制了在代码实际运行后发生的事情。前者管理请求，后者管理执行环境，运行代码的智能体两者都需要。" }, { "q": "沙箱会降低运行速度。这值得吗？", "a": "请与替代方案的成本进行对比，而不是与零成本对比。大部分延迟来自于环境启动，这可以通过资源池和预热镜像在很大程度上消除；而它所防范的失效后果是运行智能体的宿主机被攻破。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/semantic-caching", "api_url": "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." } ] }, "fr": { "name": "Mise en cache sémantique", "summary": "La mise en cache sémantique stocke les réponses passées des modèles et les réutilise lorsqu'une nouvelle requête est sémantiquement similaire à une précédente — en faisant correspondre le sens via des plongements (embeddings), et non par texte exact. Elle réduit les coûts et la latence pour les requêtes répétitives ou quasi-identiques fréquentes en production.", "problem": "De nombreuses requêtes en production sont des paraphrases de requêtes déjà traitées, de sorte que réexécuter le modèle complet pour chacune d'elles gaspille du budget et de la latence.", "context": "Utilisez la mise en cache sémantique lorsque le trafic contient de nombreuses questions similaires ou répétées et que les réponses sont suffisamment stables pour être réutilisées — FAQ, support, assistants de documentation.", "solution": [ "Générez un embedding pour chaque requête entrante et recherchez dans un cache d'embeddings de requêtes antérieures. Si une entrée suffisamment similaire existe (au-dessus d'un seuil de similitude), renvoyez sa réponse stockée ; sinon, appelez le modèle et stockez la nouvelle paire.", "Ajustez soigneusement le seuil de similitude : un seuil trop lâche renvoie des réponses erronées pour des questions subtilement différentes ; un seuil trop strict manque des correspondances valides. Ajoutez des TTL et de l'invalidation pour éviter que les réponses mises en cache ne deviennent obsolètes." ], "components": [ "Embedding de la requête", "Cache vectoriel", "Seuil de similitude", "TTL / invalidation", "Repli sur le modèle" ], "benefits": [ "Coût réduit en évitant les appels répétés au modèle.", "Latence réduite lors des accès au cache (cache hits).", "Réponses plus cohérentes pour des questions similaires." ], "risks": [ "Un seuil trop lâche renvoie des réponses erronées mises en cache.", "Cache obsolète en l'absence de TTL ou d'invalidation.", "Les réponses personnalisées ou sensibles au facteur temps se prêtent mal à la mise en cache." ], "whenNot": [ "Lorsque la plupart des requêtes sont uniques.", "Lorsque les réponses dépendent de données fraîches, spécifiques à l'utilisateur ou au temps.", "Lorsque même de légères divergences sont inacceptables." ], "examples": [ "Réutiliser la réponse à « comment réinitialiser mon mot de passe » à travers ses nombreuses formulations.", "Mettre en cache les questions fréquentes de la documentation dans un assistant de support.", "Court-circuiter les questions d'analyse identiques et répétées." ], "productionEvidence": { "context": "Déploiement OpenClaw local-first à opérateur unique observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des traces de trajectoire de l'agent lui-même.", "scenario": "La mise en cache des prompts et du contexte est conçue avec des marqueurs cache_control, ainsi qu'un cache de fichiers d'espace de travail et un cache de routes, de sorte que la structure répétée soit servie depuis le cache.", "technology": "Injection cache_control d'Anthropic sur le système et les messages, passerelle OpenRouter, cache de fichiers d'espace de travail, cache de routes et comptabilisation des coûts de lecture/écriture du cache (cache_read/write).", "load": "28,1 millions de tokens au total sur 57 jours, dont environ 19,6 millions servis en lecture de cache.", "results": "Environ 70 % des tokens ont été servis depuis le cache, maintenant le coût mixte à 15,21 $ par million de tokens (41 $ de lecture de cache contre 374 $ d'entrées fraîches). Déploiement local-first à opérateur unique — ce ratio reflète la répétitivité de cette charge de travail ; mesurez la vôtre." }, "kpis": [ { "metric": "Taux de succès du cache", "note": "Part des requêtes servies depuis le cache ; le levier pour réduire à la fois les coûts et la latence." }, { "metric": "Taux de faux positifs", "note": "Fréquence à laquelle une correspondance sémantiquement « similaire » renvoie une réponse erronée ou obsolète — le risque central de la mise en cache par le sens." }, { "metric": "Coût et latence économisés par succès", "note": "Tokens et temps évités lors des accès au cache, le bénéfice obtenu en contrepartie du risque de faux positif." }, { "metric": "Calibrage du seuil de similitude", "note": "Détermine si le seuil de correspondance équilibre le taux de succès et les faux positifs ; un seuil trop lâche nuit à la qualité, un seuil trop strict annule les économies." } ], "failureModes": [ "Faux positifs : deux requêtes sont proches dans l'espace d'embedding mais nécessitent des réponses différentes, de sorte que le cache renvoie une réponse erronée.", "Obsolescence : les réponses mises en cache deviennent périmées alors que les faits sous-jacents changent.", "Mauvais réglage du seuil : un seuil trop lâche renvoie des réponses erronées, un seuil trop strict ne génère presque aucun succès.", "Empoisonnement du cache : une mauvaise réponse est mise en cache puis servie de manière répétée." ], "lessons": [ "Ajustez le seuil de similitude par rapport au trafic réel ; c'est le paramètre décisif.", "Ne mettez jamais en cache lorsque la fraîcheur ou l'exactitude est critique sans stratégie d'invalidation.", "Valisez ou échantillonnez les accès au cache pour détecter les fausses correspondances avant les utilisateurs.", "Restreignez la portée des caches (par locataire, par contexte) pour éviter de divulguer une mauvaise réponse à d'autres utilisateurs." ], "faqs": [ { "q": "En quoi cela diffère-t-il d'un cache normal ?", "a": "Un cache normal fait correspondre des clés exactes ; un cache sémantique fait correspondre par le sens à l'aide d'embeddings, de sorte que les questions paraphrasées génèrent tout de même un succès." }, { "q": "Quel est le risque principal ?", "a": "Un seuil de similitude trop lâche renvoie une réponse mise en cache pour une question qui est en réalité différente. Ajustez le seuil et validez sur du trafic réel." }, { "q": "Comment éviter les réponses obsolètes ?", "a": "Définissez des TTL et invalidez les entrées lorsque les données sous-jacentes changent ; évitez de mettre en cache des réponses personnalisées ou sensibles au facteur temps." } ] }, "de": { "name": "Semantisches Caching", "summary": "Semantisches Caching speichert frühere Modellantworten und verwendet sie wieder, wenn eine neue Anfrage einer vorherigen semantisch ähnlich ist – der Abgleich erfolgt über die Bedeutung mittels Embeddings, nicht über exakten Text. Dies senkt Kosten und Latenz bei sich wiederholenden oder nahezu identischen Abfragen, wie sie in der Produktion häufig vorkommen.", "problem": "Viele Abfragen in der Produktion sind Paraphrasen bereits beantworteter Fragen, sodass die erneute Ausführung des vollständigen Modells für jede Anfrage unnötig Kosten und Latenz verursacht.", "context": "Verwenden Sie semantisches Caching, wenn der Traffic viele ähnliche oder wiederholte Fragen enthält und die Antworten stabil genug für eine Wiederverwendung sind – z. B. bei FAQs, im Support oder bei Dokumentations-Assistenten.", "solution": [ "Erstellen Sie ein Embedding für jede eingehende Anfrage und durchsuchen Sie einen Cache nach früheren Anfrage-Embeddings. Wenn ein ausreichend ähnlicher Eintrag existiert (oberhalb eines Ähnlichkeitsschwellenwerts), geben Sie die gespeicherte Antwort zurück; andernfalls rufen Sie das Modell auf und speichern Sie das neue Paar.", "Stimmen Sie den Ähnlichkeitsschwellenwert sorgfältig ab: Ein zu niedriger Schwellenwert liefert falsche Antworten auf leicht unterschiedliche Fragen; ein zu strenger Schwellenwert verfehlt gültige Treffer. Fügen Sie TTLs und Invalidierungen hinzu, damit zwischengespeicherte Antworten nicht veralten." ], "components": [ "Embedding der Anfrage", "Vektor-Cache", "Ähnlichkeitsschwellenwert", "TTL / Invalidierung", "Fallback auf das Modell" ], "benefits": [ "Geringere Kosten durch die Vermeidung wiederholter Modellaufrufe.", "Geringere Latenz bei Cache-Treffern.", "Konsistentere Antworten auf ähnliche Fragen." ], "risks": [ "Ein zu niedriger Schwellenwert liefert falsche zwischengespeicherte Antworten.", "Veralteter Cache ohne TTL oder Invalidierung.", "Personalisierte oder zeitkritische Antworten lassen sich schlecht zwischenspeichern." ], "whenNot": [ "Wenn die meisten Anfragen einzigartig sind.", "Wenn Antworten von aktuellen, benutzer- oder zeitspezifischen Daten abhängen.", "Wenn selbst geringfügige Abweichungen inakzeptabel sind." ], "examples": [ "Wiederverwendung der Antwort auf „Wie setze ich mein Passwort zurück“ über viele verschiedene Formulierungen hinweg.", "Zwischenspeichern häufiger Dokumentationsfragen in einem Support-Assistenten.", "Abkürzen von wiederholten, identischen Analysefragen." ], "productionEvidence": { "context": "Lokale OpenClaw-Bereitstellung für einen einzelnen Operator, beobachtet über 57 Tage (161 Sitzungen / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Prompt- und Kontext-Caching ist mit `cache_control`-Markern sowie einem Workspace-Datei-Cache und einem Route-Cache implementiert, sodass wiederholte Strukturen aus dem Cache bedient werden.", "technology": "Anthropic `cache_control`-Injektion auf System und Nachrichten, OpenRouter-Passthrough, Workspace-Datei-Cache, Route-Cache und `cache_read`/`write`-Kostenabrechnung.", "load": "Insgesamt 28,1 Mio. Token über 57 Tage, wovon ca. 19,6 Mio. als Cache-Read bedient wurden.", "results": "Etwa 70 % der Token wurden aus dem Cache bedient, wodurch die Mischkosten bei 15,21 $ pro 1 Mio. Token gehalten wurden (41 $ für Cache-Reads gegenüber 374 $ für neue Eingaben). Lokale Bereitstellung für einen einzelnen Operator – das Verhältnis spiegelt die Wiederholungsrate dieses Workloads wider; messen Sie Ihre eigene." }, "kpis": [ { "metric": "Cache-Hit-Rate", "note": "Anteil der aus dem Cache bedienten Anfragen; der Hebel für Kosten- und Latenzeinsparungen." }, { "metric": "False-Hit-Rate", "note": "Wie oft ein semantisch „ähnlicher“ Treffer eine falsche oder veraltete Antwort liefert – das zentrale Risiko beim Caching nach Bedeutung." }, { "metric": "Eingesparte Kosten und Latenz pro Treffer", "note": "Vermeidbare Token und Zeit bei Cache-Treffern – der Vorteil, für den Sie das Risiko von False-Hits in Kauf nehmen." }, { "metric": "Kalibrierung des Ähnlichkeitsschwellenwerts", "note": "Ob der Übereinstimmungsschwellenwert die Hit-Rate gegen False-Hits ausbalanciert; ein zu niedriger Schwellenwert schadet der Qualität, ein zu strenger verhindert Einsparungen." } ], "failureModes": [ "False-Hits: Zwei Anfragen sind im Embedding-Raum ähnlich, erfordern aber unterschiedliche Antworten, sodass der Cache eine falsche Antwort zurückgibt.", "Veraltung: Zwischengespeicherte Antworten veralten, während sich die zugrunde liegenden Fakten ändern.", "Fehlkalibrierung des Schwellenwerts: Ein zu niedriger Schwellenwert liefert falsche Antworten, ein zu strenger führt zu fast keinen Treffern.", "Cache-Poisoning: Eine fehlerhafte Antwort wird zwischengespeichert und anschließend wiederholt ausgegeben." ], "lessons": [ "Stimmen Sie den Ähnlichkeitsschwellenwert anhand des echten Datenverkehrs ab; er ist der entscheidende Parameter.", "Führen Sie kein Caching durch, wenn Aktualität oder Korrektheit kritisch sind, es sei denn, Sie haben eine Invalidierungsstrategie.", "Validieren oder stichprobenartig prüfen Sie Cache-Treffer, um falsche Übereinstimmungen zu erkennen, bevor die Benutzer es tun.", "Grenzen Sie Caches eng ein (pro Mandant, pro Kontext), um zu verhindern, dass falsche Antworten an andere Benutzer weitergegeben werden." ], "faqs": [ { "q": "Wie unterscheidet sich dies von einem normalen Cache?", "a": "Ein normaler Cache gleicht exakte Schlüssel ab; ein semantischer Cache gleicht die Bedeutung mithilfe von Embeddings ab, sodass auch umformulierte Fragen zu Treffern führen." }, { "q": "Was ist das Hauptrisiko?", "a": "Ein zu niedriger Ähnlichkeitsschwellenwert liefert eine zwischengespeicherte Antwort für eine Frage, die eigentlich anders ist. Stimmen Sie den Schwellenwert ab und validieren Sie ihn anhand des echten Datenverkehrs." }, { "q": "Wie vermeide ich veraltete Antworten?", "a": "Setzen Sie TTLs und invalidieren Sie Einträge, wenn sich die zugrunde liegenden Daten ändern; vermeiden Sie das Zwischenspeichern von personalisierten oder zeitkritischen Antworten." } ] }, "ja": { "name": "セマンティックキャッシュ", "summary": "セマンティックキャッシュは、過去のモデルの応答を保存し、新しいリクエストが以前のリクエストと意味的に類似している場合にそれを再利用します。これは、正確なテキストではなく、埋め込み（embeddings）を介して意味でマッチングを行います。本番環境でよく見られる、繰り返されるクエリやほぼ重複するクエリのコストとレイテンシーを削減します。", "problem": "本番環境のクエリの多くは、すでに回答されたクエリの言い換えであるため、毎回フルモデルを再実行するとコストとレイテンシーが無駄になります。", "context": "トラフィックに類似した質問や繰り返される質問が多く含まれ、回答が再利用できるほど安定している場合（FAQ、サポート、ドキュメントアシスタントなど）に、セマンティックキャッシュを使用します。", "solution": [ "受信した各リクエストを埋め込み（Embedding）に変換し、過去のリクエストの埋め込みキャッシュを検索します。十分に類似したエントリが存在する場合（類似度しきい値以上）、保存されているレスポンスを返します。そうでない場合はモデルを呼び出し、新しいペアを保存します。", "類似度しきい値は慎重に調整してください。緩すぎると、微妙に異なる質問に対して誤った回答を返してしまい、厳しすぎると、有効なヒットを逃してしまいます。キャッシュされた回答が古くならないよう、TTLと無効化（invalidation）を追加します。" ], "components": [ "リクエストの埋め込み（Embedding）", "ベクトルキャッシュ", "類似度しきい値", "TTL / 無効化", "モデルへのフォールバック" ], "benefits": [ "モデルの繰り返し呼び出しを避けることによるコスト削減。", "キャッシュヒット時のレイテンシ低下。", "類似した質問に対する回答の一貫性の向上。" ], "risks": [ "しきい値が緩いと、誤ったキャッシュ回答を返してしまう。", "TTLや無効化がないと、キャッシュが古くなる。", "パーソナライズされた回答や時間経過に敏感な回答は、キャッシュに適さない。" ], "whenNot": [ "ほとんどのクエリが一意である場合。", "回答が、最新のデータ、ユーザー固有のデータ、または時間固有のデータに依存する場合。", "わずかな不一致も許容されない場合。" ], "examples": [ "「パスワードの再設定方法」という質問に対する回答を、多様な言い回しにわたって再利用する。", "サポートアシスタントにおいて、ドキュメントに関する一般的な質問をキャッシュする。", "繰り返される同一の分析質問をショートサーキット（早期リターン）する。" ], "productionEvidence": { "context": "57日間にわたり観測された、シングルオペレーターかつローカルファーストのOpenClawデプロイメント（161セッション / 2,776ターン）。エージェント自身のトラジェクトリトレースから集計。", "scenario": "プロンプトとコンテキストのキャッシュは、`cache_control`マーカーに加えて、ワークスペースファイルキャッシュおよびルートキャッシュを使用して設計されており、繰り返される構造はキャッシュから提供されます。", "technology": "systemおよびmessagesへのAnthropic `cache_control`インジェクション、OpenRouterパススルー、ワークスペースファイルキャッシュ、ルートキャッシュ、および`cache_read`/`write`コスト会計。", "load": "57日間で合計2,810万トークン。そのうち約1,960万トークンが`cache-read`として提供されました。", "results": "トークンの約70%がキャッシュから提供され、ブレンドコストを100万トークンあたり15.21ドルに抑えました（`cache-read`が41ドルに対し、新規入力が374ドル）。シングルオペレーターかつローカルファーストのデプロイメントにおける結果であり、この比率は当該ワークロードの反復性を反映しています。ご自身の環境で測定してください。" }, "kpis": [ { "metric": "キャッシュヒット率", "note": "キャッシュから提供されたリクエストの割合。コスト削減とレイテンシ短縮の両方を左右するレバーとなります。" }, { "metric": "誤ヒット率", "note": "意味的に「類似している」ヒットが、誤った回答や古い回答を返す頻度。意味によるキャッシュにおける中心的なリスクです。" }, { "metric": "ヒットあたりの削減コストとレイテンシ", "note": "キャッシュヒットによって回避されたトークンと時間。誤ヒットのリスクと引き換えに得られるメリットです。" }, { "metric": "類似度しきい値のキャリブレーション", "note": "一致しきい値がヒット率と誤ヒットのバランスを保てているかどうか。緩すぎると品質が低下し、厳しすぎるとコスト削減効果が失われます。" } ], "failureModes": [ "誤ヒット：2つのクエリが埋め込み空間で類似しているものの、異なる回答を必要とするため、キャッシュが誤った回答を返してしまう。", "陳腐化：基礎となる事実が変化しているにもかかわらず、キャッシュされた回答が古いままである。", "しきい値の調整ミス：緩すぎると誤った回答を返し、厳しすぎるとほとんどヒットしなくなる。", "キャッシュ汚染：不適切な回答がキャッシュされ、その後繰り返し提供されてしまう。" ], "lessons": [ "実際のトラフィックに合わせて類似度しきい値を調整してください。これは成否を分ける極めて重要なパラメータです。", "最新性や正確性が極めて重要な場合、無効化戦略なしにキャッシュを行ってはなりません。", "キャッシュヒットを検証またはサンプリングし、ユーザーが気づく前に誤った一致を検出します。", "ユーザー間で誤った回答が漏洩するのを防ぐため、キャッシュのスコープを狭く（テナントごと、コンテキストごとなど）制限します。" ], "faqs": [ { "q": "通常のキャッシュと何が違うのですか？", "a": "通常のキャッシュは正確なキーを一致させますが、セマンティックキャッシュは埋め込みを使用して意味で一致させるため、言い換えられた質問でもヒットします。" }, { "q": "主なリスクは何ですか？", "a": "類似度しきい値が緩すぎると、実際には異なる質問に対してキャッシュされた回答を返してしまいます。しきい値を調整し、実際のトラフィックで検証してください。" }, { "q": "古い回答を避けるにはどうすればよいですか？", "a": "TTLを設定し、基礎となるデータが変更されたときにエントリを無効化します。パーソナライズされた回答や時間経過に敏感なレスポンスのキャッシュは避けてください。" } ] }, "zh": { "name": "语义缓存", "summary": "语义缓存存储以往的模型响应，并在新请求与先前请求语义相似时重新使用它们——通过嵌入（embeddings）按含义进行匹配，而非精确文本匹配。它降低了生产环境中常见的重复或近乎重复查询的成本和延迟。", "problem": "许多生产环境中的查询只是对已回答问题的改写，因此对每个查询都重新运行完整模型会浪费成本并增加延迟。", "context": "当流量中包含许多相似或重复的问题，且答案足够稳定可供复用时（如常见问题解答 FAQ、技术支持、文档助手），请使用语义缓存。", "solution": [ "对每个传入的请求进行向量化（Embed），并在先前请求的向量缓存中进行搜索。如果存在足够相似的条目（高于相似度阈值），则返回其存储的响应；否则调用模型并存储这一新的请求-响应对。", "仔细调整相似度阈值：过宽的阈值会针对有细微差别的提问返回错误的答案；过严的阈值则会漏掉有效的缓存命中。添加 TTL 和失效机制，以防缓存的答案过期。" ], "components": [ "请求的向量化（Embedding）", "向量缓存", "相似度阈值", "TTL / 失效机制", "回退到模型" ], "benefits": [ "通过避免重复的模型调用来降低成本。", "缓存命中时延迟更低。", "对相似问题提供更一致的回答。" ], "risks": [ "过宽的阈值会提供错误的缓存答案。", "若没有 TTL 或失效机制，缓存会过期变质。", "个性化或时效性强的回答缓存效果较差。" ], "whenNot": [ "当大多数查询都是唯一的时候。", "当回答依赖于最新的、特定于用户或特定于时间的数据时。", "当即使是微小的偏差也无法接受时。" ], "examples": [ "在“如何重置密码”的多种不同表述中复用同一个答案。", "在支持助手（Support Assistant）中缓存常见的文档问题。", "对重复的相同分析问题进行快速短路处理（直接返回缓存）。" ], "productionEvidence": { "context": "在 57 天内观察到的单操作员、本地优先的 OpenClaw 部署（161 个会话 / 2,776 轮对话），数据聚合自智能体自身的轨迹追踪。", "scenario": "提示词和上下文缓存是通过 cache_control 标记、工作区文件缓存以及路由缓存来构建的，因此重复的结构可以直接从缓存中提供。", "technology": "在系统和消息上注入 Anthropic cache_control、OpenRouter 透传、工作区文件缓存、路由缓存，以及 cache_read/write 成本核算。", "load": "57 天内总计 28.1M token，其中约 19.6M token 通过缓存读取（cache-read）提供。", "results": "大约 70% 的 token 由缓存提供，将混合成本控制在每 1M token 15.21 美元（缓存读取费用为 41 美元，而全新输入费用为 374 美元）。这是单操作员、本地优先的部署——该比例反映了此工作负载'的重复性；请根据您自己的情况进行评估。" }, "kpis": [ { "metric": "缓存命中率", "note": "从缓存中提供服务的请求比例；这是节省成本和降低延迟的关键杠杆。" }, { "metric": "误命中率", "note": "语义上“相似”的命中返回错误或过期答案的频率——这是按含义进行缓存的核心风险。" }, { "metric": "每次命中节省的成本和延迟", "note": "缓存命中时省去的 token 和时间，这是您用误命中风险换取的收益。" }, { "metric": "相似度阈值校准", "note": "匹配阈值是否平衡了命中率与误命中率；过宽会损害质量，过严则会抹杀节省的效果。" } ], "failureModes": [ "误命中：两个查询在向量空间中相似，但需要不同的答案，导致缓存返回了错误的结果。", "过期：底层事实已发生变化，而缓存的答案已过时。", "阈值微调不当：过宽会返回错误答案，过严则几乎无法命中。", "缓存污染：错误的答案被缓存，随后被反复提供。" ], "lessons": [ "根据实际流量调整相似度阈值；这是决定成败的关键参数。", "在时效性或正确性至关重要的场景下，如果没有失效策略，切勿进行缓存。", "对缓存命中进行验证或抽样，以便在用户发现之前捕获错误的匹配。", "严格限制缓存范围（按租户、按上下文），以避免在不同用户之间泄露错误的答案。" ], "faqs": [ { "q": "这与普通缓存有什么区别？", "a": "普通缓存匹配精确的键；语义缓存则使用向量化（Embeddings）按含义进行匹配，因此换个说法的提问仍能命中。" }, { "q": "主要风险是什么？", "a": "过宽的相似度阈值会针对实际上不同的问题返回缓存的答案。请调整阈值并在实际流量中进行验证。" }, { "q": "如何避免过期的答案？", "a": "设置 TTL 并在底层数据发生变化时使条目失效；避免缓存个性化或时效性强的响应。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/supervisor-agent", "api_url": "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." } ] }, "fr": { "name": "Agent superviseur", "summary": "Un agent superviseur est un coordinateur persistant qui gère une équipe de sous-agents spécialisés. Il lit l'état de la conversation, décide quel spécialiste doit intervenir ensuite, lui oriente les messages et intègre les résultats renvoyés pour atteindre l'objectif. Contrairement à un décomposeur ponctuel (one-shot), le superviseur reste actif tout au long de nombreux tours, déléguant par compétence et replanifiant jusqu'à ce que la tâche soit accomplie ou restituée à l'utilisateur.", "problem": "Un agent unique doté de trop nombreux outils, instructions et domaines perd sa concentration : son prompt s'alourdit, la sélection des outils se dégrade et il confond des sujets sans rapport. Les flux de travail réels nécessitent des expertises différentes à chaque étape (recherche, codage, facturation, conformité), mais aucun agent unique et plat ne parvient à choisir de manière fiable la bonne compétence au bon moment ni à maintenir la cohérence de longues interactions multi-étapes.", "context": "Utilisez un superviseur lorsque le travail fait appel à plusieurs compétences spécialisées distinctes et réutilisables qui doivent collaborer au cours d'une conversation ou d'une boucle multi-tours, lorsque les décisions d'aiguillage dépendent d'un état évolutif plutôt que d'un plan fixe, et lorsque vous avez besoin d'un point central clair pour appliquer des politiques, gérer les transferts et observer quel agent a fait quoi. Cela convient mieux aux équipes hétérogènes d'agents qu'à des travailleurs parallèles uniformes.", "solution": [ "Le superviseur détient la boucle de contrôle et l'état partagé de la conversation. À chaque tour, il inspecte les derniers messages et l'objectif, puis décide s'il doit répondre directement, déléguer à un spécialiste désigné ou terminer. La délégation se fait par compétence : chaque sous-agent a un périmètre déclaré (par exemple, un agent de code, un agent de données, un agent de connaissances), et le superviseur oriente la partie pertinente du contexte vers l'élu. Le spécialiste exécute sa propre boucle d'outils ciblée et renvoie un résultat ou une demande de clarification, que le superviseur enregistre avant de décider de l'étape suivante.", "Le contrôle revient au superviseur après chaque tour de spécialiste, de sorte qu'il reste l'unique point de décision au lieu de laisser les agents s'appeler librement entre eux. Le superviseur intègre les résultats partiels, résout les conflits entre spécialistes, décide quand un objectif est atteint et quand restituer la main à l'utilisateur. Des garde-fous tels que des budgets d'étapes, des règles de transition autorisées et des conditions de fin explicites empêchent la boucle de tourner indéfiniment. Des messages de transfert structurés et une trace partagée rendent chaque délégation auditable, permettant aux équipes de voir qui a été sollicité pour quoi et pourquoi." ], "components": [ "Superviseur (routeur/planificateur)", "Sous-agents spécialistes avec périmètres déclarés", "Stockage partagé de la conversation/de l'état", "Protocole de transfert et schéma de message", "Budget d'étapes et garde-fou de terminaison", "Trace et observabilité par agent" ], "benefits": [ "Spécialistes ciblés avec des prompts plus courts et plus propres", "Aiguillage centralisé et application des politiques", "Agents modulaires pouvant évoluer indépendamment", "Piste d'audit claire de qui a fait quoi" ], "risks": [ "Boucles de transfert infinies ou en ping-pong", "La surcharge de coordination gonfle la latence et le coût", "Le superviseur devient un goulot d'étranglement pour l'aiguillage", "La perte de contexte lors des transferts dégrade la qualité" ], "whenNot": [ "Une seule compétence gère l'intégralité de la tâche", "Une distribution parallèle fixe convient mieux (orchestrateur-travailleurs)", "Les budgets de latence ou de coût interdisent les étapes supplémentaires" ], "examples": [ "Aiguillage du support client entre les spécialistes de la facturation, de la technique et des comptes", "Tâche logicielle répartie entre des agents de codage, de test et de documentation", "Assistant de recherche déléguant à des agents de recherche, d'analyse et de rédaction" ], "kpis": [ { "metric": "Taux de réussite des tâches / d'atteinte des objectifs", "note": "Part des sessions atteignant le résultat escompté sans intervention humaine ; le principal indicateur de qualité pour l'équipe de supervision." }, { "metric": "Transferts par tâche résolue", "note": "Nombre moyen de délégations jusqu'à l'achèvement ; surveillez toute dérive à la hausse, signe d'indécision ou d'emballement de l'aiguillage, et non d'un travail plus riche." }, { "metric": "Surcharge de coordination", "note": "Tokens, appels et latence supplémentaires imputables au superviseur par rapport à un agent unique ; un bon résultat signifie que l'aiguillage justifie son coût." }, { "metric": "Précision du routage", "note": "Fraction des délégations envoyées au bon spécialiste dès la première tentative, évaluée par rapport à des cas étiquetés." } ], "failureModes": [ "Deux agents se renvoient le travail mutuellement sans progresser jusqu'à ce qu'un budget interrompe la boucle", "Le superviseur oriente mal la demande vers le mauvais spécialiste et ne parvient jamais à reprendre le fil", "Le contexte critique est perdu lors du transfert, de sorte que le spécialiste résout le mauvais problème", "Les résultats partiels des spécialistes entrent en conflit et le superviseur les fusionne de manière incohérente" ], "lessons": [ "Imposer des budgets d'étapes stricts et une terminaison explicite pour que les boucles se terminent toujours", "Structurer les transferts avec une intention et une portée claires, plutôt que de simples transferts de messages bruts", "Maintenir des périmètres de spécialistes étroits et sans chevauchement pour réduire l'ambiguïté du routage", "Instrumenter chaque délégation ; impossible de déboguer une boucle multi-agent invisible" ], "faqs": [ { "q": "En quoi cela diffère-t-il du modèle orchestrateur-travailleurs ?", "a": "Le modèle orchestrateur-travailleurs décompose une tâche en appels parallèles à des travailleurs souvent homogènes, puis fusionne leurs résultats. Un superviseur est un coordinateur persistant qui gère des spécialistes hétérogènes au sein d'une boucle à plusieurs tours, réévaluant le routage à mesure que l'état évolue plutôt que d'exécuter un plan fixe." }, { "q": "Comment éviter les boucles de transfert infinies ?", "a": "Renvoyer le contrôle au superviseur après chaque tour de spécialiste, interdire les appels directs de pair à pair, définir un budget d'étapes ou de jetons, spécifier les transitions autorisées et ajouter des conditions de terminaison explicites pour empêcher la boucle de tourner indéfiniment." }, { "q": "Quand un spécialiste doit-il redonner la main au superviseur ?", "a": "Dès qu'il termine sa tâche définie, a besoin d'une capacité qu'il ne possède pas, rencontre une ambiguïté nécessitant une décision, ou détecte qu'il n'est pas l'agent approprié pour la requête. Le superviseur intègre alors les informations et choisit l'étape suivante." } ] }, "de": { "name": "Supervisor-Agent", "summary": "Ein Supervisor-Agent ist ein persistenter Koordinator, der ein Team von spezialisierten Sub-Agenten verwaltet. Er liest den Konversationsstatus, entscheidet, welcher Spezialist als Nächstes agieren soll, leitet Nachrichten an diesen weiter und integriert die zurückgegebenen Ergebnisse im Hinblick auf das Ziel. Im Gegensatz zu einem One-Shot-Decomposer bleibt der Supervisor über viele Turns hinweg in der Schleife, delegiert nach Fähigkeiten und plant neu, bis die Aufgabe erledigt ist oder an den Benutzer zurückgegeben wird.", "problem": "Ein einzelner Agent, dem viele Tools, Anweisungen und Domänen zugewiesen werden, verliert den Fokus: Sein Prompt bläht sich auf, die Tool-Auswahl verschlechtert sich und er verwechselt unzusammenhängende Belange. Reale Workflows erfordern unterschiedliche Fachkenntnisse in verschiedenen Schritten (Recherche, Codierung, Abrechnung, Compliance), aber kein einzelner, flacher Agent wählt zuverlässig die richtige Fähigkeit im richtigen Moment aus oder hält lange, mehrstufige Interaktionen kohärent.", "context": "Verwenden Sie einen Supervisor, wenn die Arbeit mehrere unterschiedliche, wiederverwendbare Spezialistenfähigkeiten umfasst, die über eine mehrstufige Konversation oder Schleife hinweg zusammenarbeiten müssen, wenn Routing-Entscheidungen von einem sich entwickelnden Zustand statt von einem festen Plan abhängen und wenn Sie eine klare, zentrale Stelle benötigen, um Richtlinien durchzusetzen, Handoffs zu verwalten und zu beobachten, welcher Agent was getan hat. Dies eignet sich eher für heterogene Teams von Agenten als für einheitliche, parallele Worker.", "solution": [ "Der Supervisor besitzt die Kontrollschleife und den gemeinsamen Konversationsstatus. Bei jedem Turn prüft er die neuesten Nachrichten und das Ziel und entscheidet dann, ob er direkt antwortet, an einen bestimmten Spezialisten delegiert oder abschließt. Die Delegation erfolgt nach Fähigkeiten: Jeder Sub-Agent hat einen deklarierten Bereich (z. B. ein Code-Agent, ein Daten-Agent, ein Wissens-Agent), und der Supervisor leitet den relevanten Teil des Kontextes an den ausgewählten Agenten weiter. Der Spezialist führt seine eigene, fokussierte Tool-Schleife aus und gibt ein Ergebnis oder eine Bitte um Klärung zurück, die der Supervisor aufzeichnet, bevor er über den nächsten Schritt entscheidet.", "Die Kontrolle kehrt nach jedem Turn eines Spezialisten zum Supervisor zurück, sodass dieser der einzige Entscheidungspunkt bleibt, anstatt den Agenten zu erlauben, sich gegenseitig frei aufzurufen. Der Supervisor integriert Teilergebnisse, löst Konflikte zwischen Spezialisten, entscheidet, wann ein Ziel erreicht ist, und entscheidet, wann die Kontrolle an den Benutzer zurückgegeben wird. Guardrails wie Schritt-Budgets, Regeln für erlaubte Übergänge und explizite Abbruchbedingungen verhindern, dass die Schleife endlos läuft. Strukturierte Handoff-Nachrichten und ein gemeinsamer Trace machen jede Delegation überprüfbar, sodass Teams sehen können, wer wozu aufgefordert wurde und warum." ], "components": [ "Supervisor (Router/Planer)", "Spezialisierte Sub-Agenten mit deklarierten Bereichen", "Gemeinsamer Konversations-/Statusspeicher", "Handoff-Protokoll und Nachrichtenschema", "Schritt-Budget und Abbruch-Guard", "Trace und Observability pro Agent" ], "benefits": [ "Fokussierte Spezialisten mit kleineren, saubereren Prompts", "Zentralisiertes Routing und Durchsetzung von Richtlinien", "Modulare Agenten, die sich unabhängig voneinander weiterentwickeln können", "Klarer Audit-Trail darüber, wer was getan hat" ], "risks": [ "Unendliche oder Ping-Pong-Handoff-Schleifen", "Koordinations-Overhead erhöht Latenz und Kosten", "Supervisor wird zum Routing-Engpass", "Kontextverlust bei Handoffs beeinträchtigt die Qualität" ], "whenNot": [ "Eine einzige Fähigkeit bewältigt die gesamte Aufgabe", "Ein fester paralleler Fan-out eignet sich besser (Orchestrator-Worker)", "Latenz- oder Kostenbudgets verbieten zusätzliche Hops" ], "examples": [ "Kundensupport-Routing über Spezialisten für Abrechnung, Technik und Konten", "Aufteilung von Softwareaufgaben auf Codierungs-, Test- und Dokumentations-Agenten", "Recherche-Assistent, der an Such-, Analyse- und Schreib-Agenten delegiert" ], "kpis": [ { "metric": "Aufgabenerfolgs- / Zielerreichungsrate", "note": "Anteil der Sitzungen, die das gewünschte Ergebnis ohne menschliches Eingreifen erreichen; das wichtigste Qualitätssignal für das Supervisor-Team." }, { "metric": "Handoffs pro gelöster Aufgabe", "note": "Durchschnittliche Delegationen bis zum Abschluss; achten Sie auf einen Aufwärtstrend, der auf Unentschlossenheit oder Routing-Thrashing hindeutet, nicht auf produktivere Arbeit." }, { "metric": "Koordinations-Overhead", "note": "Zusätzliche Token, Aufrufe und Latenzzeiten, die dem Supervisor im Vergleich zu einem einzelnen Agenten zuzuschreiben sind; ein guter Wert bedeutet, dass das Routing seine Kosten wert ist." }, { "metric": "Routing-Genauigkeit", "note": "Anteil der Delegierungen, die beim ersten Versuch an den richtigen Spezialisten gesendet wurden, gemessen an gelabelten Fällen." } ], "failureModes": [ "Zwei Agenten übergeben sich gegenseitig Arbeit hin und her, ohne Fortschritt zu erzielen, bis ein Budget den Loop abbricht", "Der Supervisor leitet fälschlicherweise an den falschen Spezialisten weiter und findet nie wieder zum ursprünglichen Thread zurück", "Kritischer Kontext geht bei der Übergabe verloren, sodass der Spezialist das falsche Problem löst", "Teilergebnisse der Spezialisten stehen im Konflikt zueinander und der Supervisor führt sie inkohärent zusammen" ], "lessons": [ "Harte Schritt-Budgets und explizite Abbruchbedingungen erzwingen, damit Loops immer enden", "Übergaben strukturiert gestalten, mit Absicht und Scope, statt roher Message-Dumps", "Den Scope von Spezialisten eng und überschneidungsfrei halten, um Routing-Mehrdeutigkeiten zu reduzieren", "Jede Delegierung instrumentieren; man kann einen Multi-Agenten-Loop nicht debuggen, den man nicht sehen kann" ], "faqs": [ { "q": "Wie unterscheidet sich dies von Orchestrator-Worker-Mustern?", "a": "Orchestrator-Worker zerlegt eine Aufgabe in parallele, oft homogene Worker-Aufrufe und führt sie zusammen. Ein Supervisor ist ein persistenter Koordinator über heterogene Spezialisten hinweg in einem Multi-Turn-Loop, der das Routing bei jeder Zustandsänderung neu entscheidet, anstatt einen festen Plan auszuführen." }, { "q": "Wie verhindere ich endlose Übergabe-Loops?", "a": "Leiten Sie die Kontrolle nach jedem Spezialisten-Turn zurück an den Supervisor, verbieten Sie freie Peer-to-Peer-Aufrufe, legen Sie ein Schritt- oder Token-Budget fest, definieren Sie erlaubte Übergänge und fügen Sie explizite Abbruchbedingungen hinzu, damit der Loop nicht unendlich läuft." }, { "q": "Wann sollte ein Spezialist die Kontrolle an den Supervisor zurückgeben?", "a": "Immer dann, wenn er seine zugewiesene Aufgabe abgeschlossen hat, eine Fähigkeit benötigt, die er nicht besitzt, auf eine Mehrdeutigkeit stößt, die eine Entscheidung erfordert, oder feststellt, dass er der falsche Agent für die Anfrage ist. Der Supervisor integriert dann die Ergebnisse und wählt den nächsten Schritt." } ] }, "ja": { "name": "スーパーバイザーエージェント", "summary": "スーパーバイザーエージェントは、専門化されたサブエージェントのチームを管理する永続的なコーディネーターです。会話の状態を読み取り、次にどのスペシャリストが動作すべきかを決定し、メッセージをルーティングし、返された結果を統合して目標に向かって進めます。ワンショットのデコンポーザー（分解器）とは異なり、スーパーバイザーは多数のターンにわたってループ内にとどまり、機能ごとに委任し、タスクが完了するかユーザーに返されるまで再計画を行います。", "problem": "単一のエージェントに多数のツール、指示、ドメインを与えると、焦点が定まらなくなります。プロンプトが肥大化し、ツール選択の精度が低下し、無関係な関心事を混同してしまいます。実際のワークフローでは、ステップごとに異なる専門知識（調査、コーディング、請求、コンプライアンスなど）が必要になりますが、単一のフラットなエージェントでは、適切なタイミングで適切な機能を確実に選択したり、長期にわたるマルチステップのやり取りの一貫性を維持したりすることは困難です。", "context": "作業が、マルチターンの会話やループにわたって連携する必要がある複数の明確で再利用可能なスペシャリスト機能に及ぶ場合、ルーティングの決定が固定された計画ではなく変化する状態に依存する場合、そしてポリシーの適用、ハンドオフの管理、どのエージェントが何を行ったかの監視を行うための明確で中央集権的な場所が必要な場合に、スーパーバイザーを使用します。これは、均一な並列ワーカーよりも、異種混合のエージェントチームに適しています。", "solution": [ "スーパーバイザーは、制御ループと共有会話状態を所有します。各ターンで最新のメッセージと目標を検査し、直接回答するか、指定されたスペシャリストに委任するか、または終了するかを決定します。委任は機能ごとに行われます。各サブエージェントには宣言されたスコープ（例：コードエージェント、データエージェント、ナレッジエージェントなど）があり、スーパーバイザーはコンテキストの関連するスライスを選択されたエージェントにルーティングします。スペシャリストは、自身の焦点を絞ったツールループを実行し、結果または明確化の要求を返します。スーパーバイザーはそれを記録した上で、次のステップを決定します。", "スペシャリストの各ターンの後、制御はスーパーバイザーに戻るため、エージェント同士が自由に呼び出し合うのではなく、スーパーバイザーが唯一の決定ポイントであり続けます。スーパーバイザーは、部分的な結果を統合し、スペシャリスト間の競合を解決し、目標が達成されたタイミングを判断し、ユーザーに引き渡すタイミングを決定します。ステップ予算、遷移許可ルール、明示的な終了条件などのガードレールにより、ループの無限循環を防ぎます。構造化されたハンドオフメッセージと共有トレースにより、すべての委任が監査可能になり、チームは誰が何をなぜ依頼されたかを確認できます。" ], "components": [ "スーパーバイザー（ルーター/プランナー）", "宣言されたスコープを持つスペシャリストサブエージェント", "共有会話/状態ストア", "ハンドオフプロトコルとメッセージスキーマ", "ステップ予算と終了ガード", "トレースとエージェントごとのオブザーバビリティ" ], "benefits": [ "より小さくクリーンなプロンプトを持つ、焦点を絞ったスペシャリスト", "中央集権的なルーティングとポリシー適用", "独立して進化できるモジュール式エージェント", "誰が何を行ったかの明確な監査トレイル" ], "risks": [ "無限ループまたはピンポンハンドオフ（往復）ループ", "調整オーバーヘッドによるレイテンシとコストの増大", "スーパーバイザーがルーティングのボトルネックになる", "ハンドオフ間のコンテキスト喪失による品質低下" ], "whenNot": [ "単一の機能でタスク全体を処理できる場合", "固定された並列ファンアウト（オーケストレーター・ワーカー）の方が適している場合", "レイテンシやコストの予算により、余分なホップが許容されない場合" ], "examples": [ "請求、技術、アカウントのスペシャリスト間にまたがるカスタマーサポートのルーティング", "コーディング、テスト、ドキュメント作成のエージェント間で分割されたソフトウェアタスク", "検索、分析、執筆のエージェントに委任するリサーチアシスタント" ], "kpis": [ { "metric": "タスク成功率 / 目標達成率", "note": "人間の介入なしに意図した成果に達したセッションの割合。スーパーバイザーチームの主要な品質シグナルとなります。" }, { "metric": "解決されたタスクあたりのハンドオフ数", "note": "完了までの平均委任回数。これが上昇傾向にある場合は、より高度な作業が行われているのではなく、優柔不断やルーティングの混乱が生じている兆候であるため注意が必要です。" }, { "metric": "調整オーバーヘッド", "note": "単一のエージェントと比較して、スーパーバイザーに起因する追加のトークン、呼び出し、およびレイテンシ。これが良好であれば、ルーティングがそのコストに見合っていることを意味します。" }, { "metric": "ルーティング精度", "note": "ラベル付きケースに照らして判定された、最初の試行で正しい専門エージェントに送信された委譲の割合。" } ], "failureModes": [ "2つのエージェントが、予算（バジェット）によってループが遮断されるまで、進捗がないまま処理を相互に引き渡し続ける", "スーパーバイザーが誤った専門エージェントにルーティングしてしまい、スレッドを二度と復旧できない", "引き渡しの際に重要なコンテキストが脱落し、専門エージェントが誤った問題を解決してしまう", "専門エージェントの部分的な結果が競合し、スーパーバイザーがそれらを一貫性のない形でマージしてしまう" ], "lessons": [ "ループが必ず終了するように、厳格なステップバジェットと明示的な終了条件を強制する", "引き渡しを、生のメッセージダンプではなく、意図とスコープを持った構造化されたものにする", "ルーティングの曖昧さを減らすため、専門エージェントのスコープを狭く、重複しないように保つ", "すべての委譲をインスツルメント（可視化・計測）する。見えないマルチエージェントループをデバッグすることはできない" ], "faqs": [ { "q": "オーケストレーター・ワーカー（orchestrator-workers）パターンとは何が違うのですか？", "a": "オーケストレーター・ワーカーは、1つのタスクを並列の（多くの場合同質な）ワーカー呼び出しに分解してマージします。一方、スーパーバイザーは、マルチターンのループ全体で異質な専門エージェントを統括する永続的なコーディネーターであり、固定された計画を実行するのではなく、状態の遷移に応じてルーティングを再決定します。" }, { "q": "無限の引き渡しループを防ぐにはどうすればよいですか？", "a": "各専門エージェントのターンの後に制御をスーパーバイザーに戻し、エージェント間の自由なピアツーピア呼び出しを禁止します。また、ステップやトークンのバジェットを設定し、許可された遷移を定義し、明示的な終了条件を追加することで、ループが無限に循環するのを防ぎます。" }, { "q": "専門エージェントはどのようなときにスーパーバイザーに制御を戻すべきですか？", "a": "スコープ内のタスクを完了したとき、自身が持っていない機能が必要になったとき、意思決定を要する曖昧さに直面したとき、またはそのリクエストに対して自身が適切なエージェントではないと検知したときです。その後、スーパーバイザーが統合を行い、次のステップを選択します。" } ] }, "zh": { "name": "主管智能体（Supervisor Agent）", "summary": "主管智能体是一个持久的协调器，用于管理一个由专业子智能体组成的团队。它读取对话状态，决定下一个应该由哪个专家执行，将消息路由给它，并整合返回的结果以实现目标。与一次性分解器不同，主管智能体在多轮对话中始终保持在控制流中，按能力进行委派并重新规划，直到任务完成或交还给用户。", "problem": "如果给单个智能体分配过多的工具、指令和领域，它就会失去焦点：其提示词会膨胀，工具选择能力会下降，并且会混淆不相关的关注点。实际的工作流在不同的步骤（研究、编码、计费、合规）中需要不同的专业知识，但没有哪一个单一的扁平智能体能够可靠地在正确的时刻选择正确的能力，或者保持长期的多步骤交互的连贯性。", "context": "当工作跨越多个不同的、可复用的专家能力，且这些能力必须在多轮对话或循环中进行协作时；当路由决策依赖于不断演变的状态而非固定计划时；以及当您需要一个清晰、集中的地方来执行策略、管理交接并观察哪个智能体执行了什么操作时，请使用主管智能体。它更适合异构的智能体团队，而非统一的并行工作节点。", "solution": [ "主管智能体拥有控制循环和共享的对话状态。在每一轮中，它会检查最新的消息和目标，然后决定是直接回答、委派给指定的专家，还是结束任务。委派是按能力进行的：每个子智能体都有声明的范围（例如代码智能体、数据智能体、知识智能体），主管智能 whistle 会将相关的上下文切片路由给所选的智能体。专家智能体运行其自身专注的工具循环，并返回结果或澄清请求，主管智能体在决定下一步之前会记录这些内容。", "在每个专家轮次之后，控制权都会返回给主管智能体，因此它仍然是唯一的决策点，而不是让智能体之间自由地相互调用。主管智能体整合阶段性结果，解决专家之间的冲突，决定何时满足目标，并决定何时交还给用户。诸如步骤预算、允许的转换规则和显式终止条件等护栏可以防止循环。结构化的交接消息和共享的轨迹使每次委派都可审计，从而使团队能够看到谁被要求做了什么以及原因。" ], "components": [ "主管智能体（路由/规划器）", "具有声明范围的专业子智能体", "共享对话/状态存储", "交接协议和消息 Schema", "步骤预算和终止护栏", "轨迹和单智能体可观测性" ], "benefits": [ "专注的专家，拥有更小、更干净的提示词", "集中式路由和策略执行", "可以独立演进的模块化智能体", "清晰的审计轨迹，记录谁做了什么" ], "risks": [ "无限或乒乓式的交接循环", "协调开销增加了延迟和成本", "主管智能体成为路由瓶颈", "交接过程中的上下文丢失会降低质量" ], "whenNot": [ "单一能力即可处理整个任务", "固定的并行扇出更合适（编排器-工作节点模式）", "延迟或成本预算不允许额外的跳转" ], "examples": [ "在计费、技术和账户专家之间进行客户支持路由", "在编码、测试和文档智能体之间拆分软件任务", "研究助手委派给搜索、分析和写作智能体" ], "kpis": [ { "metric": "任务成功率 / 目标完成率", "note": "在无需人工干预的情况下达到预期结果的会话比例；这是主管智能体团队的核心质量指标。" }, { "metric": "每个已解决任务的交接次数", "note": "完成任务所需的平均委派次数；注意向上漂移的趋势，这通常信号着决策犹豫或路由抖动，而非更丰富的工作内容。" }, { "metric": "协调开销", "note": "与单个智能体相比，归因于主管智能体的额外 token、调用和延迟；表现良好意味着路由带来的收益超过了其成本。" }, { "metric": "路由准确率", "note": "首次尝试即发送给正确专家的委派比例，根据标注案例进行评估。" } ], "failureModes": [ "两个智能体在没有进展的情况下反复交接工作，直到预算限制切断循环", "主管智能体错误地路由到不正确的专家，且再也无法恢复该线程", "关键上下文在交接中丢失，导致专家解决了错误的问题", "专家的阶段性结果发生冲突，主管智能体对它们进行了不连贯的合并" ], "lessons": [ "强制执行硬性步骤预算和显式终止条件，以确保循环总能结束", "使交接结构化，包含意图和范围，而不是原始消息的堆砌", "保持专家的职责范围狭窄且不重叠，以减少路由歧义", "对每一次委派进行插桩分析；你无法调试看不见的多智能体循环" ], "faqs": [ { "q": "这与编排器-工作者（orchestrator-workers）模式有什么不同？", "a": "编排器-工作者模式将一个任务分解为并行的、通常是同构的工作者调用并进行合并。而主管智能体是在多轮循环中管理异构专家的持久协调器，它随着状态的演变重新决定路由，而不是执行固定的计划。" }, { "q": "如何防止无限交接循环？", "a": "在每个专家轮次结束后将控制权路由回主管智能体，禁止自由的点对点调用，设置步骤或 token 预算，定义允许的转换，并添加显式终止条件，以防止循环无限进行。" }, { "q": "专家应该在什么时候将控制权交还给主管智能体？", "a": "每当它完成其范围内的任务、需要其不具备的能力、遇到需要决策的歧义，或者检测到自己不是处理该请求的正确智能体时。然后由主管智能体进行整合并选择下一步。" } ] } } }, { "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", "canonical_url": "https://santismm.com/en/patterns/task-prioritization", "api_url": "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." } ] }, "fr": { "name": "Priorisation des tâches", "summary": "Ordonner les tâches candidates d'un agent par valeur, urgence, dépendances et coût plutôt que de les traiter selon le principe du premier entré, premier sorti (FIFO). Une fonction de score et une file d'attente prioritaire déterminent l'exécution suivante, afin d'allouer les ressources de calcul, le budget et le temps limités aux travaux les plus importants. Réévaluer les scores à chaque changement d'état et limiter la taille de la file d'attente pour éviter une croissance infinie.", "problem": "Un agent qui décompose un objectif se retrouve souvent avec de nombreuses tâches candidates simultanées : recherches à effectuer, fichiers à lire, outils à appeler, sous-objectifs à poursuivre. Les traiter par ordre d'arrivée revient à accorder la même importance à une étape de nettoyage triviale qu'à une tâche bloquante soumise à une échéance. Les travaux importants attendent derrière des bruits de fond mineurs, les dépendances ne sont pas respectées et le budget est gaspillé pour des tâches devenues inutiles suite à l'évolution de la situation.", "context": "À utiliser lorsqu'un agent ou un orchestrateur gère un backlog de tâches indépendantes ou faiblement couplées et ne peut pas toutes les exécuter immédiatement en raison de contraintes de calcul, de limites de débit, de coût ou de temps réel. Ce modèle convient aux architectures de planification et de supervision où un composant choisit la prochaine exécution. Il suppose que vous pouvez associer des signaux — impact, échéance, dépendance, coût — à chaque tâche, et que les priorités peuvent évoluer à mesure que de nouvelles observations apparaissent.", "solution": [ "Associer des signaux explicites à chaque tâche : impact attendu sur l'objectif, urgence ou échéance, relations de dépendance (ce qui doit se terminer en premier) et coût estimé en jetons, en argent ou en latence. Combiner ces éléments en un score unique à l'aide d'une fonction transparente et auditable plutôt que d'un jugement de modèle opaque. Injecter les tâches évaluées dans une file d'attente prioritaire afin d'exécuter la tâche prête ayant la plus haute valeur. Respecter systématiquement les dépendances en premier : une tâche dont les prérequis ne sont pas satisfaits n'est pas considérée comme « prête », quel que soit son score, ce qui garantit un ordonnancement correct et évite les tentatives infructueuses.", "Rendre la priorisation dynamique. Après chaque étape, réévaluer le score des tâches concernées car les nouveaux résultats modifient l'impact, les échéances approchent et certaines tâches deviennent obsolètes et peuvent être abandonnées. Se prémunir contre la famine par le vieillissement (aging) — en augmentant progressivement la priorité des tâches en attente depuis longtemps — ou en réservant de la capacité pour les niveaux inférieurs. Limiter le backlog par un plafond explicite et une politique d'admission : lorsque la file d'attente est pleine, rejeter, fusionner ou évincer les tâches les moins prioritaires au lieu de la laisser croître indéfiniment. Conserver des poids de notation configurables et consigner les raisons du choix de chaque tâche afin de garantir l'explicabilité du comportement." ], "components": [ "Extracteur de signaux", "Fonction de notation", "File d'attente prioritaire", "Résolveur de dépendances", "Boucle de repriorisation", "Contrôleur d'admission et de vieillissement" ], "benefits": [ "Les ressources de calcul, le budget et le temps limités sont consacrés aux travaux à forte valeur ajoutée et urgents, plutôt qu'à ce qui est arrivé en premier.", "Le respect des prérequis évite les tentatives infructueuses et les retouches inutiles causées par l'exécution de tâches avant que leurs entrées ne soient disponibles.", "La réévaluation des scores permet à l'agent d'abandonner les tâches devenues inutiles et de promouvoir celles nouvellement urgentes à mesure que la situation évolue.", "Une notation sensible aux coûts et une file d'attente limitée permettent de maîtriser les budgets de jetons et de latence plutôt que de les laisser illimités." ], "risks": [ "Une mauvaise pondération ou une estimation erronée des coûts peut systématiquement priver de ressources les travaux importants ou privilégier des tâches de faible valeur ; la formule nécessite un examen et un étalonnage.", "Sans vieillissement ni capacité réservée, les tâches à faible priorité risquent de ne jamais être exécutées, laissant les travaux de nettoyage ou de fond nécessaires définitivement inachevés.", "Une réévaluation trop fréquente des scores peut amener l'agent à changer constamment de focus, subissant ainsi le coût des changements de contexte sans jamais rien terminer.", "Si la décomposition ajoute des tâches plus rapidement qu'elles ne sont accomplies, un backlog non limité gonfle la mémoire, les coûts et la latence de planification." ], "whenNot": [ "Lorsqu'il n'y a qu'une poignée de tâches similaires, le FIFO ou un parallélisme simple est plus aisé et le surcoût lié à la notation n'en vaut pas la peine.", "Si les tâches doivent s'exécuter selon une séquence fixe dictée par le domaine, un flux de travail statique ou un DAG est plus clair qu'une file d'attente prioritaire dynamique.", "Lorsque vous pouvez tout exécuter immédiatement dans le respect du budget et des limites, il n'y a rien à prioriser et l'ordonnancement ajoute une complexité inutile." ], "examples": [ "Un agent chargé de rassembler des preuves priorise les recherches les plus susceptibles de résoudre les questions en suspens et ignore les requêtes redondantes une fois qu'une affirmation est confirmée.", "Un agent d'exploitation ordonne les étapes de remédiation selon le rayon d'impact et l'échéance, traitant l'interruption de service côté client avant les avertissements à faible impact.", "Un agent de pipeline planifie en priorité les documents à forte valeur ou proches de leur échéance et diffère les éléments de traitement par lots peu coûteux, tandis que le vieillissement empêche la file d'attente de traitement par lots de stagner indéfiniment." ], "productionEvidence": { "context": "Déploiement OpenClaw mono-opérateur, local-first, observé sur 57 jours (161 sessions / 2 776 tours), agrégé à partir des traces de trajectoire propres à l'agent.", "scenario": "Un agent autonome est activé selon un calendrier (heartbeat + cron), avec un décalage en début d'heure et un délai de récupération (cooldown) du heartbeat fournissant une contre-pression pour éviter l'accumulation des tâches.", "technology": "Planificateur CronService, heartbeat-runner, décalage de 5 minutes en début d'heure, logique de report par heartbeat-cooldown, et champ de priorité faible/normale/haute sur les résultats du heartbeat.", "load": "2 801 tours de heartbeat + 57 tours de cron + 106 tours d'utilisateur sur 57 jours (le heartbeat représentant environ 94 % des déclenchements).", "results": "Le planificateur a maintenu environ cinquante réveils autonomes par jour, le décalage et le délai de récupération empêchant l'accumulation des tâches ; aucun mode de défaillance lié à la planification n'est apparu. Déploiement mono-opérateur local-first." }, "kpis": [ { "metric": "Valeur pondérée des tâches accomplies par unité de coût", "note": "Indique si l'effort se concentre sur les travaux à fort impact ; un bon résultat correspond à une valeur plus pertinente par rapport à l'objectif fournie par jeton ou par dollar par rapport à une référence FIFO." }, { "metric": "Respect des échéances / SLA pour les tâches critiques", "note": "Montre que les signaux d'urgence fonctionnent ; un bon résultat correspond à des tâches urgentes se terminant avant leur échéance la plupart du temps." }, { "metric": "Indicateur de famine (temps d'attente maximal et de traîne pour les tâches à faible priorité)", "note": "Révèle si le vieillissement est efficace ; un bon résultat correspond à des attentes maximales limitées, sans qu'aucune tâche ne reste bloquée indéfiniment." }, { "metric": "Profondeur de la file d'attente par rapport au plafond et taux d'admission/éviction", "note": "Confirme que le backlog reste limité ; un bon résultat correspond à une profondeur maintenue sous le plafond, l'éviction étant réservée aux tâches de valeur réellement faible." } ], "failureModes": [ "Une tâche hautement prioritaire attend un prérequis de faible priorité qui n'est jamais planifié ; le résolveur doit propager l'urgence aux éléments bloquants.", "Des priorités calculées une seule fois et jamais actualisées entraînent des décisions basées sur des informations d'impact ou d'échéance obsolètes ; la réévaluation des scores doit donc être déclenchée lors des changements d'état pertinents.", "Sous-estimer le coût d'une tâche lui permet de monopoliser le budget ; les estimations ont besoin des retours de la consommation réelle mesurée.", "Une politique d'admission agressive abandonne une tâche qui s'avère ultérieurement nécessaire, imposant une redécouverte coûteuse ; l'éviction devrait privilégier les éléments véritablement redondants." ], "lessons": [ "Une formule auditable et configurable est plus facile à déboguer et à ajuster qu'un jugement de modèle opaque sur l'action suivante à mener.", "Traiter la finalisation des prérequis comme une vérification de disponibilité distincte afin qu'un score élevé ne permette jamais à une tâche de devancer ses entrées.", "Ajouter du vieillissement ou de la capacité réservée dès le départ ; les travaux de fond à faible priorité qui ne s'exécutent jamais deviennent un écart de conformité silencieux.", "Une limite stricte assortie d'une politique d'admission claire constitue la défense la plus simple contre une décomposition incontrôlée qui gonflerait les coûts et la latence." ], "faqs": [ { "q": "En quoi cela diffère-t-il de la décomposition des objectifs ?", "a": "La décomposition produit les tâches ; la priorisation détermine l'ordre dans lequel les tâches résultantes sont exécutées. Elles sont complémentaires : la décomposition remplit le backlog, la priorisation le vide de manière sensée." }, { "q": "Le LLM doit-il lui-même évaluer les priorités ?", "a": "Il peut proposer des signaux tels que l'impact estimé, mais il convient de les combiner avec une fonction transparente et auditable. Une formule déterministe basée sur des signaux nommés est plus facile à calibrer, à journaliser et à faire confiance qu'un unique appel de classement opaque." }, { "q": "Comment éviter que les tâches de faible priorité ne s'exécutent jamais ?", "a": "Utilisez le vieillissement pour augmenter progressivement la priorité des tâches en attente depuis longtemps, ou réservez une fraction de la capacité aux niveaux inférieurs, et surveillez le temps d'attente de queue pour confirmer que rien n'est laissé de côté." } ] }, "de": { "name": "Aufgabenpriorisierung", "summary": "Ordnen Sie die potenziellen Aufgaben eines Agenten nach Wert, Dringlichkeit, Abhängigkeiten und Kosten, anstatt sie nach dem First-In-First-Out-Prinzip zu verarbeiten. Eine Scoring-Funktion und eine Priority Queue entscheiden, was als Nächstes ausgeführt wird, sodass begrenzte Rechenleistung, Budget und Zeit in die wichtigste Arbeit fließen. Berechnen Sie Scores bei Zustandsänderungen neu und begrenzen Sie die Queue, damit sie nicht unendlich wächst.", "problem": "Ein Agent, der ein Ziel zerlegt, steht oft vor vielen potenziellen Aufgaben gleichzeitig: Suchen ausführen, Dateien lesen, Tools aufrufen, Unterziele verfolgen. Die Verarbeitung in der Reihenfolge des Eintreffens behandelt einen trivialen Bereinigungsschritt gleichwertig mit einer blockierenden, termingebundenen Aufgabe. Wichtige Arbeit wartet hinter unwichtigem Rauschen, Abhängigkeiten werden verletzt und Budget wird für Aufgaben ausgegeben, die nach einer Lageänderung keine Rolle mehr spielen.", "context": "Verwenden Sie dieses Muster, wenn ein Agent oder Orchestrator ein Backlog unabhängiger oder lose gekoppelter Aufgaben verwaltet und diese aufgrund von Einschränkungen bei Rechenleistung, Rate-Limits, Kosten oder realer Zeit nicht alle sofort ausführen kann. Es eignet sich für Planer- und Supervisor-Architekturen, bei denen eine Komponente entscheidet, was als Nächstes ausgeführt wird. Es setzt voraus, dass Sie jeder Aufgabe Signale – Auswirkung, Deadline, Abhängigkeit, Kosten – zuweisen können und dass sich Prioritäten verschieben können, wenn neue Beobachtungen eintreffen.", "solution": [ "Weisen Sie jeder Aufgabe explizite Signale zu: erwartete Auswirkung auf das Ziel, Dringlichkeit oder Deadline, Abhängigkeitsbeziehungen (was zuerst abgeschlossen sein muss) und geschätzte Kosten in Token, Geld oder Latenz. Kombinieren Sie diese mithilfe einer transparenten, überprüfbaren Funktion zu einem einzigen Score, statt sich auf ein undurchsichtiges Modellurteil zu verlassen. Leiten Sie bewertete Aufgaben in eine Priority Queue, sodass die bereitstehende Aufgabe mit dem höchsten Wert als Nächstes ausgeführt wird. Berücksichtigen Sie Abhängigkeiten immer zuerst: Eine Aufgabe, deren Voraussetzungen nicht erfüllt sind, ist unabhängig von ihrem Score nicht „bereit“, was die korrekte Reihenfolge wahrt und unnötige Fehlversuche verhindert.", "Gestalten Sie die Priorisierung dynamisch. Berechnen Sie nach jedem Schritt die Scores betroffener Aufgaben neu, da neue Ergebnisse die Auswirkung verändern, Deadlines näher rücken und manche Aufgaben obsolet werden und verworfen werden können. Schützen Sie sich vor Starvation durch Aging – indem Sie die Priorität lange wartender Aufgaben schrittweise erhöhen – oder durch die Reservierung von Kapazitäten für niedrigere Stufen. Begrenzen Sie das Backlog mit einem expliziten Limit und einer Admission Policy: Wenn die Queue voll ist, weisen Sie die schwächsten Aufgaben ab, führen Sie sie zusammen oder verwerfen Sie sie, anstatt die Queue unbegrenzt wachsen zu lassen. Halten Sie die Scoring-Gewichtungen konfigurierbar und protokollieren Sie, warum jede Aufgabe ausgewählt wurde, damit das Verhalten nachvollziehbar bleibt." ], "components": [ "Signal-Extraktor", "Scoring-Funktion", "Priority Queue", "Abhängigkeits-Resolver", "Repriorisierungs-Loop", "Admission- und Aging-Controller" ], "benefits": [ "Begrenzte Rechenleistung, Budget und Zeit fließen in wertvolle, zeitkritische Arbeit statt in das, was zuerst eingetroffen ist.", "Die Berücksichtigung von Voraussetzungen vermeidet unnötige Fehlversuche und Nacharbeiten, die entstehen, wenn Aufgaben ausgeführt werden, bevor ihre Inputs vorliegen.", "Die Neuberechnung der Scores ermöglicht es dem Agenten, inzwischen irrelevante Aufgaben zu verwerfen und neu dringliche Aufgaben vorzuziehen, wenn sich die Situation weiterentwickelt.", "Kostenbewusstes Scoring und eine begrenzte Queue halten Token- und Latenz-Budgets unter Kontrolle, statt sie ausufern zu lassen." ], "risks": [ "Eine falsche Gewichtung oder eine schlechte Kostenschätzung kann systematisch wichtige Arbeit blockieren (Starvation) oder unwichtigen Aufgaben hinterherjagen; die Formel erfordert Überprüfung und Kalibrierung.", "Ohne Aging oder reservierte Kapazitäten werden Aufgaben mit niedriger Priorität möglicherweise nie ausgeführt, wodurch notwendige Bereinigungen oder Hintergrundarbeiten dauerhaft unerledigt bleiben.", "Zu häufiges Repriorisieren kann dazu führen, dass der Agent ständig den Fokus wechselt, Latenz durch Kontextwechsel verursacht und nie etwas zu Ende bringt.", "Wenn die Zerlegung schneller neue Aufgaben hinzufügt, als diese abgeschlossen werden, bläht ein unbegrenztes Backlog den Speicherbedarf, die Kosten und die Planungslatenz auf." ], "whenNot": [ "Wenn es nur eine Handvoll ähnlicher Aufgaben gibt, ist FIFO oder einfache Parallelisierung unkomplizierter und der Scoring-Overhead lohnt sich nicht.", "Wenn Aufgaben in einer festen, durch die Domäne vorgegebenen Reihenfolge ausgeführt werden müssen, ist ein statischer Workflow oder ein DAG klarer als eine dynamische Priority Queue.", "Wenn Sie alles sofort innerhalb des Budgets und der Limits ausführen können, gibt es nichts zu priorisieren, und eine Sortierung bringt nur unnötige Komplexität." ], "examples": [ "Ein Agent, der Beweise sammelt, priorisiert die Suchen, die am wahrscheinlichsten offene Fragen klären, und überspringt redundante Abfragen, sobald eine Behauptung bestätigt ist.", "Ein Operations-Agent ordnet Behebungsschritte nach Schadensradius und Deadline und behebt den kundenwirksamen Ausfall vor Warnungen mit geringer Auswirkung.", "Ein Pipeline-Agent plant wertvolle oder zeitkritische Dokumente zuerst ein und stellt günstige Massenaufgaben zurück, während Aging verhindert, dass die Massen-Queue dauerhaft blockiert." ], "productionEvidence": { "context": "Single-Operator, Local-First OpenClaw-Bereitstellung, beobachtet über 57 Tage (161 Sessions / 2.776 Turns), aggregiert aus den eigenen Trajektorien-Traces des Agenten.", "scenario": "Ein autonomer Agent wird nach einem Zeitplan geweckt (Heartbeat + Cron), wobei ein Staggering zu Beginn jeder Stunde und ein Heartbeat-Cooldown für Backpressure sorgen, damit sich Jobs nicht anhäufen.", "technology": "CronService-Scheduler, Heartbeat-Runner, ein 5-minütiges Staggering zu Beginn jeder Stunde, Heartbeat-Cooldown-Verzögerungslogik und ein Feld für niedrige/normale/hohe Priorität bei Heartbeat-Ergebnissen.", "load": "2.801 Heartbeat-Turns + 57 Cron-Turns + 106 User-Turns über 57 Tage (Heartbeat ~94 % der Trigger).", "results": "Der Scheduler hielt täglich etwa fünfzig autonome Aktivierungen aufrecht, wobei Staggering und Cooldown ein Anhäufen von Jobs verhinderten; es trat kein zeitplangesteuerter Fehler auf. Single-Operator, Local-First-Bereitstellung." }, "kpis": [ { "metric": "Gewichteter Wert abgeschlossener Aufgaben pro Kosteneinheit", "note": "Erfasst, ob der Aufwand in hochwirksame Arbeit fließt; ein gutes Ergebnis zeigt sich in mehr zielrelevantem Wert pro Token oder Dollar im Vergleich zu einer FIFO-Baseline." }, { "metric": "Einhaltung von Deadlines / SLAs bei zeitkritischen Aufgaben", "note": "Zeigt, ob Dringlichkeitssignale funktionieren; ein gutes Ergebnis bedeutet, dass dringende Aufgaben meist vor ihrer Deadline abgeschlossen werden." }, { "metric": "Starvation-Indikator (maximale und Tail-Wartezeit für Aufgaben mit niedriger Priorität)", "note": "Zeigt, ob Aging effektiv ist; ein gutes Ergebnis sind begrenzte Wartezeiten im Worst Case, ohne dass eine Aufgabe unendlich festsitzt." }, { "metric": "Queue-Tiefe im Verhältnis zum Limit und Admission-/Eviction-Rate", "note": "Bestätigt, dass das Backlog begrenzt bleibt; ein gutes Ergebnis zeigt sich in einer Tiefe unter dem Limit, wobei das Verwerfen (Eviction) wirklich geringwertigen Aufgaben vorbehalten bleibt." } ], "failureModes": [ "Eine hochpriorisierte Aufgabe wartet auf eine Voraussetzung mit niedriger Priorität, die nie eingeplant wird; der Resolver muss die Dringlichkeit auf Blockierer übertragen.", "Einmalig berechnete und nie aktualisierte Prioritäten führen zu Entscheidungen auf Basis veralteter Auswirkungs- oder Deadline-Informationen; daher muss eine Neuberechnung bei relevanten Zustandsänderungen getriggert werden.", "Eine Unterschätzung der Kosten einer Aufgabe führt dazu, dass sie das Budget monopolisiert; Schätzungen benötigen Feedback aus dem tatsächlich gemessenen Verbrauch.", "Eine aggressive Admission Policy verwirft eine Aufgabe, die sich später als notwendig herausstellt, was eine teure erneute Ermittlung erzwingt; das Verwerfen (Eviction) sollte wirklich redundante Elemente bevorzugen." ], "lessons": [ "Eine überprüfbare, konfigurierbare Formel ist einfacher zu debuggen und abzustimmen als ein undurchsichtiges Modellurteil darüber, was als Nächstes zu tun ist.", "Behandeln Sie den Abschluss von Voraussetzungen als separate Bereitschaftsprüfung, damit ein hoher Score eine Aufgabe niemals vor ihre Inputs springen lässt.", "Fügen Sie von Anfang an Aging oder reservierte Kapazitäten hinzu; Hintergrundarbeit mit niedriger Priorität, die nie ausgeführt wird, führt zu einer unbemerkten Korrektheitslücke.", "Eine harte Obergrenze mit einer klaren Zulassungsrichtlinie ist der einfachste Schutz gegen eine ausufernde Dekomposition, die Kosten und Latenz in die Höhe treibt." ], "faqs": [ { "q": "Wie unterscheidet sich dies von der Zieldekomposition?", "a": "Die Dekomposition erzeugt die Aufgaben; die Priorisierung entscheidet über die Reihenfolge, in der die resultierenden Aufgaben ausgeführt werden. Sie ergänzen sich gegenseitig: Die Dekomposition füllt das Backlog, die Priorisierung baut es sinnvoll ab." }, { "q": "Sollte das LLM selbst die Prioritäten bewerten?", "a": "Es kann Signale wie den geschätzten Impact vorschlagen, aber kombinieren Sie diese mit einer transparenten, überprüfbaren Funktion. Eine deterministische Formel über benannte Signale ist einfacher zu kalibrieren, zu protokollieren und vertrauenswürdiger als ein einzelner, undurchsichtiger Ranking-Aufruf." }, { "q": "Wie verhindere ich, dass Aufgaben mit niedriger Priorität niemals ausgeführt werden?", "a": "Nutzen Sie Aging, um die Priorität von lange wartenden Aufgaben schrittweise zu erhöhen, oder reservieren Sie einen Teil der Kapazität für niedrigere Stufen, und überwachen Sie die Tail-Wartezeit, um sicherzustellen, dass nichts verhungert." } ] }, "ja": { "name": "タスクの優先順位付け", "summary": "エージェントの候補タスクを先入れ先出し（FIFO）で処理するのではなく、価値、緊急度、依存関係、およびコストに基づいて順序付けします。スコアリング関数と優先度付きキューが次に実行するタスクを決定するため、限られた計算リソース、予算、時間を最も重要な作業に割り当てることができます。状態の変化に応じて再スコアリングを行い、キューに上限を設けて無制限に肥大化するのを防ぎます。", "problem": "ゴールを分解するエージェントは、実行すべき検索、読み込むべきファイル、呼び出すべきツール、追求すべきサブゴールなど、一度に多くの候補タスクを抱えがちです。これらを到着順に処理すると、些細なクリーンアップステップが、期限付きのブロッキングタスクと同等に扱われてしまいます。重要な作業が低価値のノイズの後回しになり、依存関係が侵害され、状況が変わった後ではもはや重要ではないタスクに予算が費やされてしまいます。", "context": "エージェントまたはオーケストレーターが、独立した、あるいは疎結合のタスクのバックログを保持しており、計算リソース、レート制限、コスト、または実時間の制約により、それらすべてを即座に実行できない場合に使用します。これは、1つのコンポーネントが次に実行するものを選択するプランナーやスーパーバイザーのアーキテクチャに適しています。各タスクにシグナル（影響度、期限、依存関係、コスト）を付与でき、新しい観測結果が得られるにつれて優先度がシフトする可能性があることを前提としています。", "solution": [ "すべてのタスクに明示的なシグナルを付与します。これには、ゴールに対する期待される影響度、緊急度または期限、依存関係（最初に完了すべきもの）、およびトークン、費用、またはレイテンシにおける推定コストが含まれます。これらを、不透明なモデルの判断ではなく、透明で監査可能な関数を使用して単一のスコアに結合します。スコアリングされたタスクを優先度付きキューに投入し、最も価値の高い「準備完了（ready）」状態のタスクが次に実行されるようにします。常に依存関係を最優先してください。前提条件が満たされていないタスクは、スコアに関係なく「準備完了」とはみなされません。これにより、順序付けが正しく保たれ、無駄な再試行を防ぐことができます。", "優先順位付けを動的に行います。各ステップの後、影響を受けるタスクを再スコアリングします。新しい結果によって影響度が変化し、期限が近づき、一部のタスクは不要になって破棄できるためです。エイジング（長時間待機しているタスクの優先度を徐々に上げる）や、下位層向けのキャパシティ確保によって、スターベーション（飢餓状態）を防ぎます。明示的な上限と受付ポリシーによってバックログを制限します。キューが満杯のときは、無制限に肥大化させるのではなく、最も優先度の低いタスクを拒否、マージ、または破棄（エビクト）します。スコアリングの重みを設定可能に保ち、各タスクが選択された理由をログに記録することで、動作の説明可能性を維持します。" ], "components": [ "シグナル抽出器", "スコアリング関数", "優先度付きキュー", "依存関係リゾルバー", "再優先順位付けループ", "受付・エイジングコントローラー" ], "benefits": [ "限られた計算リソース、予算、時間が、最初に到着したものにではなく、価値が高く時間的制約のある作業に費やされます。", "前提条件を尊重することで、インプットが存在する前にタスクを実行することによる無駄な再試行や手戻りを回避できます。", "再スコアリングにより、状況の進展に応じて、エージェントは関連性のなくなったタスクを破棄し、新たに緊急性の高まったタスクを昇格させることができます。", "コストを意識したスコアリングと上限付きキューにより、トークンとレイテンシのバジェットを、際限なく膨らむことなく管理下に置くことができます。" ], "risks": [ "重み付けの誤りや不適切なコスト見積もりは、重要な作業をシステム的にスターベーション（飢餓状態）に陥らせたり、低価値のタスクを追いかけさせたりする可能性があります。数式の見直しとキャリブレーションが必要です。", "エイジングや予約されたキャパシティがないと、優先度の低いタスクが実行されず、必要なクリーンアップやバックグラウンド作業が永久に未完了のまま放置される可能性があります。", "頻繁すぎる再スコアリングは、エージェントに絶え間ないフォーカスの切り替えを発生させ、コンテキストスイッチのコストを支払うだけで、何も完了できなくなる可能性があります。", "タスクの分解によって追加されるタスクのペースが完了ペースを上回る場合、上限のないバックログはメモリ、コスト、およびプランニングのレイテンシを膨張させます。" ], "whenNot": [ "同様のタスクが数個しかない場合は、FIFOや単純な並列処理の方がシンプルであり、スコアリングのオーバーヘッドに見合う価値はありません。", "ドメインによって規定された固定の順序でタスクを実行する必要がある場合は、動的な優先度付きキューよりも、静的なワークフローやDAG（有向非巡回グラフ）の方が明確です。", "予算と制限の範囲内ですべてを即座に実行できる場合、優先順位を付ける必要はなく、順序付けは不要な複雑さを招くだけです。" ], "examples": [ "証拠を収集するエージェントは、未解決の疑問を解決する可能性が最も高い検索を優先し、主張が確認された後は冗長なクエリをスキップします。", "運用エージェントは、影響範囲（ブラスト半径）と期限に基づいて修復ステップを順序付けし、影響の少ない警告よりも先に、顧客に影響する障害に対応します。", "パイプラインエージェントは、価値の高いドキュメントや期限の近いドキュメントを優先してスケジュールし、低コストの一括処理（バルク）アイテムを後回しにします。その際、エイジングによってバルクキューが永久に失速するのを防ぎます。" ], "productionEvidence": { "context": "57日間にわたり観測された、シングルオペレーター、ローカルファーストのOpenClawデプロイメント（161セッション / 2,776ターン）。エージェント自身のトラジェクトリトレースから集計。", "scenario": "自律エージェントがスケジュール（ハートビート + cron）に基づいて起動されます。毎正時のスタッガー（時間差起動）とハートビートのクールダウンがバックプレッシャーを提供し、ジョブが集中するのを防ぎます。", "technology": "CronServiceスケジューラー、heartbeat-runner、5分間の毎正時スタッガー、heartbeat-cooldown遅延ロジック、およびハートビート結果のlow/normal/high優先度フィールド。", "load": "57日間にわたる2,801回のハートビートターン + 57回のcronターン + 106回のユーザーターン（トリガーの約94%がハートビート）。", "results": "スケジューラーは1日あたり約50回の自律的な起動を維持し、スタッガーとクールダウンによって集中を防止しました。スケジュール起因の障害モードは発生しませんでした。シングルオペレーター、ローカルファーストのデプロイメント。" }, "kpis": [ { "metric": "単位コストあたりに完了した重み付けタスク価値", "note": "取り組みが影響度の高い作業に向けられているかを捉えます。良好な状態とは、FIFOの基準値と比較して、トークンまたはドルあたりに提供されるゴール関連の価値がより多くなることです。" }, { "metric": "時間的制約のあるタスクにおける期限/SLA遵守率", "note": "緊急度シグナルが機能していることを示します。良好な状態とは、緊急タスクの大部分が期限前に完了することです。" }, { "metric": "スターベーション指標（低優先度タスクの最大およびテール待ち時間）", "note": "エイジングが効果的であるかを示します。良好な状態とは、最悪の場合の待ち時間が制限され、タスクが永久にスタックしないことです。" }, { "metric": "キューの深さ対上限、および受付/破棄（エビクション）率", "note": "バックログが制限内に収まっていることを確認します。良好な状態とは、キューの深さが上限未満に維持され、破棄が真に低価値のタスクのみに限定されていることです。" } ], "failureModes": [ "高優先度のタスクが、スケジュールされない低優先度の前提タスクを待機してしまう。リゾルバーはブロッキングタスクに緊急度を伝播させる必要があります。", "一度計算されたきり更新されない優先度に基づいて、古い影響度や期限の情報で意思決定が行われてしまう。関連する状態の変化に応じて再スコアリングをトリガーする必要があります。", "タスクのコストを過小評価すると、そのタスクが予算を独占してしまいます。見積もりには、実際に測定された消費量からのフィードバックが必要です。", "積極的な受付ポリシーによって、後から必要であることが判明するタスクを破棄してしまい、高コストな再検出を余儀なくされる。破棄（エビクション）は、真に冗長なアイテムを優先すべきです。" ], "lessons": [ "次に何をすべきかに関する不透明なモデルの判断よりも、監査可能で設定可能な数式の方が、デバッグや調整が容易です。", "前提条件の完了を個別の準備完了チェックとして扱うことで、高いスコアによってタスクがインプットよりも先に実行されるのを防ぎます。", "最初からエイジングまたは予約されたキャパシティを追加してください。実行されない低優先度のバックグラウンド作業は、静かな正確性の欠如につながります。", "明確な受け入れポリシーを伴う厳格な上限（ハードキャップ）を設定することは、タスク分解の暴走によるコストやレイテンシの膨張を防ぐ最もシンプルな防御策です。" ], "faqs": [ { "q": "これはゴールの分解とどう違うのですか？", "a": "分解はタスクを生成し、優先順位付けは生成されたタスクを実行する順序を決定します。これらは相互補完的です。分解がバックログを満たし、優先順位付けがそれを合理的に消化します。" }, { "q": "LLM自体が優先度をスコアリングすべきですか？", "a": "推定される影響度などのシグナルをLLMに提案させることは可能ですが、それらは透明で監査可能な関数と組み合わせるべきです。名前付きシグナルに基づく決定論的な数式は、単一の不透明なランキング呼び出しよりも、調整、ログ記録、そして信頼が容易になります。" }, { "q": "低優先度のタスクがいつまでも実行されないのを防ぐにはどうすればよいですか？", "a": "エイジング（経年処理）を使用して長時間待機しているタスクの優先度を徐々に上げるか、キャパシティの一部を低優先度層のために確保し、テールの待ち時間を監視してスターベーションが発生していないことを確認します。" } ] }, "zh": { "name": "任务优先级排序", "summary": "根据价值、紧急程度、依赖关系和成本对智能体的候选任务进行排序，而不是按照先进先出（FIFO）的方式进行处理。通过评分函数和优先级队列决定下一步运行什么，从而将有限的算力、预算和时间投入到最重要的工作中。随着状态的变化重新评分，并限制队列大小以防止其无限制增长。", "problem": "分解目标的智能体通常会同时产生许多候选任务：要运行的搜索、要读取的文件、要调用的工具、要追求的子目标。按到达顺序处理这些任务会将琐碎的清理步骤与具有截止日期的阻塞性任务同等对待。重要的工作在廉价的噪音之后等待，依赖关系被破坏，并且在情况发生变化后，预算被浪费在不再重要的任务上。", "context": "当智能体或编排器积压了独立或松耦合的任务，且由于算力、速率限制、成本或实际时间限制而无法立即运行所有任务时，请使用此模式。它适用于由一个组件选择下一步执行内容的规划器和主管智能体架构。它假设你可以为每个任务附加信号（影响、截止日期、依赖关系、成本），并且随着新观测结果的到来，优先级可能会发生变化。", "solution": [ "为每个任务附加显式信号：对目标的预期影响、紧急程度或截止日期、依赖关系（必须先完成什么）以及在 token、资金或延迟方面的预估成本。通过透明、可审计的函数将这些信号组合成一个分数，而不是依靠不透明的模型判断。将评分后的任务输入优先级队列，以便下一步运行价值最高且已就绪的任务。务必首先遵守依赖关系：无论分数如何，前置条件未满足的任务都不是“就绪”状态，这可以保持正确的顺序并防止无谓的重试。", "使优先级排序动态化。在每一步之后，重新对受影响的任务进行评分，因为新结果会改变影响、截止日期会临近，且某些任务会变得过时并可以丢弃。通过老化机制（aging，逐渐提高等待时间较长任务的优先级）或为较低层级保留容量来防止饥饿。通过显式上限和准入策略限制积压工作：当队列满时，拒绝、合并或驱逐最弱的任务，而不是让其无限制增长。保持评分权重可配置，并记录选择每个任务的原因，以确保行为保持可解释性。" ], "components": [ "信号提取器", "评分函数", "优先级队列", "依赖解析器", "重新优先级排序循环", "准入与老化控制器" ], "benefits": [ "有限的算力、预算和时间会被投入到高价值、时间紧迫的工作中，而不是最先到达的任务。", "遵守前置条件可以避免因在输入存在之前运行任务而导致的无谓重试和返工。", "重新评分使智能体能够随着情况的演变放弃目前已无关紧要的任务，并提升新紧急任务的优先级。", "成本感知评分和受限队列使 token 和延迟预算保持在可控范围内，而不是无限制的。" ], "risks": [ "错误的权重或糟糕的成本估算可能会系统性地导致重要工作饥饿，或盲目追求低价值任务；该公式需要审查和校准。", "如果没有老化机制或保留容量，低优先级任务可能永远不会运行，导致必要的清理或后台工作永久处于未完成状态。", "过于频繁的重新评分会导致智能体不断切换焦点，付出上下文切换的成本且永远无法完成任何工作。", "如果任务分解添加任务的速度快于完成速度，未设上限的积压工作将导致内存、成本和规划延迟膨胀。" ], "whenNot": [ "当只有少数几个相似的任务时，FIFO 或简单的并行处理会更简单，评分的开销并不划算。", "如果任务必须按照领域规定的固定顺序运行，那么静态工作流或 DAG 会比动态优先级队列更清晰。", "当你可以立即在预算和限制范围内运行所有内容时，就没有什么需要排定优先级的，排序只会增加不必要的复杂性。" ], "examples": [ "收集证据的智能体会优先处理最有可能解决未决问题的搜索，并在断言得到确认后跳过冗余查询。", "运维智能体根据爆炸半径和截止日期对修复步骤进行排序，在处理低影响告警之前先处理面向客户的停机故障。", "流水线智能体会优先调度高价值或临近截止日期的文档，并推迟廉价的批量项目，同时老化机制可防止批量队列永久停滞。" ], "productionEvidence": { "context": "在 57 天内（161 个会话 / 2,776 个轮次）观察到的单操作员、本地优先的 OpenClaw 部署，数据从智能体自身的轨迹追踪中聚合而来。", "scenario": "自主智能体按计划被唤醒（心跳 + cron），通过整点错峰和心跳冷却提供背压，以防止任务堆积。", "technology": "CronService 调度器、心跳运行器、5 分钟整点错峰、心跳冷却推迟逻辑，以及心跳结果上的低/中/高优先级字段。", "load": "57 天内包含 2,801 个心跳轮次 + 57 个 cron 轮次 + 106 个用户轮次（心跳约占触发源的 94%）。", "results": "调度器每天维持大约 50 次自主唤醒，错峰和冷却机制防止了任务堆积；未出现由调度驱动的失效模式。单操作员本地优先部署。" }, "kpis": [ { "metric": "单位成本完成的加权任务价值", "note": "捕获精力是否投入到高影响力的工作上；表现良好意味着与 FIFO 基线相比，每个 token 或美元交付了更多与目标相关的价值。" }, { "metric": "时间紧迫型任务的截止日期 / SLA 遵守率", "note": "表明紧急信号正在发挥作用；表现良好意味着紧急任务在大多数情况下都能在截止日期前完成。" }, { "metric": "饥饿指标（低优先级任务的最大和尾部等待时间）", "note": "揭示老化机制是否有效；表现良好意味着最坏情况下的等待时间是有界的，且没有任务无限期卡住。" }, { "metric": "队列深度与上限对比以及准入/驱逐率", "note": "确认积压工作保持有界；表现良好意味着深度保持在上限以下，且驱逐仅针对真正低价值的任务。" } ], "failureModes": [ "高优先级任务等待一个永远不会被调度的低优先级前置条件；解析器必须将紧急程度传播给阻塞任务。", "仅计算一次且从未刷新的优先级会基于过时的影响或截止日期信息做出决策，因此必须在相关状态发生变化时触发重新评分。", "低估任务成本会导致其垄断预算；估算需要来自实际测量消耗的反馈。", "激进的准入策略会丢弃后来被证明是必需的任务，从而迫使进行昂贵的重新发现；驱逐应优先选择真正冗余的项目。" ], "lessons": [ "与关于下一步做什么的不透明模型判断相比，可审计、可配置的公式更容易调试和微调。", "将前置条件的完成视为独立的就绪检查，这样高评分绝不会让任务抢在其输入之前执行。", "从一开始就添加老化机制或保留容量；永远不运行的低优先级后台工作会成为隐蔽的正确性缺陷。", "设立具有明确准入策略的硬性上限，是防止失控的任务分解导致成本和延迟飙升的最简单防御手段。" ], "faqs": [ { "q": "这与目标分解有什么不同？", "a": "分解产生任务；优先级排序决定这些任务的执行顺序。它们是互补的：分解负责填充待办列表，优先级排序负责合理地消耗它。" }, { "q": "LLM 本身应该对优先级进行评分吗？", "a": "它可以提出诸如预估影响之类的信号，但应将这些信号与透明、可审计的函数结合起来。相比于单次不透明的排序调用，基于命名信号的确定性公式更容易校准、记录和信任。" }, { "q": "如何防止低优先级任务永远无法运行？", "a": "使用老化（aging）机制逐渐提高等待时间较长任务的优先级，或者为较低层级保留一部分容量，并监控尾部等待时间以确保没有任务被饿死。" } ] } } } ] }