santismm-knowledge-mcp 0.2.1

package/content/harness/HRN-010-orchestration.md

@@ -0,0 +1,149 @@
+---
+id: HRN-010
+title: Orchestration
+domain: Harness
+category: Orchestration
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: Orchestration is the harness layer that drives execution—single vs multi-agent topologies, supervisor/worker delegation, routing, state machines, and durable workflows—turning a plan into reliable, resumable action.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-003
+  - HRN-009
+  - PAT-002
+  - PAT-005
+tags:
+  - orchestration
+  - multi-agent
+  - supervisor-worker
+  - state-machine
+  - durable-execution
+---
+
+# Orchestration
+
+## Executive Summary
+
+Orchestration is the engine room of the harness: the layer that decides *who acts, in what order, and what happens when a step fails*. It spans the spectrum from a single agent running a loop to fleets of specialized agents coordinated by a supervisor. This chapter frames orchestration as the bridge between a represented plan (HRN-009) and reliable execution, and argues that the central engineering problem is not intelligence but **durability**: long-running, non-deterministic, partially-failing workflows must survive crashes, resume cleanly, and never silently lose or duplicate effects. The right default is the simplest topology that meets the requirement — complexity in orchestration is a cost, not a virtue.
+
+## Key Concepts
+
+- **Topology:** the arrangement of agents — single, pipeline, supervisor/worker, or network.
+- **Supervisor / orchestrator agent:** an agent that plans and delegates to workers (see PAT-002).
+- **Worker agent:** a specialized agent that executes a delegated sub-task (see PAT-005).
+- **Routing:** selecting the next agent, tool, or branch based on state.
+- **State machine:** an explicit graph of states and transitions governing execution.
+- **Durable execution:** workflow semantics where progress is checkpointed and resumable.
+- **Handoff:** transferring control and context from one agent to another.
+
+## Definition
+
+> **Orchestration** is the harness discipline of executing a plan across one or more agents and tools — selecting topology, routing control, coordinating state, and guaranteeing durable, exactly-the-right-number-of-times execution under failure.
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph Durable Workflow Engine
+      SUP[Supervisor Agent] -->|delegate| R{Router}
+      R -->|task A| W1[Worker: Retrieval]
+      R -->|task B| W2[Worker: Code/Tool]
+      R -->|task C| W3[Worker: Drafting]
+      W1 --> AGG[Aggregator / Reducer]
+      W2 --> AGG
+      W3 --> AGG
+      AGG --> SUP
+    end
+    SUP -->|checkpoint| ST[(Durable State Store)]
+    ST -->|resume after crash| SUP
+    SUP --> OUT[Verified Result]
+```
+
+## Detailed Explanation
+
+**Topology selection** is the first and most consequential decision. A *single agent* with tools is the correct default for most tasks: it is cheapest, easiest to observe, and has the fewest coordination failure modes. Reach for multi-agent only when the task genuinely benefits — when sub-tasks need *different* tool permissions, *different* context windows, or *parallel* independent execution. The common topologies are: **pipeline** (fixed sequence of stages), **supervisor/worker** (PAT-002 + PAT-005: a planner delegates to specialists and aggregates), and **network/peer** (agents hand off freely). Coordination cost rises sharply with topology freedom; peer networks are powerful but hardest to make reliable, govern, and debug.
+
+**Routing** is how control moves through the system. Routing can be *model-driven* (the supervisor chooses the next worker via tool-calling), *rule-driven* (deterministic transitions in a state machine), or *hybrid*. Deterministic routing is preferred wherever the path is known, because it is governable and testable; model-driven routing is reserved for genuinely open-ended branching. Encoding the workflow as an explicit **state machine** — states, allowed transitions, and guards — is the single highest-leverage reliability technique in orchestration: it bounds the space of behaviors, makes the system inspectable, and lets governance (HRN-008) attach controls to transitions.
+
+**Durability** is the property that separates a demo from a production system. Agentic workflows are long-running (seconds to hours), call flaky external tools, and may crash mid-flight. A durable execution engine checkpoints progress after each step so that on failure the workflow *resumes* from the last completed step rather than restarting. This demands careful effect semantics: tool calls with side effects must be **idempotent** or guarded by dedup keys so a resume does not double-charge a card or re-send an email. The hard cases are the *non-idempotent external effects*; the harness handles them with the saga pattern — record intent, execute, confirm, and provide compensating actions for partial failure.
+
+**State and context management** across agents is where multi-agent systems leak reliability. Each handoff (PAT-005) must transfer *exactly* the context the worker needs — too little and it fails, too much and it is expensive and prone to distraction. Shared state belongs in a durable store with clear ownership, not in a free-floating shared context window. Aggregation of worker outputs needs an explicit reducer with conflict resolution, because parallel workers will produce overlapping or contradictory results.
+
+Finally, orchestration owns **concurrency and failure isolation**. Parallel branches (exposed by the DAG plan from HRN-009) improve latency but require backpressure, rate-limit coordination across shared tools, and bulkheading so one failing worker cannot exhaust the budget or block siblings. Timeouts, circuit breakers, and per-worker budgets are orchestration concerns, not application concerns.
+
+## Production Evidence
+
+> **Illustrative / representative scenario.** Evidence level: theoretical · Confidence: medium · Source: industry_observation, personal_experience. The numbers below are representative ranges, not a measurement from one verified deployment.
+
+- **Context:** A research-and-synthesis agent answering complex enterprise questions.
+- **Scenario:** A supervisor decomposes a question, dispatches parallel retrieval/analysis workers, and aggregates a cited answer.
+- **Technology:** Durable workflow engine, supervisor/worker topology, deterministic router for known stages, dedup keys on side-effecting tools.
+- **Load:** Concurrent multi-worker runs; each run minutes long with several external tool calls.
+- **Results (representative):** Parallel fan-out commonly cuts wall-clock latency by a meaningful multiple over sequential execution, while durable checkpointing reduces failed-run rates by eliminating crash-induced full restarts. The cost is higher token spend (more agents, more context) and added coordination complexity.
+
+### Lessons Learned
+
+Most teams reach for multi-agent too early. The reliable progression is: make a single agent work, encode it as a state machine, add durability, *then* split into workers only where parallelism or permission isolation pays for the coordination cost.
+
+## Observed Failure Modes
+
+| Failure Mode | Trigger | Mitigation |
+|---|---|---|
+| Duplicate side effects | Resume re-runs a non-idempotent step | Idempotency keys / saga compensation |
+| Lost progress on crash | No checkpointing | Durable execution engine |
+| Context loss at handoff | Worker under-receives state | Explicit, typed handoff contracts |
+| Coordination deadlock | Workers wait on each other | Acyclic routing, timeouts, supervisor arbitration |
+| Cost explosion | Recursive/peer delegation unbounded | Per-run agent budget + delegation depth cap |
+| Conflicting aggregation | Parallel workers disagree | Explicit reducer with conflict resolution |
+| Shared-tool throttling | Workers hammer one rate-limited API | Centralized rate-limit + backpressure |
+
+## KPIs
+
+| Metric | Target | Notes |
+|---|---|---|
+| Task completion rate | High | End-to-end, verified |
+| Latency p50/p95/p99 | Minimized | Parallelism improves p50; tails dominated by slow workers |
+| Resume success rate | → 100% | Workflows that recover after a crash |
+| Duplicate-effect rate | → 0 | Idempotency correctness |
+| Cost per task | Bounded | Caps on agents/depth/tokens |
+| Throughput | Scales with concurrency | Limited by shared-tool rate limits |
+
+## Cost Metrics
+
+- **Token cost** grows with agent count and per-agent context; multi-agent is materially more expensive than single-agent for the same task.
+- **Orchestration overhead:** supervisor planning + aggregation inference per run.
+- **Durability overhead:** checkpoint writes (cheap) vs. the large savings from not restarting failed runs.
+
+## Scaling Characteristics
+
+Single-agent throughput scales horizontally and statelessly. Supervisor/worker scales sub-tasks in parallel up to shared-tool rate limits, which become the true ceiling. Durable workflow engines scale with the number of in-flight workflows; checkpoint storage and the dispatcher are the components to size. Peer/network topologies scale worst — coordination overhead and failure surface grow super-linearly with agent count, which is why bounded supervisor topologies are the enterprise default.
+
+## Related Content
+
+- HRN-003 — Orchestration's place in the harness taxonomy.
+- HRN-009 — The plan that orchestration executes.
+- PAT-002 — Supervisor Agent pattern.
+- PAT-005 — Multi-Agent Delegation pattern.
+
+## References
+
+- Temporal / durable-execution workflow engines (Saga pattern, workflow durability).
+- Anthropic, "Building Effective Agents" (single-agent-first, topology guidance).
+- LangGraph and state-machine orchestration for agents.
+
+## FAQs
+
+**Q: Single agent or multi-agent?**
+A: Default to single agent. Add agents only for parallelism or permission/context isolation that pays back the coordination cost.
+
+**Q: Why a state machine instead of free-form agent loops?**
+A: State machines bound behavior, are testable, and let governance attach controls to transitions. Free-form loops are powerful but hard to make reliable or auditable.
+
+**Q: How do I avoid double-charging a customer on retry?**
+A: Make side-effecting tool calls idempotent (dedup keys) or wrap them in a saga with compensating actions, and run on a durable engine that resumes rather than restarts.

package/content/harness/HRN-010-orchestration.pt.md

@@ -0,0 +1,107 @@
+---
+title: "Orquestração"
+summary: "O ciclo que governa o sistema: quem chama o modelo, com que contexto, o que acontece à saída, e como se coordenam vários agentes sem perder controle nem rastreabilidade."
+---
+
+# Orquestração
+
+## Resumo executivo
+
+A orquestração é a casa das máquinas do harness: a camada que decide *quem age, por que ordem e o que acontece quando um passo falha*. Abrange desde um único agente executando um ciclo até frotas de agentes especializados coordenados por um supervisor. Este capítulo enquadra a orquestração como a ponte entre um plano representado (HRN-009) e uma execução confiável, e sustenta que o problema central de engenharia não é a inteligência mas a **durabilidade**: fluxos de longa duração, não deterministas e com falhas parciais têm de sobreviver às quedas, retomar de forma limpa e nunca perder nem duplicar efeitos em silêncio. O valor por padrão certo é a topologia mais simples que cumpra o requisito: a complexidade na orquestração é um custo, não uma virtude.
+
+## Conceitos-chave
+
+- **Topologia:** a disposição dos agentes: único, pipeline, supervisor/trabalhador ou rede.
+- **Agente supervisor ou orquestrador:** um agente que planeja e delega em trabalhadores (ver PAT-002).
+- **Agente trabalhador:** um agente especializado que executa uma subtarefa delegada (ver PAT-005).
+- **Encaminhamento:** selecionar o próximo agente, ferramenta ou ramo em função do estado.
+- **Máquina de estados:** um grafo explícito de estados e transições que governa a execução.
+- **Execução duradoura:** semântica de fluxo em que o progresso é persistido em pontos de controle e é retomável.
+- **Passagem (handoff):** transferir controle e contexto de um agente para outro.
+
+## Definição
+
+> A **orquestração** é a disciplina do harness que executa um plano através de um ou vários agentes e ferramentas: seleciona a topologia, encaminha o controle, coordena o estado e garante uma execução duradoura e com exatamente o número certo de repetições perante a falha.
+
+## Explicação detalhada
+
+A **seleção de topologia** é a primeira decisão e a de maior consequência. Um *agente único* com ferramentas é o padrão certo para a maioria das tarefas: é o mais barato, o mais fácil de observar e o que tem menos modos de falha por coordenação. Recorra ao multiagente apenas quando a tarefa beneficie a sério: quando as subtarefas precisarem de permissões de ferramenta *diferentes*, janelas de contexto *diferentes* ou execução *paralela* e independente. As topologias habituais são: **pipeline** (sequência fixa de etapas), **supervisor/trabalhador** (PAT-002 + PAT-005: um planejador delega em especialistas e agrega) e **rede ou pares** (os agentes passam o controle livremente). O custo de coordenação sobe abruptamente com a liberdade da topologia; as redes de pares são poderosas mas as mais difíceis de tornar confiáveis, de governar e de depurar.
+
+O **encaminhamento** é como o controle se move pelo sistema. Pode ser *dirigido pelo modelo* (o supervisor escolhe o próximo trabalhador por chamada a ferramenta), *dirigido por regras* (transições deterministas numa máquina de estados) ou *híbrido*. O encaminhamento determinista é preferível sempre que o caminho seja conhecido, porque é governável e testável; o dirigido pelo modelo se reserva para as ramificações genuinamente abertas. Codificar o fluxo como uma **máquina de estados** explícita — estados, transições permitidas e guardas — é a técnica de confiabilidade com maior alavancagem na orquestração: limita o espaço de comportamentos, torna o sistema inspecionável e permite à governança (HRN-008) ligar controles às transições.
+
+A **durabilidade** é a propriedade que separa uma demonstração de um sistema de produção. Os fluxos agênticos são de longa duração (de segundos a horas), chamam ferramentas externas instáveis e podem cair a meio do voo. Um motor de execução duradoura persiste o progresso após cada passo, de modo que perante uma falha o fluxo *retoma* a partir do último passo concluído em vez de reiniciar. Isso exige cuidado com a semântica de efeitos: as chamadas a ferramentas com efeitos secundários têm de ser **idempotentes** ou estar protegidas com chaves de desduplicação, para que uma retoma não cobre duas vezes um cartão nem reenvie um email. Os casos difíceis são os *efeitos externos não idempotentes*; o harness trata-os com o padrão saga: registar a intenção, executar, confirmar e oferecer ações compensatórias perante uma falha parcial.
+
+A **gestão de estado e contexto** entre agentes é onde os sistemas multiagente perdem confiabilidade. Cada passagem (PAT-005) tem de transferir *exatamente* o contexto de que o trabalhador precisa: a menos e falha; a mais e sai caro e propenso à distração. O estado compartilhado pertence a um armazém duradouro com propriedade clara, não a uma janela de contexto compartilhada flutuando livremente. A agregação das saídas dos trabalhadores precisa de um redutor explícito com resolução de conflitos, porque os trabalhadores paralelos produzirão resultados sobrepostos ou contraditórios.
+
+Por fim, a orquestração é dona da **concorrência e do isolamento de falhas**. Os ramos paralelos (expostos pelo plano em DAG de HRN-009) melhoram a latência, mas exigem contrapressão, coordenação de limites de taxa entre ferramentas compartilhadas e compartimentação para que um trabalhador que falha não esgote o orçamento nem bloqueie os irmãos. Os tempos limite, os disjuntores e os orçamentos por trabalhador são assuntos da orquestração, não da aplicação.
+
+## Evidência de produção
+
+> **Cenário ilustrativo e representativo.** Nível de evidência: teórico · Confiança: média · Fonte: observação de indústria, experiência pessoal. Os números seguintes são intervalos representativos, não uma medição de uma implantação verificada concreta.
+
+- **Contexto:** um agente de investigação e síntese que responde a perguntas empresariais complexas.
+- **Cenário:** um supervisor decompõe uma pergunta, despacha trabalhadores de recuperação e análise em paralelo, e agrega uma resposta com citações.
+- **Tecnologia:** motor de fluxo duradouro, topologia supervisor/trabalhador, encaminhador determinista para as etapas conhecidas, chaves de desduplicação nas ferramentas com efeitos.
+- **Carga:** execuções concorrentes de vários trabalhadores; cada execução dura minutos e faz várias chamadas a ferramentas externas.
+- **Resultados (representativos):** o leque paralelo costuma cortar a latência de relógio num múltiplo significativo diante da execução sequencial, enquanto os pontos de controle duradouros reduzem a taxa de execuções com falha ao eliminar os reinícios completos provocados por quedas. O custo é uma maior despesa em tokens (mais agentes, mais contexto) e uma complexidade de coordenação acrescentada.
+
+### Lições aprendidas
+
+A maioria das equipes recorre ao multiagente demasiado cedo. A progressão confiável é: fazer funcionar um agente único, codificá-lo como máquina de estados, acrescentar durabilidade e *só então* dividir em trabalhadores, apenas onde o paralelismo ou o isolamento de permissões compense o custo de coordenação.
+
+## Modos de falha observados
+
+| Modo de falha | Gatilho | Mitigação |
+|---|---|---|
+| Efeitos secundários duplicados | A retoma reexecuta um passo não idempotente | Chaves de idempotência / compensação saga |
+| Progresso perdido numa queda | Sem pontos de controle | Motor de execução duradoura |
+| Perda de contexto na passagem | O trabalhador recebe menos estado do que precisa | Contratos de passagem explícitos e tipados |
+| Impasse de coordenação | Os trabalhadores esperam uns pelos outros | Encaminhamento acíclico, tempos limite, arbitragem do supervisor |
+| Explosão de custo | Delegação recursiva ou entre pares sem limite | Orçamento de agentes por execução + limite de profundidade de delegação |
+| Agregação contraditória | Os trabalhadores paralelos discordam | Redutor explícito com resolução de conflitos |
+| Gargalo de ferramenta compartilhada | Os trabalhadores martelam uma API com limite de taxa | Limite de taxa centralizado + contrapressão |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Taxa de conclusão de tarefa | Alta | De ponta a ponta, verificada |
+| Latência p50/p95/p99 | Minimizada | O paralelismo melhora p50; as caudas são dominadas pelos trabalhadores lentos |
+| Taxa de sucesso de retoma | → 100 % | Fluxos que recuperam após uma queda |
+| Taxa de efeitos duplicados | → 0 | Correção da idempotência |
+| Custo por tarefa | Limitado | Limites de agentes, profundidade e tokens |
+| Débito | Escala com a concorrência | Limitado pelos limites de taxa das ferramentas compartilhadas |
+
+## Métricas de custo
+
+- O **custo em tokens** cresce com o número de agentes e o contexto por agente; o multiagente é materialmente mais caro do que o agente único para a mesma tarefa.
+- **Sobrecusto de orquestração:** inferência de planejamento do supervisor mais a de agregação por execução.
+- **Sobrecusto de durabilidade:** as escritas de ponto de controle (baratas) diante da grande economia de não reiniciar as execuções com falha.
+
+## Características de escalabilidade
+
+O débito do agente único escala horizontalmente e sem estado. O supervisor/trabalhador escala as subtarefas em paralelo até aos limites de taxa das ferramentas compartilhadas, que se tornam o teto real. Os motores de fluxo duradouro escalam com o número de fluxos em andamento; o armazenamento de pontos de controle e o despachante são os componentes a dimensionar. As topologias de rede ou pares são as que pior escalam: o sobrecusto de coordenação e a superfície de falha crescem de forma superlinear com o número de agentes, e por isso as topologias de supervisor limitadas são o padrão na empresa.
+
+## Conteúdo relacionado
+
+- HRN-003 — O lugar da orquestração na taxonomia do harness.
+- HRN-009 — O plano que a orquestração executa.
+- PAT-002 — Padrão de agente supervisor.
+- PAT-005 — Padrão de delegação multiagente.
+
+## Referências
+
+- Temporal e outros motores de fluxo de execução duradoura (padrão saga, durabilidade de fluxos).
+- Anthropic, “Building Effective Agents” (agente único primeiro, orientação de topologias).
+- LangGraph e a orquestração por máquina de estados para agentes.
+
+## Perguntas frequentes
+
+**P: Agente único ou multiagente?**
+R: Por padrão, agente único. Acrescente agentes apenas por paralelismo ou por isolamento de permissões ou contexto que compense o custo de coordenação.
+
+**P: Por que uma máquina de estados em vez de ciclos de agente livres?**
+R: As máquinas de estados limitam o comportamento, são testáveis e permitem à governança ligar controles às transições. Os ciclos livres são poderosos, mas difíceis de tornar confiáveis ou auditáveis.
+
+**P: Como evito cobrar duas vezes a um cliente numa repetição?**
+R: Torne idempotentes as chamadas a ferramentas com efeitos (chaves de desduplicação) ou envolva-as numa saga com ações compensatórias, e execute-as sobre um motor duradouro que retome em vez de reiniciar.

package/content/harness/HRN-011-security-for-agentic-systems.es.md

@@ -0,0 +1,107 @@
+---
+title: "Seguridad para sistemas agénticos"
+summary: "Tratar al modelo como componente no confiable y manipulable: inyección de prompts, exfiltración por herramientas, límites de autoridad y defensa en profundidad del harness."
+---
+
+# Seguridad para sistemas agénticos
+
+## Resumen ejecutivo
+
+Los sistemas agénticos amplían la superficie de ataque de una forma que las aplicaciones tradicionales no conocen: el agente lee datos no confiables, toma decisiones con consecuencias y posee privilegios para actuar, de modo que una sola entrada comprometida puede convertirse en una acción comprometida. La seguridad para sistemas agénticos es la capa del harness que asume que el modelo puede ser manipulado —y lo será— y construye el andamiaje circundante para que esa manipulación no pueda causar daño. El principio rector es **mínimo privilegio con radio de impacto acotado**: tratar al modelo como componente no confiable, situar los controles de seguridad *fuera* de su superficie persuadible y garantizar que incluso un agente completamente secuestrado solo pueda hacer un daño acotado y auditable.
+
+## Conceptos clave
+
+- **Inyección de prompt:** contenido no confiable que secuestra las instrucciones u objetivos del agente.
+- **Inyección indirecta de prompt:** inyección entregada a través de datos que el agente recupera (documentos, páginas web, salidas de herramientas).
+- **Aislamiento de herramientas (sandboxing):** aislar la ejecución de una herramienta para que no pueda exceder su autoridad prevista.
+- **Mínimo privilegio:** conceder a cada agente los permisos mínimos que su tarea necesita.
+- **Identidad del agente:** un principal distinto y atribuible para cada agente, con alcance limitado y revocable.
+- **Exfiltración de datos:** salida no autorizada de datos sensibles a través de salidas de herramientas o contenido renderizado.
+- **Trifecta letal:** la combinación peligrosa de acceso a datos privados, exposición a contenido no confiable y capacidad de comunicarse al exterior.
+
+## Definición
+
+> La **seguridad para sistemas agénticos** es la disciplina del harness que trata al modelo como un componente no confiable y manipulable, y construye controles de identidad, permisos, aislamiento y salida de datos para que el daño máximo que pueda causar cualquier agente comprometido esté acotado, sea atribuible y quede auditado.
+
+## Explicación detallada
+
+La amenaza fundacional es la **inyección de prompt**, y el error fundacional es intentar resolverla dentro del modelo. Ningún grado de endurecimiento del prompt de sistema detiene de forma fiable una instrucción suficientemente astuta incrustada en contenido recuperado, porque el modelo no tiene una frontera robusta y de principio entre «datos» e «instrucción». La inyección indirecta es la variante peligrosa: un agente que resume una página web o lee un ticket puede ser tomado por el texto que el atacante plantó allí. La respuesta del harness es **arquitectónica, no de prompting**: asumir que la inyección tendrá éxito a veces y garantizar que un agente secuestrado siga sin poder hacer nada que sus *permisos* prohíban. Los guardarraíles de entrada (detección de inyección y jailbreak) reducen la *frecuencia* de las inyecciones exitosas; los controles de permisos y de salida acotan la *consecuencia*. Hacen falta ambos; ninguno basta por sí solo.
+
+El **mínimo privilegio y la identidad del agente** son la columna vertebral de la seguridad agéntica. Cada agente debería ejecutarse como un principal distinto y atribuible, con credenciales limitadas exactamente a los recursos que su tarea requiere: tokens de vida corta, ámbitos OAuth estrechos, solo lectura donde no haga falta escribir y aislamiento de datos por inquilino aplicado *por debajo* del agente (en la capa de datos), nunca pidiéndole con buenas maneras al modelo que no se salga de su carril. Cuando un agente actúa en nombre de un usuario, debe llevar la autorización de ese usuario y no una cuenta de servicio con poderes absolutos, para que el agente no pueda exceder nunca lo que el usuario podría hacer directamente. Las credenciales debe inyectarlas el harness en el momento de la llamada, jamás colocarse en la ventana de contexto, donde una inyección podría leerlas y exfiltrarlas.
+
+El **aislamiento de herramientas** confina la ejecución. Las herramientas que ejecutan código lo hacen en cajas de arena efímeras, con red restringida y recursos topados. Los catálogos de herramientas están en **lista de permitidos** por agente, de modo que un agente secuestrado no puede alcanzar una herramienta que nunca se le concedió. Las herramientas de alta consecuencia quedan detrás de una aprobación humana (PAT-007 / PAT-001), para que incluso una llamada autorizada pero manipulada requiera que una persona la confirme. El principio es la *defensa en profundidad*: la autorización decide *si* la llamada está permitida, la caja de arena acota *qué puede tocar* y la puerta de aprobación añade un punto de control humano para las acciones irreversibles.
+
+La **exfiltración de datos** es el riesgo agéntico más infravalorado. La «trifecta letal» —un agente con (1) acceso a datos privados, (2) exposición a contenido no confiable y (3) capacidad de comunicarse al exterior— es explotable: instrucciones inyectadas le dicen al agente que incruste secretos en una petición saliente, en la URL de una imagen renderizada o en el argumento de una herramienta. El harness rompe la trifecta eliminando al menos una de sus patas en los contextos sensibles: restringir los destinos de salida a una lista de permitidos, ejecutar comprobaciones de prevención de fuga de datos sobre cada carga saliente, eliminar o fijar el renderizado de contenido externo y prohibir que el agente construya URL salientes arbitrarias. Si un agente debe tocar datos privados, su capacidad de comunicarse al exterior tiene que estar fuertemente restringida, y viceversa.
+
+Todo ello se apoya en la **observabilidad y la auditabilidad** (HRN-006): cada acción, la identidad que la realizó, la decisión de permiso y la comprobación de salida deben quedar registradas de forma inmutable. Una seguridad que no puedes demostrar es una seguridad que no tienes. Estos controles implementan las obligaciones definidas en el marco de gobernanza (GOV-001) y encajan en la taxonomía general del harness (HRN-003).
+
+## Evidencia de producción
+
+> **Escenario ilustrativo y representativo.** Nivel de evidencia: teórico · Confianza: media · Fuente: observación de industria, experiencia personal. Las descripciones siguientes son patrones representativos de ataque y mitigación, no mediciones de un despliegue verificado concreto.
+
+- **Contexto:** un agente de soporte al cliente con acceso a una base de conocimiento y capacidad de enviar correos a clientes.
+- **Escenario:** un atacante planta texto de inyección en un ticket de soporte intentando que el agente envíe por correo los datos de la cuenta de otro cliente a una dirección externa.
+- **Tecnología:** credenciales con alcance por agente, lista de permitidos de salida, prevención de fuga de datos sobre el correo saliente, detección de inyección en el contenido recuperado, registro de auditoría.
+- **Carga:** alto volumen de tickets, con una fracción pequeña pero no nula que porta intentos de inyección.
+- **Resultados (representativos):** en despliegues de esta forma, los controles arquitectónicos (lista de permitidos de salida + prevención de fuga + mínimo privilegio) bloquean la *consecuencia* de la inyección incluso cuando la detección se pierde el *intento*, llevando la exfiltración exitosa hacia cero, mientras que la detección de inyección por sí sola deja riesgo residual.
+
+### Lecciones aprendidas
+
+Las estrategias basadas solo en detección acaban fallando; las defensas fiables son las arquitectónicas, las que acotan la consecuencia. Romper la trifecta letal —sobre todo restringiendo la salida— hace más por la seguridad que cualquier clasificador aislado.
+
+## Modos de fallo observados
+
+| Modo de fallo | Disparador | Mitigación |
+|---|---|---|
+| Inyección directa de prompt | Instrucción maliciosa del usuario | Guardarraíles de entrada + acotado de permisos |
+| Inyección indirecta | Texto malicioso en los datos recuperados | Tratar todo contenido recuperado como no confiable; controles de salida |
+| Exfiltración de datos | Trifecta letal explotada | Romper la trifecta: lista de permitidos de salida + prevención de fuga |
+| Escalada de privilegios | Credenciales de servicio demasiado amplias | Credenciales con alcance por agente y vida corta; autorización delegada por el usuario |
+| Fuga de credenciales | Secretos en la ventana de contexto | Inyectar las credenciales en el momento de la llamada, nunca en el contexto |
+| Fuga de la caja de arena | Código o red sin restringir en las herramientas | Cajas de arena efímeras, aisladas de red y con recursos topados |
+| Delegado confuso | El agente se usa como proxy para acciones prohibidas | Portar la identidad del llamante; autorizar en el efector |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Tasa de exfiltración exitosa | → 0 | La métrica que más importa |
+| Exhaustividad de la detección de inyección | Alta | Reduce la frecuencia de intentos, no es la única defensa |
+| Estrechez del alcance de permisos | Concesiones mínimas | Auditar permisos sin usar o demasiado amplios |
+| Cobertura de la lista de permitidos de salida | 100 % | Sin destinos salientes arbitrarios |
+| Tiempo medio hasta la revocación | Bajo | Revocación de la identidad de un agente comprometido |
+| Completitud de auditoría | 100 % | Toda acción atribuible |
+
+## Métricas de coste
+
+- **Coste de inferencia de los guardarraíles:** los clasificadores de inyección y de fuga de datos añaden inferencia auxiliar por petición; hay que presupuestarla dentro del coste por tarea.
+- **Sobrecoste de las cajas de arena:** el arranque de una caja efímera añade latencia a las herramientas de código; se amortiza con pools calientes.
+- **Coste de ingeniería:** la identidad con alcance y la lista de permitidos de salida son trabajo de IAM por adelantado que se rentabiliza en todos los agentes.
+
+## Características de escalado
+
+Los controles de permisos e identidad escalan con la infraestructura de IAM y de secretos, sin estado por llamada. Los clasificadores de guardarraíl escalan con la capacidad de inferencia y son el coste de rendimiento; cortocircuítalos antes con comprobaciones deterministas baratas (listas de permitidos, expresiones regulares, esquema). Las cajas de arena escalan con un pool gestionado; los pools calientes cambian coste ocioso por latencia. Los controles de salida escalan de forma trivial y nunca deberían ser el cuello de botella: son el control de mayor valor por coste de toda la pila.
+
+## Contenido relacionado
+
+- HRN-003 — El lugar de la seguridad en la taxonomía del harness.
+- GOV-001 — Obligaciones de gobernanza que estos controles de seguridad implementan.
+- PAT-007 — Patrón de control de herramientas y permisos (aislamiento y uso de herramientas con puerta).
+
+## Referencias
+
+- OWASP Top 10 para aplicaciones LLM (LLM01 inyección de prompt, LLM06 divulgación de información sensible).
+- Simon Willison, «The lethal trifecta for AI agents».
+- NIST AI RMF y NIST SP 800-53 (mínimo privilegio, identidad).
+- MITRE ATLAS — panorama de amenazas adversarias para sistemas de IA.
+
+## Preguntas frecuentes
+
+**P: ¿Se puede prevenir por completo la inyección de prompt?**
+R: No. Diseña contando con ella: asume que a veces tendrá éxito y acota la consecuencia con mínimo privilegio, control de salida y aislamiento.
+
+**P: ¿Cuál es el control de mayor valor?**
+R: Romper la trifecta letal; de la forma más barata, restringiendo la salida a una lista de permitidos con prevención de fuga de datos, para que un agente secuestrado no pueda exfiltrar nada.
+
+**P: ¿Deberían los agentes compartir una cuenta de servicio?**
+R: No. Dale a cada agente una identidad distinta, con alcance limitado y vida corta, y haz que porte la autorización del usuario llamante para que no pueda exceder nunca los derechos de ese usuario.

package/content/harness/HRN-011-security-for-agentic-systems.md

@@ -0,0 +1,147 @@
+---
+id: HRN-011
+title: Security for Agentic Systems
+domain: Harness
+category: Security
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: Security for agentic systems is the harness layer that defends against prompt injection, sandboxes tools and permissions, prevents data exfiltration, and enforces agent identity and least privilege across every action.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-003
+  - GOV-001
+  - PAT-007
+tags:
+  - security
+  - prompt-injection
+  - least-privilege
+  - sandboxing
+  - data-exfiltration
+  - agent-identity
+---
+
+# Security for Agentic Systems
+
+## Executive Summary
+
+Agentic systems expand the attack surface in a way traditional applications do not: the agent reads untrusted data, makes consequential decisions, and holds privileges to act — so a single compromised input can become a compromised action. Security for agentic systems is the harness layer that assumes the model can and will be manipulated, and engineers the surrounding scaffolding so that manipulation cannot cause harm. The governing principle is **least privilege with a constrained blast radius**: treat the model as an untrusted component, place security controls *outside* its persuadable surface, and ensure that even a fully hijacked agent can do only bounded, auditable damage.
+
+## Key Concepts
+
+- **Prompt injection:** untrusted content that hijacks the agent's instructions or goals.
+- **Indirect prompt injection:** injection delivered via data the agent retrieves (documents, web pages, tool outputs).
+- **Tool sandboxing:** isolating tool execution so it cannot exceed its intended authority.
+- **Least privilege:** granting each agent the minimum permissions needed for its task.
+- **Agent identity:** a distinct, attributable principal for each agent, scoped and revocable.
+- **Data exfiltration:** unauthorized egress of sensitive data through tool outputs or rendered content.
+- **Lethal trifecta:** the dangerous combination of access to private data, exposure to untrusted content, and the ability to externally communicate.
+
+## Definition
+
+> **Security for agentic systems** is the harness discipline of treating the model as an untrusted, manipulable component and engineering identity, permission, isolation, and egress controls so that the maximum harm any compromised agent can cause is bounded, attributable, and auditable.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+    UNT[Untrusted Inputs\nuser, web, docs, tool output] --> IG[Input Guardrails\ninjection detection]
+    IG --> AGENT[Agent Reasoning Loop\n(treated as untrusted)]
+    AGENT -->|proposed tool call| AUTH[AuthZ + Least Privilege\nagent identity, scoped creds]
+    AUTH --> SBX[Tool Sandbox\nisolation, allowlist]
+    SBX --> EFF[Effector / External System]
+    EFF --> OG[Output / Egress Guardrails\nDLP, exfil checks]
+    OG --> SINK[Allowed Destination]
+    AUTH -.deny/quarantine.-> BLK[Block + Alert]
+    AGENT --> AUD[(Immutable Audit Log)]
+    AUTH --> AUD
+    OG --> AUD
+```
+
+## Detailed Explanation
+
+The foundational threat is **prompt injection**, and the foundational mistake is trying to solve it inside the model. No amount of system-prompt hardening reliably stops a sufficiently clever instruction embedded in retrieved content, because the model has no robust, principled boundary between "data" and "instruction." Indirect injection is the dangerous variant: an agent that summarizes a web page or reads a ticket can be commandeered by text the attacker planted there. The harness response is **architectural, not prompt-based**: assume injection will sometimes succeed, and ensure that a hijacked agent still cannot do anything its *permissions* forbid. Input guardrails (injection/jailbreak detection) reduce the *frequency* of successful injection; permission and egress controls bound the *consequence*. Both are required; neither alone suffices.
+
+**Least privilege and agent identity** are the spine of agentic security. Each agent should run as a distinct, attributable principal with credentials scoped to exactly the resources its task requires — short-lived tokens, narrow OAuth scopes, read-only where writes aren't needed, and per-tenant data isolation enforced *below* the agent (in the data layer), never by asking the model nicely to stay in its lane. When an agent acts on behalf of a user, it should carry that user's authorization, not a god-mode service account, so the agent can never exceed what the user could do directly. Credentials must be injected by the harness at call time, never placed in the context window where injection could read and exfiltrate them.
+
+**Tool sandboxing** isolates execution. Code-running tools execute in ephemeral, network-restricted, resource-capped sandboxes. Tool catalogs are **allowlisted** per agent, so a hijacked agent cannot reach a tool it was never granted. High-consequence tools sit behind human approval (PAT-007 / PAT-001) so that even an authorized-but-manipulated call requires a human to commit it. The principle is *defense in depth*: AuthZ decides *whether* a call is permitted, the sandbox bounds *what the call can touch*, and the approval gate adds a human checkpoint for irreversible actions.
+
+**Data exfiltration** is the most under-appreciated agentic risk. The "lethal trifecta" — an agent with (1) access to private data, (2) exposure to untrusted content, and (3) the ability to communicate externally — is exploitable: injected instructions tell the agent to embed secrets into an outbound request, a rendered image URL, or a tool argument. The harness breaks the trifecta by removing at least one leg for sensitive contexts: restrict egress destinations to an allowlist, run data-loss-prevention checks on every outbound payload, strip or pin external content rendering, and forbid the agent from constructing arbitrary outbound URLs. If an agent must touch private data, its ability to communicate externally must be tightly constrained, and vice versa.
+
+Underpinning all of it is **observability and auditability** (HRN-006): every action, the identity that performed it, the permission decision, and the egress check must be logged immutably. Security you cannot prove is security you do not have. These controls implement the obligations defined in the governance framework (GOV-001) and slot into the broader harness taxonomy (HRN-003).
+
+## Production Evidence
+
+> **Illustrative / representative scenario.** Evidence level: theoretical · Confidence: medium · Source: industry_observation, personal_experience. The descriptions below are representative attack/mitigation patterns, not measurements from one verified deployment.
+
+- **Context:** A customer-support agent with access to a knowledge base and the ability to email customers.
+- **Scenario:** An attacker plants injection text in a support ticket attempting to make the agent email another customer's account data to an external address.
+- **Technology:** Per-agent scoped credentials, egress allowlist, DLP on outbound mail, injection detection on retrieved content, audit log.
+- **Load:** High ticket volume; a small but nonzero fraction carry injection attempts.
+- **Results (representative):** In deployments of this shape, the architectural controls (egress allowlist + DLP + least privilege) block the *consequence* of injection even when detection misses the *attempt*, reducing successful exfiltration toward zero while injection-detection alone leaves residual risk.
+
+### Lessons Learned
+
+Detection-only strategies fail eventually; the reliable defenses are the architectural ones that bound consequence. Breaking the lethal trifecta — especially constraining egress — does more for safety than any single classifier.
+
+## Observed Failure Modes
+
+| Failure Mode | Trigger | Mitigation |
+|---|---|---|
+| Direct prompt injection | Malicious user instruction | Input guardrails + permission bounding |
+| Indirect injection | Malicious text in retrieved data | Treat all retrieved content as untrusted; egress controls |
+| Data exfiltration | Lethal trifecta exploited | Break the trifecta: egress allowlist + DLP |
+| Privilege escalation | Over-broad service credentials | Per-agent scoped, short-lived creds; user-delegated authZ |
+| Credential leakage | Secrets in context window | Inject creds at call time, never in context |
+| Sandbox escape | Unrestricted code/network in tools | Network-isolated, resource-capped ephemeral sandboxes |
+| Confused deputy | Agent misused as a proxy for forbidden actions | Carry caller identity; authZ at the effector |
+
+## KPIs
+
+| Metric | Target | Notes |
+|---|---|---|
+| Successful exfiltration rate | → 0 | The metric that matters most |
+| Injection detection recall | High | Reduces attempt frequency, not the sole defense |
+| Permission scope tightness | Minimal grants | Audit for unused/over-broad permissions |
+| Egress allowlist coverage | 100% | No arbitrary outbound destinations |
+| Mean time to revoke | Low | Compromised agent identity revocation |
+| Audit completeness | 100% | Every action attributable |
+
+## Cost Metrics
+
+- **Guardrail inference cost:** injection/DLP classifiers add auxiliary inference per request — budget in cost-per-task.
+- **Sandbox overhead:** ephemeral sandbox spin-up adds latency to code tools; amortize with warm pools.
+- **Engineering cost:** scoped identity and egress allowlisting are upfront IAM work that pays back across all agents.
+
+## Scaling Characteristics
+
+Permission and identity controls scale with the IAM/secrets infrastructure, statelessly per call. Guardrail classifiers scale with inference capacity and are the throughput cost; short-circuit with cheap deterministic checks (allowlists, regex, schema) first. Sandboxes scale with a managed pool; warm pools trade idle cost for latency. Egress controls scale trivially and should never be the bottleneck — they are the cheapest high-value control in the stack.
+
+## Related Content
+
+- HRN-003 — Security's place in the harness taxonomy.
+- GOV-001 — Governance obligations that security controls implement.
+- PAT-007 — Tool/permission control pattern (sandboxing and gated tool use).
+
+## References
+
+- OWASP Top 10 for LLM Applications (LLM01 Prompt Injection, LLM06 Sensitive Information Disclosure).
+- Simon Willison, "The lethal trifecta for AI agents."
+- NIST AI RMF and NIST SP 800-53 (least privilege, identity).
+- MITRE ATLAS — adversarial threat landscape for AI systems.
+
+## FAQs
+
+**Q: Can prompt injection be fully prevented?**
+A: No. Engineer for it: assume injection succeeds sometimes and bound the consequence with least privilege, egress control, and sandboxing.
+
+**Q: What is the single highest-value control?**
+A: Breaking the lethal trifecta — most cheaply by constraining egress to an allowlist with DLP — so a hijacked agent cannot exfiltrate data.
+
+**Q: Should agents share a service account?**
+A: No. Give each agent a distinct, scoped, short-lived identity, and have it carry the calling user's authorization so it can never exceed the user's own rights.