santismm-knowledge-mcp 0.2.1

package/content/knowledge/multi-agent-architecture.json

@@ -0,0 +1,153 @@
+{
+  "slug": "multi-agent-architecture",
+  "category": "architecture",
+  "updated": "2026-06-21",
+  "version": "1.0",
+  "related": ["agentic-ai", "ai-agent", "harness-engineering", "model-context-protocol"],
+  "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" }
+  ],
+  "evidence": {
+    "evidenceLevel": "industry_observation",
+    "confidenceLevel": "high",
+    "sourceType": ["industry_observation", "paper"]
+  },
+  "locales": {
+    "en": {
+      "title": "What is a Multi-Agent Architecture?",
+      "summary": "A multi-agent architecture divides a task among several specialized agents that collaborate, delegate or compete to reach a goal, instead of relying on one general agent. Common shapes include an orchestrator that delegates to workers, pipelines where each agent owns a stage, and debate or critic patterns. It can improve modularity and reliability for complex tasks, but adds coordination overhead and should be adopted only when a single agent demonstrably falls short.",
+      "definition": "A multi-agent architecture is a system design in which multiple specialized AI agents coordinate — through an orchestrator, a pipeline or peer interaction — to accomplish a task that is decomposed across them.",
+      "takeaways": [
+        "Several specialized agents beat one generalist for some complex tasks.",
+        "Common patterns: orchestrator-workers, pipelines, debate/critic.",
+        "Specialization improves modularity and focus per role.",
+        "Coordination, latency and cost overhead are the main costs.",
+        "Default to a single agent; go multi-agent only when measurement justifies it."
+      ],
+      "context": [
+        "As tasks grow, a single agent's context and reasoning get stretched. Splitting the work into focused roles — researcher, writer, reviewer; or planner and executors — can make each part more reliable and easier to evaluate.",
+        "But multi-agent is not automatically better. Every added agent adds communication, failure modes and cost. The discipline is to decompose only where roles are genuinely separable and a single agent measurably underperforms."
+      ],
+      "architecture": [
+        "Orchestrator-workers: a lead agent plans and delegates subtasks to worker agents, then synthesizes results. Pipeline: agents are arranged in stages, each transforming the output of the previous. Peer patterns: agents debate, critique or vote to improve quality.",
+        "Cross-cutting concerns — shared memory, message passing, error handling, budgets and observability — are where most multi-agent systems succeed or fail. Clear contracts between agents matter more than clever role names."
+      ],
+      "components": ["Orchestrator / lead agent", "Worker / specialist agents", "Shared memory & state", "Message passing", "Tools (often via MCP)", "Guardrails & budgets", "Observability"],
+      "pros": [
+        "Modular, specialized roles that are easier to evaluate.",
+        "Parallelism for independent subtasks.",
+        "Separation of concerns across complex workflows.",
+        "Critic/debate patterns can raise output quality."
+      ],
+      "risks": [
+        "Coordination overhead and added latency.",
+        "More failure modes and harder debugging.",
+        "Higher token cost from inter-agent communication.",
+        "Premature complexity when one agent would suffice."
+      ],
+      "tools": ["LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)"],
+      "examples": [
+        "An orchestrator delegating research, drafting and review to specialist agents.",
+        "A pipeline that extracts, transforms and validates data across stages.",
+        "A critic agent reviewing another agent's output before it is finalized."
+      ],
+      "faqs": [
+        { "q": "Is multi-agent always better than a single agent?", "a": "No. It adds coordination, cost and failure modes. Prefer a single agent and adopt multi-agent only when a task is clearly separable and a single agent underperforms." },
+        { "q": "What is the orchestrator-workers pattern?", "a": "A lead agent plans a task, delegates subtasks to specialized worker agents, and synthesizes their results into a final answer." },
+        { "q": "How do multi-agent systems fail?", "a": "Through unclear contracts between agents, lost context, runaway loops, and compounding errors — which is why budgets and observability are essential." },
+        { "q": "How does MCP relate to multi-agent systems?", "a": "MCP standardizes how each agent connects to tools and data, making integrations reusable across the agents in the system." }
+      ]
+    },
+    "es": {
+      "title": "¿Qué es una Arquitectura Multiagente?",
+      "summary": "Una arquitectura multiagente divide una tarea entre varios agentes especializados que colaboran, delegan o compiten para alcanzar un objetivo, en lugar de depender de un único agente general. Formas habituales: un orquestador que delega en trabajadores, pipelines donde cada agente posee una etapa, y patrones de debate o crítico. Puede mejorar la modularidad y la fiabilidad en tareas complejas, pero añade coste de coordinación y solo debe adoptarse cuando un solo agente se queda corto de forma demostrable.",
+      "definition": "Una arquitectura multiagente es un diseño de sistema en el que varios agentes de IA especializados se coordinan —mediante un orquestador, un pipeline o interacción entre pares— para realizar una tarea descompuesta entre ellos.",
+      "takeaways": [
+        "Varios agentes especializados superan a uno generalista en ciertas tareas complejas.",
+        "Patrones habituales: orquestador-trabajadores, pipelines, debate/crítico.",
+        "La especialización mejora la modularidad y el foco por rol.",
+        "El coste principal es la coordinación, la latencia y el gasto.",
+        "Por defecto, un solo agente; ir a multiagente solo cuando la medición lo justifique."
+      ],
+      "context": [
+        "A medida que crecen las tareas, el contexto y el razonamiento de un solo agente se tensan. Dividir el trabajo en roles enfocados —investigador, redactor, revisor; o planificador y ejecutores— puede hacer cada parte más fiable y fácil de evaluar.",
+        "Pero multiagente no es automáticamente mejor. Cada agente añadido suma comunicación, modos de fallo y coste. La disciplina es descomponer solo donde los roles sean realmente separables y un solo agente rinda peor de forma medible."
+      ],
+      "architecture": [
+        "Orquestador-trabajadores: un agente líder planifica y delega subtareas a agentes trabajadores, y luego sintetiza los resultados. Pipeline: los agentes se disponen en etapas, cada una transformando la salida de la anterior. Patrones entre pares: los agentes debaten, critican o votan para mejorar la calidad.",
+        "Las preocupaciones transversales —memoria compartida, paso de mensajes, gestión de errores, presupuestos y observabilidad— son donde la mayoría de sistemas multiagente triunfan o fracasan. Los contratos claros entre agentes importan más que los nombres ingeniosos de roles."
+      ],
+      "components": ["Orquestador / agente líder", "Agentes trabajadores / especialistas", "Memoria y estado compartidos", "Paso de mensajes", "Herramientas (a menudo vía MCP)", "Guardarraíles y presupuestos", "Observabilidad"],
+      "pros": [
+        "Roles modulares y especializados, más fáciles de evaluar.",
+        "Paralelismo para subtareas independientes.",
+        "Separación de responsabilidades en flujos complejos.",
+        "Los patrones de crítico/debate pueden elevar la calidad."
+      ],
+      "risks": [
+        "Coste de coordinación y latencia añadida.",
+        "Más modos de fallo y depuración más difícil.",
+        "Mayor coste de tokens por la comunicación entre agentes.",
+        "Complejidad prematura cuando bastaría un agente."
+      ],
+      "tools": ["LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)"],
+      "examples": [
+        "Un orquestador que delega investigación, redacción y revisión a agentes especialistas.",
+        "Un pipeline que extrae, transforma y valida datos por etapas.",
+        "Un agente crítico que revisa la salida de otro agente antes de finalizarla."
+      ],
+      "faqs": [
+        { "q": "¿Multiagente es siempre mejor que un solo agente?", "a": "No. Añade coordinación, coste y modos de fallo. Prefiere un solo agente y adopta multiagente solo cuando la tarea sea claramente separable y un agente rinda peor." },
+        { "q": "¿Qué es el patrón orquestador-trabajadores?", "a": "Un agente líder planifica una tarea, delega subtareas a agentes trabajadores especializados y sintetiza sus resultados en una respuesta final." },
+        { "q": "¿Cómo fallan los sistemas multiagente?", "a": "Por contratos poco claros entre agentes, pérdida de contexto, bucles descontrolados y acumulación de errores; por eso presupuestos y observabilidad son esenciales." },
+        { "q": "¿Cómo se relaciona MCP con los sistemas multiagente?", "a": "MCP estandariza cómo cada agente se conecta a herramientas y datos, haciendo las integraciones reutilizables entre los agentes del sistema." }
+      ]
+    },
+    "pt": {
+      "title": "O que é uma Arquitetura Multiagente?",
+      "summary": "Uma arquitetura multiagente divide uma tarefa entre vários agentes especializados que colaboram, delegam ou competem para alcançar um objetivo, em vez de depender de um único agente geral. Formas comuns: um orquestrador que delega a trabalhadores, pipelines em que cada agente possui uma etapa, e padrões de debate ou crítico. Pode melhorar a modularidade e a confiabilidade em tarefas complexas, mas adiciona custo de coordenação e só deve ser adotada quando um único agente fica aquém de forma demonstrável.",
+      "definition": "Uma arquitetura multiagente é um design de sistema em que vários agentes de IA especializados se coordenam — por um orquestrador, um pipeline ou interação entre pares — para realizar uma tarefa decomposta entre eles.",
+      "takeaways": [
+        "Vários agentes especializados superam um generalista em certas tarefas complexas.",
+        "Padrões comuns: orquestrador-trabalhadores, pipelines, debate/crítico.",
+        "A especialização melhora a modularidade e o foco por papel.",
+        "O custo principal é a coordenação, a latência e o gasto.",
+        "Por padrão, um único agente; ir para multiagente só quando a medição justificar."
+      ],
+      "context": [
+        "À medida que as tarefas crescem, o contexto e o raciocínio de um único agente se esticam. Dividir o trabalho em papéis focados — pesquisador, redator, revisor; ou planejador e executores — pode tornar cada parte mais confiável e fácil de avaliar.",
+        "Mas multiagente não é automaticamente melhor. Cada agente adicionado soma comunicação, modos de falha e custo. A disciplina é decompor só onde os papéis sejam realmente separáveis e um único agente tenha desempenho mensuravelmente pior."
+      ],
+      "architecture": [
+        "Orquestrador-trabalhadores: um agente líder planeja e delega subtarefas a agentes trabalhadores, e depois sintetiza os resultados. Pipeline: os agentes são dispostos em etapas, cada uma transformando a saída da anterior. Padrões entre pares: os agentes debatem, criticam ou votam para melhorar a qualidade.",
+        "As preocupações transversais — memória compartilhada, passagem de mensagens, tratamento de erros, orçamentos e observabilidade — são onde a maioria dos sistemas multiagente tem sucesso ou falha. Contratos claros entre agentes importam mais que nomes engenhosos de papéis."
+      ],
+      "components": ["Orquestrador / agente líder", "Agentes trabalhadores / especialistas", "Memória e estado compartilhados", "Passagem de mensagens", "Ferramentas (muitas vezes via MCP)", "Guard-rails e orçamentos", "Observabilidade"],
+      "pros": [
+        "Papéis modulares e especializados, mais fáceis de avaliar.",
+        "Paralelismo para subtarefas independentes.",
+        "Separação de responsabilidades em fluxos complexos.",
+        "Padrões de crítico/debate podem elevar a qualidade."
+      ],
+      "risks": [
+        "Custo de coordenação e latência adicional.",
+        "Mais modos de falha e depuração mais difícil.",
+        "Maior custo de tokens pela comunicação entre agentes.",
+        "Complexidade prematura quando bastaria um agente."
+      ],
+      "tools": ["LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)"],
+      "examples": [
+        "Um orquestrador que delega pesquisa, redação e revisão a agentes especialistas.",
+        "Um pipeline que extrai, transforma e valida dados por etapas.",
+        "Um agente crítico que revisa a saída de outro agente antes de finalizá-la."
+      ],
+      "faqs": [
+        { "q": "Multiagente é sempre melhor que um único agente?", "a": "Não. Adiciona coordenação, custo e modos de falha. Prefira um único agente e adote multiagente só quando a tarefa for claramente separável e um agente tiver desempenho pior." },
+        { "q": "O que é o padrão orquestrador-trabalhadores?", "a": "Um agente líder planeja uma tarefa, delega subtarefas a agentes trabalhadores especializados e sintetiza seus resultados numa resposta final." },
+        { "q": "Como os sistemas multiagente falham?", "a": "Por contratos pouco claros entre agentes, perda de contexto, laços descontrolados e acúmulo de erros; por isso orçamentos e observabilidade são essenciais." },
+        { "q": "Como o MCP se relaciona com sistemas multiagente?", "a": "O MCP padroniza como cada agente se conecta a ferramentas e dados, tornando as integrações reutilizáveis entre os agentes do sistema." }
+      ]
+    }
+  }
+}

