santismm-knowledge-mcp 0.2.1

package/content/patterns/semantic-caching.json

@@ -0,0 +1,201 @@
+{
+  "slug": "semantic-caching",
+  "category": "cost",
+  "updated": "2026-06-24",
+  "version": "1.1",
+  "technologies": ["Embedding models", "Vector databases", "GPTCache", "Redis / KV stores"],
+  "related": ["routing", "prompt-chaining"],
+  "references": [
+    { "title": "OpenAI — Vector embeddings guide", "url": "https://platform.openai.com/docs/guides/embeddings" }
+  ],
+  "evidence": {
+    "evidenceLevel": "production",
+    "confidenceLevel": "low",
+    "sourceType": ["production_system", "personal_experience", "industry_observation"]
+  },
+  "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." }
+      ]
+    }
+  }
+}

package/content/patterns/supervisor-agent.json

@@ -0,0 +1,290 @@
+{
+  "slug": "supervisor-agent",
+  "category": "orchestration",
+  "updated": "2026-06-21",
+  "version": "1.0",
+  "featured": false,
+  "technologies": [
+    "LangGraph (supervisor)",
+    "OpenAI Agents SDK",
+    "Multi-agent frameworks",
+    "Message routing"
+  ],
+  "related": [
+    "orchestrator-workers",
+    "routing",
+    "goal-decomposition"
+  ],
+  "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/"
+    }
+  ],
+  "evidence": {
+    "evidenceLevel": "industry_observation",
+    "confidenceLevel": "high",
+    "sourceType": [
+      "industry_observation",
+      "paper"
+    ]
+  },
+  "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."
+        }
+      ]
+    }
+  }
+}