package/content/knowledge/prompt-engineering.json

@@ -0,0 +1,153 @@
+{
+  "slug": "prompt-engineering",
+  "category": "concept",
+  "updated": "2026-06-21",
+  "version": "1.0",
+  "related": ["context-engineering", "tool-use", "agentic-ai", "harness-engineering"],
+  "references": [
+    { "title": "Wei et al. — Chain-of-Thought Prompting Elicits Reasoning in LLMs (2022)", "url": "https://arxiv.org/abs/2201.11903" },
+    { "title": "Anthropic — Prompt engineering overview", "url": "https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview" }
+  ],
+  "evidence": {
+    "evidenceLevel": "benchmark",
+    "confidenceLevel": "high",
+    "sourceType": ["benchmark", "paper", "industry_observation"]
+  },
+  "locales": {
+    "en": {
+      "title": "What is Prompt Engineering?",
+      "summary": "Prompt engineering is the practice of designing the inputs given to a language model so it produces the desired output reliably. A good prompt specifies the role, the task, the constraints, the output format and, when useful, examples. It is the most accessible lever for steering model behavior — and one layer of the broader harness around a model — but on its own it does not make a system reliable at scale.",
+      "definition": "Prompt engineering is the practice of designing and refining the instructions, context and examples given to a language model to reliably elicit a desired output.",
+      "takeaways": [
+        "A strong prompt states role, task, constraints, format and examples.",
+        "Examples (few-shot) usually beat instructions alone for structured tasks.",
+        "Chain-of-thought prompting improves multi-step reasoning.",
+        "Prompts should be tested and versioned, not hand-tuned by feel.",
+        "It is one layer of the harness, not a substitute for tools, memory and evaluation."
+      ],
+      "context": [
+        "Because models follow instructions in natural language, the way a task is phrased materially changes the result. Prompt engineering is the discipline of phrasing it well: being explicit about the goal, the audience, the constraints and the format you want back.",
+        "It is the fastest, cheapest way to improve output quality, which is why it is where most teams start. But as systems grow into agents, prompting becomes one component among tools, memory, retrieval and evaluation — the full harness."
+      ],
+      "architecture": [
+        "Common techniques: zero-shot (instruction only), few-shot (instruction plus examples), chain-of-thought (ask for step-by-step reasoning), role and format specification, and decomposition (breaking a task into smaller prompts).",
+        "Mature practice treats prompts as code: stored, versioned, tested against evals, and changed deliberately. Reusable prompt templates and structured output schemas reduce variance."
+      ],
+      "components": ["Role / persona", "Task instruction", "Constraints", "Output format", "Examples (few-shot)", "Reasoning cues"],
+      "pros": [
+        "Fastest, cheapest way to change model behavior.",
+        "No training or infrastructure required.",
+        "Works across models and tasks.",
+        "Easy to iterate and combine with other techniques."
+      ],
+      "risks": [
+        "Fragile: small wording changes can shift behavior.",
+        "Prompt injection when prompts include untrusted input.",
+        "Hard to scale reliability by prompting alone.",
+        "Hidden coupling to a specific model's quirks."
+      ],
+      "tools": ["Prompt templates", "Structured output / JSON schema", "LangSmith / Langfuse (prompt testing)", "Evaluation suites"],
+      "examples": [
+        "Adding a few worked examples to make a model output consistent JSON.",
+        "Asking for step-by-step reasoning to improve a math or logic answer.",
+        "Specifying a strict format so downstream code can parse the response."
+      ],
+      "faqs": [
+        { "q": "Is prompt engineering still relevant as models improve?", "a": "Yes, but its role narrows. Better models need less coaxing, yet clear instructions, examples and format specs still measurably improve reliability — especially inside agents." },
+        { "q": "What is the difference from context engineering?", "a": "Prompt engineering focuses on the instruction. Context engineering is the broader task of deciding what information enters the model's limited context window at each step." },
+        { "q": "Does chain-of-thought always help?", "a": "It helps most on multi-step reasoning tasks, at the cost of more tokens. For simple lookups it adds latency without benefit." },
+        { "q": "How do you keep prompts reliable?", "a": "Treat them as code: version them, test them against evals, and change them deliberately rather than by trial and error." }
+      ]
+    },
+    "es": {
+      "title": "¿Qué es la Ingeniería de Prompts (Prompt Engineering)?",
+      "summary": "La ingeniería de prompts es la práctica de diseñar las entradas que se dan a un modelo de lenguaje para que produzca la salida deseada de forma fiable. Un buen prompt especifica el rol, la tarea, las restricciones, el formato de salida y, cuando conviene, ejemplos. Es la palanca más accesible para guiar el comportamiento del modelo —y una capa del harness más amplio— pero por sí sola no hace fiable a un sistema a escala.",
+      "definition": "La ingeniería de prompts es la práctica de diseñar y refinar las instrucciones, el contexto y los ejemplos que se dan a un modelo de lenguaje para obtener de forma fiable la salida deseada.",
+      "takeaways": [
+        "Un buen prompt indica rol, tarea, restricciones, formato y ejemplos.",
+        "Los ejemplos (few-shot) suelen superar a las instrucciones solas en tareas estructuradas.",
+        "El chain-of-thought mejora el razonamiento de varios pasos.",
+        "Los prompts deben probarse y versionarse, no ajustarse a ojo.",
+        "Es una capa del harness, no un sustituto de herramientas, memoria y evaluación."
+      ],
+      "context": [
+        "Como los modelos siguen instrucciones en lenguaje natural, la forma de plantear una tarea cambia materialmente el resultado. La ingeniería de prompts es la disciplina de plantearla bien: ser explícito sobre el objetivo, la audiencia, las restricciones y el formato que quieres recibir.",
+        "Es la forma más rápida y barata de mejorar la calidad, por eso es donde empiezan la mayoría de equipos. Pero al crecer hacia agentes, el prompting pasa a ser un componente entre herramientas, memoria, recuperación y evaluación: el harness completo."
+      ],
+      "architecture": [
+        "Técnicas habituales: zero-shot (solo instrucción), few-shot (instrucción más ejemplos), chain-of-thought (pedir razonamiento paso a paso), especificación de rol y formato, y descomposición (dividir una tarea en prompts más pequeños).",
+        "La práctica madura trata los prompts como código: se guardan, se versionan, se prueban contra evaluaciones y se cambian de forma deliberada. Las plantillas reutilizables y los esquemas de salida estructurada reducen la varianza."
+      ],
+      "components": ["Rol / persona", "Instrucción de tarea", "Restricciones", "Formato de salida", "Ejemplos (few-shot)", "Pistas de razonamiento"],
+      "pros": [
+        "La forma más rápida y barata de cambiar el comportamiento del modelo.",
+        "No requiere entrenamiento ni infraestructura.",
+        "Funciona entre modelos y tareas.",
+        "Fácil de iterar y combinar con otras técnicas."
+      ],
+      "risks": [
+        "Frágil: pequeños cambios de redacción alteran el comportamiento.",
+        "Inyección de prompts cuando incluyen entrada no confiable.",
+        "Difícil escalar la fiabilidad solo con prompting.",
+        "Acoplamiento oculto a las peculiaridades de un modelo."
+      ],
+      "tools": ["Plantillas de prompts", "Salida estructurada / JSON schema", "LangSmith / Langfuse (pruebas de prompts)", "Suites de evaluación"],
+      "examples": [
+        "Añadir ejemplos para que un modelo devuelva JSON consistente.",
+        "Pedir razonamiento paso a paso para mejorar una respuesta de lógica o matemáticas.",
+        "Especificar un formato estricto para que el código posterior pueda parsear la respuesta."
+      ],
+      "faqs": [
+        { "q": "¿Sigue siendo relevante el prompt engineering según mejoran los modelos?", "a": "Sí, pero su papel se estrecha. Los mejores modelos necesitan menos persuasión, pero instrucciones claras, ejemplos y formato siguen mejorando la fiabilidad de forma medible, sobre todo dentro de agentes." },
+        { "q": "¿En qué se diferencia de la ingeniería de contexto?", "a": "El prompt engineering se centra en la instrucción. La ingeniería de contexto es la tarea más amplia de decidir qué información entra en la ventana de contexto limitada del modelo en cada paso." },
+        { "q": "¿El chain-of-thought ayuda siempre?", "a": "Ayuda sobre todo en tareas de razonamiento de varios pasos, a costa de más tokens. Para búsquedas simples añade latencia sin beneficio." },
+        { "q": "¿Cómo se mantienen fiables los prompts?", "a": "Tratándolos como código: versionarlos, probarlos contra evaluaciones y cambiarlos de forma deliberada en vez de por ensayo y error." }
+      ]
+    },
+    "pt": {
+      "title": "O que é Engenharia de Prompts (Prompt Engineering)?",
+      "summary": "A engenharia de prompts é a prática de projetar as entradas dadas a um modelo de linguagem para que ele produza a saída desejada de forma confiável. Um bom prompt especifica o papel, a tarefa, as restrições, o formato de saída e, quando útil, exemplos. É a alavanca mais acessível para guiar o comportamento do modelo — e uma camada do harness mais amplo — mas sozinha não torna um sistema confiável em escala.",
+      "definition": "A engenharia de prompts é a prática de projetar e refinar as instruções, o contexto e os exemplos dados a um modelo de linguagem para obter de forma confiável a saída desejada.",
+      "takeaways": [
+        "Um bom prompt indica papel, tarefa, restrições, formato e exemplos.",
+        "Exemplos (few-shot) costumam superar instruções sozinhas em tarefas estruturadas.",
+        "O chain-of-thought melhora o raciocínio de vários passos.",
+        "Os prompts devem ser testados e versionados, não ajustados no olho.",
+        "É uma camada do harness, não um substituto de ferramentas, memória e avaliação."
+      ],
+      "context": [
+        "Como os modelos seguem instruções em linguagem natural, a forma de formular uma tarefa muda materialmente o resultado. A engenharia de prompts é a disciplina de formulá-la bem: ser explícito sobre o objetivo, o público, as restrições e o formato que você quer receber.",
+        "É a forma mais rápida e barata de melhorar a qualidade, por isso é onde a maioria das equipes começa. Mas ao crescer rumo a agentes, o prompting passa a ser um componente entre ferramentas, memória, recuperação e avaliação: o harness completo."
+      ],
+      "architecture": [
+        "Técnicas comuns: zero-shot (só instrução), few-shot (instrução mais exemplos), chain-of-thought (pedir raciocínio passo a passo), especificação de papel e formato, e decomposição (dividir uma tarefa em prompts menores).",
+        "A prática madura trata os prompts como código: são guardados, versionados, testados contra avaliações e alterados de forma deliberada. Modelos reutilizáveis e esquemas de saída estruturada reduzem a variância."
+      ],
+      "components": ["Papel / persona", "Instrução de tarefa", "Restrições", "Formato de saída", "Exemplos (few-shot)", "Pistas de raciocínio"],
+      "pros": [
+        "A forma mais rápida e barata de mudar o comportamento do modelo.",
+        "Não requer treinamento nem infraestrutura.",
+        "Funciona entre modelos e tarefas.",
+        "Fácil de iterar e combinar com outras técnicas."
+      ],
+      "risks": [
+        "Frágil: pequenas mudanças de redação alteram o comportamento.",
+        "Injeção de prompts quando incluem entrada não confiável.",
+        "Difícil escalar a confiabilidade só com prompting.",
+        "Acoplamento oculto às peculiaridades de um modelo."
+      ],
+      "tools": ["Modelos de prompts", "Saída estruturada / JSON schema", "LangSmith / Langfuse (testes de prompts)", "Suítes de avaliação"],
+      "examples": [
+        "Adicionar exemplos para um modelo devolver JSON consistente.",
+        "Pedir raciocínio passo a passo para melhorar uma resposta de lógica ou matemática.",
+        "Especificar um formato estrito para o código posterior poder parsear a resposta."
+      ],
+      "faqs": [
+        { "q": "A engenharia de prompts ainda é relevante conforme os modelos melhoram?", "a": "Sim, mas seu papel se estreita. Modelos melhores precisam de menos persuasão, mas instruções claras, exemplos e formato continuam melhorando a confiabilidade de forma mensurável, sobretudo dentro de agentes." },
+        { "q": "Qual a diferença para a engenharia de contexto?", "a": "A engenharia de prompts foca na instrução. A engenharia de contexto é a tarefa mais ampla de decidir qual informação entra na janela de contexto limitada do modelo a cada passo." },
+        { "q": "O chain-of-thought sempre ajuda?", "a": "Ajuda sobretudo em tarefas de raciocínio de vários passos, ao custo de mais tokens. Para buscas simples adiciona latência sem benefício." },
+        { "q": "Como manter os prompts confiáveis?", "a": "Tratando-os como código: versioná-los, testá-los contra avaliações e alterá-los de forma deliberada em vez de por tentativa e erro." }
+      ]
+    }
+  }
+}

package/content/knowledge/prompt-injection.json

@@ -0,0 +1,138 @@
+{
+  "slug": "prompt-injection",
+  "category": "governance",
+  "updated": "2026-06-21",
+  "version": "1.0",
+  "related": ["guardrails", "tool-use", "ai-governance", "model-context-protocol", "ai-cyberdefense", "agentic-threat-model"],
+  "references": [
+    { "title": "OWASP — Top 10 for LLM Applications (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" }
+  ],
+  "evidence": {
+    "evidenceLevel": "industry_observation",
+    "confidenceLevel": "high",
+    "sourceType": ["industry_observation", "paper"]
+  },
+  "locales": {
+    "en": {
+      "title": "What is Prompt Injection?",
+      "summary": "Prompt injection is an attack in which malicious instructions hidden in the input to a language model hijack its behavior — making it ignore its rules, leak data or misuse tools. It tops the OWASP Top 10 for LLM applications. The root cause is that models cannot reliably separate trusted instructions from untrusted content, so any text an agent reads — a web page, a document, a tool result — can carry an attack.",
+      "definition": "Prompt injection is a security attack where adversarial instructions embedded in untrusted input cause a language model to deviate from its intended behavior, bypass safeguards, or perform unintended actions.",
+      "takeaways": [
+        "Untrusted text a model reads can contain hidden instructions.",
+        "It is the #1 risk in the OWASP Top 10 for LLM applications.",
+        "Indirect injection hides payloads in documents, pages or tool outputs.",
+        "Risk grows with tool access — injection can trigger real actions.",
+        "There is no single fix; defense is layered (least privilege, isolation, human approval)."
+      ],
+      "context": [
+        "Models follow instructions in natural language and cannot reliably tell trusted system instructions from untrusted user or document content. An attacker exploits this by planting instructions like 'ignore previous instructions and…' where the model will read them.",
+        "Direct injection comes from the user; indirect (and more dangerous) injection hides in content the agent retrieves — a web page, an email, a file, an MCP tool result. As agents gain tool access, a successful injection can exfiltrate data or take harmful actions."
+      ],
+      "architecture": [
+        "Defense is layered, not a single control: least-privilege tool permissions, isolating and clearly delimiting untrusted content, output and action validation, allow-lists for sensitive operations, and human-in-the-loop approval for high-impact actions.",
+        "Treat all tool and retrieval outputs as untrusted input. Monitor and log agent actions (observability) so injection attempts are detectable, and red-team the system regularly."
+      ],
+      "components": ["Untrusted input boundary", "Least-privilege permissions", "Content isolation / delimiting", "Output & action validation", "Human approval for high-impact actions", "Monitoring & red teaming"],
+      "pros": [],
+      "risks": [
+        "Data exfiltration of sensitive context or credentials.",
+        "Unauthorized tool actions in connected systems.",
+        "Bypassed safety policies and guardrails.",
+        "Indirect attacks via documents, web pages or tool results."
+      ],
+      "tools": ["Input/output guardrail libraries", "Permission & sandboxing layers", "Allow-lists for tool actions", "Monitoring / observability", "Red-teaming frameworks"],
+      "examples": [
+        "A web page the agent reads contains hidden text telling it to email private data.",
+        "A document instructs a summarizer to ignore its rules and output a malicious link.",
+        "A tool result tries to make an agent call another tool it should not."
+      ],
+      "faqs": [
+        { "q": "Why can't models just ignore injected instructions?", "a": "Because they cannot reliably distinguish trusted instructions from untrusted content — both arrive as text. That ambiguity is the core vulnerability." },
+        { "q": "What is indirect prompt injection?", "a": "When the malicious instructions are hidden in external content the model retrieves — a page, file, email or tool output — rather than typed by the user. It is often more dangerous." },
+        { "q": "Can prompt injection be fully prevented?", "a": "Not by a single measure today. You reduce risk with layered defenses: least privilege, content isolation, validation, monitoring and human approval for sensitive actions." },
+        { "q": "How does tool use raise the stakes?", "a": "Without tools, injection mostly produces bad text. With tools, an injected instruction can take real actions — send data, make changes — so permissions and approval matter more." }
+      ]
+    },
+    "es": {
+      "title": "¿Qué es la Inyección de Prompts (Prompt Injection)?",
+      "summary": "La inyección de prompts es un ataque en el que instrucciones maliciosas ocultas en la entrada a un modelo de lenguaje secuestran su comportamiento, haciéndole ignorar sus reglas, filtrar datos o usar mal las herramientas. Encabeza el OWASP Top 10 para aplicaciones LLM. La causa raíz es que los modelos no pueden separar de forma fiable las instrucciones de confianza del contenido no confiable, así que cualquier texto que un agente lea —una página web, un documento, el resultado de una herramienta— puede portar un ataque.",
+      "definition": "La inyección de prompts es un ataque de seguridad en el que instrucciones adversarias incrustadas en entrada no confiable hacen que un modelo de lenguaje se desvíe de su comportamiento previsto, evite salvaguardas o realice acciones no deseadas.",
+      "takeaways": [
+        "El texto no confiable que un modelo lee puede contener instrucciones ocultas.",
+        "Es el riesgo n.º 1 del OWASP Top 10 para aplicaciones LLM.",
+        "La inyección indirecta esconde payloads en documentos, páginas o salidas de herramientas.",
+        "El riesgo crece con el acceso a herramientas: la inyección puede disparar acciones reales.",
+        "No hay una sola solución; la defensa es por capas (mínimo privilegio, aislamiento, aprobación humana)."
+      ],
+      "context": [
+        "Los modelos siguen instrucciones en lenguaje natural y no pueden distinguir de forma fiable las instrucciones de sistema confiables del contenido no confiable de usuario o documentos. Un atacante lo explota plantando instrucciones como 'ignora las instrucciones anteriores y…' donde el modelo las leerá.",
+        "La inyección directa viene del usuario; la indirecta (y más peligrosa) se esconde en contenido que el agente recupera: una página web, un correo, un fichero, el resultado de una herramienta MCP. A medida que los agentes ganan acceso a herramientas, una inyección exitosa puede exfiltrar datos o tomar acciones dañinas."
+      ],
+      "architecture": [
+        "La defensa es por capas, no un único control: permisos de herramientas de mínimo privilegio, aislar y delimitar claramente el contenido no confiable, validación de salidas y acciones, listas de permitidos para operaciones sensibles y aprobación con humano en el bucle para acciones de alto impacto.",
+        "Trata todas las salidas de herramientas y recuperación como entrada no confiable. Monitoriza y registra las acciones del agente (observabilidad) para que los intentos de inyección sean detectables, y haz red teaming del sistema con regularidad."
+      ],
+      "components": ["Frontera de entrada no confiable", "Permisos de mínimo privilegio", "Aislamiento / delimitación de contenido", "Validación de salidas y acciones", "Aprobación humana para acciones de alto impacto", "Monitorización y red teaming"],
+      "pros": [],
+      "risks": [
+        "Exfiltración de contexto sensible o credenciales.",
+        "Acciones no autorizadas de herramientas en sistemas conectados.",
+        "Políticas de seguridad y guardarraíles evitados.",
+        "Ataques indirectos vía documentos, páginas web o resultados de herramientas."
+      ],
+      "tools": ["Librerías de guardarraíles de entrada/salida", "Capas de permisos y sandboxing", "Listas de permitidos para acciones de herramientas", "Monitorización / observabilidad", "Frameworks de red teaming"],
+      "examples": [
+        "Una página web que el agente lee contiene texto oculto que le dice que envíe datos privados por correo.",
+        "Un documento instruye a un resumidor a ignorar sus reglas y emitir un enlace malicioso.",
+        "El resultado de una herramienta intenta que un agente llame a otra herramienta que no debería."
+      ],
+      "faqs": [
+        { "q": "¿Por qué los modelos no pueden simplemente ignorar las instrucciones inyectadas?", "a": "Porque no pueden distinguir de forma fiable las instrucciones confiables del contenido no confiable: ambas llegan como texto. Esa ambigüedad es la vulnerabilidad central." },
+        { "q": "¿Qué es la inyección de prompts indirecta?", "a": "Cuando las instrucciones maliciosas se esconden en contenido externo que el modelo recupera —una página, fichero, correo o salida de herramienta— en vez de escribirlas el usuario. Suele ser más peligrosa." },
+        { "q": "¿Se puede prevenir por completo la inyección de prompts?", "a": "Hoy no con una sola medida. Reduces el riesgo con defensas por capas: mínimo privilegio, aislamiento de contenido, validación, monitorización y aprobación humana para acciones sensibles." },
+        { "q": "¿Cómo eleva la apuesta el uso de herramientas?", "a": "Sin herramientas, la inyección produce sobre todo texto malo. Con herramientas, una instrucción inyectada puede tomar acciones reales —enviar datos, hacer cambios—, así que importan más los permisos y la aprobación." }
+      ]
+    },
+    "pt": {
+      "title": "O que é Injeção de Prompts (Prompt Injection)?",
+      "summary": "A injeção de prompts é um ataque em que instruções maliciosas escondidas na entrada de um modelo de linguagem sequestram seu comportamento, fazendo-o ignorar suas regras, vazar dados ou usar mal as ferramentas. Lidera o OWASP Top 10 para aplicações LLM. A causa raiz é que os modelos não conseguem separar de forma confiável as instruções confiáveis do conteúdo não confiável, então qualquer texto que um agente leia — uma página web, um documento, o resultado de uma ferramenta — pode carregar um ataque.",
+      "definition": "A injeção de prompts é um ataque de segurança em que instruções adversárias embutidas em entrada não confiável fazem um modelo de linguagem desviar de seu comportamento previsto, contornar salvaguardas ou realizar ações indesejadas.",
+      "takeaways": [
+        "O texto não confiável que um modelo lê pode conter instruções ocultas.",
+        "É o risco nº 1 do OWASP Top 10 para aplicações LLM.",
+        "A injeção indireta esconde payloads em documentos, páginas ou saídas de ferramentas.",
+        "O risco cresce com o acesso a ferramentas: a injeção pode disparar ações reais.",
+        "Não há uma única solução; a defesa é em camadas (privilégio mínimo, isolamento, aprovação humana)."
+      ],
+      "context": [
+        "Os modelos seguem instruções em linguagem natural e não conseguem distinguir de forma confiável as instruções de sistema confiáveis do conteúdo não confiável de usuário ou documentos. Um atacante explora isso plantando instruções como 'ignore as instruções anteriores e…' onde o modelo as lerá.",
+        "A injeção direta vem do usuário; a indireta (e mais perigosa) se esconde em conteúdo que o agente recupera: uma página web, um e-mail, um arquivo, o resultado de uma ferramenta MCP. À medida que os agentes ganham acesso a ferramentas, uma injeção bem-sucedida pode exfiltrar dados ou tomar ações nocivas."
+      ],
+      "architecture": [
+        "A defesa é em camadas, não um único controle: permissões de ferramentas de privilégio mínimo, isolar e delimitar claramente o conteúdo não confiável, validação de saídas e ações, listas de permitidos para operações sensíveis e aprovação com humano no laço para ações de alto impacto.",
+        "Trate todas as saídas de ferramentas e recuperação como entrada não confiável. Monitore e registre as ações do agente (observabilidade) para que as tentativas de injeção sejam detectáveis, e faça red teaming do sistema regularmente."
+      ],
+      "components": ["Fronteira de entrada não confiável", "Permissões de privilégio mínimo", "Isolamento / delimitação de conteúdo", "Validação de saídas e ações", "Aprovação humana para ações de alto impacto", "Monitoramento e red teaming"],
+      "pros": [],
+      "risks": [
+        "Exfiltração de contexto sensível ou credenciais.",
+        "Ações não autorizadas de ferramentas em sistemas conectados.",
+        "Políticas de segurança e guard-rails contornados.",
+        "Ataques indiretos via documentos, páginas web ou resultados de ferramentas."
+      ],
+      "tools": ["Bibliotecas de guard-rails de entrada/saída", "Camadas de permissões e sandboxing", "Listas de permitidos para ações de ferramentas", "Monitoramento / observabilidade", "Frameworks de red teaming"],
+      "examples": [
+        "Uma página web que o agente lê contém texto oculto que lhe diz para enviar dados privados por e-mail.",
+        "Um documento instrui um resumidor a ignorar suas regras e emitir um link malicioso.",
+        "O resultado de uma ferramenta tenta fazer um agente chamar outra ferramenta que não deveria."
+      ],
+      "faqs": [
+        { "q": "Por que os modelos não podem simplesmente ignorar as instruções injetadas?", "a": "Porque não conseguem distinguir de forma confiável as instruções confiáveis do conteúdo não confiável: ambas chegam como texto. Essa ambiguidade é a vulnerabilidade central." },
+        { "q": "O que é injeção de prompts indireta?", "a": "Quando as instruções maliciosas se escondem em conteúdo externo que o modelo recupera — uma página, arquivo, e-mail ou saída de ferramenta — em vez de digitadas pelo usuário. Costuma ser mais perigosa." },
+        { "q": "A injeção de prompts pode ser totalmente prevenida?", "a": "Hoje não com uma única medida. Você reduz o risco com defesas em camadas: privilégio mínimo, isolamento de conteúdo, validação, monitoramento e aprovação humana para ações sensíveis." },
+        { "q": "Como o uso de ferramentas eleva a aposta?", "a": "Sem ferramentas, a injeção produz sobretudo texto ruim. Com ferramentas, uma instrução injetada pode tomar ações reais — enviar dados, fazer mudanças —, então permissões e aprovação importam mais." }
+      ]
+    }
+  }
+}