{ "generated": "2026-09-11T20:55:57.809Z", "count": 23, "license": "Content © Santiago Santa María Morales, licensed CC BY 4.0. Attribution required: credit the author and link the canonical URL.", "license_spdx": "CC-BY-4.0", "license_url": "https://creativecommons.org/licenses/by/4.0/", "entries": [ { "slug": "agent-memory", "category": "harness", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/agent-memory", "api": "https://santismm.com/api/knowledge/agent-memory", "canonical_url": "https://santismm.com/en/knowledge/agent-memory", "api_url": "https://santismm.com/api/knowledge/agent-memory", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "Packer et al. — MemGPT: Towards LLMs as Operating Systems (2023)", "url": "https://arxiv.org/abs/2310.08560" }, { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "harness-engineering", "context-engineering", "ai-agent", "enterprise-rag" ], "locales": { "en": { "title": "What are Agent Memory Systems?", "summary": "Agent memory is how an AI agent retains and recalls information beyond a single context window — across steps, sessions and tasks. It typically separates short-term working memory (the current context) from long-term memory (durable stores the agent reads from and writes to). Memory is what lets an agent carry state through a long task, remember a user over time, and avoid repeating work. It is a core layer of harness engineering.", "definition": "Agent memory is the set of mechanisms an AI agent uses to store, organize and retrieve information beyond its immediate context window, spanning short-term working memory and long-term persistent memory.", "takeaways": [ "Memory extends an agent beyond a single finite context window.", "Short-term (working) vs long-term (persistent) memory serve different roles.", "Long-term memory is often retrieved on demand, like RAG over the agent's own history.", "Good memory prevents repeated work and lost state on long tasks.", "What to write, keep and forget is a design decision, not automatic." ], "context": [ "A model's context window is finite, so anything an agent must remember beyond it needs an external store. Without memory, an agent forgets earlier steps, repeats actions and cannot personalize across sessions.", "Memory turns a stateless model into a system with continuity. The hard part is curation: deciding what is worth writing down, how to organize it, and how to retrieve only what is relevant now — closely tied to context engineering." ], "architecture": [ "Two layers: working memory (the current context window, holding the active task) and long-term memory (external stores — vector, key-value, document or graph — written during a task and retrieved later). Some designs add episodic (events), semantic (facts) and procedural (skills) memory.", "The agent reads relevant memories into context at each step and writes new ones as it learns. Retrieval, summarization and forgetting policies keep memory useful rather than overwhelming." ], "components": [ "Working memory", "Long-term store (vector/KV/graph)", "Write policy", "Retrieval policy", "Summarization / consolidation", "Forgetting / expiry" ], "pros": [ "Continuity across steps, sessions and tasks.", "Personalization that persists over time.", "Avoids repeated work and lost context.", "Enables long-horizon, stateful agents." ], "risks": [ "Stale or wrong memories poison future answers.", "Privacy and governance obligations on stored data.", "Retrieval of irrelevant memories adds noise.", "Unbounded growth without consolidation or expiry." ], "tools": [ "Vector databases", "Key-value / document stores", "MemGPT-style memory managers", "Agent frameworks (LangGraph, Agents SDKs)" ], "examples": [ "An assistant remembering a user's preferences across sessions.", "A long-running agent summarizing progress so it never repeats a step.", "A support agent recalling a customer's prior tickets when relevant." ], "faqs": [ { "q": "How is agent memory different from RAG?", "a": "RAG retrieves from an external knowledge base; agent memory retrieves from the agent's own accumulated state. The retrieval machinery is similar, but the source and write path differ." }, { "q": "What is the difference between short- and long-term memory?", "a": "Short-term (working) memory is the live context window for the current task; long-term memory is a persistent store the agent reads from and writes to across tasks and sessions." }, { "q": "Why not keep everything in the context window?", "a": "Windows are finite and quality drops as they fill. Externalizing state to memory and retrieving only what is relevant keeps the agent focused and affordable." }, { "q": "What are the governance concerns?", "a": "Stored memory may contain personal or sensitive data, so it needs access control, retention limits and the ability to correct or delete entries." } ] }, "es": { "title": "¿Qué son los Sistemas de Memoria de Agentes?", "summary": "La memoria de un agente es cómo un agente de IA retiene y recuerda información más allá de una sola ventana de contexto: entre pasos, sesiones y tareas. Suele separar la memoria de trabajo a corto plazo (el contexto actual) de la memoria a largo plazo (almacenes duraderos que el agente lee y escribe). La memoria es lo que permite a un agente arrastrar estado en una tarea larga, recordar a un usuario en el tiempo y evitar repetir trabajo. Es una capa central de la ingeniería de harness.", "definition": "La memoria de agente es el conjunto de mecanismos que un agente de IA usa para almacenar, organizar y recuperar información más allá de su ventana de contexto inmediata, abarcando memoria de trabajo a corto plazo y memoria persistente a largo plazo.", "takeaways": [ "La memoria extiende a un agente más allá de una sola ventana de contexto finita.", "La memoria a corto plazo (de trabajo) y a largo plazo (persistente) cumplen roles distintos.", "La memoria a largo plazo suele recuperarse bajo demanda, como RAG sobre el historial del agente.", "Una buena memoria evita repetir trabajo y perder estado en tareas largas.", "Qué escribir, conservar y olvidar es una decisión de diseño, no automática." ], "context": [ "La ventana de contexto de un modelo es finita, así que todo lo que un agente deba recordar más allá de ella necesita un almacén externo. Sin memoria, un agente olvida pasos previos, repite acciones y no puede personalizar entre sesiones.", "La memoria convierte un modelo sin estado en un sistema con continuidad. Lo difícil es la curación: decidir qué merece anotarse, cómo organizarlo y cómo recuperar solo lo relevante ahora, muy ligado a la ingeniería de contexto." ], "architecture": [ "Dos capas: memoria de trabajo (la ventana de contexto actual, con la tarea activa) y memoria a largo plazo (almacenes externos —vectorial, clave-valor, documental o de grafo— escritos durante una tarea y recuperados después). Algunos diseños añaden memoria episódica (eventos), semántica (hechos) y procedimental (habilidades).", "El agente lee memorias relevantes al contexto en cada paso y escribe nuevas a medida que aprende. Las políticas de recuperación, resumen y olvido mantienen la memoria útil en vez de abrumadora." ], "components": [ "Memoria de trabajo", "Almacén a largo plazo (vectorial/KV/grafo)", "Política de escritura", "Política de recuperación", "Resumen / consolidación", "Olvido / expiración" ], "pros": [ "Continuidad entre pasos, sesiones y tareas.", "Personalización que persiste en el tiempo.", "Evita repetir trabajo y perder contexto.", "Habilita agentes con estado y de horizonte largo." ], "risks": [ "Memorias obsoletas o erróneas contaminan respuestas futuras.", "Obligaciones de privacidad y gobernanza sobre los datos guardados.", "Recuperar memorias irrelevantes añade ruido.", "Crecimiento sin límite sin consolidación ni expiración." ], "tools": [ "Bases de datos vectoriales", "Almacenes clave-valor / documentales", "Gestores de memoria estilo MemGPT", "Frameworks de agentes (LangGraph, SDKs de agentes)" ], "examples": [ "Un asistente que recuerda las preferencias de un usuario entre sesiones.", "Un agente de larga duración que resume su progreso para no repetir un paso.", "Un agente de soporte que recuerda los tickets previos de un cliente cuando es relevante." ], "faqs": [ { "q": "¿En qué se diferencia la memoria de agente de RAG?", "a": "RAG recupera de una base de conocimiento externa; la memoria de agente recupera del propio estado acumulado del agente. La maquinaria de recuperación es similar, pero la fuente y la ruta de escritura difieren." }, { "q": "¿Cuál es la diferencia entre memoria a corto y largo plazo?", "a": "La memoria a corto plazo (de trabajo) es la ventana de contexto viva para la tarea actual; la de largo plazo es un almacén persistente que el agente lee y escribe entre tareas y sesiones." }, { "q": "¿Por qué no guardar todo en la ventana de contexto?", "a": "Las ventanas son finitas y la calidad cae al llenarse. Externalizar el estado a memoria y recuperar solo lo relevante mantiene al agente enfocado y asequible." }, { "q": "¿Cuáles son las preocupaciones de gobernanza?", "a": "La memoria guardada puede contener datos personales o sensibles, así que necesita control de acceso, límites de retención y capacidad de corregir o borrar entradas." } ] }, "pt": { "title": "O que são Sistemas de Memória de Agentes?", "summary": "A memória de um agente é como um agente de IA retém e recupera informação além de uma única janela de contexto: entre passos, sessões e tarefas. Costuma separar a memória de trabalho de curto prazo (o contexto atual) da memória de longo prazo (armazenamentos duráveis que o agente lê e escreve). A memória é o que permite a um agente carregar estado numa tarefa longa, lembrar de um usuário ao longo do tempo e evitar repetir trabalho. É uma camada central da engenharia de harness.", "definition": "A memória de agente é o conjunto de mecanismos que um agente de IA usa para armazenar, organizar e recuperar informação além de sua janela de contexto imediata, abrangendo memória de trabalho de curto prazo e memória persistente de longo prazo.", "takeaways": [ "A memória estende um agente além de uma única janela de contexto finita.", "Memória de curto prazo (de trabalho) e de longo prazo (persistente) cumprem papéis distintos.", "A memória de longo prazo costuma ser recuperada sob demanda, como RAG sobre o histórico do agente.", "Uma boa memória evita repetir trabalho e perder estado em tarefas longas.", "O que escrever, manter e esquecer é uma decisão de design, não automática." ], "context": [ "A janela de contexto de um modelo é finita, então tudo o que um agente precise lembrar além dela precisa de um armazenamento externo. Sem memória, um agente esquece passos anteriores, repete ações e não consegue personalizar entre sessões.", "A memória transforma um modelo sem estado num sistema com continuidade. O difícil é a curadoria: decidir o que vale anotar, como organizá-lo e como recuperar só o relevante agora, muito ligado à engenharia de contexto." ], "architecture": [ "Duas camadas: memória de trabalho (a janela de contexto atual, com a tarefa ativa) e memória de longo prazo (armazenamentos externos — vetorial, chave-valor, documental ou de grafo — escritos durante uma tarefa e recuperados depois). Alguns designs adicionam memória episódica (eventos), semântica (fatos) e procedural (habilidades).", "O agente lê memórias relevantes ao contexto a cada passo e escreve novas conforme aprende. Políticas de recuperação, resumo e esquecimento mantêm a memória útil em vez de avassaladora." ], "components": [ "Memória de trabalho", "Armazenamento de longo prazo (vetorial/KV/grafo)", "Política de escrita", "Política de recuperação", "Resumo / consolidação", "Esquecimento / expiração" ], "pros": [ "Continuidade entre passos, sessões e tarefas.", "Personalização que persiste ao longo do tempo.", "Evita repetir trabalho e perder contexto.", "Habilita agentes com estado e de horizonte longo." ], "risks": [ "Memórias obsoletas ou erradas contaminam respostas futuras.", "Obrigações de privacidade e governança sobre os dados guardados.", "Recuperar memórias irrelevantes adiciona ruído.", "Crescimento sem limite sem consolidação nem expiração." ], "tools": [ "Bancos de dados vetoriais", "Armazenamentos chave-valor / documentais", "Gerenciadores de memória estilo MemGPT", "Frameworks de agentes (LangGraph, SDKs de agentes)" ], "examples": [ "Um assistente que lembra as preferências de um usuário entre sessões.", "Um agente de longa duração que resume seu progresso para não repetir um passo.", "Um agente de suporte que lembra os chamados anteriores de um cliente quando relevante." ], "faqs": [ { "q": "Como a memória de agente difere do RAG?", "a": "O RAG recupera de uma base de conhecimento externa; a memória de agente recupera do próprio estado acumulado do agente. A maquinaria de recuperação é similar, mas a fonte e o caminho de escrita diferem." }, { "q": "Qual a diferença entre memória de curto e longo prazo?", "a": "A memória de curto prazo (de trabalho) é a janela de contexto viva para a tarefa atual; a de longo prazo é um armazenamento persistente que o agente lê e escreve entre tarefas e sessões." }, { "q": "Por que não guardar tudo na janela de contexto?", "a": "Janelas são finitas e a qualidade cai ao se encherem. Externalizar o estado para a memória e recuperar só o relevante mantém o agente focado e acessível." }, { "q": "Quais são as preocupações de governança?", "a": "A memória guardada pode conter dados pessoais ou sensíveis, então precisa de controle de acesso, limites de retenção e capacidade de corrigir ou apagar entradas." } ] }, "fr": { "title": "Qu'est-ce que les systèmes de mémoire d'agent ?", "summary": "La mémoire d'agent désigne la manière dont un agent d'IA conserve et rappelle des informations au-delà d'une seule fenêtre de contexte — à travers les étapes, les sessions et les tâches. Elle sépare généralement la mémoire de travail à court terme (le contexte actuel) de la mémoire à long terme (des espaces de stockage durables dans lesquels l'agent lit et écrit). La mémoire est ce qui permet à un agent de conserver un état tout au long d'une tâche complexe, de se souvenir d'un utilisateur au fil du temps et d'éviter de répéter le même travail. C'est une couche fondamentale de la discipline Harness Engineering.", "definition": "La mémoire d'agent est l'ensemble des mécanismes qu'un agent d'IA utilise pour stocker, organiser et récupérer des informations au-delà de sa fenêtre de contexte immédiate, englobant la mémoire de travail à court terme et la mémoire persistante à long terme.", "takeaways": [ "La mémoire permet à un agent de s'étendre au-delà d'une seule fenêtre de contexte finie.", "La mémoire à court terme (de travail) et la mémoire à long terme (persistante) jouent des rôles différents.", "La mémoire à long terme est souvent récupérée à la demande, à l'instar d'un RAG appliqué à l'historique propre de l'agent.", "Une bonne mémoire évite la répétition des tâches et la perte d'état lors de travaux de longue durée.", "Déterminer ce qu'il faut écrire, conserver et oublier relève d'une décision de conception, et non d'un processus automatique." ], "context": [ "La fenêtre de contexte d'un modèle étant finie, tout ce qu'un agent doit mémoriser au-delà de celle-ci nécessite un stockage externe. Sans mémoire, un agent oublie les étapes précédentes, répète des actions et ne peut pas personnaliser l'expérience d'une session à l'autre.", "La mémoire transforme un modèle sans état (stateless) en un système doté d'une continuité. La difficulté réside dans la curation : décider de ce qui mérite d'être consigné, comment l'organiser et comment ne récupérer que ce qui est pertinent à l'instant T — un aspect étroitement lié au context engineering." ], "architecture": [ "Deux couches : la mémoire de travail (la fenêtre de contexte actuelle, contenant la tâche active) et la mémoire à long terme (stockages externes — vectoriels, clé-valeur, documents ou graphes — alimentés pendant une tâche et récupérés ultérieurement). Certaines architectures y ajoutent une mémoire épisodique (événements), sémantique (faits) et procédurale (compétences).", "L'agent charge les souvenirs pertinents dans son contexte à chaque étape et en écrit de nouveaux au fil de son apprentissage. Des politiques de récupération, de résumé et d'oubli permettent de maintenir la mémoire utile plutôt qu'encombrante." ], "components": [ "Mémoire de travail", "Stockage à long terme (vectoriel/clé-valeur/graphe)", "Politique d'écriture", "Politique de récupération", "Résumé / consolidation", "Oubli / expiration" ], "pros": [ "Continuité à travers les étapes, les sessions et les tâches.", "Personnalisation persistante dans le temps.", "Évite la répétition des tâches et la perte de contexte.", "Permet de concevoir des agents avec état (stateful) sur de longs horizons." ], "risks": [ "Des souvenirs obsolètes ou erronés corrompent les réponses futures.", "Obligations de confidentialité et de gouvernance sur les données stockées.", "La récupération de souvenirs non pertinents ajoute du bruit.", "Croissance illimitée en l'absence de consolidation ou d'expiration." ], "tools": [ "Bases de données vectorielles", "Stockages clé-valeur / de documents", "Gestionnaires de mémoire de type MemGPT", "Frameworks d'agents (LangGraph, SDK d'agents)" ], "examples": [ "Un assistant se souvenant des préférences d'un utilisateur d'une session à l'autre.", "Un agent à exécution longue résumant sa progression pour ne jamais répéter une étape.", "Un agent de support rappelant les anciens tickets d'un client lorsque c'est pertinent." ], "faqs": [ { "q": "En quoi la mémoire d'agent diffère-t-elle du RAG ?", "a": "Le RAG effectue des recherches dans une base de connaissances externe ; la mémoire d'agent récupère des informations à partir de l'état accumulé par l'agent lui-même. Le mécanisme de récupération est similaire, mais la source et le chemin d'écriture diffèrent." }, { "q": "Quelle est la différence entre la mémoire à court terme et la mémoire à long terme ?", "a": "La mémoire à court terme (de travail) est la fenêtre de contexte active pour la tâche en cours ; la mémoire à long terme est un stockage persistant dans lequel l'agent lit et écrit à travers les tâches et les sessions." }, { "q": "Pourquoi ne pas tout conserver dans la fenêtre de contexte ?", "a": "Les fenêtres sont finies et la qualité diminue à mesure qu'elles se remplissent. Externaliser l'état vers la mémoire et ne récupérer que ce qui est pertinent permet de garder l'agent concentré et d'optimiser les coûts." }, { "q": "Quelles sont les préoccupations en matière de gouvernance ?", "a": "La mémoire stockée peut contenir des données personnelles ou sensibles, elle nécessite donc un contrôle d'accès, des limites de conservation et la possibilité de corriger ou de supprimer des entrées." } ] }, "de": { "title": "Was sind Agenten-Gedächtnissysteme?", "summary": "Das Agenten-Gedächtnis (Agent Memory) ermöglicht es einem KI-Agenten, Informationen über ein einzelnes Kontextfenster hinaus zu behalten und abzurufen – über Schritte, Sitzungen und Aufgaben hinweg. Es trennt typischerweise das Kurzzeit-Arbeitsgedächtnis (den aktuellen Kontext) vom Langzeitgedächtnis (dauerhafte Speicher, aus denen der Agent liest und in die er schreibt). Das Gedächtnis ermöglicht es einem Agenten, den Zustand über eine lange Aufgabe hinweg beizubehalten, sich im Laufe der Zeit an einen Benutzer zu erinnern und doppelte Arbeit zu vermeiden. Es ist eine Kernschicht des Harness Engineering.", "definition": "Das Agenten-Gedächtnis ist die Gesamtheit der Mechanismen, die ein KI-Agent nutzt, um Informationen über sein unmittelbares Kontextfenster hinaus zu speichern, zu organisieren und abzurufen, und umfasst sowohl das Kurzzeit-Arbeitsgedächtnis als auch das persistente Langzeitgedächtnis.", "takeaways": [ "Das Gedächtnis erweitert die Fähigkeiten eines Agenten über ein einzelnes, begrenztes Kontextfenster hinaus.", "Kurzzeit- (Arbeits-) und Langzeitgedächtnis (persistentes Gedächtnis) erfüllen unterschiedliche Aufgaben.", "Das Langzeitgedächtnis wird oft bei Bedarf abgerufen, ähnlich wie RAG über die eigene Historie des Agenten.", "Ein gutes Gedächtnis verhindert doppelte Arbeit und den Verlust des Zustands bei langwierigen Aufgaben.", "Was geschrieben, behalten und vergessen wird, ist eine Designentscheidung und geschieht nicht automatisch." ], "context": [ "Das Kontextfenster eines Modells ist begrenzt. Alles, was sich ein Agent darüber hinaus merken muss, erfordert daher einen externen Speicher. Ohne Gedächtnis vergisst ein Agent frühere Schritte, wiederholt Aktionen und kann sitzungsübergreifend keine Personalisierung vornehmen.", "Das Gedächtnis macht aus einem zustandslosen Modell ein System mit Kontinuität. Die Herausforderung liegt in der Kuration: der Entscheidung, was aufzeichnungswürdig ist, wie es organisiert wird und wie nur das abgerufen wird, was im Moment relevant ist – eng verknüpft mit dem Context Engineering." ], "architecture": [ "Zwei Schichten: das Arbeitsgedächtnis (das aktuelle Kontextfenster, das die aktive Aufgabe enthält) und das Langzeitgedächtnis (externe Speicher – Vektor-, Key-Value-, Dokumenten- oder Graphspeicher –, die während einer Aufgabe beschrieben und später abgerufen werden). Einige Architekturen ergänzen dies um ein episodisches (Ereignisse), semantisches (Fakten) und prozedurales (Fähigkeiten) Gedächtnis.", "Der Agent liest bei jedem Schritt relevante Erinnerungen in den Kontext ein und schreibt beim Lernen neue hinzu. Strategien für Abruf (Retrieval), Zusammenfassung und Vergessen sorgen dafür, dass das Gedächtnis nützlich bleibt, anstatt das System zu überlasten." ], "components": [ "Arbeitsgedächtnis", "Langzeitspeicher (Vektor/KV/Graph)", "Schreibstrategie", "Abrufstrategie", "Zusammenfassung / Konsolidierung", "Vergessen / Ablauf" ], "pros": [ "Kontinuität über Schritte, Sitzungen und Aufgaben hinweg.", "Personalisierung, die über die Zeit hinweg bestehen bleibt.", "Vermeidet doppelte Arbeit und den Verlust von Kontext.", "Ermöglicht zustandsbehaftete Agenten mit langem Zeithorizont." ], "risks": [ "Veraltete oder fehlerhafte Erinnerungen beeinträchtigen zukünftige Antworten.", "Datenschutz- und Governance-Verpflichtungen für gespeicherte Daten.", "Der Abruf irrelevanter Erinnerungen führt zu Rauschen.", "Unbegrenztes Wachstum ohne Konsolidierung oder Ablauf." ], "tools": [ "Vektordatenbanken", "Key-Value- / Dokumentenspeicher", "Memory-Manager im MemGPT-Stil", "Agenten-Frameworks (LangGraph, Agents SDKs)" ], "examples": [ "Ein Assistent, der sich sitzungsübergreifend an die Präferenzen eines Benutzers erinnert.", "Ein langlaufender Agent, der den Fortschritt zusammenfasst, um keinen Schritt zu wiederholen.", "Ein Support-Agent, der bei Bedarf frühere Tickets eines Kunden abruft." ], "faqs": [ { "q": "Wie unterscheidet sich das Agenten-Gedächtnis von RAG?", "a": "RAG ruft Informationen aus einer externen Wissensdatenbank ab; das Agenten-Gedächtnis greift auf den eigenen, akkumulierten Zustand des Agenten zu. Die Abrufmechanismen sind ähnlich, aber die Quelle und der Schreibpfad unterscheiden sich." }, { "q": "Was ist der Unterschied zwischen Kurz- und Langzeitgedächtnis?", "a": "Das Kurzzeit- (Arbeits-) Gedächtnis ist das aktive Kontextfenster für die aktuelle Aufgabe; das Langzeitgedächtnis ist ein persistenter Speicher, aus dem der Agent über Aufgaben und Sitzungen hinweg liest und in den er schreibt." }, { "q": "Warum behält man nicht einfach alles im Kontextfenster?", "a": "Kontextfenster sind begrenzt, und die Qualität sinkt, je voller sie werden. Die Auslagerung des Zustands in ein Gedächtnis und der gezielte Abruf relevanter Informationen sorgen dafür, dass der Agent fokussiert und kosteneffizient bleibt." }, { "q": "Welche Governance-Bedenken gibt es?", "a": "Das gespeicherte Gedächtnis kann personenbezogene oder sensible Daten enthalten. Daher sind Zugriffskontrollen, Aufbewahrungsfristen sowie die Möglichkeit zur Korrektur oder Löschung von Einträgen erforderlich." } ] }, "ja": { "title": "エージェントメモリシステムとは何か？", "summary": "エージェントメモリとは、AIエージェントが単一のコンテキストウィンドウを超えて、ステップ、セッション、タスク間で情報を保持および想起する方法である。通常、短期のワーキングメモリ（現在のコンテキスト）と、長期メモリ（エージェントが読み書きする永続的なストレージ）を分離する。メモリによって、エージェントは長いタスクを通じて状態を維持し、時間の経過とともにユーザーを記憶し、重複する作業を避けることができる。これはハーネスエンジニアリング (Harness Engineering) のコアレイヤーである。", "definition": "エージェントメモリとは、AIエージェントが当面のコンテキストウィンドウを超えて情報を保存、整理、検索するために使用する一連のメカニズムであり、短期のワーキングメモリと長期の永続メモリにまたがる。", "takeaways": [ "メモリは、単一の有限なコンテキストウィンドウを超えてエージェントを拡張する。", "短期（ワーキング）メモリと長期（永続）メモリは、それぞれ異なる役割を果たす。", "長期メモリは、エージェント自身の履歴に対するRAGのように、多くの場合オンデマンドで検索される。", "優れたメモリは、長いタスクにおける重複作業や状態の喪失を防ぐ。", "何を書き込み、保持し、忘れるかは設計上の決定事項であり、自動的に行われるものではない。" ], "context": [ "モデルのコンテキストウィンドウは有限であるため、エージェントがそれを超えて記憶する必要があるものはすべて外部ストレージを必要とする。メモリがなければ、エージェントは以前のステップを忘れ、アクションを繰り返し、セッションをまたいだパーソナライズを行うことができない。", "メモリは、ステートレスなモデルを連続性のあるシステムへと変える。難しいのはキュレーションである。何を書き留める価値があるか、それをどのように整理するか、そして今関連するものだけをどのように検索するかを決定することであり、これはコンテキストエンジニアリングと密接に関連している。" ], "architecture": [ "2つのレイヤー：ワーキングメモリ（アクティブなタスクを保持する現在のコンテキストウィンドウ）と、長期メモリ（タスク中に書き込まれ、後で検索されるベクトル、キーバリュー、ドキュメント、グラフなどの外部ストレージ）。一部の設計では、エピソードメモリ（イベント）、意味メモリ（事実）、手続きメモリ（スキル）が追加される。", "エージェントは各ステップで関連するメモリをコンテキストに読み込み、学習するにつれて新しいメモリを書き込む。検索、要約、忘却のポリシーにより、メモリは肥大化することなく有用な状態に保たれる。" ], "components": [ "ワーキングメモリ", "長期ストレージ（ベクトル/KV/グラフ）", "書き込みポリシー", "検索ポリシー", "要約 / 統合", "忘却 / 有効期限" ], "pros": [ "ステップ、セッション、タスク間の連続性。", "時間の経過とともに持続するパーソナライズ。", "重複作業やコンテキストの喪失を回避。", "長期的なステートフルエージェントを実現。" ], "risks": [ "古くなったり誤ったりしたメモリが、将来の回答を汚染する。", "保存されたデータに対するプライバシーおよびガバナンスの義務。", "無関係なメモリの検索によるノイズの増加。", "統合や有効期限がないことによる、制限のない肥大化。" ], "tools": [ "ベクトルデータベース", "キーバリュー / ドキュメントストア", "MemGPTスタイルのメモリマネージャー", "エージェントフレームワーク（LangGraph、Agents SDK）" ], "examples": [ "セッションをまたいでユーザーの好みを記憶するアシスタント。", "ステップを繰り返さないように進捗を要約する、長期実行型のエージェント。", "関連する場合に、顧客の過去のチケットを想起するサポートエージェント。" ], "faqs": [ { "q": "エージェントメモリはRAGとどう違うのですか？", "a": "RAGは外部のナレッジベースから検索しますが、エージェントメモリはエージェント自身が蓄積した状態から検索します。検索の仕組みは似ていますが、ソースと書き込みパスが異なります。" }, { "q": "短期メモリと長期メモリの違いは何ですか？", "a": "短期（ワーキング）メモリは現在のタスクのためのライブなコンテキストウィンドウであり、長期メモリはエージェントがタスクやセッションをまたいで読み書きする永続的なストレージです。" }, { "q": "すべてをコンテキストウィンドウに保持しないのはなぜですか？", "a": "ウィンドウは有限であり、満たされるにつれて品質が低下します。状態をメモリに外部化し、関連するものだけを検索することで、エージェントのフォーカスを維持し、コストを抑えることができます。" }, { "q": "ガバナンス上の懸念にはどのようなものがありますか？", "a": "保存されたメモリには個人データや機密データが含まれる可能性があるため、アクセス制御、保持制限、およびエントリを修正または削除する機能が必要です。" } ] }, "zh": { "title": "什么是智能体记忆系统？", "summary": "智能体记忆是 AI 智能体在单个上下文窗口之外保留和检索信息的方式——跨越步骤、会话和任务。它通常将短期工作记忆（当前上下文）与长期记忆（智能体读写的持久化存储）区分开来。记忆使智能体能够在长期任务中携带状态、长期记住用户并避免重复工作。它是 Harness Engineering（智能体支撑系统工程）的核心层。", "definition": "智能体记忆是 AI 智能体用于在其直接上下文窗口之外存储、组织和检索信息的一系列机制，涵盖短期工作记忆和长期持久记忆。", "takeaways": [ "记忆使智能体能够超越单个有限的上下文窗口。", "短期（工作）记忆与长期（持久）记忆承担着不同的角色。", "长期记忆通常是按需检索的，类似于对智能体自身历史记录进行 RAG。", "良好的记忆力可以防止在长期任务中出现重复工作和状态丢失。", "写入、保留和遗忘哪些内容是一项设计决策，而非自动进行的。" ], "context": [ "模型的上下文窗口是有限的，因此智能体必须记住的超出该窗口的任何内容都需要外部存储。如果没有记忆，智能体就会忘记先前的步骤、重复操作，并且无法跨会话进行个性化。", "记忆将无状态模型转变为具有连续性的系统。难点在于整理：决定什么值得记录、如何组织它，以及如何仅检索当前相关的内容——这与上下文工程密切相关。" ], "architecture": [ "两个层级：工作记忆（当前上下文窗口，保存活动任务）和长期记忆（外部存储——向量、键值、文档或图——在任务期间写入并在以后检索）。某些设计还增加了情景记忆（事件）、语义记忆（事实）和程序记忆（技能）。", "智能体在每一步将相关的记忆读取到上下文中，并在学习时写入新的记忆。检索、总结和遗忘策略使记忆保持实用，而不会使其过载。" ], "components": [ "工作记忆", "长期存储（向量/KV/图）", "写入策略", "检索策略", "总结 / 整合", "遗忘 / 过期" ], "pros": [ "跨步骤、会话和任务的连续性。", "随时间持久保留的个性化。", "避免重复工作和上下文丢失。", "支持长周期、有状态的智能体。" ], "risks": [ "陈旧或错误的记忆会污染未来的回答。", "对存储数据的隐私和治理义务。", "检索到无关的记忆会增加噪音。", "若无整合或过期机制，记忆会无限制增长。" ], "tools": [ "向量数据库", "键值 / 文档存储", "MemGPT 风格的记忆管理器", "智能体框架（LangGraph、Agents SDK）" ], "examples": [ "助手跨会话记住用户的偏好。", "长期运行的智能体总结进度，从而绝不重复步骤。", "支持智能体在相关时召回客户先前的工单。" ], "faqs": [ { "q": "智能体记忆与 RAG 有何不同？", "a": "RAG 从外部知识库中检索；智能体记忆则从智能体自身积累的状态中检索。检索机制类似，但数据源 and 写入路径不同。" }, { "q": "短期记忆和长期记忆有什么区别？", "a": "短期（工作）记忆是当前任务的实时上下文窗口；长期记忆是智能体在跨任务和会话时进行读写的持久化存储。" }, { "q": "为什么不把所有内容都保留在上下文窗口中？", "a": "窗口是有限的，且随着窗口填满，质量会下降。将状态外部化到记忆中并仅检索相关内容，可以使智能体保持专注且成本可控。" }, { "q": "有哪些治理方面的顾虑？", "a": "存储的记忆可能包含个人或敏感数据，因此需要访问控制、保留期限限制以及纠正或删除条目的能力。" } ] } } }, { "slug": "agentic-ai", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/agentic-ai", "api": "https://santismm.com/api/knowledge/agentic-ai", "canonical_url": "https://santismm.com/en/knowledge/agentic-ai", "api_url": "https://santismm.com/api/knowledge/agentic-ai", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "Yao et al. — ReAct: Synergizing Reasoning and Acting in Language Models (2022)", "url": "https://arxiv.org/abs/2210.03629" }, { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" }, { "title": "Model Context Protocol — Introduction", "url": "https://modelcontextprotocol.io" } ], "related": [ "ai-agent", "harness-engineering", "multi-agent-architecture", "agentic-evaluation" ], "locales": { "en": { "title": "What is Agentic AI?", "summary": "Agentic AI refers to systems that pursue goals over multiple steps — planning, calling tools, acting on an environment and reacting to feedback — instead of producing a single response. It turns a language model from a text generator into an actor that can complete tasks. The shift it represents is from do-it-yourself software, where the human drives every step, to do-it-for-me software, where the system carries out the work and reports back.", "definition": "Agentic AI is the class of AI systems that autonomously plan and execute multi-step tasks by combining a model with memory, tools and a control loop.", "takeaways": [ "An agent = model + tools + memory + a control loop that decides what to do next.", "Autonomy is a spectrum, from a single tool call to long-horizon task execution.", "Reliability comes mostly from the harness around the model, not raw model IQ.", "Tool use (function calling) is what connects the model to real systems and data.", "Evaluation must measure task completion (agency), not just answer quality (capability)." ], "context": [ "For most of the LLM era, models were used as one-shot responders: a prompt in, an answer out. Agentic AI breaks that pattern by giving the model a loop — it can decide to call a tool, read the result, revise its plan and continue until the goal is met or a budget is exhausted.", "This is the dominant frontier of applied AI in the enterprise because it moves the value from answering questions to completing work: resolving a support ticket end to end, refactoring a codebase, running a research task, operating a workflow." ], "architecture": [ "A minimal agent has four parts: a reasoning model, a set of tools it can invoke, some form of memory or state, and an orchestration loop that turns model outputs into actions and feeds observations back in.", "Patterns range from simple (a model with tools and a stop condition) to complex (planner-executor splits, reflection, and multi-agent teams). Anthropic's guidance is to prefer the simplest pattern that works and add structure only when measurably needed." ], "components": [ "Reasoning model", "Tools / function calling", "Memory & state", "Orchestration loop", "Guardrails", "Observability" ], "pros": [ "Completes multi-step work, not just single answers.", "Adapts to feedback and recovers from intermediate errors.", "Integrates with real systems through tools and APIs.", "Scales repetitive knowledge work that was previously human-only." ], "risks": [ "Compounding errors over long task horizons.", "Unbounded cost and latency without budgets and stop conditions.", "Security exposure from tool access and prompt injection.", "Hard to evaluate and debug compared with single-shot prompts." ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "A customer-service agent that reads a ticket, looks up the order, applies a refund and replies — all through tools.", "A coding agent that edits files, runs tests and iterates until the suite passes.", "A research agent that searches, reads sources, verifies claims and writes a cited summary." ], "faqs": [ { "q": "What is the difference between an AI agent and agentic AI?", "a": "An AI agent is a concrete system; agentic AI is the broader paradigm of building software around such goal-directed, multi-step systems." }, { "q": "Do you need a more powerful model to be agentic?", "a": "Not necessarily. The same model can succeed or fail at a task depending almost entirely on the harness — the tools, memory, prompts and control loop around it." }, { "q": "Is RAG agentic?", "a": "Plain retrieval-augmented generation is a single step. It becomes agentic when the system decides when and what to retrieve as part of a multi-step loop." }, { "q": "What makes agents unreliable?", "a": "Long horizons compound small errors, tools fail, and context gets lost. Reliability comes from harness engineering: good tools, memory, guardrails and evaluation." }, { "q": "How do you measure an agent?", "a": "With agentic benchmarks and task-based evals that score end-to-end task completion in an environment, not just the quality of a single answer." } ] }, "es": { "title": "¿Qué es la IA Agéntica (Agentic AI)?", "summary": "La IA agéntica designa sistemas que persiguen objetivos en varios pasos —planifican, llaman a herramientas, actúan sobre un entorno y reaccionan al feedback— en lugar de producir una única respuesta. Convierte a un modelo de lenguaje de generador de texto en un actor capaz de completar tareas. El cambio que representa es pasar del software 'hazlo tú', donde la persona conduce cada paso, al software 'hazlo por mí', donde el sistema ejecuta el trabajo y reporta el resultado.", "definition": "La IA agéntica es la clase de sistemas de IA que planifican y ejecutan de forma autónoma tareas de varios pasos combinando un modelo con memoria, herramientas y un bucle de control.", "takeaways": [ "Un agente = modelo + herramientas + memoria + un bucle de control que decide el siguiente paso.", "La autonomía es un espectro, desde una sola llamada a herramienta hasta tareas de horizonte largo.", "La fiabilidad viene sobre todo del 'harness' alrededor del modelo, no del coeficiente del modelo.", "El uso de herramientas (function calling) es lo que conecta el modelo con sistemas y datos reales.", "La evaluación debe medir la finalización de la tarea (agencia), no solo la calidad de la respuesta (capacidad)." ], "context": [ "Durante buena parte de la era LLM los modelos se usaron como respondedores de un solo turno: entra un prompt, sale una respuesta. La IA agéntica rompe ese patrón dándole al modelo un bucle: puede decidir llamar a una herramienta, leer el resultado, revisar su plan y continuar hasta cumplir el objetivo o agotar un presupuesto.", "Es la frontera dominante de la IA aplicada en la empresa porque mueve el valor de responder preguntas a completar trabajo: resolver un ticket de soporte de principio a fin, refactorizar un código, ejecutar una investigación, operar un flujo de trabajo." ], "architecture": [ "Un agente mínimo tiene cuatro partes: un modelo de razonamiento, un conjunto de herramientas que puede invocar, alguna forma de memoria o estado, y un bucle de orquestación que convierte las salidas del modelo en acciones y reintroduce las observaciones.", "Los patrones van de lo simple (un modelo con herramientas y una condición de parada) a lo complejo (separación planificador-ejecutor, reflexión y equipos multiagente). La recomendación de Anthropic es preferir el patrón más simple que funcione y añadir estructura solo cuando aporte de forma medible." ], "components": [ "Modelo de razonamiento", "Herramientas / function calling", "Memoria y estado", "Bucle de orquestación", "Guardarraíles", "Observabilidad" ], "pros": [ "Completa trabajo de varios pasos, no solo respuestas sueltas.", "Se adapta al feedback y se recupera de errores intermedios.", "Se integra con sistemas reales mediante herramientas y APIs.", "Escala trabajo de conocimiento repetitivo antes exclusivamente humano." ], "risks": [ "Acumulación de errores en horizontes de tarea largos.", "Coste y latencia sin límite si faltan presupuestos y condiciones de parada.", "Exposición de seguridad por el acceso a herramientas y la inyección de prompts.", "Difícil de evaluar y depurar frente a los prompts de un solo turno." ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "Un agente de atención al cliente que lee un ticket, consulta el pedido, aplica un reembolso y responde, todo a través de herramientas.", "Un agente de programación que edita ficheros, ejecuta tests e itera hasta que la suite pasa.", "Un agente de investigación que busca, lee fuentes, verifica afirmaciones y escribe un resumen con citas." ], "faqs": [ { "q": "¿Cuál es la diferencia entre un agente de IA y la IA agéntica?", "a": "Un agente de IA es un sistema concreto; la IA agéntica es el paradigma más amplio de construir software en torno a esos sistemas dirigidos a objetivos y de varios pasos." }, { "q": "¿Hace falta un modelo más potente para ser agéntico?", "a": "No necesariamente. El mismo modelo puede triunfar o fracasar en una tarea casi por completo según su harness: las herramientas, la memoria, los prompts y el bucle de control que lo rodean." }, { "q": "¿RAG es agéntico?", "a": "El RAG simple es un único paso. Se vuelve agéntico cuando el sistema decide cuándo y qué recuperar como parte de un bucle de varios pasos." }, { "q": "¿Qué hace poco fiables a los agentes?", "a": "Los horizontes largos acumulan errores pequeños, las herramientas fallan y se pierde contexto. La fiabilidad viene de la ingeniería de harness: buenas herramientas, memoria, guardarraíles y evaluación." }, { "q": "¿Cómo se mide un agente?", "a": "Con benchmarks agénticos y evaluaciones basadas en tareas que puntúan la finalización de extremo a extremo en un entorno, no solo la calidad de una respuesta." } ] }, "pt": { "title": "O que é IA Agêntica (Agentic AI)?", "summary": "A IA agêntica designa sistemas que perseguem objetivos em vários passos — planejam, chamam ferramentas, agem sobre um ambiente e reagem ao feedback — em vez de produzir uma única resposta. Transforma um modelo de linguagem de gerador de texto em um ator capaz de concluir tarefas. A mudança que representa é passar do software 'faça você mesmo', em que a pessoa conduz cada passo, ao software 'faça por mim', em que o sistema executa o trabalho e reporta o resultado.", "definition": "A IA agêntica é a classe de sistemas de IA que planejam e executam de forma autônoma tarefas de vários passos combinando um modelo com memória, ferramentas e um laço de controle.", "takeaways": [ "Um agente = modelo + ferramentas + memória + um laço de controle que decide o próximo passo.", "A autonomia é um espectro, de uma única chamada de ferramenta a tarefas de horizonte longo.", "A confiabilidade vem sobretudo do 'harness' em torno do modelo, não do QI do modelo.", "O uso de ferramentas (function calling) é o que conecta o modelo a sistemas e dados reais.", "A avaliação deve medir a conclusão da tarefa (agência), não só a qualidade da resposta (capacidade)." ], "context": [ "Durante boa parte da era LLM os modelos foram usados como respondedores de um único turno: entra um prompt, sai uma resposta. A IA agêntica quebra esse padrão dando ao modelo um laço: ele pode decidir chamar uma ferramenta, ler o resultado, revisar seu plano e continuar até cumprir o objetivo ou esgotar um orçamento.", "É a fronteira dominante da IA aplicada na empresa porque move o valor de responder perguntas para concluir trabalho: resolver um chamado de suporte de ponta a ponta, refatorar um código, executar uma pesquisa, operar um fluxo de trabalho." ], "architecture": [ "Um agente mínimo tem quatro partes: um modelo de raciocínio, um conjunto de ferramentas que pode invocar, alguma forma de memória ou estado, e um laço de orquestração que converte as saídas do modelo em ações e realimenta as observações.", "Os padrões vão do simples (um modelo com ferramentas e uma condição de parada) ao complexo (separação planejador-executor, reflexão e equipes multiagente). A recomendação da Anthropic é preferir o padrão mais simples que funcione e adicionar estrutura só quando agregar de forma mensurável." ], "components": [ "Modelo de raciocínio", "Ferramentas / function calling", "Memória e estado", "Laço de orquestração", "Guard-rails", "Observabilidade" ], "pros": [ "Conclui trabalho de vários passos, não só respostas isoladas.", "Adapta-se ao feedback e se recupera de erros intermediários.", "Integra-se a sistemas reais por meio de ferramentas e APIs.", "Escala trabalho de conhecimento repetitivo antes exclusivamente humano." ], "risks": [ "Acúmulo de erros em horizontes de tarefa longos.", "Custo e latência sem limite sem orçamentos e condições de parada.", "Exposição de segurança pelo acesso a ferramentas e pela injeção de prompts.", "Difícil de avaliar e depurar frente aos prompts de um único turno." ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "Um agente de atendimento que lê um chamado, consulta o pedido, aplica um reembolso e responde, tudo via ferramentas.", "Um agente de programação que edita arquivos, executa testes e itera até a suíte passar.", "Um agente de pesquisa que busca, lê fontes, verifica afirmações e escreve um resumo com citações." ], "faqs": [ { "q": "Qual é a diferença entre um agente de IA e IA agêntica?", "a": "Um agente de IA é um sistema concreto; a IA agêntica é o paradigma mais amplo de construir software em torno desses sistemas orientados a objetivos e de vários passos." }, { "q": "É preciso um modelo mais potente para ser agêntico?", "a": "Não necessariamente. O mesmo modelo pode ter sucesso ou falhar numa tarefa quase inteiramente conforme seu harness: as ferramentas, a memória, os prompts e o laço de controle ao seu redor." }, { "q": "RAG é agêntico?", "a": "O RAG simples é um único passo. Torna-se agêntico quando o sistema decide quando e o que recuperar como parte de um laço de vários passos." }, { "q": "O que torna os agentes pouco confiáveis?", "a": "Horizontes longos acumulam pequenos erros, ferramentas falham e contexto se perde. A confiabilidade vem da engenharia de harness: boas ferramentas, memória, guard-rails e avaliação." }, { "q": "Como se mede um agente?", "a": "Com benchmarks agênticos e avaliações baseadas em tarefas que pontuam a conclusão de ponta a ponta num ambiente, não só a qualidade de uma resposta." } ] }, "fr": { "title": "Qu'est-ce que l'IA agentique ?", "summary": "L'IA agentique désigne des systèmes qui poursuivent des objectifs à travers plusieurs étapes — planification, appel d'outils, action sur un environnement et réaction aux retours — plutôt que de produire une réponse unique. Elle transforme un modèle de langage, de simple générateur de texte en un acteur capable de mener à bien des tâches. Elle représente une transition entre les logiciels de type « faites-le vous-même », où l'humain pilote chaque étape, et les logiciels de type « faites-le pour moi », où le système exécute le travail et rend compte du résultat.", "definition": "L'IA agentique est la catégorie de systèmes d'IA qui planifient et exécutent de manière autonome des tâches multi-étapes en combinant un modèle avec de la mémoire, des outils et une boucle de contrôle.", "takeaways": [ "Un agent = modèle + outils + mémoire + une boucle de contrôle qui décide de l'action suivante.", "L'autonomie est un spectre, allant d'un simple appel d'outil à l'exécution de tâches sur un long horizon.", "La fiabilité provient principalement du harness entourant le modèle, et non du QI brut du modèle.", "L'utilisation d'outils (l'appel de fonctions) est ce qui connecte le modèle aux systèmes et données réels.", "L'évaluation doit mesurer la réalisation de la tâche (l'agentivité), et pas seulement la qualité de la réponse (la capacité)." ], "context": [ "Pendant la majeure partie de l'ère des LLM, les modèles ont été utilisés comme des répondeurs ponctuels (one-shot) : une invite en entrée, une réponse en sortie. L'IA agentique rompt avec ce schéma en dotant le modèle d'une boucle — il peut décider d'appeler un outil, d'en lire le résultat, de réviser son plan et de continuer jusqu'à ce que l'objectif soit atteint ou qu'un budget soit épuisé.", "C'est la frontière dominante de l'IA appliquée en entreprise, car elle déplace la valeur de la simple réponse aux questions vers la réalisation de travaux concrets : résolution de bout en bout d'un ticket de support, refactorisation d'une base de code, exécution d'une tâche de recherche ou pilotage d'un flux de travail." ], "architecture": [ "Un agent minimal comporte quatre parties : un modèle de raisonnement, un ensemble d'outils qu'il peut invoquer, une forme de mémoire ou d'état, et une boucle d'orchestration qui transforme les sorties du modèle en actions et y réinjecte les observations.", "Les architectures vont du plus simple (un modèle avec des outils et une condition d'arrêt) au plus complexe (séparation planificateur-exécuteur, réflexion et équipes multi-agents). Les recommandations d'Anthropic consistent à privilégier l'architecture la plus simple possible et à n'ajouter de la structure que lorsque cela s'avère mesurablement nécessaire." ], "components": [ "Modèle de raisonnement", "Outils / appel de fonctions", "Mémoire et état", "Boucle d'orchestration", "Garde-fous", "Observabilité" ], "pros": [ "Réalise des travaux multi-étapes, et pas seulement des réponses uniques.", "S'adapte aux retours et se rétablit après des erreurs intermédiaires.", "S'intègre aux systèmes réels via des outils et des API.", "Met à l'échelle le travail intellectuel répétitif qui était auparavant réservé aux humains." ], "risks": [ "Cumul d'erreurs sur de longs horizons de tâches.", "Coût et latence illimités en l'absence de budgets et de conditions d'arrêt.", "Exposition de sécurité liée à l'accès aux outils et aux injections d'invites (prompt injection).", "Difficile à évaluer et à déboguer par rapport aux invites ponctuelles (single-shot)." ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "Un agent de service client qui lit un ticket, recherche la commande, applique un remboursement et répond — le tout via des outils.", "Un agent de codage qui modifie des fichiers, exécute des tests et itère jusqu'à ce que la suite de tests réussisse.", "Un agent de recherche qui cherche, lit des sources, vérifie des affirmations et rédige un résumé avec citations." ], "faqs": [ { "q": "Quelle est la différence entre un agent IA et l'IA agentique ?", "a": "Un agent IA est un système concret ; l'IA agentique est le paradigme plus large consistant à concevoir des logiciels autour de ces systèmes multi-étapes orientés vers des objectifs." }, { "q": "Faut-il un modèle plus puissant pour être agentique ?", "a": "Pas nécessairement. Un même modèle peut réussir ou échouer dans une tâche en fonction presque entièrement du harness — les outils, la mémoire, les prompts et la boucle de contrôle qui l'entourent." }, { "q": "Le RAG est-il agentique ?", "a": "La génération augmentée de récupération (RAG) classique est une étape unique. Elle devient agentique lorsque le système décide quand et quoi récupérer dans le cadre d'une boucle multi-étapes." }, { "q": "Qu'est-ce qui rend les agents peu fiables ?", "a": "Les horizons lointains amplifient les petites erreurs, les outils échouent et le contexte se perd. La fiabilité provient du Harness Engineering : de bons outils, de la mémoire, des garde-fous et de l'évaluation." }, { "q": "Comment évalue-t-on un agent ?", "a": "Avec des benchmarks agentiques et des évaluations basées sur les tâches qui notent la réalisation de bout en bout d'une tâche dans un environnement, et non pas seulement la qualité d'une réponse unique." } ] }, "de": { "title": "Was ist Agentic AI?", "summary": "Agentic AI bezieht sich auf Systeme, die Ziele über mehrere Schritte hinweg verfolgen – durch Planung, den Aufruf von Tools, Interaktion mit einer Umgebung und Reaktion auf Feedback –, anstatt nur eine einzige Antwort zu generieren. Sie verwandelt ein Sprachmodell von einem reinen Textgenerator in einen Akteur, der Aufgaben eigenständig ausführen kann. Dies markiert den Übergang von „Do-it-yourself“-Software, bei der der Mensch jeden Schritt steuert, zu „Do-it-for-me“-Software, bei der das System die Arbeit erledigt und Bericht erstattet.", "definition": "Agentic AI bezeichnet die Klasse von KI-Systemen, die durch die Kombination eines Modells mit Gedächtnis, Tools und einer Kontrollschleife mehrstufige Aufgaben autonom planen und ausführen.", "takeaways": [ "Ein Agent = Modell + Tools + Gedächtnis + eine Kontrollschleife, die entscheidet, was als Nächstes zu tun ist.", "Autonomie ist ein Spektrum, das vom einfachen Tool-Aufruf bis zur Ausführung von Aufgaben mit langem Zeithorizont reicht.", "Zuverlässigkeit entsteht vor allem durch das Harness um das Modell herum, nicht durch die reine Modell-IQ.", "Die Nutzung von Tools (Function Calling) verbindet das Modell mit realen Systemen und Daten.", "Die Evaluierung muss die Aufgabenerfüllung (Handlungsfähigkeit/Agency) messen, nicht nur die Antwortqualität (Leistungsfähigkeit)." ], "context": [ "In der bisherigen LLM-Ära wurden Modelle meist als One-Shot-Systeme genutzt: Prompt rein, Antwort raus. Agentic AI bricht dieses Muster auf, indem sie dem Modell eine Schleife bereitstellt – es kann entscheiden, ein Tool aufzurufen, das Ergebnis zu lesen, seinen Plan anzupassen und fortzufahren, bis das Ziel erreicht oder ein Budget aufgebraucht ist.", "Dies ist die wichtigste Entwicklungslinie für angewandte KI in Unternehmen, da sich der Wert von der Beantwortung von Fragen hin zur Erledigung von Arbeit verschiebt: die End-to-End-Lösung eines Support-Tickets, das Refactoring einer Codebasis, die Durchführung einer Rechercheaufgabe oder das Betreiben eines Workflows." ], "architecture": [ "Ein minimaler Agent besteht aus vier Teilen: einem Reasoning-Modell, einer Reihe von Tools, die er aufrufen kann, einer Form von Gedächtnis oder Zustand und einer Orchestrierungsschleife, die Modell-Outputs in Aktionen umsetzt und Beobachtungen zurückspielt.", "Die Muster reichen von einfach (ein Modell mit Tools und einer Abbruchbedingung) bis komplex (Aufteilung in Planer und Ausführer, Reflexion und Multi-Agenten-Teams). Die Empfehlung von Anthropic lautet, das einfachste funktionierende Muster zu bevorzugen und Struktur nur dann hinzuzufügen, wenn dies messbar erforderlich ist." ], "components": [ "Reasoning-Modell", "Tools / Function Calling", "Gedächtnis & Zustand", "Orchestrierungsschleife", "Guardrails", "Observability" ], "pros": [ "Erledigt mehrstufige Arbeitsschritte, statt nur einzelne Antworten zu liefern.", "Passt sich an Feedback an und behebt Zwischenfehler selbstständig.", "Integriert sich über Tools und APIs in reale Systeme.", "Skaliert repetitive Wissensarbeit, die zuvor nur von Menschen erledigt werden konnte." ], "risks": [ "Sich summierende Fehler bei langen Aufgabenhorizonten.", "Unbegrenzte Kosten und Latenzzeiten ohne Budgets und Abbruchbedingungen.", "Sicherheitsrisiken durch Tool-Zugriff und Prompt-Injection.", "Schwer zu evaluieren und zu debuggen im Vergleich zu Single-Shot-Prompts." ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "Ein Kundenservice-Agent, der ein Ticket liest, die Bestellung nachschlägt, eine Rückerstattung veranlasst und antwortet – alles über Tools.", "Ein Coding-Agent, der Dateien bearbeitet, Tests ausführt und iteriert, bis die Testsuite erfolgreich durchläuft.", "Ein Recherche-Agent, der sucht, Quellen liest, Behauptungen verifiziert und eine zitierte Zusammenfassung schreibt." ], "faqs": [ { "q": "Was ist der Unterschied zwischen einem KI-Agenten und Agentic AI?", "a": "Ein KI-Agent ist ein konkretes System; Agentic AI ist das breitere Paradigma, Software um solche zielgerichteten, mehrstufigen Systeme herum aufzubauen." }, { "q": "Benötigt man ein leistungsstärkeres Modell, um agentisch zu agieren?", "a": "Nicht unbedingt. Dasselbe Modell kann bei einer Aufgabe erfolgreich sein oder scheitern, was fast ausschließlich vom Harness abhängt – den Tools, dem Speicher, den Prompts und der Kontrollschleife drumherum." }, { "q": "Ist RAG agentisch?", "a": "Einfache Retrieval-Augmented Generation ist ein einzelner Schritt. Sie wird agentisch, wenn das System im Rahmen einer mehrstufigen Schleife entscheidet, wann und was abgerufen werden soll." }, { "q": "Was macht Agenten unzuverlässig?", "a": "Lange Zeithorizonte summieren kleine Fehler auf, Tools schlagen fehl und der Kontext geht verloren. Zuverlässigkeit entsteht durch Harness Engineering: gute Tools, Speicher, Guardrails und Evaluation." }, { "q": "Wie misst man einen Agenten?", "a": "Mit agentischen Benchmarks und aufgabenbasierten Evals, die den End-to-End-Erfolg einer Aufgabe in einer Umgebung bewerten, nicht nur die Qualität einer einzelnen Antwort." } ] }, "ja": { "title": "Agentic AIとは何か？", "summary": "Agentic AIとは、単一の回答を生成するのではなく、計画、ツールの呼び出し、環境への働きかけ、フィードバックへの対応など、複数のステップにわたって目標を追求するシステムを指す。これにより、言語モデルはテキスト生成器から、タスクを完了できる実行者へと変化する。これが表すシフトは、人間がすべてのステップを主導する「DIY（Do-It-Yourself）ソフトウェア」から、システムが作業を実行して報告する「DIFM（Do-It-For-Me）ソフトウェア」への移行である。", "definition": "Agentic AIとは、モデルをメモリ、ツール、コントロールループと組み合わせることで、複数ステップのタスクを自律的に計画および実行するAIシステムのクラスである。", "takeaways": [ "エージェント ＝ モデル ＋ ツール ＋ メモリ ＋ 次に何をすべきかを決定するコントロールループ。", "自律性は、単一のツール呼び出しから長期的なタスク実行まで、スペクトラム（連続体）である。", "信頼性は、モデル自体の生のIQからではなく、主にモデルを取り囲むハーネスから得られる。", "ツールの使用（ファンクションコーリング）は、モデルを実際のシステムやデータに接続するものである。", "評価では、単なる回答の品質（能力）だけでなく、タスクの完了（エージェンシー）を測定しなければならない。" ], "context": [ "LLM時代の大部分において、モデルはワンショットの応答者として使用されてきた。つまり、プロンプトを入力し、回答を出力する。Agentic AIは、モデルにループを提供することでこのパターンを打破する。モデルはツールの呼び出し、結果の読み取り、計画の修正を決定し、目標が達成されるか予算が使い果たされるまで継続できる。", "これは、価値を「質問への回答」から「作業の完了」へと移行させるため、企業における応用AIの主要なフロンティアとなっている。例えば、サポートチケットのエンドツーエンドでの解決、コードベースのリファクタリング、調査タスクの実行、ワークフローの運用などである。" ], "architecture": [ "最小限のエージェントは、推論モデル、呼び出し可能なツール群、何らかの形式のメモリまたは状態、そしてモデルの出力をアクションに変換して観察結果をフィードバックするオーケストレーションループの4つの部分で構成される。", "パターンは、単純なもの（ツールと停止条件を備えたモデル）から複雑なもの（プランナーとエグゼキューターの分離、リフレクション、マルチエージェントチーム）まで多岐にわたる。Anthropicのガイダンスでは、機能する最も単純なパターンを優先し、測定可能な形で必要とされた場合にのみ構造を追加することを推奨している。" ], "components": [ "推論モデル", "ツール / ファンクションコーリング", "メモリ＆状態", "オーケストレーションループ", "ガードレール", "オブザーバビリティ" ], "pros": [ "単一の回答だけでなく、複数ステップの作業を完了する。", "フィードバックに適応し、途中のエラーから回復する。", "ツールやAPIを介して実際のシステムと統合する。", "従来は人間のみが行っていた反復的な知識労働をスケールさせる。" ], "risks": [ "長期的なタスクにおいてエラーが蓄積すること。", "予算や停止条件がない場合、コストとレイテンシが際限なく増加すること。", "ツールのアクセス権限やプロンプトインジェクションによるセキュリティリスク。", "ワンショットのプロンプトと比較して、評価やデバッグが困難であること。" ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "チケットを読み取り、注文を検索し、返金を適用して返信する、これらすべてをツールを介して行うカスタマーサービスエージェント。", "ファイルを編集し、テストを実行し、テストスイートが合格するまで繰り返すコーディングエージェント。", "検索、ソースの読み込み、主張の検証を行い、引用文献付きの要約を作成するリサーチエージェント。" ], "faqs": [ { "q": "AIエージェントとアジェンティックAI（Agentic AI）の違いは何ですか？", "a": "AIエージェントは具体的なシステムを指します。一方、アジェンティックAIは、そのような目標指向型でマルチステップのシステムを中心にソフトウェアを構築する、より広範なパラダイムを指します。" }, { "q": "アジェンティックであるためには、より強力なモデルが必要ですか？", "a": "必ずしもそうとは限りません。同じモデルであっても、タスクの成否は、それを取り囲むハーネス（ツール、メモリ、プロンプト、制御ループ）にほぼ完全に依存します。" }, { "q": "RAGはアジェンティックですか？", "a": "単なる検索拡張生成（RAG）は単一のステップです。マルチステップのループの一部として、システムが「いつ」「何を」検索するかを自律的に決定するようになったときに、アジェンティックになります。" }, { "q": "エージェントの信頼性が低くなる原因は何ですか？", "a": "長期的なタスク（ロングホライズン）では小さなエラーが蓄積され、ツールが失敗し、コンテキストが失われます。信頼性はハーネスエンジニアリング (Harness Engineering)（優れたツール、メモリ、ガードレール、評価）によってもたらされます。" }, { "q": "エージェントはどのように測定（評価）しますか？", "a": "単一の回答の品質だけでなく、環境内でのエンドツーエンドのタスク完了率をスコア化する、アジェンティックなベンチマークやタスクベースの評価（evals）を使用します。" } ] }, "zh": { "title": "什么是 Agentic AI？", "summary": "Agentic AI 是指通过多个步骤追求目标的系统——进行规划、调用工具、对环境做出行动并对反馈做出反应——而不是仅生成单一的响应。它将语言模型从文本生成器转变为能够完成任务的执行者。它代表了从“自主操作”（do-it-yourself）软件（人类主导每一步）向“代劳”（do-it-for-me）软件（系统执行工作并汇报结果）的转变。", "definition": "Agentic AI 是一类通过将模型与记忆、工具和控制循环相结合，自主规划并执行多步任务的 AI 系统。", "takeaways": [ "智能体 = 模型 + 工具 + 记忆 + 决定下一步做什么的控制循环。", "自主性是一个光谱，从单一的工具调用到长周期的任务执行。", "可靠性主要来自模型周围的支撑系统（harness），而非模型本身的原始智商。", "工具使用（函数调用）是将模型连接到真实系统和数据的纽带。", "评估必须衡量任务完成度（主动性/agency），而不仅仅是回答质量（能力/capability）。" ], "context": [ "在 LLM 时代的大部分时间里，模型都被用作单次响应器：输入提示词，输出回答。Agentic AI 打破了这一模式，为模型引入了循环——它可以决定调用工具、读取结果、修改计划并继续，直到实现目标或预算耗尽。", "这是企业应用 AI 的主导前沿，因为它将价值从回答问题转向了完成工作：端到端地解决支持工单、重构代码库、运行研究任务、操作工作流。" ], "architecture": [ "一个极简的智能体包含四个部分：推理模型、一组可调用的工具、某种形式的记忆或状态，以及一个将模型输出转化为行动并将观察结果反馈回去的编排循环。", "模式从简单（带有工具和停止条件的模型）到复杂（规划器-执行器分离、反思以及多智能体团队）不等。Anthropic 的建议是优先选择可行的最简模式，仅在有明确衡量需求时才增加结构。" ], "components": [ "推理模型", "工具 / 函数调用", "记忆与状态", "编排循环", "护栏", "可观测性" ], "pros": [ "完成多步工作，而不仅仅是提供单一回答。", "适应反馈并能从中间错误中恢复。", "通过工具和 API 与真实系统集成。", "规模化处理以前只能由人类完成的重复性知识工作。" ], "risks": [ "在长周期任务中误差会不断累积。", "若无预算和停止条件，成本和延迟将无限制增长。", "工具访问和提示词注入带来的安全风险。", "与单次提示词相比，难以进行评估和调试。" ], "tools": [ "LangGraph", "OpenAI Agents SDK", "Claude Agent SDK", "Model Context Protocol (MCP)", "Vertex AI Agent Engine" ], "examples": [ "一个客服智能体，它读取工单、查询订单、执行退款并进行回复——全部通过工具完成。", "一个编码智能体，它编辑文件、运行测试并进行迭代，直到测试套件通过。", "一个研究型智能体，能够进行搜索、阅读源文件、验证陈述并撰写包含引用的摘要。" ], "faqs": [ { "q": "AI智能体与智能体AI（Agentic AI）有什么区别？", "a": "AI智能体是一个具体的系统；而智能体AI则是围绕这种以目标为导向、多步骤系统构建软件的更广泛范式。" }, { "q": "要实现智能体化，是否需要更强大的模型？", "a": "不一定。同一个模型在任务中是成功还是失败，几乎完全取决于其支撑系统（harness）——即围绕它构建的工具、记忆、提示词和控制循环。" }, { "q": "RAG属于智能体化吗？", "a": "单纯的检索增强生成（RAG）是一个单一的步骤。只有当系统在多步骤循环中自主决定何时检索以及检索什么时，它才具有智能体特性。" }, { "q": "是什么导致智能体不可靠？", "a": "长时程会累积微小的误差、工具可能会失效，且上下文容易丢失。可靠性源自 Harness Engineering（智能体支撑系统工程）：优秀的工具、记忆、护栏和评估。" }, { "q": "如何评估智能体？", "a": "通过智能体基准测试和基于任务的评估（evals），在特定环境中对端到端任务的完成情况进行评分，而不仅仅是评估单个回答的质量。" } ] } } }, { "slug": "agentic-evaluation", "category": "concept", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/knowledge/agentic-evaluation", "api": "https://santismm.com/api/knowledge/agentic-evaluation", "canonical_url": "https://santismm.com/en/knowledge/agentic-evaluation", "api_url": "https://santismm.com/api/knowledge/agentic-evaluation", "evidence": { "evidenceLevel": "production", "confidenceLevel": "medium", "sourceType": [ "production_system", "personal_experience", "industry_observation", "paper" ] }, "references": [ { "title": "Jimenez et al. — SWE-bench: Can Language Models Resolve Real-World GitHub Issues? (2023)", "url": "https://arxiv.org/abs/2310.06770" }, { "title": "Santiago Santa María — The Stopwatch and the Exam", "url": "https://articles.santismm.com/the-stopwatch-and-the-exam/" } ], "related": [ "agentic-ai", "harness-engineering", "ai-agent", "ai-governance" ], "locales": { "en": { "title": "What is Agentic AI Evaluation?", "summary": "Agentic AI evaluation is the practice of measuring how well an agent completes multi-step, tool-using tasks in an environment — not just the quality of a single answer. As models saturate static knowledge benchmarks, evaluation is shifting from measuring capability (what a model knows) to measuring agency (what a system can actually get done). Good evals are the feedback loop that makes harness engineering possible.", "definition": "Agentic evaluation is the measurement of an AI agent's end-to-end task performance — success rate, reliability, cost and safety — on realistic, multi-step tasks in an environment.", "takeaways": [ "Evaluate task completion (agency), not just answer quality (capability).", "Agentic benchmarks test tools, environments and long horizons.", "Static benchmarks saturate; agentic ones are the new frontier.", "Evals are the feedback loop for improving the harness.", "Measure success, reliability, cost, latency and safety together." ], "context": [ "Traditional benchmarks ask a model questions and score the answers. That measures capability, but it tells you little about whether a system can complete real work. Agentic evaluation instead places an agent in an environment with tools and a goal, and scores whether it actually achieves it.", "This shift matters because production value comes from task completion. An agent that answers well but fails to finish tasks is not useful. Evaluation is also what lets teams improve harnesses systematically rather than by anecdote." ], "architecture": [ "An agentic eval defines tasks, an environment (real or simulated) with tools, a success criterion, and metrics. The agent runs; its trajectory and outcome are scored automatically where possible, with human review for nuanced cases.", "Beyond a single success rate, mature evaluation tracks reliability across runs, cost and latency budgets, and safety (did the agent stay within authorization and avoid harmful actions). Traces from observability feed directly into eval design." ], "components": [ "Task suite", "Environment & tools", "Success criteria", "Metrics (success, cost, latency, safety)", "Automated graders", "Human review", "Trajectory traces" ], "pros": [ "Measures what actually matters: task completion.", "Catches regressions before they reach users.", "Turns harness improvement into a measurable loop.", "Surfaces reliability, cost and safety, not just accuracy." ], "risks": [ "Hard to build realistic environments and graders.", "Overfitting to a benchmark instead of real performance.", "Saturation: benchmarks lose discriminative power over time.", "Automated grading can miss nuance; human review is costly." ], "tools": [ "SWE-bench and other agentic benchmarks", "LangSmith / Langfuse", "OpenAI Evals", "Custom task harnesses", "LLM-as-judge graders" ], "examples": [ "Scoring a coding agent on whether its patch makes a real test suite pass.", "Measuring a support agent's end-to-end ticket resolution rate.", "Tracking reliability of a workflow agent across repeated runs.", "In practice: evaluating an autonomous agent (OpenClaw) over 57 days straight from production traces — 161 sessions at 98.8% success (2 errors), with per-model reliability of 100% vs 95.7% across two model versions — a reliability baseline computed directly from operational traces rather than a curated benchmark set." ], "faqs": [ { "q": "What is the difference between capability and agency?", "a": "Capability is what a model knows or can do in isolation; agency is what a full system can actually accomplish in an environment. Agentic evaluation measures the latter." }, { "q": "Why are static benchmarks no longer enough?", "a": "Top models saturate them, so they stop discriminating. They also do not test tool use, environments or long-horizon tasks, which is where real agent performance lives." }, { "q": "What is an agentic benchmark?", "a": "A test that scores an agent's ability to complete multi-step, tool-using tasks in an environment — for example resolving real software issues." }, { "q": "How do evals relate to harness engineering?", "a": "Evals are the measurement loop that makes harness engineering possible: you change the harness, measure the effect, and keep what demonstrably improves task performance." } ] }, "es": { "title": "¿Qué es la Evaluación de IA Agéntica?", "summary": "La evaluación de IA agéntica es la práctica de medir cómo de bien un agente completa tareas de varios pasos con uso de herramientas en un entorno, no solo la calidad de una única respuesta. A medida que los modelos saturan los benchmarks estáticos de conocimiento, la evaluación se desplaza de medir capacidad (lo que un modelo sabe) a medir agencia (lo que un sistema realmente logra hacer). Unas buenas evaluaciones son el bucle de feedback que hace posible la ingeniería de harness.", "definition": "La evaluación agéntica es la medición del rendimiento de extremo a extremo de un agente de IA —tasa de éxito, fiabilidad, coste y seguridad— en tareas realistas de varios pasos dentro de un entorno.", "takeaways": [ "Evaluar la finalización de la tarea (agencia), no solo la calidad de la respuesta (capacidad).", "Los benchmarks agénticos prueban herramientas, entornos y horizontes largos.", "Los benchmarks estáticos se saturan; los agénticos son la nueva frontera.", "Las evaluaciones son el bucle de feedback para mejorar el harness.", "Medir juntos éxito, fiabilidad, coste, latencia y seguridad." ], "context": [ "Los benchmarks tradicionales hacen preguntas a un modelo y puntúan las respuestas. Eso mide capacidad, pero dice poco sobre si un sistema puede completar trabajo real. La evaluación agéntica, en cambio, coloca a un agente en un entorno con herramientas y un objetivo, y puntúa si realmente lo alcanza.", "Este cambio importa porque el valor en producción viene de completar tareas. Un agente que responde bien pero no termina las tareas no es útil. La evaluación es también lo que permite mejorar los harness de forma sistemática y no por anécdota." ], "architecture": [ "Una evaluación agéntica define tareas, un entorno (real o simulado) con herramientas, un criterio de éxito y métricas. El agente se ejecuta; su trayectoria y su resultado se puntúan automáticamente cuando es posible, con revisión humana para casos con matiz.", "Más allá de una sola tasa de éxito, la evaluación madura sigue la fiabilidad entre ejecuciones, los presupuestos de coste y latencia, y la seguridad (¿se mantuvo el agente dentro de su autorización y evitó acciones dañinas?). Las trazas de observabilidad alimentan directamente el diseño de las evaluaciones." ], "components": [ "Suite de tareas", "Entorno y herramientas", "Criterios de éxito", "Métricas (éxito, coste, latencia, seguridad)", "Evaluadores automáticos", "Revisión humana", "Trazas de trayectoria" ], "pros": [ "Mide lo que de verdad importa: la finalización de la tarea.", "Detecta regresiones antes de que lleguen a los usuarios.", "Convierte la mejora del harness en un bucle medible.", "Saca a la luz fiabilidad, coste y seguridad, no solo precisión." ], "risks": [ "Difícil construir entornos y evaluadores realistas.", "Sobreajuste a un benchmark en vez del rendimiento real.", "Saturación: los benchmarks pierden poder discriminativo con el tiempo.", "La evaluación automática puede perder matices; la revisión humana es cara." ], "tools": [ "SWE-bench y otros benchmarks agénticos", "LangSmith / Langfuse", "OpenAI Evals", "Harness de tareas a medida", "Evaluadores LLM-as-judge" ], "examples": [ "Puntuar a un agente de programación según si su parche hace pasar una suite de tests real.", "Medir la tasa de resolución de tickets de extremo a extremo de un agente de soporte.", "Seguir la fiabilidad de un agente de flujo de trabajo en ejecuciones repetidas.", "En la práctica: evaluar un agente autónomo (OpenClaw) durante 57 días directamente desde trazas de producción — 161 sesiones con 98,8% de éxito (2 errores), con fiabilidad por modelo de 100% frente a 95,7% en dos versiones — una línea base de fiabilidad calculada directamente desde trazas operativas, no desde un set de benchmark curado." ], "faqs": [ { "q": "¿Cuál es la diferencia entre capacidad y agencia?", "a": "La capacidad es lo que un modelo sabe o puede hacer de forma aislada; la agencia es lo que un sistema completo logra realmente en un entorno. La evaluación agéntica mide esto último." }, { "q": "¿Por qué ya no bastan los benchmarks estáticos?", "a": "Los mejores modelos los saturan y dejan de discriminar. Además no prueban uso de herramientas, entornos ni tareas de horizonte largo, que es donde está el rendimiento real de un agente." }, { "q": "¿Qué es un benchmark agéntico?", "a": "Una prueba que puntúa la capacidad de un agente para completar tareas de varios pasos con uso de herramientas en un entorno; por ejemplo, resolver incidencias reales de software." }, { "q": "¿Cómo se relacionan las evaluaciones con la ingeniería de harness?", "a": "Las evaluaciones son el bucle de medición que hace posible la ingeniería de harness: cambias el harness, mides el efecto y conservas lo que demuestra mejorar el rendimiento en la tarea." } ] }, "pt": { "title": "O que é Avaliação de IA Agêntica?", "summary": "A avaliação de IA agêntica é a prática de medir quão bem um agente conclui tarefas de vários passos com uso de ferramentas num ambiente, não só a qualidade de uma única resposta. À medida que os modelos saturam os benchmarks estáticos de conhecimento, a avaliação se desloca de medir capacidade (o que um modelo sabe) para medir agência (o que um sistema realmente consegue concluir). Boas avaliações são o laço de feedback que torna possível a engenharia de harness.", "definition": "A avaliação agêntica é a medição do desempenho de ponta a ponta de um agente de IA — taxa de sucesso, confiabilidade, custo e segurança — em tarefas realistas de vários passos dentro de um ambiente.", "takeaways": [ "Avaliar a conclusão da tarefa (agência), não só a qualidade da resposta (capacidade).", "Os benchmarks agênticos testam ferramentas, ambientes e horizontes longos.", "Os benchmarks estáticos saturam; os agênticos são a nova fronteira.", "As avaliações são o laço de feedback para melhorar o harness.", "Medir juntos sucesso, confiabilidade, custo, latência e segurança." ], "context": [ "Os benchmarks tradicionais fazem perguntas a um modelo e pontuam as respostas. Isso mede capacidade, mas diz pouco sobre se um sistema consegue concluir trabalho real. A avaliação agêntica, em vez disso, coloca um agente num ambiente com ferramentas e um objetivo, e pontua se ele realmente o alcança.", "Essa mudança importa porque o valor em produção vem de concluir tarefas. Um agente que responde bem mas não termina as tarefas não é útil. A avaliação é também o que permite melhorar os harnesses de forma sistemática e não por anedota." ], "architecture": [ "Uma avaliação agêntica define tarefas, um ambiente (real ou simulado) com ferramentas, um critério de sucesso e métricas. O agente é executado; sua trajetória e seu resultado são pontuados automaticamente quando possível, com revisão humana para casos com nuance.", "Além de uma única taxa de sucesso, a avaliação madura acompanha a confiabilidade entre execuções, os orçamentos de custo e latência, e a segurança (o agente se manteve dentro de sua autorização e evitou ações nocivas?). Os rastros de observabilidade alimentam diretamente o design das avaliações." ], "components": [ "Suíte de tarefas", "Ambiente e ferramentas", "Critérios de sucesso", "Métricas (sucesso, custo, latência, segurança)", "Avaliadores automáticos", "Revisão humana", "Rastros de trajetória" ], "pros": [ "Mede o que de fato importa: a conclusão da tarefa.", "Detecta regressões antes de chegarem aos usuários.", "Transforma a melhoria do harness num laço mensurável.", "Revela confiabilidade, custo e segurança, não só precisão." ], "risks": [ "Difícil construir ambientes e avaliadores realistas.", "Sobreajuste a um benchmark em vez do desempenho real.", "Saturação: os benchmarks perdem poder discriminativo com o tempo.", "A avaliação automática pode perder nuances; a revisão humana é cara." ], "tools": [ "SWE-bench e outros benchmarks agênticos", "LangSmith / Langfuse", "OpenAI Evals", "Harness de tarefas sob medida", "Avaliadores LLM-as-judge" ], "examples": [ "Pontuar um agente de programação conforme seu patch faça passar uma suíte de testes real.", "Medir a taxa de resolução de chamados de ponta a ponta de um agente de suporte.", "Acompanhar a confiabilidade de um agente de fluxo de trabalho em execuções repetidas.", "Na prática: avaliar um agente autônomo (OpenClaw) por 57 dias diretamente a partir de rastros de produção — 161 sessões com 98,8% de sucesso (2 erros), com confiabilidade por modelo de 100% ante 95,7% em duas versões — uma linha de base de confiabilidade calculada diretamente de rastros operacionais, não de um conjunto de benchmark curado." ], "faqs": [ { "q": "Qual é a diferença entre capacidade e agência?", "a": "Capacidade é o que um modelo sabe ou pode fazer isoladamente; agência é o que um sistema completo realmente realiza num ambiente. A avaliação agêntica mede o segundo." }, { "q": "Por que os benchmarks estáticos já não bastam?", "a": "Os melhores modelos os saturam e deixam de discriminar. Além disso não testam uso de ferramentas, ambientes nem tarefas de horizonte longo, que é onde está o desempenho real de um agente." }, { "q": "O que é um benchmark agêntico?", "a": "Um teste que pontua a capacidade de um agente de concluir tarefas de vários passos com uso de ferramentas num ambiente; por exemplo, resolver issues reais de software." }, { "q": "Como as avaliações se relacionam com a engenharia de harness?", "a": "As avaliações são o laço de medição que torna possível a engenharia de harness: você muda o harness, mede o efeito e mantém o que comprovadamente melhora o desempenho na tarefa." } ] }, "fr": { "title": "Qu'est-ce que l'évaluation de l'IA agentique ?", "summary": "L'évaluation de l'IA agentique consiste à mesurer la capacité d'un agent à accomplir des tâches multi-étapes utilisant des outils dans un environnement — et non pas seulement la qualité d'une réponse unique. Alors que les modèles saturent les benchmarks de connaissances statiques, l'évaluation passe de la mesure de la capacité (ce qu'un modèle sait) à la mesure de l'agentivité (ce qu'un système peut réellement accomplir). De bonnes évaluations constituent la boucle de rétroaction qui rend possible le Harness Engineering.", "definition": "L'évaluation agentique est la mesure des performances de bout en bout d'un agent IA — taux de réussite, fiabilité, coût et sécurité — sur des tâches réalistes et multi-étapes dans un environnement.", "takeaways": [ "Évaluez la réalisation des tâches (agentivité), pas seulement la qualité des réponses (capacité).", "Les benchmarks agentiques testent les outils, les environnements et les horizons lointains.", "Les benchmarks statiques saturent ; les benchmarks agentiques sont la nouvelle frontière.", "Les évaluations sont la boucle de rétroaction pour améliorer le harness.", "Mesurez ensemble la réussite, la fiabilité, le coût, la latence et la sécurité." ], "context": [ "Les benchmarks traditionnels posent des questions à un modèle et notent les réponses. Cela mesure la capacité, mais ne dit pas grand-chose sur l'aptitude d'un système à accomplir un travail réel. L'évaluation agentique place plutôt un agent dans un environnement avec des outils et un objectif, et évalue s'il y parvient réellement.", "Ce changement est crucial car la valeur en production provient de la réalisation des tâches. Un agent qui répond bien mais ne parvient pas à terminer ses tâches n'est pas utile. L'évaluation est également ce qui permet aux équipes d'améliorer les harnesses de manière systématique plutôt qu'anecdotique." ], "architecture": [ "Une évaluation agentique définit des tâches, un environnement (réel ou simulé) avec des outils, un critère de réussite et des métriques. L'agent s'exécute ; sa trajectoire et son résultat sont notés automatiquement dans la mesure du possible, avec une révision humaine pour les cas nuancés.", "Au-delà d'un simple taux de réussite, une évaluation mature suit la fiabilité d'une exécution à l'autre, les budgets de coût et de latence, ainsi que la sécurité (l'agent est-il resté dans les limites de ses autorisations et a-t-il évité des actions nuisibles). Les traces issues de l'observabilité alimentent directement la conception des évaluations." ], "components": [ "Suite de tâches", "Environnement et outils", "Critères de réussite", "Métriques (réussite, coût, latence, sécurité)", "Évaluateurs automatisés", "Révision humaine", "Traces de trajectoire" ], "pros": [ "Mesure ce qui compte vraiment : la réalisation des tâches.", "Détecte les régressions avant qu'elles n'atteignent les utilisateurs.", "Transforme l'amélioration du harness en une boucle mesurable.", "Met en évidence la fiabilité, le coût et la sécurité, et pas seulement la précision." ], "risks": [ "Difficile de concevoir des environnements et des évaluateurs réalistes.", "Surapprentissage (overfitting) par rapport à un benchmark plutôt qu'aux performances réelles.", "Saturation : les benchmarks perdent leur pouvoir discriminant au fil du temps.", "L'évaluation automatisée peut manquer de nuance ; la révision humaine est coûteuse." ], "tools": [ "SWE-bench et autres benchmarks agentiques", "LangSmith / Langfuse", "OpenAI Evals", "Harnesses de tâches personnalisés", "Évaluateurs de type LLM-as-a-judge" ], "examples": [ "Noter un agent de codage selon que son correctif permet de valider une véritable suite de tests.", "Mesurer le taux de résolution de tickets de bout en bout d'un agent de support.", "Suivre la fiabilité d'un agent de workflow sur des exécutions répétées.", "En pratique : évaluer un agent autonome (OpenClaw) sur 57 jours consécutifs à partir de traces de production — 161 sessions avec un taux de réussite de 98,8 % (2 erreurs), et une fiabilité par modèle de 100 % contre 95,7 % sur deux versions de modèle — une base de référence de fiabilité calculée directement à partir des traces opérationnelles plutôt que d'un ensemble de benchmarks prédéfinis." ], "faqs": [ { "q": "Quelle est la différence entre capacité et agentivité ?", "a": "La capacité est ce qu'un modèle sait ou peut faire de manière isolée ; l'agentivité est ce qu'un système complet peut réellement accomplir dans un environnement. L'évaluation agentique mesure cette dernière." }, { "q": "Pourquoi les benchmarks statiques ne suffisent-ils plus ?", "a": "Les meilleurs modèles les saturent, ils cessent donc d'être discriminants. De plus, ils ne testent pas l'utilisation d'outils, les environnements ou les tâches à horizon lointain, qui sont pourtant au cœur des performances réelles des agents." }, { "q": "Qu'est-ce qu'un benchmark agentique ?", "a": "Un test qui évalue la capacité d'un agent à accomplir des tâches multi-étapes utilisant des outils dans un environnement — par exemple, résoudre de réels problèmes logiciels." }, { "q": "Quel est le lien entre les évaluations et le Harness Engineering ?", "a": "Les évaluations sont la boucle de mesure qui rend possible le Harness Engineering : vous modifiez le harness, mesurez l'effet et conservez ce qui améliore manifestement les performances des tâches." } ] }, "de": { "title": "Was ist Agentic AI Evaluation?", "summary": "Agentic AI Evaluation ist die Praxis zu messen, wie gut ein Agent mehrstufige, Tool-nutzende Aufgaben in einer Umgebung bewältigt – nicht nur die Qualität einer einzelnen Antwort. Da Modelle statische Wissens-Benchmarks sättigen, verschiebt sich die Evaluation von der Messung der Fähigkeit (was ein Modell weiß) zur Messung der Handlungsfähigkeit (was ein System tatsächlich erledigen kann). Gute Evals sind die Feedbackschleife, die Harness Engineering erst möglich macht.", "definition": "Agentische Evaluation ist die Messung der End-to-End-Aufgabenleistung eines KI-Agenten – Erfolgsquote, Zuverlässigkeit, Kosten und Sicherheit – bei realistischen, mehrstufigen Aufgaben in einer Umgebung.", "takeaways": [ "Evaluieren Sie die Aufgabenerledigung (Handlungsfähigkeit), nicht nur die Antwortqualität (Fähigkeit).", "Agentische Benchmarks testen Tools, Umgebungen und lange Zeithorizonte.", "Statische Benchmarks sättigen; agentische Benchmarks sind die neue Grenze.", "Evals are the feedback loop for improving the harness.", "Messen Sie Erfolg, Zuverlässigkeit, Kosten, Latenz und Sicherheit zusammen." ], "context": [ "Traditionelle Benchmarks stellen einem Modell Fragen und bewerten die Antworten. Das misst die Fähigkeit, sagt aber wenig darüber aus, ob ein System echte Arbeit erledigen kann. Die agentische Evaluation platziert stattdessen einen Agenten in einer Umgebung mit Tools und einem Ziel und bewertet, ob er dieses tatsächlich erreicht.", "Diese Verschiebung ist wichtig, da der produktive Nutzen aus der Aufgabenerledigung resultiert. Ein Agent, der zwar gut antwortet, aber Aufgaben nicht zu Ende führt, ist nicht nützlich. Die Evaluation ist zudem das, was es Teams ermöglicht, Harnesses systematisch statt nur anekdotisch zu verbessern." ], "architecture": [ "Ein agentischer Eval definiert Aufgaben, eine Umgebung (real oder simuliert) mit Tools, ein Erfolgskriterium und Metriken. Der Agent läuft; seine Trajektorie und das Ergebnis werden, wo möglich, automatisch bewertet, mit menschlicher Überprüfung für nuancierte Fälle.", "Über eine einfache Erfolgsquote hinaus verfolgt eine ausgereifte Evaluation die Zuverlässigkeit über mehrere Durchläufe hinweg, Kosten- und Latenzbudgets sowie die Sicherheit (blieb der Agent innerhalb seiner Autorisierung und hat schädliche Aktionen vermieden). Traces aus der Observability fließen direkt in das Eval-Design ein." ], "components": [ "Aufgabensuite", "Umgebung & Tools", "Erfolgskriterien", "Metriken (Erfolg, Kosten, Latenz, Sicherheit)", "Automatisierte Grader", "Menschliche Überprüfung", "Trajektorien-Traces" ], "pros": [ "Misst, worauf es wirklich ankommt: die Aufgabenerledigung.", "Erkennt Regressionen, bevor sie die Benutzer erreichen.", "Macht die Verbesserung des Harness zu einer messbaren Schleife.", "Zeigt Zuverlässigkeit, Kosten und Sicherheit auf, nicht nur Genauigkeit." ], "risks": [ "Schwierig, realistische Umgebungen und Grader zu erstellen.", "Overfitting auf einen Benchmark statt echter Leistung.", "Sättigung: Benchmarks verlieren im Laufe der Zeit an Unterscheidungskraft.", "Automatisierte Bewertung kann Nuancen übersehen; menschliche Überprüfung ist kostspielig." ], "tools": [ "SWE-bench und andere agentische Benchmarks", "LangSmith / Langfuse", "OpenAI Evals", "Benutzerdefinierte Aufgaben-Harnesses", "LLM-as-a-Judge-Grader" ], "examples": [ "Bewertung eines Coding-Agenten danach, ob sein Patch eine echte Testsuite erfolgreich durchlaufen lässt.", "Messung der End-to-End-Ticketlösungsquote eines Support-Agenten.", "Verfolgung der Zuverlässigkeit eines Workflow-Agenten über wiederholte Durchläufe hinweg.", "In der Praxis: Evaluierung eines autonomen Agenten (OpenClaw) über 57 Tage hinweg direkt aus Produktions-Traces – 161 Sitzungen mit 98,8 % Erfolg (2 Fehler), mit einer modellspezifischen Zuverlässigkeit von 100 % vs. 95,7 % über zwei Modellversionen hinweg – eine Zuverlässigkeits-Baseline, die direkt aus operativen Traces statt aus einem kuratierten Benchmark-Set berechnet wurde." ], "faqs": [ { "q": "Was ist der Unterschied zwischen Fähigkeit (Capability) und Handlungsfähigkeit (Agency)?", "a": "Fähigkeit ist das, was ein Modell isoliert weiß oder tun kann; Handlungsfähigkeit ist das, was ein vollständiges System tatsächlich in einer Umgebung erreichen kann. Die agentische Evaluation misst Letzteres." }, { "q": "Warum reichen statische Benchmarks nicht mehr aus?", "a": "Spitzenmodelle sättigen sie, sodass sie nicht mehr differenzieren. Zudem testen sie weder Tool-Nutzung, Umgebungen noch Aufgaben mit langem Zeithorizont – also genau das, worauf es bei der tatsächlichen Leistung von Agenten ankommt." }, { "q": "Was ist ein agentischer Benchmark?", "a": "Ein Test, der die Fähigkeit eines Agenten bewertet, mehrstufige, Tool-nutzende Aufgaben in einer Umgebung zu lösen – beispielsweise das Beheben echter Softwareprobleme." }, { "q": "Wie hängen Evals mit Harness Engineering zusammen?", "a": "Evals sind die Messschleife, die Harness Engineering erst möglich macht: Sie verändern den Harness, messen den Effekt und behalten das bei, was die Aufgabenleistung nachweislich verbessert." } ] }, "ja": { "title": "アジェンティックAI評価とは何ですか？", "summary": "アジェンティックAI評価とは、単一の回答の品質だけでなく、エージェントが環境内でツールを使用するマルチステップのタスクをどれだけ適切に完了できるかを測定する手法です。モデルが静的な知識ベンチマークで飽和状態に達するにつれ、評価は「能力（モデルが何を知っているか）」の測定から「エージェンシー（システムが実際に何を達成できるか）」の測定へと移行しています。優れた評価（evals）は、ハーネスエンジニアリングを可能にするフィードバックループとなります。", "definition": "アジェンティック評価とは、環境内における現実的でマルチステップのタスクに対する、AIエージェントのエンドツーエンドのタスクパフォーマンス（成功率、信頼性、コスト、安全性）の測定です。", "takeaways": [ "回答の品質（能力）だけでなく、タスクの完了（エージェンシー）を評価する。", "アジェンティックなベンチマークは、ツール、環境、および長期的なタスク（ロングホライズン）をテストする。", "静的なベンチマークは飽和しており、アジェンティックなベンチマークが新たなフロンティアである。", "評価（evals）はハーネスを改善するためのフィードバックループである。", "成功率、信頼性、コスト、レイテンシ、安全性を総合的に測定する。" ], "context": [ "従来のベンチマークは、モデルに質問を投げかけてその回答をスコア化します。これは能力を測定しますが、システムが実際の業務を完了できるかどうかについてはほとんどわかりません。対照的に、アジェンティック評価は、エージェントをツールと目標が存在する環境に配置し、実際にそれを達成できるかどうかをスコア化します。", "この移行が重要である理由は、本番環境における価値がタスクの完了から生まれるためです。優れた回答をしてもタスクを完了できないエージェントは役に立ちません。また、評価を行うことで、チームは経験則（逸話）に頼るのではなく、体系的にハーネスを改善できるようになります。" ], "architecture": [ "アジェンティック評価（eval）では、タスク、ツールを備えた環境（実環境またはシミュレーション環境）、成功基準、およびメトリクスを定義します。エージェントを実行し、その軌跡（トラジェトリ）と結果を可能な限り自動的にスコア化し、微妙なケースについては人間がレビューします。", "単一の成功率にとどまらず、成熟した評価では、複数回実行時の信頼性、コストとレイテンシの予算、安全性（エージェントが権限の範囲内にとどまり、有害なアクションを回避したか）を追跡します。オブザーバビリティから得られるトレースは、評価設計に直接フィードバックされます。" ], "components": [ "タスクスイート", "環境とツール", "成功基準", "メトリクス（成功率、コスト、レイテンシ、安全性）", "自動グレーダー", "人によるレビュー", "軌跡（トラジェトリ）トレース" ], "pros": [ "実際に重要なこと、すなわち「タスクの完了」を測定できる。", "ユーザーに届く前にデグレード（退行）を検知できる。", "ハーネスの改善を測定可能なループに変換できる。", "正確性だけでなく、信頼性、コスト、安全性を可視化できる。" ], "risks": [ "現実的な環境やグレーダーを構築するのが難しい。", "実際のパフォーマンスではなく、ベンチマークに過剰適合（オーバーフィッティング）してしまう。", "飽和：時間の経過とともにベンチマークの識別力が失われる。", "自動グレーディングでは微妙なニュアンスを見落とす可能性があり、人によるレビューはコストがかかる。" ], "tools": [ "SWE-benchおよびその他のアジェンティックなベンチマーク", "LangSmith / Langfuse", "OpenAI Evals", "カスタムタスクハーネス", "LLM-as-a-judge（裁判官としてのLLM）グレーダー" ], "examples": [ "コーディングエージェントが作成したパッチによって、実際のテストスイートがパスするかどうかに基づいてスコア化する。", "サポートエージェントのエンドツーエンドのチケット解決率を測定する。", "繰り返し実行におけるワークフローエージェントの信頼性を追跡する。", "実践例：本番環境のトレースから、自律型エージェント（OpenClaw）を57日間連続で評価。161セッションで成功率98.8%（エラー2件）、2つのモデルバージョン間でモデルごとの信頼性が100%対95.7%を記録。これは、厳選されたベンチマークセットではなく、運用トレースから直接計算された信頼性の基準値（ベースライン）です。" ], "faqs": [ { "q": "能力（capability）とエージェンシー（agency）の違いは何ですか？", "a": "能力とは、モデルが単体で知っていることや実行できることです。エージェンシーとは、システム全体が環境内で実際に達成できることです。アジェンティック評価は後者を測定します。" }, { "q": "なぜ静的なベンチマークだけでは不十分になったのですか？", "a": "最先端のモデルがそれらを飽和させてしまい、識別力が失われるためです。また、静的なベンチマークでは、ツールの使用、環境、長期的なタスク（ロングホライズン）がテストされませんが、これらこそが実際のエージェントのパフォーマンスが発揮される領域です。" }, { "q": "アジェンティックなベンチマークとは何ですか？", "a": "環境内でツールを使用するマルチステップのタスク（例：実際のソフトウェアの問題の解決など）を完了するエージェントの能力をスコア化するテストです。" }, { "q": "評価（evals）はハーネスエンジニアリングとどのように関係していますか？", "a": "評価は、ハーネスエンジニアリングを可能にする測定ループです。ハーネスを変更し、その効果を測定し、タスクパフォーマンスを明らかに向上させるものを維持します。" } ] }, "zh": { "title": "什么是智能体AI评估？", "summary": "智能体AI评估是指在特定环境中衡量智能体完成多步骤、使用工具的任务的能力，而不仅仅是评估单个回答的质量。随着模型在静态知识基准测试上趋于饱和，评估正在从衡量能力（模型知道什么）转向衡量能动性（系统实际能完成什么）。优秀的评估是实现支撑系统工程的反馈闭环。", "definition": "智能体评估是指在特定环境中，对AI智能体在真实的、多步骤任务上的端到端任务表现（成功率、可靠性、成本和安全性）进行衡量。", "takeaways": [ "评估任务完成度（能动性），而不仅仅是回答质量（能力）。", "智能体基准测试旨在测试工具、环境和长时程任务。", "静态基准测试已趋于饱和；智能体基准测试是新的前沿。", "评估是改进支撑系统的反馈闭环。", "综合衡量成功率、可靠性、成本、延迟和安全性。" ], "context": [ "传统的基准测试向模型提问并对回答进行评分。这衡量了模型的能力，但几乎无法告诉你系统是否能完成实际工作。相比之下，智能体评估将智能体置于带有工具和目标的特定环境中，并对其是否真正实现目标进行评分。", "这种转变至关重要，因为生产价值源自任务的完成。一个回答得很好但无法完成任务的智能体是没有实用价值的。评估也是让团队能够系统性地（而非凭感觉地）改进支撑系统的关键。" ], "architecture": [ "智能体评估定义了任务、带有工具的环境（真实或模拟）、成功标准和指标。智能体运行后，系统会尽可能自动对其轨迹和结果进行评分，并在复杂微妙的情况下引入人工审核。", "除了单一的成功率之外，成熟的评估还会追踪多次运行的可靠性、成本和延迟预算，以及安全性（智能体是否保持在授权范围内并避免了有害行为）。来自可观测性的追踪数据（Traces）会直接反馈到评估设计中。" ], "components": [ "任务套件", "环境与工具", "成功标准", "指标（成功率、成本、延迟、安全性）", "自动评分器", "人工审核", "轨迹追踪" ], "pros": [ "衡量真正重要的指标：任务完成度。", "在影响用户之前捕获性能回退。", "将支撑系统的改进转化为可衡量的闭环。", "展现可靠性、成本和安全性，而不仅仅是准确率。" ], "risks": [ "难以构建真实的测试环境和评分器。", "过度拟合基准测试，而非关注实际表现。", "饱和：随着时间的推移，基准测试会失去区分度。", "自动评分可能会遗漏细微差别；而人工审核成本高昂。" ], "tools": [ "SWE-bench 及其他智能体基准测试", "LangSmith / Langfuse", "OpenAI Evals", "自定义任务支撑系统", "LLM-as-judge（大模型作为裁判）评分器" ], "examples": [ "对编码智能体进行评分，看其补丁是否能通过真实的测试套件。", "衡量客服智能体的端到端工单解决率。", "追踪工作流智能体在多次重复运行中的可靠性。", "实践案例：直接通过生产追踪数据，连续 57 天对自主智能体（OpenClaw）进行评估——在 161 个会话中实现了 98.8% 的成功率（2 次错误），两个模型版本的单模型可靠性分别为 100% 和 95.7%——这是一个直接从运行追踪数据中计算出的可靠性基线，而非来自人工整理的基准测试集。" ], "faqs": [ { "q": "能力（Capability）与能动性（Agency）有什么区别？", "a": "能力是模型单独知道什么或能做什么；能动性则是整个系统在特定环境中实际能完成什么。智能体评估衡量的正是后者。" }, { "q": "为什么静态基准测试不再足够？", "a": "顶尖模型在这些测试上已趋于饱和，导致其失去区分度。此外，它们无法测试工具使用、环境交互或长时程任务，而这些正是衡量真实智能体性能的关键所在。" }, { "q": "什么是智能体基准测试？", "a": "一种旨在评估智能体在特定环境中完成多步骤、使用工具的任务（例如解决真实的软件问题）能力的测试。" }, { "q": "评估与支撑系统工程有何关系？", "a": "评估是让支撑系统工程成为可能的衡量闭环：你修改支撑系统，衡量其效果，并保留那些能明显提升任务性能的改进。" } ] } } }, { "slug": "agentic-threat-model", "category": "governance", "updated": "2026-08-22", "version": "1.0", "url": "https://santismm.com/en/knowledge/agentic-threat-model", "api": "https://santismm.com/api/knowledge/agentic-threat-model", "canonical_url": "https://santismm.com/en/knowledge/agentic-threat-model", "api_url": "https://santismm.com/api/knowledge/agentic-threat-model", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper", "personal_experience" ] }, "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "OWASP — LLM01: Prompt Injection", "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/" }, { "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems", "url": "https://atlas.mitre.org/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "ai-cyberdefense", "prompt-injection", "guardrails", "tool-use", "agent-memory", "human-in-the-loop", "ai-governance" ], "locales": { "en": { "title": "What is an Agentic Threat Model?", "summary": "An agentic threat model is the map of how an autonomous agent can be attacked: not through its weights, but through everything it reads, remembers, calls and is allowed to do. It names the surfaces — direct and indirect prompt injection, tool poisoning, excessive agency, memory poisoning, supply chain, exfiltration channels, the confused deputy — so each one gets a control in the harness instead of a hope in the system prompt.", "definition": "An agentic threat model is a structured enumeration of the attack surfaces, adversary goals and abuse paths specific to an AI agent — its inputs, context, memory, tools, credentials and autonomy — used to decide which harness controls are required before the agent is given production access.", "takeaways": [ "Threat-model the agent's actions, not the model's outputs.", "Every input the agent reads is an instruction channel: documents, pages, tool results, other agents.", "Every tool the agent can call is a capability an attacker inherits the moment an injection succeeds.", "Memory turns a one-shot attack into a persistent one.", "Blast radius is set by credentials and egress, not by the prompt.", "An unnamed surface is not an absent one — write down accepted risks explicitly." ], "context": [ "Classic threat modelling asks what an attacker can send to your system. With agents the harder question is what your system will read on its own initiative and treat as instructions. An agent that fetches a page, opens a ticket or reads a tool result has enlarged its trust boundary without anyone deciding to.", "The second shift is agency. A chatbot that is fooled produces a wrong sentence; an agent that is fooled makes a call, moves money, deletes a branch or emails a file. The severity of a successful attack is set by the tools and credentials attached to the agent, which is why permissioning is a security decision rather than a convenience one.", "Frameworks anchor the exercise: the OWASP Top 10 for LLM Applications names the vulnerability classes and MITRE ATLAS catalogues adversary tactics observed against AI systems. Use them as checklists over your own architecture, not as substitutes for having one." ], "architecture": [ "Direct prompt injection — the person talking to the agent tries to override its instructions. Cheapest to attempt and easiest to bound, because that user is already inside whatever permission the session grants.", "Indirect prompt injection — instructions hidden in content the agent retrieves: a web page, a PDF, a ticket comment, an email, a source file, another agent's output. The attacker never talks to your agent; they plant text where it will read.", "Tool poisoning — a tool whose description or result is itself adversarial. A server can describe a benign tool at approval time and change it afterwards, so trust is checked once and exercised forever.", "Excessive agency — the agent holds permissions broader than any single task requires. Nothing has gone wrong yet; the surface is that a hijacked agent instantly inherits everything the harness was willing to grant.", "Memory poisoning — false facts or instructions written into persistent memory or a vector store, so the attack survives the session and re-triggers on future, unrelated tasks.", "Supply chain — models, system prompts, MCP servers, packages and datasets pulled from outside the organisation. A dependency that can rewrite a tool description is a dependency that can rewrite the agent's behaviour.", "Exfiltration channels — any path by which bytes can leave: an outbound fetch, an image URL rendered in a reply, an email or webhook tool, a commit. Data does not need to be read by a human to be stolen; a URL is enough.", "Confused deputy — the agent acts with credentials the requester does not have, so an attacker who cannot reach a system directly asks the agent to reach it on their behalf." ], "components": [ "Asset inventory: the data, systems and credentials the agent can touch, listed by the agent's reach rather than by the team's org chart.", "Trust boundaries: which inputs are instructions, which are data, and where that line is enforced in code rather than in prose.", "Tool catalogue with permissions: every tool, its scope, whether it writes, and what an attacker gains by calling it.", "Egress map: every way bytes can leave, including the accidental ones — link previews, rendered images, log shipping, error reporting.", "Adversary goals: exfiltrate, escalate, persist, disrupt, deceive — each mapped onto the surfaces above.", "Controls with owners: which harness component bounds each path, and who maintains it.", "Accepted risks: paths deliberately left open, with the reason and the compensating detection.", "Test cases: for each surface, the injection or abuse attempt that proves the control works. A control never seen failing is a control never verified." ], "pros": [ "It converts 'is our agent safe?' into a finite list of surfaces that each have an owner and a control.", "It makes permission decisions explicit and reviewable before production access is granted.", "It gives red teams a target list and gives evaluation suites concrete cases to automate.", "It ages well: models change often, surfaces change slowly, so the map survives the next model swap." ], "risks": [ "Modelling the chatbot and not the agent — enumerating output harms while ignoring the tools that turn them into actions.", "Treating the model as the control point. Alignment reduces attempts; it does not bound consequences.", "A document written once and never revisited. Every new tool is a new surface, so the model belongs in the change process.", "Confusing coverage with defence: naming a surface is not controlling it, and an untested control is a claim." ], "tools": [ "OWASP Top 10 for LLM Applications — shared vocabulary for the vulnerability classes.", "MITRE ATLAS — adversary tactics and techniques observed against AI systems.", "NIST AI RMF — the governance frame the map plugs into (Govern, Map, Measure, Manage).", "Agent traces and audit logs — the evidence layer; without them the model is unfalsifiable.", "Automated red-team suites — injection corpora run in CI so regressions surface before release.", "Policy and permission engines — where the conclusions of the model are actually enforced." ], "examples": [ "A support agent that reads customer email: the message body is untrusted instruction input, the CRM tool is the capability, and the reply channel is the exfiltration path. Three surfaces from one feature.", "A coding agent with repository write access and network egress: injection through a dependency's README, capability through the commit tool, exfiltration through any registry it can reach.", "A retrieval agent over an internal wiki: anyone who can edit a page can write instructions the agent will read, which makes a low-privilege internal editor an injection vector." ], "faqs": [ { "q": "How is this different from a normal threat model?", "a": "The method is the same; the surfaces are new. Classic models assume code executes instructions and data does not. With an agent, data is instructions — so retrieval, memory and tool results all become input channels an attacker can reach." }, { "q": "Do I need one if my agent is read-only?", "a": "Yes, a smaller one. A read-only agent still has an exfiltration surface — anything it can read it can be made to repeat — and 'read-only' is a property that has to be enforced at the tool layer, not assumed from the prompt." }, { "q": "Where do I start if I have nothing written?", "a": "List the tools the agent can call and the data each one reaches. That single table produces most of the map: capabilities are the blast radius, and the inputs that can reach them are the attack paths." }, { "q": "How often should it be revisited?", "a": "Whenever a tool, a data source or an autonomy level changes — those are the events that create surfaces. Model upgrades matter less than people expect; they change likelihood, not reach." } ] }, "es": { "title": "¿Qué es un Modelo de Amenazas Agéntico?", "summary": "Un modelo de amenazas agéntico es el mapa de cómo se puede atacar a un agente autónomo: no a través de sus pesos, sino de todo lo que lee, recuerda, invoca y tiene permitido hacer. Nombra las superficies —inyección de prompts directa e indirecta, envenenamiento de herramientas, exceso de agencia, envenenamiento de memoria, cadena de suministro, canales de exfiltración, diputado confundido— para que cada una tenga un control en el arnés en lugar de una esperanza en el system prompt.", "definition": "Un modelo de amenazas agéntico es la enumeración estructurada de las superficies de ataque, objetivos del adversario y rutas de abuso propias de un agente de IA —sus entradas, su contexto, su memoria, sus herramientas, sus credenciales y su autonomía— que sirve para decidir qué controles del arnés son obligatorios antes de dar al agente acceso a producción.", "takeaways": [ "Modela las amenazas sobre las acciones del agente, no sobre las salidas del modelo.", "Cada entrada que el agente lee es un canal de instrucciones: documentos, páginas, resultados de herramientas, otros agentes.", "Cada herramienta que el agente puede invocar es una capacidad que el atacante hereda en cuanto una inyección tiene éxito.", "La memoria convierte un ataque puntual en un ataque persistente.", "El radio de impacto lo fijan las credenciales y la salida de datos, no el prompt.", "Una superficie sin nombrar no es una superficie ausente: escribe los riesgos aceptados de forma explícita." ], "context": [ "El modelado de amenazas clásico pregunta qué puede enviarte un atacante. Con agentes la pregunta difícil es qué va a leer tu sistema por iniciativa propia y tratar como instrucciones. Un agente que descarga una página, abre un ticket o lee el resultado de una herramienta ha ampliado su frontera de confianza sin que nadie lo decidiera.", "El segundo cambio es la agencia. Un chatbot engañado produce una frase incorrecta; un agente engañado hace una llamada, mueve dinero, borra una rama o envía un fichero por correo. La gravedad de un ataque con éxito la fijan las herramientas y credenciales del agente: por eso los permisos son una decisión de seguridad y no de comodidad.", "Hay marcos que anclan el ejercicio: el OWASP Top 10 para aplicaciones LLM nombra las clases de vulnerabilidad y MITRE ATLAS cataloga tácticas de adversario observadas contra sistemas de IA. Úsalos como listas de comprobación sobre tu arquitectura, no como sustituto de tenerla." ], "architecture": [ "Inyección directa de prompts: la persona que habla con el agente intenta anular sus instrucciones. Es lo más barato de intentar y lo más fácil de acotar, porque ese usuario ya está dentro de los permisos que le da la sesión.", "Inyección indirecta de prompts: instrucciones escondidas en contenido que el agente recupera —una página web, un PDF, el comentario de un ticket, un correo, un fichero de código, la salida de otro agente—. El atacante nunca habla con tu agente; planta el texto donde lo va a leer.", "Envenenamiento de herramientas: una herramienta cuya descripción o resultado es en sí mismo adversarial. Un servidor puede describir una herramienta inocua en el momento de la aprobación y cambiarla después: la confianza se comprueba una vez y se ejerce para siempre.", "Exceso de agencia: el agente tiene permisos más amplios de los que requiere cualquier tarea concreta. Todavía no ha pasado nada; la superficie es que un agente secuestrado hereda al instante todo lo que el arnés estuvo dispuesto a conceder.", "Envenenamiento de memoria: hechos o instrucciones falsas escritas en memoria persistente o en un almacén vectorial, de modo que el ataque sobrevive a la sesión y se vuelve a disparar en tareas futuras sin relación.", "Cadena de suministro: modelos, system prompts, servidores MCP, paquetes y datasets traídos de fuera de la organización. Una dependencia que puede reescribir la descripción de una herramienta es una dependencia que puede reescribir el comportamiento del agente.", "Canales de exfiltración: cualquier vía por la que pueden salir bytes —una descarga saliente, la URL de una imagen renderizada en la respuesta, una herramienta de correo o webhook, un commit—. Los datos no necesitan que un humano los lea para estar robados; basta una URL.", "Diputado confundido: el agente actúa con credenciales que quien lo invoca no tiene, así que un atacante que no puede llegar a un sistema directamente le pide al agente que llegue por él." ], "components": [ "Inventario de activos: los datos, sistemas y credenciales que el agente puede tocar, listados por el alcance del agente y no por el organigrama del equipo.", "Fronteras de confianza: qué entradas son instrucciones, cuáles son datos y dónde se aplica esa línea en el código y no en la prosa.", "Catálogo de herramientas con permisos: cada herramienta, su alcance, si escribe y qué gana un atacante al invocarla.", "Mapa de salida de datos: todas las formas en que pueden salir bytes, incluidas las accidentales —previsualizaciones de enlaces, imágenes renderizadas, envío de logs, reporte de errores—.", "Objetivos del adversario: exfiltrar, escalar, persistir, interrumpir, engañar; cada uno mapeado sobre las superficies anteriores.", "Controles con responsable: qué componente del arnés acota cada ruta y quién lo mantiene.", "Riesgos aceptados: rutas que se dejan abiertas a propósito, con el motivo y la detección compensatoria.", "Casos de prueba: para cada superficie, el intento de inyección o abuso que demuestra que el control funciona. Un control que nunca se ha visto fallar es un control que nunca se ha verificado." ], "pros": [ "Convierte «¿es seguro nuestro agente?» en una lista finita de superficies, cada una con responsable y control.", "Hace explícitas y revisables las decisiones de permisos antes de conceder acceso a producción.", "Da al equipo de red team una lista de objetivos y a las suites de evaluación casos concretos que automatizar.", "Envejece bien: los modelos cambian a menudo, las superficies cambian despacio, así que el mapa sobrevive al siguiente cambio de modelo." ], "risks": [ "Modelar el chatbot y no el agente: enumerar daños de salida ignorando las herramientas que los convierten en acciones.", "Tratar el modelo como punto de control. El alineamiento reduce los intentos; no acota las consecuencias.", "Un documento escrito una vez y nunca revisado. Cada herramienta nueva es una superficie nueva, así que el modelo forma parte del proceso de cambio.", "Confundir cobertura con defensa: nombrar una superficie no es controlarla, y un control sin probar es una afirmación." ], "tools": [ "OWASP Top 10 para aplicaciones LLM: vocabulario común para las clases de vulnerabilidad.", "MITRE ATLAS: tácticas y técnicas de adversario observadas contra sistemas de IA.", "NIST AI RMF: el marco de gobierno en el que encaja el mapa (Govern, Map, Measure, Manage).", "Trazas de agente y logs de auditoría: la capa de evidencia; sin ellos el modelo es infalsable.", "Suites de red team automatizadas: corpus de inyección ejecutados en CI para que las regresiones aparezcan antes del despliegue.", "Motores de política y de permisos: donde realmente se aplican las conclusiones del modelo." ], "examples": [ "Un agente de soporte que lee correo de clientes: el cuerpo del mensaje es entrada de instrucciones no confiable, la herramienta de CRM es la capacidad y el canal de respuesta es la vía de exfiltración. Tres superficies de una sola funcionalidad.", "Un agente de programación con escritura en el repositorio y salida a red: inyección por el README de una dependencia, capacidad por la herramienta de commit, exfiltración por cualquier registro al que pueda llegar.", "Un agente de recuperación sobre una wiki interna: cualquiera que pueda editar una página puede escribir instrucciones que el agente leerá, lo que convierte a un editor interno de bajo privilegio en vector de inyección." ], "faqs": [ { "q": "¿En qué se diferencia de un modelo de amenazas normal?", "a": "El método es el mismo; las superficies son nuevas. Los modelos clásicos asumen que el código ejecuta instrucciones y los datos no. Con un agente, los datos son instrucciones: la recuperación, la memoria y los resultados de herramientas se convierten en canales de entrada al alcance del atacante." }, { "q": "¿Necesito uno si mi agente es de solo lectura?", "a": "Sí, uno más pequeño. Un agente de solo lectura sigue teniendo superficie de exfiltración —todo lo que puede leer se le puede hacer repetir— y «solo lectura» es una propiedad que hay que aplicar en la capa de herramientas, no suponer desde el prompt." }, { "q": "¿Por dónde empiezo si no tengo nada escrito?", "a": "Lista las herramientas que el agente puede invocar y los datos a los que llega cada una. Esa única tabla produce casi todo el mapa: las capacidades son el radio de impacto y las entradas que pueden alcanzarlas son las rutas de ataque." }, { "q": "¿Cada cuánto hay que revisarlo?", "a": "Siempre que cambie una herramienta, una fuente de datos o un nivel de autonomía: esos son los eventos que crean superficies. Las actualizaciones de modelo importan menos de lo que se cree; cambian la probabilidad, no el alcance." } ] }, "pt": { "title": "O que é um Modelo de Ameaças Agêntico?", "summary": "Um modelo de ameaças agêntico é o mapa de como um agente autônomo pode ser atacado: não pelos seus pesos, mas por tudo o que ele lê, memoriza, invoca e tem permissão para fazer. Ele nomeia as superfícies — injeção de prompts direta e indireta, envenenamento de ferramentas, excesso de agência, envenenamento de memória, cadeia de suprimentos, canais de exfiltração, deputado confuso — para que cada uma tenha um controle no harness em vez de uma esperança no system prompt.", "definition": "Um modelo de ameaças agêntico é a enumeração estruturada das superfícies de ataque, objetivos do adversário e caminhos de abuso próprios de um agente de IA — suas entradas, seu contexto, sua memória, suas ferramentas, suas credenciais e sua autonomia — usada para decidir quais controles do harness são obrigatórios antes de dar ao agente acesso à produção.", "takeaways": [ "Modele as ameaças sobre as ações do agente, não sobre as saídas do modelo.", "Toda entrada que o agente lê é um canal de instruções: documentos, páginas, resultados de ferramentas, outros agentes.", "Toda ferramenta que o agente pode invocar é uma capacidade que o atacante herda assim que uma injeção tem êxito.", "A memória transforma um ataque pontual em um ataque persistente.", "O raio de impacto é definido pelas credenciais e pela saída de dados, não pelo prompt.", "Uma superfície não nomeada não é uma superfície ausente: escreva os riscos aceitos de forma explícita." ], "context": [ "A modelagem de ameaças clássica pergunta o que um atacante pode enviar ao seu sistema. Com agentes, a pergunta difícil é o que o seu sistema vai ler por iniciativa própria e tratar como instruções. Um agente que baixa uma página, abre um chamado ou lê o resultado de uma ferramenta ampliou sua fronteira de confiança sem que ninguém decidisse isso.", "A segunda mudança é a agência. Um chatbot enganado produz uma frase errada; um agente enganado faz uma chamada, movimenta dinheiro, apaga um branch ou envia um arquivo por e-mail. A gravidade de um ataque bem-sucedido é definida pelas ferramentas e credenciais do agente — por isso permissionamento é uma decisão de segurança, não de conveniência.", "Existem frameworks que ancoram o exercício: o OWASP Top 10 para aplicações LLM nomeia as classes de vulnerabilidade e o MITRE ATLAS cataloga táticas de adversário observadas contra sistemas de IA. Use-os como listas de verificação sobre a sua arquitetura, não como substituto de tê-la." ], "architecture": [ "Injeção direta de prompts: a pessoa que fala com o agente tenta anular suas instruções. É o mais barato de tentar e o mais fácil de limitar, porque esse usuário já está dentro das permissões que a sessão concede.", "Injeção indireta de prompts: instruções escondidas em conteúdo que o agente recupera — uma página web, um PDF, o comentário de um chamado, um e-mail, um arquivo de código, a saída de outro agente. O atacante nunca fala com o seu agente; ele planta o texto onde o agente vai ler.", "Envenenamento de ferramentas: uma ferramenta cuja descrição ou resultado é em si adversarial. Um servidor pode descrever uma ferramenta inofensiva no momento da aprovação e alterá-la depois: a confiança é verificada uma vez e exercida para sempre.", "Excesso de agência: o agente detém permissões mais amplas do que qualquer tarefa concreta exige. Ainda não aconteceu nada; a superfície é que um agente sequestrado herda instantaneamente tudo o que o harness se dispôs a conceder.", "Envenenamento de memória: fatos ou instruções falsas gravadas em memória persistente ou em um banco vetorial, de modo que o ataque sobrevive à sessão e volta a disparar em tarefas futuras e não relacionadas.", "Cadeia de suprimentos: modelos, system prompts, servidores MCP, pacotes e datasets trazidos de fora da organização. Uma dependência que pode reescrever a descrição de uma ferramenta é uma dependência que pode reescrever o comportamento do agente.", "Canais de exfiltração: qualquer caminho pelo qual bytes possam sair — uma requisição de saída, a URL de uma imagem renderizada na resposta, uma ferramenta de e-mail ou webhook, um commit. Os dados não precisam ser lidos por um humano para estarem roubados; basta uma URL.", "Deputado confuso: o agente age com credenciais que quem o invoca não tem, então um atacante que não consegue alcançar um sistema diretamente pede ao agente que o alcance por ele." ], "components": [ "Inventário de ativos: os dados, sistemas e credenciais que o agente pode tocar, listados pelo alcance do agente e não pelo organograma do time.", "Fronteiras de confiança: quais entradas são instruções, quais são dados e onde essa linha é aplicada no código e não na prosa.", "Catálogo de ferramentas com permissões: cada ferramenta, seu escopo, se escreve e o que um atacante ganha ao invocá-la.", "Mapa de saída de dados: todas as formas pelas quais bytes podem sair, inclusive as acidentais — pré-visualizações de links, imagens renderizadas, envio de logs, relatórios de erro.", "Objetivos do adversário: exfiltrar, escalar, persistir, interromper, enganar; cada um mapeado sobre as superfícies acima.", "Controles com responsável: qual componente do harness limita cada caminho e quem o mantém.", "Riscos aceitos: caminhos deixados abertos de propósito, com o motivo e a detecção compensatória.", "Casos de teste: para cada superfície, a tentativa de injeção ou abuso que prova que o controle funciona. Um controle que nunca foi visto falhando é um controle que nunca foi verificado." ], "pros": [ "Converte “o nosso agente é seguro?” em uma lista finita de superfícies, cada uma com responsável e controle.", "Torna as decisões de permissão explícitas e revisáveis antes de conceder acesso à produção.", "Dá ao red team uma lista de alvos e às suítes de avaliação casos concretos para automatizar.", "Envelhece bem: modelos mudam com frequência, superfícies mudam devagar, então o mapa sobrevive à próxima troca de modelo." ], "risks": [ "Modelar o chatbot e não o agente: enumerar danos de saída ignorando as ferramentas que os transformam em ações.", "Tratar o modelo como ponto de controle. O alinhamento reduz as tentativas; não limita as consequências.", "Um documento escrito uma vez e nunca revisitado. Cada ferramenta nova é uma superfície nova, então o modelo faz parte do processo de mudança.", "Confundir cobertura com defesa: nomear uma superfície não é controlá-la, e um controle não testado é uma afirmação." ], "tools": [ "OWASP Top 10 para aplicações LLM: vocabulário comum para as classes de vulnerabilidade.", "MITRE ATLAS: táticas e técnicas de adversário observadas contra sistemas de IA.", "NIST AI RMF: o marco de governança em que o mapa se encaixa (Govern, Map, Measure, Manage).", "Traces de agente e logs de auditoria: a camada de evidência; sem eles o modelo é infalsificável.", "Suítes de red team automatizadas: corpora de injeção executados em CI para que regressões apareçam antes do lançamento.", "Motores de política e de permissão: onde as conclusões do modelo são de fato aplicadas." ], "examples": [ "Um agente de suporte que lê e-mails de clientes: o corpo da mensagem é entrada de instruções não confiável, a ferramenta de CRM é a capacidade e o canal de resposta é a via de exfiltração. Três superfícies em uma única funcionalidade.", "Um agente de programação com escrita no repositório e saída de rede: injeção pelo README de uma dependência, capacidade pela ferramenta de commit, exfiltração por qualquer registro que ele consiga alcançar.", "Um agente de recuperação sobre uma wiki interna: qualquer pessoa que possa editar uma página pode escrever instruções que o agente vai ler, o que transforma um editor interno de baixo privilégio em vetor de injeção." ], "faqs": [ { "q": "Em que isso difere de um modelo de ameaças normal?", "a": "O método é o mesmo; as superfícies são novas. Os modelos clássicos assumem que o código executa instruções e os dados não. Com um agente, os dados são instruções: recuperação, memória e resultados de ferramentas viram canais de entrada ao alcance do atacante." }, { "q": "Preciso de um se o meu agente é somente leitura?", "a": "Sim, um menor. Um agente somente leitura ainda tem superfície de exfiltração — tudo o que ele pode ler pode ser levado a repetir — e “somente leitura” é uma propriedade que precisa ser aplicada na camada de ferramentas, não presumida a partir do prompt." }, { "q": "Por onde começo se não tenho nada escrito?", "a": "Liste as ferramentas que o agente pode invocar e os dados que cada uma alcança. Essa única tabela produz quase todo o mapa: as capacidades são o raio de impacto e as entradas que conseguem alcançá-las são os caminhos de ataque." }, { "q": "Com que frequência deve ser revisitado?", "a": "Sempre que uma ferramenta, uma fonte de dados ou um nível de autonomia mudar — esses são os eventos que criam superfícies. Atualizações de modelo importam menos do que se imagina; mudam a probabilidade, não o alcance." } ] }, "fr": { "title": "Qu'est-ce qu'un modèle de menace agentique ?", "summary": "Un modèle de menace agentique cartographie la manière dont un agent autonome peut être attaqué : non pas à travers ses poids, mais à travers tout ce qu'il lit, mémorise, appelle et est autorisé à faire. Il identifie les surfaces d'attaque — injection de prompt directe et indirecte, empoisonnement d'outils, agentivité excessive, empoisonnement de la mémoire, chaîne d'approvisionnement, canaux d'exfiltration, le problème du député confus — afin que chacune bénéficie d'un contrôle dans le harness plutôt que d'un simple espoir dans le prompt système.", "definition": "Un modèle de menace agentique est une énumération structurée des surfaces d'attaque, des objectifs de l'adversaire et des voies d'abus spécifiques à un agent IA — ses entrées, son contexte, sa mémoire, ses outils, ses identifiants et son autonomie — utilisée pour décider quels contrôles de harness sont requis avant de donner à l'agent un accès à la production.", "takeaways": [ "Modélisez les menaces pesant sur les actions de l'agent, et non sur les sorties du modèle.", "Chaque entrée lue par l'agent est un canal d'instructions : documents, pages, résultats d'outils, autres agents.", "Chaque outil que l'agent peut appeler est une capacité dont l'attaquant hérite dès qu'une injection réussit.", "La mémoire transforme une attaque ponctuelle en une attaque persistante.", "Le rayon d'impact est défini par les identifiants et les flux sortants, non par le prompt.", "Une surface d'attaque non identifiée n'est pas une surface absente — consignez explicitement par écrit les risques acceptés." ], "context": [ "La modélisation classique des menaces s'intéresse à ce qu'un attaquant peut envoyer à votre système. Avec les agents, la question la plus difficile est de savoir ce que votre système va lire de sa propre initiative et traiter comme des instructions. Un agent qui récupère une page, ouvre un ticket ou lit le résultat d'un outil a élargi sa frontière de confiance sans que personne ne l'ait explicitement décidé.", "Le second changement réside dans l'agentivité. Un chatbot trompé produit une phrase erronée ; un agent trompé effectue un appel, transfère de l'argent, supprime une branche ou envoie un fichier par e-mail. La gravité d'une attaque réussie est déterminée par les outils et les identifiants associés à l'agent, c'est pourquoi la gestion des permissions est une décision de sécurité et non de commodité.", "Des frameworks structurent cet exercice : l'OWASP Top 10 pour les applications LLM répertorie les classes de vulnérabilités et MITRE ATLAS catalogue les tactiques adverses observées contre les systèmes d'IA. Utilisez-les comme des listes de contrôle pour votre propre architecture, et non comme des substituts à celle-ci." ], "architecture": [ "Injection de prompt directe — la personne qui interagit avec l'agent tente de contourner ses instructions. C'est la tentative la moins coûteuse et la plus facile à limiter, car cet utilisateur se trouve déjà dans les limites des permissions accordées par la session.", "Injection de prompt indirecte — instructions dissimulées dans le contenu récupéré par l'agent : une page web, un PDF, un commentaire de ticket, un e-mail, un fichier source, la sortie d'un autre agent. L'attaquant n'interagit jamais directement avec votre agent ; il place du texte là où l'agent va le lire.", "Empoisonnement d'outil — un outil dont la description ou le résultat est lui-même malveillant. Un serveur peut décrire un outil inoffensif au moment de l'approbation et le modifier par la suite, de sorte que la confiance est vérifiée une seule fois mais exploitée indéfiniment.", "Agentivité excessive — l'agent détient des permissions plus larges que ce que requiert une tâche unique. Rien n'a encore mal tourné ; la surface d'attaque réside dans le fait qu'un agent détourné hérite instantanément de tout ce que le harness était prêt à lui accorder.", "Empoisonnement de la mémoire — de faux faits ou instructions sont écrits dans la mémoire persistante ou une base de données vectorielle, de sorte que l'attaque survit à la session et se déclenche à nouveau lors de tâches futures et non liées.", "Chaîne d'approvisionnement — modèles, prompts système, serveurs MCP, packages et jeux de données importés de l'extérieur de l'organisation. Une dépendance capable de réécrire la description d'un outil est une dépendance capable de réécrire le comportement de l'agent.", "Canaux d'exfiltration — toute voie par laquelle des octets peuvent sortir : une requête fetch sortante, une URL d'image affichée dans une réponse, un outil d'e-mail ou de webhook, un commit. Les données n'ont pas besoin d'être lues par un humain pour être volées ; une URL suffit.", "Député confus — l'agent agit avec des identifiants que le demandeur ne possède pas, de sorte qu'un attaquant ne pouvant pas accéder directement à un système demande à l'agent d'y accéder pour son compte." ], "components": [ "Inventaire des actifs : les données, systèmes et identifiants auxquels l'agent peut accéder, répertoriés selon la portée de l'agent plutôt que selon l'organigramme de l'équipe.", "Limites de confiance : quelles entrées sont des instructions, lesquelles sont des données, et où cette frontière est appliquée dans le code plutôt que dans du texte brut.", "Catalogue d'outils avec permissions : chaque outil, sa portée, s'il effectue des écritures, et ce qu'un attaquant gagne en l'appelant.", "Carte des sorties : toutes les manières dont des octets peuvent s'échapper, y compris accidentelles — aperçus de liens, images affichées, transfert de journaux, rapports d'erreurs.", "Objectifs de l'adversaire : exfiltrer, élever les privilèges, persister, perturber, tromper — chacun étant mis en correspondance avec les surfaces ci-dessus.", "Contrôles avec responsables : quel composant du harness limite chaque chemin, et qui en assure la maintenance.", "Risques acceptés : chemins délibérément laissés ouverts, avec la justification et la détection compensatoire associée.", "Cas de test : pour chaque surface, la tentative d'injection ou d'abus qui prouve l'efficacité du contrôle. Un contrôle que l'on n'a jamais vu échouer est un contrôle qui n'a jamais été vérifié." ], "pros": [ "Il transforme la question « notre agent est-il sûr ? » en une liste finie de surfaces disposant chacune d'un responsable et d'un contrôle.", "Il rend les décisions relatives aux permissions explicites et vérifiables avant que l'accès à la production ne soit accordé.", "Il fournit aux red teams une liste de cibles et offre aux suites d'évaluation des cas concrets à automatiser.", "Il vieillit bien : les modèles changent souvent, les surfaces évoluent lentement, de sorte que la cartographie survit au prochain changement de modèle." ], "risks": [ "Modéliser le chatbot et non l'agent — énumérer les préjudices liés aux sorties tout en ignorant les outils qui les transforment en actions.", "Traiter le modèle comme le point de contrôle. L'alignement réduit les tentatives ; il ne limite pas les conséquences.", "Un document rédigé une fois et jamais révisé. Chaque nouvel outil constitue une nouvelle surface, le modèle doit donc être intégré au processus de gestion du changement.", "Confondre couverture et défense : nommer une surface ne signifie pas la contrôler, et un contrôle non testé n'est qu'une simple affirmation." ], "tools": [ "OWASP Top 10 for LLM Applications — vocabulaire partagé pour les classes de vulnérabilités.", "MITRE ATLAS — tactiques et techniques des adversaires observées contre les systèmes d'IA.", "NIST AI RMF — le cadre de gouvernance dans lequel s'inscrit la cartographie (Gouverner, Cartographier, Mesurer, Gérer).", "Traces d'agents et journaux d'audit — la couche de preuves ; sans elles, le modèle est invérifiable.", "Suites de red-teaming automatisées — corpus d'injections exécutés en CI pour que les régressions apparaissent avant la mise en production.", "Moteurs de politiques et de permissions — là où les conclusions du modèle sont réellement appliquées." ], "examples": [ "Un agent de support qui lit les e-mails des clients : le corps du message est une entrée d'instruction non approuvée, l'outil CRM est la capacité, et le canal de réponse est le chemin d'exfiltration. Trois surfaces pour une seule fonctionnalité.", "Un agent de codage avec accès en écriture au dépôt et sortie réseau : injection via le README d'une dépendance, capacité via l'outil de commit, exfiltration via tout registre qu'il peut atteindre.", "Un agent de recherche sur un wiki interne : toute personne pouvant modifier une page peut rédiger des instructions que l'agent lira, ce qui fait d'un éditeur interne à faibles privilèges un vecteur d'injection." ], "faqs": [ { "q": "En quoi cela diffère-t-il d'un modèle de menace classique ?", "a": "La méthode est la même ; ce sont les surfaces qui sont nouvelles. Les modèles classiques partent du principe que le code exécute des instructions et que les données n'en contiennent pas. Avec un agent, les données sont des instructions — ainsi, la recherche, la mémoire et les résultats des outils deviennent tous des canaux d'entrée accessibles par un attaquant." }, { "q": "En ai-je besoin si mon agent est en lecture seule ?", "a": "Oui, mais plus restreint. Un agent en lecture seule possède toujours une surface d'exfiltration — on peut lui faire répéter tout ce qu'il peut lire — et la « lecture seule » est une propriété qui doit être appliquée au niveau de la couche de l'outil, et non supposée à partir du prompt." }, { "q": "Par quoi commencer si je n'ai encore rien rédigé ?", "a": "Listez les outils que l'agent peut appeler et les données auxquelles chacun accède. Ce simple tableau génère la majeure partie de la cartographie : les capacités représentent le rayon d'impact, et les entrées qui peuvent les atteindre constituent les chemins d'attaque." }, { "q": "À quelle fréquence doit-il être révisé ?", "a": "Chaque fois qu'un outil, une source de données ou un niveau d'autonomie change — ce sont ces événements qui créent des surfaces. Les mises à niveau des modèles importent moins qu'on ne le pense ; elles modifient la probabilité, pas la portée." } ] }, "de": { "title": "Was ist ein Agentic Threat Model?", "summary": "Ein Agentic Threat Model ist die Abbildung dessen, wie ein autonomer Agent angegriffen werden kann: nicht über seine Gewichte, sondern über alles, was er liest, sich merkt, aufruft und tun darf. Es benennt die Angriffsflächen – direkte und indirekte Prompt Injection, Tool Poisoning, übermäßige Handlungsfähigkeit (Excessive Agency), Memory Poisoning, Lieferkette, Exfiltrationskanäle, der Confused Deputy –, sodass jede einzelne eine Kontrolle im Harness erhält, statt nur auf eine Hoffnung im System-Prompt zu setzen.", "definition": "Ein Agentic Threat Model ist eine strukturierte Aufzählung der Angriffsflächen, Angreiferziele und Missbrauchspfade, die spezifisch für einen KI-Agenten sind – seine Eingaben, sein Kontext, sein Speicher, seine Tools, seine Anmeldedaten und seine Autonomie. Es dient der Entscheidung, welche Harness-Kontrollen erforderlich sind, bevor dem Agenten Zugriff auf die Produktion gewährt wird.", "takeaways": [ "Erstellen Sie das Bedrohungsmodell für die Aktionen des Agenten, nicht für die Ausgaben des Modells.", "Jede Eingabe, die der Agent liest, ist ein Anweisungskanal: Dokumente, Seiten, Tool-Ergebnisse, andere Agenten.", "Jedes Tool, das der Agent aufrufen kann, ist eine Fähigkeit, die ein Angreifer in dem Moment erbt, in dem eine Injection erfolgreich ist.", "Speicher verwandelt einen One-Shot-Angriff in einen persistenten Angriff.", "Der Blast Radius wird durch Anmeldedaten und Egress bestimmt, nicht durch den Prompt.", "Eine unbenannte Angriffsfläche ist keine nicht vorhandene – schreiben Sie akzeptierte Risiken explizit auf." ], "context": [ "Klassisches Threat Modelling fragt danach, was ein Angreifer an Ihr System senden kann. Bei Agenten lautet die schwierigere Frage, was Ihr System von sich aus liest und als Anweisungen behandelt. Ein Agent, der eine Seite abruft, ein Ticket öffnet oder ein Tool-Ergebnis liest, hat seine Vertrauensgrenze erweitert, ohne dass dies jemand explizit beschlossen hat.", "Die zweite Verschiebung betrifft die Handlungsfähigkeit (Agency). Ein Chatbot, der getäuscht wird, erzeugt einen falschen Satz; ein Agent, der getäuscht wird, tätigt einen Anruf, transferiert Geld, löscht einen Branch oder versendet eine Datei per E-Mail. Die Schwere eines erfolgreichen Angriffs wird durch die dem Agenten zugewiesenen Tools und Anmeldedaten bestimmt, weshalb die Rechtevergabe eine Sicherheitsentscheidung und keine reine Komfortentscheidung ist.", "Frameworks verankern diese Praxis: Die OWASP Top 10 für LLM-Anwendungen benennen die Schwachstellenklassen und MITRE ATLAS katalogisiert die gegen KI-Systeme beobachteten Taktiken von Angreifern. Nutzen Sie diese als Checklisten für Ihre eigene Architektur, nicht als Ersatz für eine solche." ], "architecture": [ "Direkte Prompt Injection – die Person, die mit dem Agenten spricht, versucht, dessen Anweisungen außer Kraft zu setzen. Am einfachsten zu versuchen und am leichtesten einzugrenzen, da sich dieser Benutzer bereits innerhalb der Berechtigungen befindet, die die Sitzung gewährt.", "Indirekte Prompt Injection – Anweisungen, die in Inhalten versteckt sind, die der Agent abruft: eine Webseite, ein PDF, ein Ticket-Kommentar, eine E-Mail, eine Quelldatei, die Ausgabe eines anderen Agenten. Der Angreifer spricht nie direkt mit Ihrem Agenten; er platziert Text dort, wo der Agent ihn lesen wird.", "Tool Poisoning – ein Tool, dessen Beschreibung oder Ergebnis selbst schädlich ist. Ein Server kann zum Zeitpunkt der Genehmigung ein harmloses Tool beschreiben und es danach ändern, sodass Vertrauen einmal geprüft und für immer ausgeübt wird.", "Übermäßige Handlungsbefugnis (Excessive Agency) — der Agent besitzt Berechtigungen, die über das für eine einzelne Aufgabe erforderliche Maß hinausgehen. Noch ist nichts schiefgegangen; die Angriffsfläche besteht darin, dass ein gekaperter Agent sofort alle Rechte erbt, die das Harness zu gewähren bereit war.", "Memory Poisoning (Speichermanipulation) — falsche Fakten oder Anweisungen, die in den persistenten Speicher oder einen Vektorspeicher geschrieben werden, sodass der Angriff die Sitzung überdauert und bei zukünftigen, nicht damit zusammenhängenden Aufgaben erneut ausgelöst wird.", "Lieferkette (Supply Chain) — Modelle, System-Prompts, MCP-Server, Pakete und Datensätze, die von außerhalb der Organisation bezogen werden. Eine Abhängigkeit, die eine Tool-Beschreibung umschreiben kann, ist eine Abhängigkeit, die das Verhalten des Agenten umschreiben kann.", "Exfiltrationskanäle — jeder Pfad, über den Bytes abfließen können: ein ausgehender Fetch-Aufruf, eine in einer Antwort gerenderte Bild-URL, ein E-Mail- oder Webhook-Tool, ein Commit. Daten müssen nicht von einem Menschen gelesen werden, um gestohlen zu werden; eine URL genügt.", "Confused Deputy — der Agent agiert mit Anmeldedaten, die der Anforderer selbst nicht besitzt, sodass ein Angreifer, der ein System nicht direkt erreichen kann, den Agenten bittet, in seinem Namen darauf zuzugreifen." ], "components": [ "Asset-Inventar: die Daten, Systeme und Anmeldedaten, auf die der Agent zugreifen kann, aufgelistet nach der Reichweite des Agenten und nicht nach dem Organigramm des Teams.", "Vertrauensgrenzen (Trust Boundaries): Welche Eingaben sind Anweisungen, welche sind Daten, und an welcher Stelle diese Grenze im Code statt in Textform erzwungen wird.", "Tool-Katalog mit Berechtigungen: jedes Tool, sein Umfang, ob es Schreibrechte besitzt und was ein Angreifer durch dessen Aufruf gewinnt.", "Egress-Map (Abflusspfade): Jeder Weg, auf dem Bytes abfließen können, einschließlich unbeabsichtigter Wege — Link-Vorschauen, gerenderte Bilder, Log-Versand, Fehlerberichterstattung.", "Ziele des Angreifers: Exfiltrieren, Rechte ausweiten (Escalate), Persistenz etablieren, Stören, Täuschen — jeweils auf die oben genannten Angriffsflächen abgebildet.", "Sicherheitskontrollen (Controls) mit Verantwortlichen: Welche Harness-Komponente den jeweiligen Pfad begrenzt und wer diese pflegt.", "Akzeptierte Risiken: bewusst offengehaltene Pfade, inklusive Begründung und kompensierender Erkennungsmaßnahmen.", "Testfälle: für jede Angriffsfläche der Injektions- oder Missbrauchsversuch, der beweist, dass die Sicherheitskontrolle funktioniert. Eine Kontrolle, deren Fehlschlagen man nie beobachtet hat, ist eine nicht verifizierte Kontrolle." ], "pros": [ "Es verwandelt die Frage „Ist unser Agent sicher?“ in eine endliche Liste von Angriffsflächen, die jeweils einen Verantwortlichen und eine Sicherheitskontrolle haben.", "Es macht Berechtigungsentscheidungen explizit und überprüfbar, bevor der Zugriff auf die Produktionsumgebung gewährt wird.", "Es liefert Red Teams eine Zielliste und bietet Evaluierungs-Suites konkrete Fälle zur Automatisierung.", "Es altert gut: Modelle ändern sich oft, Angriffsflächen ändern sich langsam, sodass die Übersicht den nächsten Modellwechsel überdauert." ], "risks": [ "Den Chatbot statt des Agenten zu modellieren — also Risiken bei der Ausgabe aufzuzählen, während die Tools ignoriert werden, die diese Ausgaben in Aktionen umsetzen.", "Das Modell als Kontrollpunkt zu behandeln. Alignment reduziert Versuche; es begrenzt nicht die Konsequenzen.", "Ein einmal geschriebenes Dokument, das nie wieder angerührt wird. Jedes neue Tool ist eine neue Angriffsfläche, daher gehört das Modell in den Change-Prozess.", "Abdeckung mit Abwehr zu verwechseln: Eine Angriffsfläche zu benennen bedeutet nicht, sie zu kontrollieren, und eine ungeprüfte Kontrolle ist lediglich eine Behauptung." ], "tools": [ "OWASP Top 10 für LLM-Anwendungen — ein gemeinsames Vokabular für die Schwachstellenklassen.", "MITRE ATLAS — Taktiken und Techniken von Angreifern, die bei KI-Systemen beobachtet wurden.", "NIST AI RMF — der Governance-Rahmen, in den sich die Übersicht einfügt (Govern, Map, Measure, Manage).", "Agenten-Traces und Audit-Logs — die Nachweisebene; ohne sie ist das Modell nicht falsifizierbar.", "Automatisierte Red-Team-Suites — Injektions-Korpora, die in der CI ausgeführt werden, damit Regressionen vor dem Release auffallen.", "Richtlinien- und Berechtigungs-Engines — dort, wo die Schlussfolgerungen des Modells tatsächlich durchgesetzt werden." ], "examples": [ "Ein Support-Agent, der Kunden-E-Mails liest: Der Nachrichtentext ist eine nicht vertrauenswürdige Anweisungseingabe, das CRM-Tool ist die Funktion (Capability) und der Antwortkanal ist der Exfiltrationspfad. Drei Angriffsflächen aus einem einzigen Feature.", "Ein Coding-Agent mit Schreibzugriff auf das Repository und Netzwerk-Egress: Injektion über die README einer Abhängigkeit, Funktion über das Commit-Tool, Exfiltration über jede erreichbare Registry.", "Ein Retrieval-Agent für ein internes Wiki: Jeder, der eine Seite bearbeiten kann, kann Anweisungen schreiben, die der Agent liest, was einen internen Editor mit geringen Rechten zu einem Injektionsvektor macht." ], "faqs": [ { "q": "Wie unterscheidet sich dies von einer normalen Bedrohungsanalyse (Threat Model)?", "a": "Die Methode ist dieselbe, die Angriffsflächen sind neu. Klassische Modelle gehen davon aus, dass Code Anweisungen ausführt und Daten dies nicht tun. Bei einem Agenten sind Daten Anweisungen — somit werden Retrieval, Speicher und Tool-Ergebnisse alle zu Eingangskanälen, die ein Angreifer erreichen kann." }, { "q": "Benötige ich eine Bedrohungsanalyse, wenn mein Agent schreibgeschützt (read-only) ist?", "a": "Ja, eine kleinere. Ein schreibgeschützter Agent hat immer noch eine Exfiltrationsfläche — alles, was er lesen kann, kann er auch wiederholen —, und „schreibgeschützt“ ist eine Eigenschaft, die auf der Tool-Ebene erzwungen werden muss und nicht einfach im Prompt vorausgesetzt werden darf." }, { "q": "Wo fange ich an, wenn ich noch nichts schriftlich festgehalten habe?", "a": "Listen Sie die Tools auf, die der Agent aufrufen kann, und die Daten, auf die jedes Tool zugreift. Diese eine Tabelle liefert den Großteil der Übersicht: Funktionen (Capabilities) stellen den Schadensradius (Blast Radius) dar, und die Eingaben, die sie erreichen können, sind die Angriffspfade." }, { "q": "Wie oft sollte sie überarbeitet werden?", "a": "Immer wenn sich ein Tool, eine Datenquelle oder eine Autonomiestufe ändert — das sind die Ereignisse, die neue Angriffsflächen schaffen. Modell-Upgrades sind weniger wichtig als gedacht; sie ändern die Wahrscheinlichkeit, nicht die Reichweite." } ] }, "ja": { "title": "アジェンティック脅威モデルとは何ですか？", "summary": "アジェンティック脅威モデルとは、自律型エージェントがどのように攻撃され得るかを示すマップです。これはモデルの重み（ウェイト）を介した攻撃ではなく、エージェントが読み取り、記憶し、呼び出し、実行を許可されているすべての要素を対象とします。直接的および間接的なプロンプトインジェクション、ツールの汚染（ツールポイズニング）、過剰なエージェンシー、メモリの汚染、サプライチェーン、情報の流出経路、混乱した代理人（Confused Deputy）問題などの攻撃対象領域（サーフェス）を特定し、システムプロンプトに期待するのではなく、ハーネス内でそれぞれに対する制御（コントロール）を実装できるようにします。", "definition": "アジェンティック脅威モデルとは、AIエージェントに特有の攻撃対象領域、攻撃者の目標、および悪用経路（入力、コンテキスト、メモリ、ツール、資格情報、自律性など）を構造化して列挙したものです。これは、エージェントに本番環境へのアクセス権を付与する前に、どのハーネス制御が必要かを決定するために使用されます。", "takeaways": [ "モデルの出力ではなく、エージェントのアクションを対象に脅威モデリングを行う。", "エージェントが読み取るすべての入力（ドキュメント、ページ、ツールの実行結果、他のエージェントなど）は、指示チャネルとなる。", "エージェントが呼び出せるすべてのツールは、インジェクションが成功した瞬間に攻撃者が継承する能力となる。", "メモリは、単発の（ワンショット）攻撃を持続的な攻撃へと変化させる。", "影響範囲（ブラストライジアス）は、プロンプトではなく、資格情報と送信（エグレス）制限によって決定される。", "明文化されていない攻撃対象領域が存在しないわけではない。許容されたリスクは明示的に文書化する。" ], "context": [ "従来の脅威モデリングでは、攻撃者がシステムに何を送信できるかを問いかけます。しかしエージェントの場合、より困難な問いは「システムが自発的に何を読み取り、それを指示として扱うか」です。ページを取得したり、チケットを開いたり、ツールの実行結果を読み取ったりするエージェントは、誰も意図しないうちに自らの信頼境界（トラストバウンダリ）を拡大してしまっています。", "2つ目の移行はエージェンシー（自律性）です。騙されたチャットボットは誤った文章を生成するだけですが、騙されたエージェントはAPIを呼び出し、資金を移動し、ブランチを削除し、あるいはファイルをメールで送信します。攻撃成功時の深刻度は、エージェントに紐付けられたツールと資格情報によって決定されます。そのため、権限付与は利便性のための判断ではなく、セキュリティ上の決定なのです。", "フレームワークは、この取り組みの指針となります。「OWASP Top 10 for LLM Applications」は脆弱性の分類を定義し、「MITRE ATLAS」はAIシステムに対して観測された攻撃者の戦術をカタログ化しています。これらは、独自のアーキテクチャを構築する代わりにするのではなく、そのアーキテクチャを検証するためのチェックリストとして使用してください。" ], "architecture": [ "直接的プロンプトインジェクション — エージェントと対話している人物が、その指示を上書きしようと試みます。セッションに付与された権限の範囲内にユーザーがすでに存在するため、最も低コストで試行でき、制限するのも最も容易です。", "間接的プロンプトインジェクション — エージェントが取得するコンテンツ（Webページ、PDF、チケットのコメント、メール、ソースファイル、他のエージェントの出力など）に指示が隠されているケースです。攻撃者はエージェントと直接対話することはなく、エージェントが読み取る場所にテキストを仕込みます。", "ツールの汚染（ツールポイズニング） — ツールの説明や実行結果自体が敵対的なものであるケースです。サーバーは承認時には無害なツールとして説明し、承認後にそれを変更することができるため、信頼性のチェックが一度行われただけで、永続的に実行されてしまうリスクがあります。", "過剰なエージェンシー（Excessive agency） — エージェントが、個々のタスクが必要とするよりも広範な権限を保持している状態。まだ問題は発生していませんが、乗っ取られたエージェントが、ハーネスが許可していたすべての権限を即座に引き継いでしまうという攻撃対象領域（サーフェス）が存在します。", "メモリポイズニング（Memory poisoning） — 永続メモリやベクトルストアに誤った事実や指示が書き込まれることで、攻撃がセッションを超えて存続し、将来の無関係なタスクで再実行されること。", "サプライチェーン — 組織の外部から取り込まれるモデル、システムプロンプト、MCPサーバー、パッケージ、データセット。ツールの説明を書き換えられる依存関係は、エージェントの動作を書き換えられる依存関係と同義です。", "流出チャネル（Exfiltration channels） — バイトデータが外部に流出する可能性のあるあらゆる経路：アウトバウンドのfetch、返答内にレンダリングされた画像URL、メールやWebhookツール、コミットなど。データが盗まれるために人間がそれを読む必要はありません。URLだけで十分です。", "代理の混乱（Confused deputy） — エージェントが要求元（リクエスター）の持っていない資格情報を使用して動作するため、システムに直接アクセスできない攻撃者が、エージェントに代理でアクセスするよう要求すること。" ], "components": [ "資産インベントリ：エージェントがアクセスできるデータ、システム、資格情報。チームの組織図ではなく、エージェントの到達範囲に基づいてリスト化されます。", "信頼境界（Trust boundaries）：どの入力が指示で、どの入力がデータであるか、そしてその境界線が自然言語（プロース）ではなくコードでどのように強制されているか。", "権限付きツールカタログ：すべてのツール、そのスコープ、書き込みを行うかどうか、および攻撃者がそれを呼び出すことで何を得られるか。", "エグレス（送信）マップ：リンクプレビュー、レンダリングされた画像、ログ転送、エラーレポートなど、意図しないものも含めて、バイトデータが外部に流出するあらゆる経路。", "敵対者の目標：流出、権限昇格、永続化、妨害、欺瞞 — それぞれが上記の攻撃対象領域（サーフェス）にマッピングされます。", "オーナー付きのコントロール：どのハーネスコンポーネントが各経路を制限しているか、およびその維持管理の担当者。", "許容されたリスク：意図的に開放されたままにしている経路、その理由、および補完的な検知策。", "テストケース：各攻撃対象領域（サーフェス）において、コントロールが機能していることを証明するインジェクションや悪用の試み。失敗が確認されたことのないコントロールは、検証されたことのないコントロールと同義です。" ], "pros": [ "『私たちのエージェントは安全か？』という問いを、それぞれにオーナーとコントロールが存在する、有限の攻撃対象領域（サーフェス）のリストへと変換します。", "本番環境へのアクセス権限が許可される前に、権限に関する決定を明確にし、レビュー可能にします。", "レッドチームにターゲットリストを提供し、評価スイートに自動化のための具体的なケースを提供します。", "経年劣化しにくい：モデルは頻繁に変更されますが、攻撃対象領域（サーフェス）の変化は緩やかであるため、このマップは次のモデルの入れ替え時にも有効であり続けます。" ], "risks": [ "エージェントではなくチャットボットをモデル化してしまうこと — 出力による害を列挙する一方で、それらを実行に移すツールを無視してしまうこと。", "モデルをコントロールポイント（制御点）として扱ってしまうこと。アライメントは試みを減らすことはできますが、結果を制限することはできません。", "一度作成されたきり、二度と見直されないドキュメント。新しいツールはすべて新しい攻撃対象領域（サーフェス）となるため、モデルは変更プロセスに組み込まれるべきです。", "カバレッジと防御を混同すること：攻撃対象領域（サーフェス）を特定することはそれを制御することではなく、テストされていないコントロールは単なる主張にすぎません。" ], "tools": [ "OWASP Top 10 for LLM Applications — 脆弱性クラスの共通語彙。", "MITRE ATLAS — AIシステムに対して観測された敵対者の戦術と技術。", "NIST AI RMF — マップが組み込まれるガバナンスフレームワーク（Govern、Map、Measure、Manage）。", "エージェントのトレースと監査ログ — エビデンス（証拠）レイヤー。これらがなければ、モデルの反証は不可能です。", "自動レッドチームスイート — リリース前にデグレード（先祖返り）を表面化させるために、CIで実行されるインジェクションコーパス。", "ポリシーおよび権限エンジン — モデルの結論が実際に強制適用される場所。" ], "examples": [ "顧客のメールを読み取るサポートエージェント：メッセージ本文は信頼できない指示入力であり、CRMツールは機能（ケイパビリティ）、返信チャネルは流出経路となります。1つの機能から3つの攻撃対象領域（サーフェス）が生じます。", "リポジトリへの書き込み権限とネットワーク送信（エグレス）権限を持つコーディングエージェント：依存関係のREADMEを介したインジェクション、コミットツールを介した機能（ケイパビリティ）、アクセス可能な任意のレジストリを介した流出。", "社内Wikiを対象とする検索（RAG）エージェント：ページを編集できる人なら誰でもエージェントが読み取る指示を書き込めるため、低権限の社内編集者がインジェクションベクターになります。" ], "faqs": [ { "q": "通常の脅威モデルと何が違うのですか？", "a": "手法は同じですが、攻撃対象領域（サーフェス）が新しくなっています。従来のモデルでは、コードが指示を実行し、データは実行しないと仮定していました。エージェントの場合、データが指示となります。そのため、検索結果、メモリ、ツールの実行結果のすべてが、攻撃者がアクセス可能な入力チャネルになります。" }, { "q": "エージェントが読み取り専用の場合でも、脅威モデルは必要ですか？", "a": "はい、小規模なものが必要です。読み取り専用のエージェントであっても、流出の攻撃対象領域（サーフェス）は存在します（読み取れるものは何でも復唱させられる可能性があります）。また、『読み取り専用』という属性は、プロンプトから想定するのではなく、ツールレイヤーで強制適用される必要があります。" }, { "q": "何も文書化されていない場合、どこから始めればよいですか？", "a": "エージェントが呼び出せるツールと、それぞれがアクセスするデータをリストアップします。その1つの表からマップの大部分が作成されます。機能（ケイパビリティ）が影響範囲（ブラストラジアス）となり、それらに到達可能な入力が攻撃経路となります。" }, { "q": "どのくらいの頻度で見直すべきですか？", "a": "ツール、データソース、または自律性のレベルが変更されるたびに見直す必要があります。これらは攻撃対象領域（サーフェス）を生み出すイベントだからです。モデルのアップグレードは、一般に思われているほど重要ではありません。アップグレードによって変わるのは発生可能性であり、到達範囲ではないからです。" } ] }, "zh": { "title": "什么是智能体威胁模型？", "summary": "智能体威胁模型是自主智能体可能遭受攻击的路径图：攻击并非通过其权重进行，而是通过它所读取、记忆、调用以及被允许执行的一切操作。它指明了各种攻击面——直接和间接提示词注入、工具投毒、过度授权、记忆投毒、供应链、数据外泄通道、混淆代理——从而让每一个攻击面都能在支撑系统中得到具体控制，而不是寄希望于系统提示词。", "definition": "智能体威胁模型是对AI智能体特有的攻击面、对手目标和滥用路径（包括其输入、上下文、记忆、工具、凭证和自主权）进行的结构化列举，用于在授予智能体生产环境访问权限之前，决定需要哪些支撑系统控制措施。", "takeaways": [ "对智能体的行为进行威胁建模，而不是对模型的输出进行威胁建模。", "智能体读取的每个输入都是一个指令通道：文档、页面、工具结果、其他智能体。", "智能体可以调用的每个工具，都是攻击者在注入成功那一刻所继承的能力。", "记忆会将单次攻击转变为持久性攻击。", "爆炸半径（受损范围）由凭证和出口决定，而不是由提示词决定。", "未被指明的攻击面并不意味着它存在——请明确记录已接受的风险。" ], "context": [ "传统的威胁建模关注攻击者可以向你的系统发送什么。而对于智能体，更难的问题是你的系统会主动读取什么并将其视为指令。一个获取页面、打开工单或读取工具结果的智能体，在未经任何人决策的情况下，就已经扩大了其信任边界。", "第二个转变是能动性。一个被愚弄的聊天机器人只会产生错误的句子；而一个被愚弄的智能体则会进行调用、转账、删除分支或发送包含文件的电子邮件。成功攻击的严重程度取决于绑定到该智能体的工具和凭证，这就是为什么权限授予是一个安全决策，而不仅仅是为了方便。", "框架为这一实践提供了支撑：OWASP Top 10 for LLM Applications 命名了漏洞类别，而 MITRE ATLAS 则编目了针对 AI 系统观察到的对手战术。将它们用作针对你自己架构的检查清单，而不是替代架构本身。" ], "architecture": [ "直接提示词注入——与智能体对话的人试图覆盖其指令。这种尝试成本最低，也最容易限制，因为该用户已经处于会话所授予的任何权限范围内。", "间接提示词注入——隐藏在智能体检索内容中的指令：网页、PDF、工单评论、电子邮件、源文件或其他智能体的输出。攻击者从未直接与你的智能体对话，他们只是在智能体将要读取的地方植入文本。", "工具投毒——工具的描述或结果本身具有对抗性。服务器可以在审批时将工具描述为无害的，并在之后对其进行修改，从而实现“一次审核，永久使用”的信任滥用。", "过度授权（Excessive agency）——智能体拥有的权限超出了任何单一任务所需的范围。目前还没有发生任何问题；其隐患在于，一旦智能体被劫持，它将立即继承支撑系统（harness）愿意授予的所有权限。", "内存毒化（Memory poisoning）——将虚假事实或指令写入持久化内存或向量数据库中，从而使攻击在会话结束后依然存在，并在未来无关的任务中重新触发。", "供应链（Supply chain）——从组织外部拉取的模型、系统提示词、MCP 服务器、依赖包和数据集。一个能够重写工具描述的依赖项，同样能够重写智能体的行为。", "外发通道（Exfiltration channels）——任何字节可以流出的路径：出站 fetch 请求、回复中渲染的图片 URL、电子邮件或 webhook 工具、提交（commit）。数据不需要被人类读取才算被盗；一个 URL 就足够了。", "混淆代理（Confused deputy）——智能体使用请求者不具备的凭据执行操作，因此无法直接访问系统的攻击者会要求智能体代表其进行访问。" ], "components": [ "资产清单：智能体可以接触的数据、系统和凭据，按智能体的触达范围而非团队的组织架构图列出。", "信任边界：哪些输入是指令，哪些是数据，以及该界限是在代码中强制执行还是仅在文本中说明。", "带权限的工具目录：每个工具及其范围、是否执行写操作，以及攻击者通过调用它能获得什么。", "出口地图：字节可以流出的每种方式，包括意外流出的方式——链接预览、渲染的图像、日志传输、错误报告。", "对手目标：外发、提权、持久化、破坏、欺骗——每个目标都映射到上述攻击面上。", "带负责人的控制措施：哪个支撑系统（harness）组件限制了每条路径，以及由谁来维护它。", "接受的风险：故意保留的开放路径，以及原因和补偿性检测措施。", "测试用例：针对每个攻击面，证明控制措施有效的注入或滥用尝试。从未见证过失败的控制措施是未经证实的控制措施。" ], "pros": [ "它将“我们的智能体安全吗？”转化为一个有限的攻击面列表，每个攻击面都有负责人和控制措施。", "它使权限决策在授予生产环境访问权限之前变得明确且可审查。", "它为红队提供了目标列表，并为评估套件提供了可自动化的具体案例。", "它经得起时间考验：模型经常变化，而攻击面变化缓慢，因此该地图在下一次模型更换后依然适用。" ], "risks": [ "对聊天机器人而非智能体进行建模——列举了输出危害，却忽略了将这些输出转化为行动的工具。", "将模型视为控制点。对齐只能减少尝试，并不能限制后果。", "文档一次写成后便再未修改。每个新工具都是一个新的攻击面，因此该模型应纳入变更流程中。", "将覆盖范围与防御混淆：命名一个攻击面并不等于控制它，未经测试的控制措施只是一种说辞。" ], "tools": [ "OWASP Top 10 for LLM Applications——漏洞类别的共享词汇表。", "MITRE ATLAS——针对 AI 系统观察到的对手战术和技术。", "NIST AI RMF——该地图接入的治理框架（治理、映射、测量、管理）。", "智能体追踪和审计日志——证据层；没有它们，模型是无法证伪的。", "自动化红队套件——在 CI 中运行的注入语料库，以便在发布前发现回归问题。", "策略和权限引擎——模型结论实际执行的地方。" ], "examples": [ "读取客户电子邮件的支持智能体：邮件正文是不可信的指令输入，CRM 工具是能力，而回复通道是外发路径。一个功能产生三个攻击面。", "具有代码库写入权限和网络出口的编码智能体：通过依赖项的 README 进行注入，通过 commit 工具获得能力，通过其可触达的任何注册表进行外发。", "针对内部 Wiki 的检索智能体：任何可以编辑页面的人都可以编写智能体将读取的指令，这使得低权限的内部编辑器成为注入向量。" ], "faqs": [ { "q": "这与普通的威胁模型有什么不同？", "a": "方法相同，但攻击面是全新的。经典模型假设代码执行指令，而数据不执行。对于智能体，数据就是指令——因此检索、内存和工具结果都变成了攻击者可以触达的输入通道。" }, { "q": "如果我的智能体是只读的，我还需要威胁模型吗？", "a": "是的，需要一个规模较小的模型。只读智能体仍然具有外发攻击面——任何它能读取的内容都可以被诱导重复输出——而且“只读”这一属性必须在工具层强制执行，而不能仅凭提示词来假设。" }, { "q": "如果我什么都还没写，该从哪里开始？", "a": "列出智能体可以调用的工具以及每个工具所触达的数据。仅凭这张表就能生成地图的大部分内容：能力是爆炸半径，而能够触达它们的输入则是攻击路径。" }, { "q": "应该多长时间重新评估一次？", "a": "每当工具、数据源或自主程度发生变化时——这些都是产生攻击面的事件。模型升级的影响比人们预期的要小；它们改变的是可能性，而不是触达范围。" } ] } } }, { "slug": "ai-agent", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/ai-agent", "api": "https://santismm.com/api/knowledge/ai-agent", "canonical_url": "https://santismm.com/en/knowledge/ai-agent", "api_url": "https://santismm.com/api/knowledge/ai-agent", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" }, { "title": "Yao et al. — ReAct (2022)", "url": "https://arxiv.org/abs/2210.03629" } ], "related": [ "agentic-ai", "harness-engineering", "model-context-protocol", "multi-agent-architecture" ], "locales": { "en": { "title": "What is an AI Agent?", "summary": "An AI agent is a system that combines a model with tools, memory and a control loop to take actions toward a goal, rather than just answering a single prompt. It perceives a situation, decides what to do, acts through tools, observes the result and repeats until done. Autonomy ranges from a single tool call to long-horizon execution of complex tasks.", "definition": "An AI agent is a system that pairs a reasoning model with tools, memory and an orchestration loop so it can plan and act over multiple steps to achieve a goal.", "takeaways": [ "Agent = model + tools + memory + control loop.", "Agents act; chatbots answer.", "Tool use is the bridge to real systems and data.", "More autonomy means more need for guardrails and evaluation.", "Reliability is engineered through the harness, not assumed from the model." ], "context": [ "A plain LLM produces text. An agent uses that text to decide and act: it can search, call APIs, write files or trigger workflows, then react to what happens. This loop is what lets it complete tasks instead of merely describing them.", "Agents sit on a spectrum of autonomy. Low-autonomy agents make one or two tool calls under tight control; high-autonomy agents run long, branching tasks with little supervision — and need correspondingly stronger guardrails." ], "architecture": [ "The core loop is sense → decide → act → observe. The model decides the next action, an orchestrator executes it via a tool, the result is fed back as an observation, and the loop continues until a goal or stop condition is reached.", "Around this loop sit memory (to carry state), guardrails (to constrain behavior), and observability (to trace what happened). These are the parts of the harness that make an agent dependable." ], "components": [ "Reasoning model", "Tools", "Memory", "Orchestration loop", "Guardrails", "Observability" ], "pros": [ "Executes tasks end to end.", "Connects models to live systems.", "Recovers from intermediate failures.", "Automates multi-step knowledge work." ], "risks": [ "Error compounding over long tasks.", "Cost and latency without budgets.", "Prompt injection and tool-misuse risks.", "Harder to test and debug than single prompts." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "A triage agent that classifies and routes incoming requests.", "A coding agent that fixes a bug and verifies it with tests.", "A data agent that queries a warehouse and assembles a report." ], "faqs": [ { "q": "Is a chatbot an AI agent?", "a": "Not by default. A chatbot answers; an agent takes actions through tools across multiple steps to reach a goal." }, { "q": "What is the simplest useful agent?", "a": "A model with one or two well-described tools and a clear stop condition. Start simple and add structure only when measurement shows you need it." }, { "q": "What makes an agent reliable?", "a": "The harness: clean tool design, good memory, guardrails, observability and evaluation — not just a stronger model." }, { "q": "Single agent or multi-agent?", "a": "Prefer a single agent until a task clearly benefits from specialized, separable roles. Multi-agent adds coordination overhead." } ] }, "es": { "title": "¿Qué es un Agente de IA?", "summary": "Un agente de IA es un sistema que combina un modelo con herramientas, memoria y un bucle de control para tomar acciones hacia un objetivo, en lugar de solo responder a un prompt. Percibe una situación, decide qué hacer, actúa mediante herramientas, observa el resultado y repite hasta terminar. La autonomía va desde una sola llamada a herramienta hasta la ejecución de tareas complejas de horizonte largo.", "definition": "Un agente de IA es un sistema que une un modelo de razonamiento con herramientas, memoria y un bucle de orquestación para planificar y actuar en varios pasos hacia un objetivo.", "takeaways": [ "Agente = modelo + herramientas + memoria + bucle de control.", "Los agentes actúan; los chatbots responden.", "El uso de herramientas es el puente hacia sistemas y datos reales.", "Más autonomía exige más guardarraíles y evaluación.", "La fiabilidad se diseña con el harness, no se da por sentada en el modelo." ], "context": [ "Un LLM simple produce texto. Un agente usa ese texto para decidir y actuar: puede buscar, llamar APIs, escribir ficheros o disparar flujos, y luego reaccionar a lo que ocurre. Ese bucle es lo que le permite completar tareas en vez de solo describirlas.", "Los agentes están en un espectro de autonomía. Los de baja autonomía hacen una o dos llamadas bajo control estricto; los de alta autonomía ejecutan tareas largas y ramificadas con poca supervisión, y necesitan guardarraíles proporcionalmente más fuertes." ], "architecture": [ "El bucle central es percibir → decidir → actuar → observar. El modelo decide la siguiente acción, un orquestador la ejecuta vía una herramienta, el resultado vuelve como observación, y el bucle continúa hasta alcanzar un objetivo o una condición de parada.", "Alrededor de ese bucle están la memoria (para arrastrar estado), los guardarraíles (para acotar el comportamiento) y la observabilidad (para trazar lo ocurrido). Son las partes del harness que hacen fiable a un agente." ], "components": [ "Modelo de razonamiento", "Herramientas", "Memoria", "Bucle de orquestación", "Guardarraíles", "Observabilidad" ], "pros": [ "Ejecuta tareas de principio a fin.", "Conecta modelos con sistemas en vivo.", "Se recupera de fallos intermedios.", "Automatiza trabajo de conocimiento de varios pasos." ], "risks": [ "Acumulación de errores en tareas largas.", "Coste y latencia sin presupuestos.", "Riesgos de inyección de prompts y mal uso de herramientas.", "Más difícil de probar y depurar que un prompt simple." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "Un agente de triaje que clasifica y enruta solicitudes entrantes.", "Un agente de programación que corrige un bug y lo verifica con tests.", "Un agente de datos que consulta un warehouse y arma un informe." ], "faqs": [ { "q": "¿Un chatbot es un agente de IA?", "a": "Por defecto no. Un chatbot responde; un agente toma acciones mediante herramientas en varios pasos para alcanzar un objetivo." }, { "q": "¿Cuál es el agente útil más simple?", "a": "Un modelo con una o dos herramientas bien descritas y una condición de parada clara. Empieza simple y añade estructura solo cuando la medición lo justifique." }, { "q": "¿Qué hace fiable a un agente?", "a": "El harness: diseño limpio de herramientas, buena memoria, guardarraíles, observabilidad y evaluación, no solo un modelo más potente." }, { "q": "¿Un agente o multiagente?", "a": "Prefiere un solo agente hasta que la tarea se beneficie claramente de roles especializados y separables. El multiagente añade coste de coordinación." } ] }, "pt": { "title": "O que é um Agente de IA?", "summary": "Um agente de IA é um sistema que combina um modelo com ferramentas, memória e um laço de controle para tomar ações rumo a um objetivo, em vez de só responder a um prompt. Ele percebe uma situação, decide o que fazer, age por meio de ferramentas, observa o resultado e repete até concluir. A autonomia vai de uma única chamada de ferramenta à execução de tarefas complexas de horizonte longo.", "definition": "Um agente de IA é um sistema que une um modelo de raciocínio a ferramentas, memória e um laço de orquestração para planejar e agir em vários passos rumo a um objetivo.", "takeaways": [ "Agente = modelo + ferramentas + memória + laço de controle.", "Agentes agem; chatbots respondem.", "O uso de ferramentas é a ponte para sistemas e dados reais.", "Mais autonomia exige mais guard-rails e avaliação.", "A confiabilidade é projetada com o harness, não presumida do modelo." ], "context": [ "Um LLM simples produz texto. Um agente usa esse texto para decidir e agir: pode buscar, chamar APIs, escrever arquivos ou disparar fluxos, e então reagir ao que acontece. Esse laço é o que lhe permite concluir tarefas em vez de só descrevê-las.", "Os agentes estão num espectro de autonomia. Os de baixa autonomia fazem uma ou duas chamadas sob controle estrito; os de alta autonomia executam tarefas longas e ramificadas com pouca supervisão, e precisam de guard-rails proporcionalmente mais fortes." ], "architecture": [ "O laço central é perceber → decidir → agir → observar. O modelo decide a próxima ação, um orquestrador a executa via uma ferramenta, o resultado retorna como observação, e o laço continua até alcançar um objetivo ou uma condição de parada.", "Em torno desse laço estão a memória (para carregar estado), os guard-rails (para limitar o comportamento) e a observabilidade (para rastrear o ocorrido). São as partes do harness que tornam um agente confiável." ], "components": [ "Modelo de raciocínio", "Ferramentas", "Memória", "Laço de orquestração", "Guard-rails", "Observabilidade" ], "pros": [ "Executa tarefas de ponta a ponta.", "Conecta modelos a sistemas ao vivo.", "Recupera-se de falhas intermediárias.", "Automatiza trabalho de conhecimento de vários passos." ], "risks": [ "Acúmulo de erros em tarefas longas.", "Custo e latência sem orçamentos.", "Riscos de injeção de prompts e mau uso de ferramentas.", "Mais difícil de testar e depurar que um prompt simples." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "Um agente de triagem que classifica e roteia solicitações recebidas.", "Um agente de programação que corrige um bug e o verifica com testes.", "Um agente de dados que consulta um warehouse e monta um relatório." ], "faqs": [ { "q": "Um chatbot é um agente de IA?", "a": "Por padrão não. Um chatbot responde; um agente toma ações por meio de ferramentas em vários passos para alcançar um objetivo." }, { "q": "Qual é o agente útil mais simples?", "a": "Um modelo com uma ou duas ferramentas bem descritas e uma condição de parada clara. Comece simples e adicione estrutura só quando a medição justificar." }, { "q": "O que torna um agente confiável?", "a": "O harness: design limpo de ferramentas, boa memória, guard-rails, observabilidade e avaliação, não só um modelo mais potente." }, { "q": "Um agente ou multiagente?", "a": "Prefira um único agente até a tarefa se beneficiar claramente de papéis especializados e separáveis. O multiagente adiciona custo de coordenação." } ] }, "fr": { "title": "Qu'est-ce qu'un agent d'IA ?", "summary": "Un agent d'IA est un système qui combine un modèle avec des outils, de la mémoire et une boucle de contrôle pour entreprendre des actions vers un objectif, plutôt que de simplement répondre à un prompt unique. Il perçoit une situation, décide de l'action à mener, agit via des outils, observe le résultat et répète le processus jusqu'à sa finalisation. L'autonomie va d'un simple appel d'outil à l'exécution à long terme de tâches complexes.", "definition": "Un agent d'IA est un système qui associe un modèle de raisonnement à des outils, de la mémoire et une boucle d'orchestration afin de pouvoir planifier et agir en plusieurs étapes pour atteindre un objectif.", "takeaways": [ "Agent = modèle + outils + mémoire + boucle de contrôle.", "Les agents agissent ; les chatbots répondent.", "L'utilisation d'outils est la passerelle vers les systèmes et données réels.", "Plus d'autonomie implique un besoin accru de garde-fous et d'évaluation.", "La fiabilité est conçue à travers le harness, et non supposée à partir du modèle." ], "context": [ "Un LLM classique produit du texte. Un agent utilise ce texte pour décider et agir : il peut effectuer des recherches, appeler des API, écrire des fichiers ou déclencher des flux de travail, puis réagir aux événements. C'est cette boucle qui lui permet de mener à bien des tâches au lieu de simplement les décrire.", "Les agents se situent sur un spectre d'autonomie. Les agents à faible autonomie effectuent un ou deux appels d'outils sous un contrôle étroit ; les agents à forte autonomie exécutent des tâches longues et ramifiées avec peu de supervision — et nécessitent des garde-fous proportionnellement plus solides." ], "architecture": [ "La boucle principale est percevoir → décider → agir → observer. Le modèle décide de l'action suivante, un orchestrateur l'exécute via un outil, le résultat est renvoyé sous forme d'observation, et la boucle continue jusqu'à ce qu'un objectif ou une condition d'arrêt soit atteint.", "Autour de cette boucle se trouvent la mémoire (pour conserver l'état), les garde-fous (pour contraindre le comportement) et l'observabilité (pour tracer ce qui s'est passé). Ce sont les éléments du harness qui rendent un agent fiable." ], "components": [ "Modèle de raisonnement", "Outils", "Mémoire", "Boucle d'orchestration", "Garde-fous", "Observabilité" ], "pros": [ "Exécute les tâches de bout en bout.", "Connecte les modèles à des systèmes en direct.", "Récupère des échecs intermédiaires.", "Automatise le travail intellectuel en plusieurs étapes." ], "risks": [ "Cumul des erreurs sur les tâches longues.", "Coût et latence en l'absence de budgets.", "Risques d'injection de prompt et de mauvaise utilisation des outils.", "Plus difficile à tester et à déboguer que des prompts uniques." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "Un agent de tri qui classifie et oriente les requêtes entrantes.", "Un agent de codage qui corrige un bug et le vérifie à l'aide de tests.", "Un agent de données qui interroge un entrepôt de données et assemble un rapport." ], "faqs": [ { "q": "Un chatbot est-il un agent d'IA ?", "a": "Pas par défaut. Un chatbot répond ; un agent entreprend des actions via des outils en plusieurs étapes pour atteindre un objectif." }, { "q": "Quel est l'agent utile le plus simple ?", "a": "Un modèle doté d'un ou deux outils bien décrits et d'une condition d'arrêt claire. Commencez simplement et n'ajoutez de la structure que lorsque les mesures indiquent que vous en avez besoin." }, { "q": "Qu'est-ce qui rend un agent fiable ?", "a": "Le harness : une conception d'outils propre, une bonne mémoire, des garde-fous, de l'observabilité et de l'évaluation — pas seulement un modèle plus puissant." }, { "q": "Agent unique ou multi-agent ?", "a": "Privilégiez un agent unique jusqu'à ce qu'une tâche bénéficie clairement de rôles spécialisés et distincts. Le multi-agent ajoute une surcharge de coordination." } ] }, "de": { "title": "Was ist ein KI-Agent?", "summary": "Ein KI-Agent ist ein System, das ein Modell mit Tools, Speicher und einer Kontrollschleife kombiniert, um Aktionen zur Erreichung eines Ziels auszuführen, anstatt nur auf einen einzelnen Prompt zu antworten. Er nimmt eine Situation wahr, entscheidet, was zu tun ist, agiert über Tools, beobachtet das Ergebnis und wiederholt dies, bis die Aufgabe erledigt ist. Die Autonomie reicht von einem einzelnen Tool-Aufruf bis hin zur langfristigen Ausführung komplexer Aufgaben.", "definition": "Ein KI-Agent ist ein System, das ein logisches Denkmodell (Reasoning Model) mit Tools, Speicher und einer Orchestrierungsschleife verbindet, um über mehrere Schritte hinweg zu planen und zu handeln, um ein Ziel zu erreichen.", "takeaways": [ "Agent = Modell + Tools + Speicher + Kontrollschleife.", "Agenten handeln; Chatbots antworten.", "Die Nutzung von Tools ist die Brücke zu realen Systemen und Daten.", "Mehr Autonomie bedeutet einen größeren Bedarf an Guardrails und Evaluierung.", "Zuverlässigkeit wird durch das Harness entwickelt, nicht vom Modell vorausgesetzt." ], "context": [ "Ein reines LLM erzeugt Text. Ein Agent nutzt diesen Text, um Entscheidungen zu treffen und zu handeln: Er kann suchen, APIs aufrufen, Dateien schreiben oder Workflows auslösen und dann auf das reagieren, was passiert. Diese Schleife ermöglicht es ihm, Aufgaben zu erledigen, anstatt sie nur zu beschreiben.", "Agenten bewegen sich auf einem Autonomie-Spektrum. Agenten mit geringer Autonomie führen unter strenger Kontrolle ein oder zwei Tool-Aufrufe aus; Agenten mit hoher Autonomie führen lange, verzweigte Aufgaben mit wenig Aufsicht aus — und benötigen entsprechend stärkere Guardrails." ], "architecture": [ "Die Kernschleife lautet: Wahrnehmen → Entscheiden → Handeln → Beobachten (Sense → Decide → Act → Observe). Das Modell entscheidet über die nächste Aktion, ein Orchestrator führt sie über ein Tool aus, das Ergebnis wird als Beobachtung zurückgegeben, und die Schleife wird fortgesetzt, bis ein Ziel oder eine Stoppbedingung erreicht ist.", "Um diese Schleife herum befinden sich der Speicher (zur Zustandserhaltung), Guardrails (zur Einschränkung des Verhaltens) und Observability (zur Nachverfolgung der Abläufe). Dies sind die Teile des Harness, die einen Agenten zuverlässig machen." ], "components": [ "Reasoning-Modell", "Tools", "Speicher", "Orchestrierungsschleife", "Guardrails", "Observability" ], "pros": [ "Führt Aufgaben End-to-End aus.", "Verbindet Modelle mit Live-Systemen.", "Erholt sich von zwischenzeitlichen Fehlern.", "Automatisiert mehrstufige Wissensarbeit." ], "risks": [ "Fehlerpotenzierung bei langen Aufgaben.", "Kosten und Latenz ohne Budgetvorgaben.", "Risiken durch Prompt-Injection und Tool-Missbrauch.", "Schwieriger zu testen und zu debuggen als einzelne Prompts." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "Ein Triage-Agent, der eingehende Anfragen klassifiziert und weiterleitet.", "Ein Coding-Agent, der einen Fehler behebt und dies mit Tests verifiziert.", "Ein Daten-Agent, der ein Data Warehouse abfragt und einen Bericht erstellt." ], "faqs": [ { "q": "Ist ein Chatbot ein KI-Agent?", "a": "Nicht standardmäßig. Ein Chatbot antwortet; ein Agent führt über mehrere Schritte hinweg Aktionen mithilfe von Tools aus, um ein Ziel zu erreichen." }, { "q": "Was ist der einfachste nützliche Agent?", "a": "Ein Modell mit ein oder zwei gut beschriebenen Tools und einer klaren Stoppbedingung. Beginnen Sie einfach und fügen Sie Struktur erst hinzu, wenn Messungen zeigen, dass Sie sie benötigen." }, { "q": "Was macht einen Agenten zuverlässig?", "a": "Das Harness: sauberes Tool-Design, gutes Gedächtnis, Guardrails, Observability und Evaluation – nicht nur ein stärkeres Modell." }, { "q": "Einzelner Agent oder Multi-Agent?", "a": "Bevorzugen Sie einen einzelnen Agenten, bis eine Aufgabe eindeutig von spezialisierten, trennbaren Rollen profitiert. Multi-Agenten-Systeme verursachen zusätzlichen Koordinationsaufwand." } ] }, "ja": { "title": "AIエージェントとは？", "summary": "AIエージェントとは、単一のプロンプトに回答するだけでなく、モデルにツール、メモリ、コントロールループを組み合わせて、目標に向けたアクションを実行するシステムです。状況を認識し、何をすべきかを決定し、ツールを介して行動し、結果を観察し、完了するまでこれを繰り返します。自律性の範囲は、単一のツール呼び出しから、複雑なタスクの長期的な実行まで多岐にわたります。", "definition": "AIエージェントとは、推論モデルにツール、メモリ、オーケストレーションループを組み合わせることで、目標を達成するために複数のステップにわたって計画し、行動できるようにしたシステムです。", "takeaways": [ "エージェント ＝ モデル ＋ ツール ＋ メモリ ＋ コントロールループ", "エージェントは行動し、チャットボットは回答する。", "ツールの使用は、実際のシステムやデータへの架け橋となる。", "自律性が高まるほど、ガードレールと評価の必要性が増す。", "信頼性はモデルから想定されるものではなく、ハーネスを通じて構築（エンジニアリング）される。" ], "context": [ "単なるLLMはテキストを生成します。一方、エージェントはそのテキストを使用して決定し、行動します。検索、APIの呼び出し、ファイルの書き込み、ワークフローのトリガーを実行し、発生した事象に対応できます。このループにより、単に説明するだけでなく、タスクを完了させることができます。", "エージェントは自律性のスペクトラム上に位置します。自律性の低いエージェントは、厳格な制御下で1つか2つのツール呼び出しを行います。自律性の高いエージェントは、ほとんど監視なしで、分岐を伴う長期的なタスクを実行します。そのため、それ相応に強力なガードレールが必要になります。" ], "architecture": [ "コアとなるループは、認識（sense）→ 決定（decide）→ 行動（act）→ 観察（observe）です。モデルが次のアクションを決定し、オーケストレーターがツールを介してそれを実行し、その結果が観察としてフィードバックされ、目標または停止条件に達するまでループが継続します。", "このループの周囲には、メモリ（状態の保持）、ガードレール（動作の制限）、オブザーバビリティ（何が起きたかの追跡）が配置されます。これらは、エージェントの信頼性を高めるためのハーネスの構成要素です。" ], "components": [ "推論モデル", "ツール", "メモリ", "オーケストレーションループ", "ガードレール", "オブザーバビリティ" ], "pros": [ "タスクをエンドツーエンドで実行する。", "モデルを実稼働システムに接続する。", "途中の失敗から回復する。", "複数ステップにわたるナレッジワークを自動化する。" ], "risks": [ "長期的なタスクにおけるエラーの累積。", "予算制限がない場合のコストとレイテンシ。", "プロンプトインジェクションおよびツールの誤用のリスク。", "単一のプロンプトよりもテストやデバッグが困難。" ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "受信したリクエストを分類してルーティングするトリアージエージェント。", "バグを修正し、テストで検証するコーディングエージェント。", "ウェアハウスにクエリを実行し、レポートを作成するデータエージェント。" ], "faqs": [ { "q": "チャットボットはAIエージェントですか？", "a": "基本的には異なります。チャットボットは回答しますが、エージェントは目標を達成するために、複数のステップにわたってツールを介してアクションを実行します。" }, { "q": "最もシンプルで実用的なエージェントとはどのようなものですか？", "a": "適切に記述された1つまたは2つのツールと、明確な停止条件を持つモデルです。シンプルに開始し、測定によって必要性が示された場合にのみ構造を追加してください。" }, { "q": "エージェントの信頼性を高めるものは何ですか？", "a": "ハーネス：クリーンなツール設計、優れたメモリ、ガードレール、オブザーバビリティ、および評価。単に強力なモデルを用意するだけではありません。" }, { "q": "単一エージェントか、マルチエージェントか？", "a": "タスクが専門化・分離された役割から明確に恩恵を受けるまでは、単一エージェントを優先してください。マルチエージェントは調整のオーバーヘッドを増加させます。" } ] }, "zh": { "title": "什么是 AI 智能体？", "summary": "AI 智能体是一种将模型与工具、内存和控制循环相结合的系统，旨在朝着目标采取行动，而不仅仅是回答单个提示词。它感知情境、决定做什么、通过工具采取行动、观察结果并重复这一过程直至完成。其自主程度从单一的工具调用到复杂任务的长周期执行不等。", "definition": "AI 智能体是一种将推理模型与工具、内存和编排循环相结合的系统，使其能够通过多个步骤进行规划和行动以实现目标。", "takeaways": [ "智能体 = 模型 + 工具 + 内存 + 控制循环。", "智能体行动；聊天机器人回答。", "工具使用是连接真实系统和数据的桥梁。", "更高的自主性意味着更需要护栏和评估。", "可靠性是通过支撑系统（harness）构建出来的，而不是假设模型本身就具备。" ], "context": [ "普通的 LLM 只生成文本。而智能体利用该文本进行决策和行动：它可以进行搜索、调用 API、写入文件或触发工作流，然后对发生的情况做出反应。正是这种循环使其能够完成任务，而不仅仅是描述任务。", "智能体处于不同的自主程度光谱中。低自主性智能体在严格控制下进行一两次工具调用；高自主性智能体在几乎没有监督的情况下运行长周期的分支任务——因此需要相应更强大的护栏。" ], "architecture": [ "核心循环是：感知 → 决策 → 行动 → 观察。模型决定下一步行动，编排器通过工具执行该行动，结果作为观察反馈回来，循环继续，直到达到目标或终止条件。", "围绕这一循环的是内存（用于承载状态）、护栏（用于约束行为）和可观测性（用于追踪发生的情况）。这些是支撑系统（harness）的组成部分，使智能体变得可靠。" ], "components": [ "推理模型", "工具", "内存", "编排循环", "护栏", "可观测性" ], "pros": [ "端到端执行任务。", "将模型连接到实时系统。", "从中间失败中恢复。", "自动化多步骤的知识性工作。" ], "risks": [ "长周期任务中的错误累积。", "在没有预算限制下的成本和延迟。", "提示词注入和工具滥用风险。", "比单个提示词更难测试和调试。" ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "CrewAI", "Model Context Protocol (MCP)" ], "examples": [ "对传入请求进行分类和分流的分诊智能体。", "修复 Bug 并通过测试进行验证的编码智能体。", "查询数据仓库并生成报告的数据智能体。" ], "faqs": [ { "q": "聊天机器人是 AI 智能体吗？", "a": "默认情况下不是。聊天机器人进行回答；而智能体通过工具跨多个步骤采取行动以实现目标。" }, { "q": "最简单且有用的智能体是什么？", "a": "一个拥有一个或两个描述详尽的工具以及明确终止条件的模型。从简单开始，只有在测量表明需要时才添加结构。" }, { "q": "是什么让智能体变得可靠？", "a": "支撑系统：清晰的工具设计、良好的记忆、安全护栏、可观测性和评估——而不仅仅是更强大的模型。" }, { "q": "单智能体还是多智能体？", "a": "优先选择单智能体，除非任务显然能从专门且可分离的角色中受益。多智能体系统会增加协调开销。" } ] } } }, { "slug": "ai-cyberdefense", "category": "governance", "updated": "2026-08-22", "version": "1.0", "url": "https://santismm.com/en/knowledge/ai-cyberdefense", "api": "https://santismm.com/api/knowledge/ai-cyberdefense", "canonical_url": "https://santismm.com/en/knowledge/ai-cyberdefense", "api_url": "https://santismm.com/api/knowledge/ai-cyberdefense", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper", "personal_experience" ] }, "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems", "url": "https://atlas.mitre.org/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" }, { "title": "European Union — AI Act (Regulation 2024/1689)", "url": "https://eur-lex.europa.eu/eli/reg/2024/1689/oj" } ], "related": [ "prompt-injection", "guardrails", "ai-governance", "tool-use", "human-in-the-loop", "harness-engineering" ], "locales": { "en": { "title": "What is AI Cyberdefense?", "summary": "AI cyberdefense is the practice of protecting AI systems — models, agents, the tools they call and the data they reach — from attacks that exploit how those systems reason and act. For agents it is not a layer added afterwards: the controls that stop an attack are the same harness components that make the agent work at all — tool permissions, context boundaries, approval gates, observability. Defending an agent is engineering its harness.", "definition": "AI cyberdefense is the practice of protecting AI systems, and the organisations that operate them, against attacks that target the AI itself — its inputs, its context, its tools and its autonomy — through controls implemented in the harness around the model rather than in the model's weights.", "takeaways": [ "The model is rarely the attack surface; the harness around it is.", "Attacks target an agent's inputs, memory, tools and autonomy — not its parameters.", "You cannot patch a language model against prompt injection. You constrain what a hijacked agent is able to do.", "Every defensive control is also a reliability control: least privilege, validation, approval gates, audit logs.", "Two directions share the name: defending AI systems, and using AI to defend. They share tooling, not threat models." ], "context": [ "Classical application security assumes code decides and data is inert. An agent breaks that assumption: it reads untrusted content and then decides from it, so any document, web page or tool response is a candidate instruction.", "This is where enterprise adoption stalls. Security review is the most common blocker between an agent demo and production, because the risk is unfamiliar: the system behaves exactly as designed and is still abused." ], "architecture": [ "Input boundary — untrusted content is delimited and labelled as data, never concatenated into the instruction channel.", "Tool layer — each tool carries the narrowest credential that still lets it work, and declares whether it is read-only.", "Action gate — irreversible or high-value actions stop for human approval instead of being trusted to the model's judgement.", "Egress control — outbound destinations are allowlisted, so exfiltration needs a hole someone opened deliberately.", "Observability — every tool call, its arguments and its outcome are logged, because an incident you cannot reconstruct is an incident you cannot close.", "Adversarial evaluation — injection and misuse cases run in CI next to the functional tests, so a regression fails a build rather than a customer." ], "components": [ "Threat model for the specific agent", "Least-privilege tool credentials", "Trust boundary between instructions and content", "Human approval gate for irreversible actions", "Egress allowlist", "Tamper-evident audit log of tool calls", "Adversarial evaluation suite", "Incident response procedure that covers agent behaviour" ], "pros": [ "Controls are auditable and testable, unlike model-level assurances that cannot be verified from outside.", "The same work buys reliability: an agent that cannot delete the wrong record by malice cannot delete it by mistake either.", "It maps directly onto obligations organisations already face — EU AI Act robustness and cybersecurity duties, ISO/IEC 42001, NIST AI RMF.", "It gives security review something concrete to approve, which is what unblocks production." ], "risks": [ "Security theatre: a guardrail model filtering text while the agent still holds a write-capable API key.", "Over-restriction that makes the agent useless and pushes people to unofficial copies without any controls.", "Assuming vendor defaults are safe, particularly for third-party tool servers nobody on the team has read.", "Treating it as a one-off review instead of a lifecycle: new tool, new attack surface." ], "tools": [ "OWASP Top 10 for LLM Applications — shared risk vocabulary", "MITRE ATLAS — adversary tactics and techniques observed against AI systems", "NIST AI RMF and its Generative AI Profile", "Input/output guardrail and validation libraries", "Sandboxed execution environments and egress proxies", "Adversarial evaluation harnesses wired into CI" ], "examples": [ "An agent that reads a shared inbox and can send mail: an injected email instructs it to forward the last twenty messages to an external address.", "A coding agent holding a repository token, pointed at a dependency whose README carries hidden instructions.", "An MCP client that connects to a third-party tool server whose tool descriptions contain instructions aimed at the model rather than the developer." ], "faqs": [ { "q": "Will a better model fix prompt injection?", "a": "No. The vulnerability is structural: instructions and content arrive through the same channel, as text. Better models raise the cost of an attack; only the harness limits its blast radius." }, { "q": "How is this different from AI governance?", "a": "Governance decides what is allowed and who answers for it. Cyberdefense makes the allowed thing hard to abuse. They share evidence — logs, evaluations, approvals — which is why they are usually built together." }, { "q": "Where should a team start?", "a": "Write the threat model for one agent, list the worst thing it could be made to do, and remove its ability to do that without a human. Everything else is refinement." }, { "q": "Does this apply to agents that only read?", "a": "Yes, with a smaller surface. A read-only agent can still exfiltrate what it reads, so context boundaries and egress control still matter even when no tool can write." } ] }, "es": { "title": "¿Qué es la ciberdefensa de la IA?", "summary": "La ciberdefensa de la IA es la práctica de proteger sistemas de IA —modelos, agentes, las herramientas que invocan y los datos que alcanzan— frente a ataques que explotan cómo esos sistemas razonan y actúan. En agentes no es una capa que se añade después: los controles que detienen un ataque son los mismos componentes del arnés que hacen que el agente funcione — permisos de herramientas, fronteras de contexto, puertas de aprobación, observabilidad. Defender un agente es diseñar su arnés.", "definition": "La ciberdefensa de la IA es la práctica de proteger los sistemas de IA, y a las organizaciones que los operan, frente a ataques dirigidos a la propia IA —sus entradas, su contexto, sus herramientas y su autonomía— mediante controles implementados en el arnés que rodea al modelo y no en los pesos del modelo.", "takeaways": [ "El modelo rara vez es la superficie de ataque; lo es el arnés que lo rodea.", "Los ataques apuntan a las entradas, la memoria, las herramientas y la autonomía del agente, no a sus parámetros.", "No puedes parchear un modelo de lenguaje contra la inyección de prompts. Lo que limitas es qué puede hacer un agente secuestrado.", "Todo control defensivo es también un control de fiabilidad: mínimo privilegio, validación, puertas de aprobación, registros de auditoría.", "Dos direcciones comparten el nombre: defender sistemas de IA y usar IA para defender. Comparten herramientas, no modelos de amenaza." ], "context": [ "La seguridad de aplicaciones clásica asume que el código decide y los datos son inertes. Un agente rompe esa premisa: lee contenido no confiable y decide a partir de él, así que cualquier documento, página web o respuesta de herramienta es una instrucción en potencia.", "Aquí es donde se atasca la adopción empresarial. La revisión de seguridad es el bloqueo más frecuente entre la demo de un agente y su paso a producción, porque el riesgo es poco familiar: el sistema se comporta exactamente como se diseñó y aun así es abusado." ], "architecture": [ "Frontera de entrada — el contenido no confiable se delimita y se etiqueta como dato, nunca se concatena en el canal de instrucciones.", "Capa de herramientas — cada herramienta lleva la credencial más estrecha con la que sigue funcionando y declara si es de solo lectura.", "Puerta de acción — las acciones irreversibles o de alto valor se detienen para aprobación humana en lugar de confiarse al criterio del modelo.", "Control de salida — los destinos externos están en una allowlist, así que exfiltrar exige un hueco que alguien abrió a propósito.", "Observabilidad — cada llamada a herramienta, sus argumentos y su resultado quedan registrados, porque un incidente que no puedes reconstruir es un incidente que no puedes cerrar.", "Evaluación adversarial — los casos de inyección y abuso se ejecutan en CI junto a las pruebas funcionales, para que una regresión rompa una build y no a un cliente." ], "components": [ "Modelo de amenazas del agente concreto", "Credenciales de herramienta con mínimo privilegio", "Frontera de confianza entre instrucciones y contenido", "Puerta de aprobación humana para acciones irreversibles", "Allowlist de salida", "Registro de auditoría a prueba de manipulación de las llamadas a herramientas", "Suite de evaluación adversarial", "Procedimiento de respuesta a incidentes que cubra el comportamiento del agente" ], "pros": [ "Los controles son auditables y comprobables, a diferencia de las garantías a nivel de modelo, que no se pueden verificar desde fuera.", "El mismo trabajo compra fiabilidad: un agente que no puede borrar el registro equivocado por malicia tampoco puede borrarlo por error.", "Encaja directamente con obligaciones que las organizaciones ya tienen — deberes de robustez y ciberseguridad del Reglamento de IA de la UE, ISO/IEC 42001, NIST AI RMF.", "Le da a la revisión de seguridad algo concreto que aprobar, que es lo que desbloquea el paso a producción." ], "risks": [ "Teatro de seguridad: un modelo guardián filtrando texto mientras el agente sigue teniendo una clave de API con permisos de escritura.", "Restricción excesiva que vuelve inútil al agente y empuja a la gente a copias no oficiales sin ningún control.", "Dar por seguros los valores por defecto del proveedor, en especial en servidores de herramientas de terceros que nadie del equipo ha leído.", "Tratarlo como una revisión puntual en vez de como un ciclo de vida: herramienta nueva, superficie de ataque nueva." ], "tools": [ "OWASP Top 10 para aplicaciones LLM — vocabulario común de riesgos", "MITRE ATLAS — tácticas y técnicas adversarias observadas contra sistemas de IA", "NIST AI RMF y su perfil de IA generativa", "Librerías de guardrails y validación de entrada/salida", "Entornos de ejecución en sandbox y proxies de salida", "Arneses de evaluación adversarial integrados en CI" ], "examples": [ "Un agente que lee un buzón compartido y puede enviar correo: un email inyectado le ordena reenviar los últimos veinte mensajes a una dirección externa.", "Un agente de programación con un token del repositorio, apuntado a una dependencia cuyo README lleva instrucciones ocultas.", "Un cliente MCP que se conecta a un servidor de herramientas de terceros cuyas descripciones contienen instrucciones dirigidas al modelo y no al desarrollador." ], "faqs": [ { "q": "¿Un modelo mejor resuelve la inyección de prompts?", "a": "No. La vulnerabilidad es estructural: instrucciones y contenido llegan por el mismo canal, como texto. Un modelo mejor encarece el ataque; solo el arnés limita su radio de daño." }, { "q": "¿En qué se diferencia de la gobernanza de IA?", "a": "La gobernanza decide qué está permitido y quién responde. La ciberdefensa hace que lo permitido sea difícil de abusar. Comparten evidencia —registros, evaluaciones, aprobaciones—, por eso suelen construirse juntas." }, { "q": "¿Por dónde empieza un equipo?", "a": "Escribe el modelo de amenazas de un agente, enumera lo peor que se le podría hacer hacer y quítale la capacidad de hacerlo sin un humano. Todo lo demás es refinamiento." }, { "q": "¿Aplica a agentes que solo leen?", "a": "Sí, con menos superficie. Un agente de solo lectura puede exfiltrar lo que lee, así que las fronteras de contexto y el control de salida siguen importando aunque ninguna herramienta escriba." } ] }, "pt": { "title": "O que é a ciberdefesa de IA?", "summary": "A ciberdefesa de IA é a prática de proteger sistemas de IA — modelos, agentes, as ferramentas que eles chamam e os dados que alcançam — contra ataques que exploram como esses sistemas raciocinam e agem. Em agentes não é uma camada adicionada depois: os controles que detêm um ataque são os mesmos componentes do harness que fazem o agente funcionar — permissões de ferramentas, fronteiras de contexto, portões de aprovação, observabilidade. Defender um agente é projetar o seu harness.", "definition": "A ciberdefesa de IA é a prática de proteger os sistemas de IA, e as organizações que os operam, contra ataques dirigidos à própria IA — suas entradas, seu contexto, suas ferramentas e sua autonomia — por meio de controles implementados no harness ao redor do modelo, e não nos pesos do modelo.", "takeaways": [ "O modelo raramente é a superfície de ataque; o harness ao redor dele é.", "Os ataques miram as entradas, a memória, as ferramentas e a autonomia do agente — não seus parâmetros.", "Não dá para corrigir um modelo de linguagem contra injeção de prompt. O que se limita é o que um agente sequestrado consegue fazer.", "Todo controle defensivo também é de confiabilidade: privilégio mínimo, validação, portões de aprovação, trilhas de auditoria.", "Duas direções compartilham o nome: defender sistemas de IA e usar IA para defender. Compartilham ferramentas, não modelos de ameaça." ], "context": [ "A segurança de aplicações clássica assume que o código decide e os dados são inertes. Um agente quebra essa premissa: ele lê conteúdo não confiável e decide a partir dele, então qualquer documento, página web ou resposta de ferramenta é uma instrução em potencial.", "É aqui que a adoção empresarial trava. A revisão de segurança é o bloqueio mais comum entre a demo de um agente e a produção, porque o risco é pouco familiar: o sistema se comporta exatamente como projetado e ainda assim é abusado." ], "architecture": [ "Fronteira de entrada — o conteúdo não confiável é delimitado e rotulado como dado, nunca concatenado no canal de instruções.", "Camada de ferramentas — cada ferramenta carrega a credencial mais estreita com que ainda funciona e declara se é somente leitura.", "Portão de ação — ações irreversíveis ou de alto valor param para aprovação humana em vez de serem confiadas ao julgamento do modelo.", "Controle de saída — os destinos externos ficam em uma allowlist, então exfiltrar exige uma brecha que alguém abriu de propósito.", "Observabilidade — cada chamada de ferramenta, seus argumentos e seu resultado ficam registrados, porque um incidente que você não consegue reconstruir é um incidente que você não consegue encerrar.", "Avaliação adversarial — casos de injeção e abuso rodam no CI ao lado dos testes funcionais, para que uma regressão quebre um build e não um cliente." ], "components": [ "Modelo de ameaças do agente específico", "Credenciais de ferramenta com privilégio mínimo", "Fronteira de confiança entre instruções e conteúdo", "Portão de aprovação humana para ações irreversíveis", "Allowlist de saída", "Trilha de auditoria à prova de adulteração das chamadas de ferramentas", "Suíte de avaliação adversarial", "Procedimento de resposta a incidentes que cubra o comportamento do agente" ], "pros": [ "Os controles são auditáveis e testáveis, ao contrário de garantias no nível do modelo, que não podem ser verificadas de fora.", "O mesmo trabalho compra confiabilidade: um agente que não pode apagar o registro errado por malícia também não o apaga por engano.", "Encaixa diretamente em obrigações que as organizações já têm — deveres de robustez e cibersegurança do Regulamento de IA da UE, ISO/IEC 42001, NIST AI RMF.", "Dá à revisão de segurança algo concreto para aprovar, que é o que desbloqueia a produção." ], "risks": [ "Teatro de segurança: um modelo guardião filtrando texto enquanto o agente continua com uma chave de API com permissão de escrita.", "Restrição excessiva que torna o agente inútil e empurra as pessoas para cópias não oficiais sem controle algum.", "Assumir que os padrões do fornecedor são seguros, sobretudo em servidores de ferramentas de terceiros que ninguém da equipe leu.", "Tratar como revisão pontual em vez de ciclo de vida: ferramenta nova, superfície de ataque nova." ], "tools": [ "OWASP Top 10 para aplicações LLM — vocabulário comum de riscos", "MITRE ATLAS — táticas e técnicas adversariais observadas contra sistemas de IA", "NIST AI RMF e seu perfil de IA generativa", "Bibliotecas de guardrails e validação de entrada/saída", "Ambientes de execução em sandbox e proxies de saída", "Harnesses de avaliação adversarial integrados ao CI" ], "examples": [ "Um agente que lê uma caixa de entrada compartilhada e pode enviar e-mail: um e-mail injetado manda encaminhar as últimas vinte mensagens para um endereço externo.", "Um agente de programação com um token do repositório, apontado para uma dependência cujo README carrega instruções ocultas.", "Um cliente MCP que se conecta a um servidor de ferramentas de terceiros cujas descrições contêm instruções dirigidas ao modelo, e não ao desenvolvedor." ], "faqs": [ { "q": "Um modelo melhor resolve a injeção de prompt?", "a": "Não. A vulnerabilidade é estrutural: instruções e conteúdo chegam pelo mesmo canal, como texto. Um modelo melhor encarece o ataque; só o harness limita o raio do dano." }, { "q": "Qual a diferença para a governança de IA?", "a": "A governança decide o que é permitido e quem responde. A ciberdefesa torna o permitido difícil de abusar. Compartilham evidência — registros, avaliações, aprovações —, por isso costumam ser construídas juntas." }, { "q": "Por onde uma equipe começa?", "a": "Escreva o modelo de ameaças de um agente, liste a pior coisa que ele poderia ser levado a fazer e retire a capacidade de fazê-la sem um humano. O resto é refinamento." }, { "q": "Vale para agentes que só leem?", "a": "Sim, com superfície menor. Um agente somente leitura ainda pode exfiltrar o que lê, então fronteiras de contexto e controle de saída continuam importando mesmo sem nenhuma ferramenta de escrita." } ] }, "fr": { "title": "Qu'est-ce que la cyberdéfense de l'IA ?", "summary": "La cyberdéfense de l'IA est la pratique consistant à protéger les systèmes d'IA — modèles, agents, outils qu'ils appellent et données auxquelles ils accèdent — contre les attaques qui exploitent la façon dont ces systèmes raisonnent et agissent. Pour les agents, il ne s'agit pas d'une couche ajoutée après coup : les contrôles qui bloquent une attaque sont les mêmes composants du harness qui permettent à l'agent de fonctionner — permissions des outils, limites de contexte, barrières d'approbation, observabilité. Défendre un agent revient à concevoir son harness.", "definition": "La cyberdéfense de l'IA est la pratique consistant à protéger les systèmes d'IA, ainsi que les organisations qui les exploitent, contre les attaques ciblant l'IA elle-même — ses entrées, son contexte, ses outils et son autonomie — grâce à des contrôles implémentés dans le harness autour du modèle plutôt que dans les poids du modèle.", "takeaways": [ "Le modèle est rarement la surface d'attaque ; c'est le harness qui l'entoure qui l'est.", "Les attaques ciblent les entrées, la mémoire, les outils et l'autonomie d'un agent — pas ses paramètres.", "Vous ne pouvez pas corriger un modèle de langage contre l'injection de requêtes. Vous devez limiter ce qu'un agent détourné est capable de faire.", "Chaque contrôle défensif est également un contrôle de fiabilité : moindre privilège, validation, barrières d'approbation, journaux d'audit.", "Deux directions partagent ce nom : défendre les systèmes d'IA et utiliser l'IA pour défendre. Elles partagent des outils, pas des modèles de menace." ], "context": [ "La sécurité applicative classique suppose que le code décide et que les données sont inertes. Un agent brise cette hypothèse : il lit du contenu non fiable puis prend des décisions à partir de celui-ci, de sorte que tout document, page web ou réponse d'outil est une instruction potentielle.", "C'est là que l'adoption en entreprise stagne. L'examen de sécurité est le bloqueur le plus courant entre la démo d'un agent et sa mise en production, car le risque est inhabituel : le système se comporte exactement comme prévu et fait pourtant l'objet d'abus." ], "architecture": [ "Limite d'entrée — le contenu non fiable est délimité et étiqueté comme donnée, jamais concaténé dans le canal d'instructions.", "Couche d'outils — chaque outil dispose de l'identifiant le plus restreint possible lui permettant de fonctionner, et déclare s'il est en lecture seule.", "Barrière d'action — les actions irréversibles ou à forte valeur s'arrêtent pour obtenir une approbation humaine au lieu de s'en remettre au jugement du modèle.", "Contrôle de sortie — les destinations sortantes sont sur liste autorisée, de sorte que l'exfiltration nécessite une faille ouverte délibérément.", "Observabilité — chaque appel d'outil, ses arguments et son résultat sont enregistrés, car un incident que vous ne pouvez pas reconstruire est un incident que vous ne pouvez pas résoudre.", "Évaluation contradictoire — les cas d'injection et d'abus s'exécutent dans la CI aux côtés des tests fonctionnels, de sorte qu'une régression fait échouer un build plutôt qu'un client." ], "components": [ "Modèle de menace pour l'agent spécifique", "Identifiants d'outils au moindre privilège", "Limite de confiance entre instructions et contenu", "Barrière d'approbation humaine pour les actions irréversibles", "Liste autorisée de sortie", "Journal d'audit infalsifiable des appels d'outils", "Suite d'évaluations contradictoires", "Procédure de réponse aux incidents couvrant le comportement de l'agent" ], "pros": [ "Les contrôles sont auditables et testables, contrairement aux assurances au niveau du modèle qui ne peuvent pas être vérifiées de l'extérieur.", "Le même travail garantit la fiabilité : un agent qui ne peut pas supprimer le mauvais enregistrement par malveillance ne peut pas non plus le supprimer par erreur.", "Il s'aligne directement sur les obligations auxquelles les organisations sont déjà confrontées — obligations de robustesse et de cybersécurité de l'EU AI Act, ISO/IEC 42001, NIST AI RMF.", "Il donne à l'examen de sécurité un élément concret à approuver, ce qui débloque la mise en production." ], "risks": [ "Théâtre de la sécurité : un modèle de garde-fous filtrant le texte alors que l'agent détient toujours une clé API avec droits d'écriture.", "Une restriction excessive qui rend l'agent inutile et pousse les utilisateurs vers des copies non officielles sans aucun contrôle.", "Supposer que les paramètres par défaut des fournisseurs sont sûrs, en particulier pour les serveurs d'outils tiers que personne dans l'équipe n'a analysés.", "Traiter cela comme un examen ponctuel plutôt que comme un cycle de vie : nouvel outil, nouvelle surface d'attaque." ], "tools": [ "OWASP Top 10 pour les applications LLM — vocabulaire de risque partagé", "MITRE ATLAS — tactiques et techniques d'adversaires observées contre les systèmes d'IA", "NIST AI RMF et son profil d'IA générative", "Bibliothèques de validation et de garde-fous d'entrée/sortie", "Environnements d'exécution isolés (sandbox) et proxys de sortie", "Harnesses d'évaluation contradictoire intégrés à la CI" ], "examples": [ "Un agent qui lit une boîte de réception partagée et peut envoyer des e-mails : un e-mail injecté lui ordonne de transférer les vingt derniers messages à une adresse externe.", "Un agent de codage détenant un jeton de dépôt, orienté vers une dépendance dont le fichier README contient des instructions cachées.", "Un client MCP qui se connecte à un serveur d'outils tiers dont les descriptions d'outils contiennent des instructions destinées au modèle plutôt qu'au développeur." ], "faqs": [ { "q": "Un meilleur modèle résoudra-t-il l'injection de requêtes ?", "a": "Non. La vulnérabilité est structurelle : les instructions et le contenu arrivent par le même canal, sous forme de texte. Les meilleurs modèles augmentent le coût d'une attaque ; seul le harness limite son rayon d'action." }, { "q": "En quoi cela diffère-t-il de la gouvernance de l'IA ?", "a": "La gouvernance décide de ce qui est autorisé et de qui en est responsable. La cyberdéfense rend difficile l'abus de ce qui est autorisé. Elles partagent des preuves — journaux, évaluations, approbations — c'est pourquoi elles sont généralement construites ensemble." }, { "q": "Par quoi une équipe devrait-elle commencer ?", "a": "Rédigez le modèle de menace pour un agent, listez la pire chose qu'on pourrait lui faire faire, et supprimez sa capacité à le faire sans intervention humaine. Tout le reste n'est que raffinement." }, { "q": "Cela s'applique-t-il aux agents qui ne font que lire ?", "a": "Oui, avec une surface plus réduite. Un agent en lecture seule peut toujours exfiltrer ce qu'il lit, de sorte que les limites de contexte et le contrôle de sortie restent importants même si aucun outil ne peut écrire." } ] }, "de": { "title": "Was ist KI-Cyberdefense?", "summary": "KI-Cyberdefense ist die Praxis des Schutzes von KI-Systemen – Modellen, Agenten, den von ihnen aufgerufenen Tools und den Daten, auf die sie zugreifen – vor Angriffen, die die Funktionsweise und das Handeln dieser Systeme ausnutzen. Bei Agenten handelt es sich nicht um eine nachträglich hinzugefügte Schicht: Die Kontrollen, die einen Angriff stoppen, sind dieselben Harness-Komponenten, die den Agenten überhaupt erst funktionsfähig machen – Tool-Berechtigungen, Kontextgrenzen, Freigabe-Gates, Observability. Einen Agenten zu verteidigen bedeutet, sein Harness zu entwickeln.", "definition": "KI-Cyberdefense ist die Praxis des Schutzes von KI-Systemen und den sie betreibenden Organisationen vor Angriffen, die auf die KI selbst abzielen – ihre Eingaben, ihren Kontext, ihre Tools und ihre Autonomie – durch Kontrollen, die im Harness um das Modell herum implementiert sind, statt in den Gewichten des Modells.", "takeaways": [ "Das Modell ist selten die Angriffsfläche; es ist das Harness um das Modell herum.", "Angriffe zielen auf die Eingaben, den Speicher, die Tools und die Autonomie eines Agenten ab – nicht auf seine Parameter.", "Man kann ein Sprachmodell nicht gegen Prompt Injection patchen. Man schränkt stattdessen ein, was ein gekaperter Agent tun kann.", "Jede defensive Kontrolle ist auch eine Zuverlässigkeitskontrolle: Least Privilege, Validierung, Freigabe-Gates, Audit-Logs.", "Zwei Richtungen teilen sich den Namen: die Verteidigung von KI-Systemen und der Einsatz von KI zur Verteidigung. Sie teilen sich die Tools, nicht die Bedrohungsmodelle." ], "context": [ "Die klassische Anwendungssicherheit geht davon aus, dass Code entscheidet und Daten träge sind. Ein Agent bricht mit dieser Annahme: Er liest nicht vertrauenswürdige Inhalte und entscheidet dann auf dieser Grundlage. Jedes Dokument, jede Webseite oder jede Tool-Antwort ist somit eine potenzielle Anweisung.", "Hier stockt die Einführung in Unternehmen. Die Sicherheitsüberprüfung ist der häufigste Blocker zwischen einer Agenten-Demo und der Produktionsumgebung, da das Risiko ungewohnt ist: Das System verhält sich genau wie entworfen und wird dennoch missbraucht." ], "architecture": [ "Eingabegrenze – nicht vertrauenswürdige Inhalte werden abgegrenzt und als Daten gekennzeichnet, niemals in den Anweisungskanal verkettet.", "Tool-Ebene – jedes Tool verfügt über die minimal erforderlichen Berechtigungen, die für seine Funktion nötig sind, und deklariert, ob es schreibgeschützt ist.", "Aktions-Gate – irreversible oder folgenschwere Aktionen erfordern eine menschliche Freigabe, anstatt dem Urteil des Modells zu vertrauen.", "Egress-Kontrolle – ausgehende Ziele stehen auf einer Allowlist, sodass eine Exfiltration eine bewusst geöffnete Lücke erfordert.", "Observability – jeder Tool-Aufruf, seine Argumente und sein Ergebnis werden protokolliert, denn ein Vorfall, den man nicht rekonstruieren kann, ist ein Vorfall, den man nicht abschließen kann.", "Adversarial Evaluation – Injektions- und Missbrauchsfälle laufen in der CI neben den funktionalen Tests, sodass eine Regression den Build fehlschlagen lässt und nicht beim Kunden auftritt." ], "components": [ "Bedrohungsmodell für den spezifischen Agenten", "Tool-Zugangsdaten nach dem Minimalprinzip (Least Privilege)", "Vertrauensgrenze zwischen Anweisungen und Inhalten", "Menschliches Freigabe-Gate für irreversible Aktionen", "Egress-Allowlist", "Manipulationssicheres Audit-Log von Tool-Aufrufen", "Adversarial-Evaluation-Suite", "Incident-Response-Verfahren, das das Verhalten des Agenten abdeckt" ], "pros": [ "Kontrollen sind auditierbar und testbar, im Gegensatz zu Zusicherungen auf Modellebene, die von außen nicht überprüft werden können.", "Derselbe Aufwand sorgt für Zuverlässigkeit: Ein Agent, der einen falschen Datensatz nicht böswillig löschen kann, kann ihn auch nicht versehentlich löschen.", "Es lässt sich direkt auf Verpflichtungen übertragen, vor denen Organisationen bereits stehen – Robustheits- und Cybersicherheitsanforderungen des EU AI Act, ISO/IEC 42001, NIST AI RMF.", "Es gibt der Sicherheitsüberprüfung etwas Konkretes zur Freigabe, was den Weg in die Produktion ebnet." ], "risks": [ "Sicherheitstheater: Ein Guardrail-Modell filtert Text, während der Agent immer noch einen API-Schlüssel mit Schreibrechten besitzt.", "Übermäßige Einschränkung, die den Agenten unbrauchbar macht und Nutzer zu inoffiziellen Kopien ohne jegliche Kontrollen drängt.", "Die Annahme, dass Standardeinstellungen von Anbietern sicher sind, insbesondere bei Tool-Servern von Drittanbietern, die niemand im Team geprüft hat.", "Die Behandlung als einmalige Überprüfung statt als Lebenszyklus: neues Tool, neue Angriffsfläche." ], "tools": [ "OWASP Top 10 für LLM-Anwendungen – gemeinsames Risikovokabular", "MITRE ATLAS – gegen KI-Systeme beobachtete Taktiken und Techniken von Angreifern", "NIST AI RMF und dessen Generative AI Profile", "Bibliotheken für Input/Output-Guardrails und Validierung", "Sandboxed-Ausführungsumgebungen und Egress-Proxies", "In die CI integrierte Adversarial-Evaluation-Harnesses" ], "examples": [ "Ein Agent, der ein gemeinsames Postfach liest und E-Mails senden kann: Eine eingeschleuste E-Mail weist ihn an, die letzten zwanzig Nachrichten an eine externe Adresse weiterzuleiten.", "Ein Coding-Agent mit einem Repository-Token, der auf eine Abhängigkeit ausgerichtet ist, deren README versteckte Anweisungen enthält.", "Ein MCP-Client, der sich mit dem Tool-Server eines Drittanbieters verbindet, dessen Tool-Beschreibungen Anweisungen enthalten, die sich an das Modell und nicht an den Entwickler richten." ], "faqs": [ { "q": "Wird ein besseres Modell Prompt Injection beheben?", "a": "Nein. Die Schwachstelle ist strukturell: Anweisungen und Inhalte kommen über denselben Kanal als Text an. Bessere Modelle erhöhen die Kosten eines Angriffs; nur das Harness begrenzt dessen Schadensradius." }, { "q": "Wie unterscheidet sich dies von AI Governance?", "a": "Governance entscheidet, was erlaubt ist und wer dafür verantwortlich ist. Cyberdefense sorgt dafür, dass das Erlaubte schwer zu missbrauchen ist. Sie teilen sich Nachweise – Logs, Evaluationen, Freigaben –, weshalb sie meist zusammen aufgebaut werden." }, { "q": "Wo sollte ein Team anfangen?", "a": "Erstellen Sie das Bedrohungsmodell für einen einzelnen Agenten, listen Sie das Schlimmste auf, was er tun könnte, und entziehen Sie ihm die Fähigkeit, dies ohne menschliche Freigabe zu tun. Alles andere ist Feinschliff." }, { "q": "Gilt dies auch für Agenten, die nur lesen?", "a": "Ja, wenn auch mit einer kleineren Angriffsfläche. Ein schreibgeschützter Agent kann dennoch die gelesenen Daten exfiltrieren, weshalb Kontextgrenzen und Egress-Kontrolle auch dann wichtig sind, wenn kein Tool schreiben kann." } ] }, "ja": { "title": "AIサイバーディフェンスとは？", "summary": "AIサイバーディフェンスとは、AIシステム（モデル、エージェント、それらが呼び出すツール、アクセスするデータ）を、それらのシステムの推論や行動の仕組みを悪用する攻撃から保護する取り組みです。エージェントにとって、これは後から追加するレイヤーではありません。攻撃を阻止するコントロールは、エージェントを機能させるためのハーネスコンポーネント（ツールの権限、コンテキスト境界、承認ゲート、オブザーバビリティ）そのものです。エージェントを防御することは、そのハーネスをエンジニアリングすることに他なりません。", "definition": "AIサイバーディフェンスとは、AIシステムおよびそれを運用する組織を、AI自体（その入力、コンテキスト、ツール、自律性）を標的とする攻撃から保護する取り組みです。これはモデルの重みではなく、モデルを取り囲むハーネスに実装されたコントロールを通じて行われます。", "takeaways": [ "攻撃対象領域（アタックサーフェス）になるのはモデル自体ではなく、ほとんどの場合、それを取り囲むハーネスです。", "攻撃が標的とするのは、エージェントの入力、メモリ、ツール、自律性であり、そのパラメータではありません。", "プロンプトインジェクションに対して言語モデルにパッチを適用することはできません。乗っ取られたエージェントが実行できる行動を制限するのです。", "すべての防御コントロール（最小権限、バリデーション、承認ゲート、監査ログ）は、信頼性コントロールでもあります。", "この名称には、AIシステムの防御と、防御のためのAIの活用という2つの方向性があります。これらはツールを共有しますが、脅威モデルは共有しません。" ], "context": [ "従来のアプリケーションセキュリティは、コードが決定を下し、データは不活性であることを前提としています。エージェントはこの前提を覆します。信頼できないコンテンツを読み込み、それに基づいて決定を下すため、あらゆるドキュメント、ウェブページ、ツールの応答が指示（インストラクション）の候補になり得るのです。", "ここで企業の導入が停滞します。エージェントのデモから本番環境への移行において、セキュリティレビューは最も一般的な障害となっています。なぜなら、そのリスクが未知のものであるためです。システムは設計通りに動作しているにもかかわらず、悪用されてしまうのです。" ], "architecture": [ "入力境界 — 信頼できないコンテンツはデータとして区切られ、ラベル付けされます。指示チャネルに直接結合されることは決してありません。", "ツールレイヤー — 各ツールは、動作に必要な最小限の資格情報（クレデンシャル）のみを保持し、読み取り専用であるかどうかを宣言します。", "アクションゲート — 不可逆的なアクションや価値の高いアクションは、モデルの判断に委ねるのではなく、人間の承認を得るために一時停止します。", "送信制御（エグレスコントロール） — 外部への送信先は許可リスト（アローリスト）に登録されるため、データの持ち出しには誰かが意図的に開けた穴が必要になります。", "オブザーバビリティ — すべてのツール呼び出し、その引数、および結果がログに記録されます。再現できないインシデントは、解決できないインシデントだからです。", "敵対的評価 — インジェクションや悪用のユースケースは、機能テストと並行してCIで実行されます。これにより、デグレードが発生した場合は、顧客に影響が及ぶ前にビルドが失敗します。" ], "components": [ "特定のエージェントに対する脅威モデル", "最小権限のツール資格情報", "指示とコンテンツの間の信頼境界", "不可逆的なアクションに対する人間の承認ゲート", "送信許可リスト", "改ざん検知可能なツール呼び出しの監査ログ", "敵対的評価スイート", "エージェントの行動をカバーするインシデント対応手順" ], "pros": [ "外部から検証できないモデルレベルの保証とは異なり、コントロールは監査可能かつテスト可能です。", "同じ取り組みが信頼性の向上にもつながります。悪意によって誤ったレコードを削除できないエージェントは、誤って削除することもありません。", "これは、組織がすでに直面している義務（EU AI法における堅牢性とサイバーセキュリティの義務、ISO/IEC 42001、NIST AI RMFなど）に直接マッピングされます。", "セキュリティレビューにおいて承認すべき具体的な対象が明確になり、本番環境への移行を阻む要因が解消されます。" ], "risks": [ "セキュリティシアター（形だけのセキュリティ）：エージェントが書き込み権限を持つAPIキーを保持したままで、ガードレールモデルがテキストをフィルタリングしている状態。", "過度な制限によりエージェントが使い物にならなくなり、ユーザーがコントロールのない非公式のコピーに流れてしまうこと。", "ベンダーのデフォルト設定が安全であると仮定すること。特に、チームの誰もコードを確認していないサードパーティのツールサーバーにおいて顕著です。", "これをライフサイクルとしてではなく、単発のレビューとして扱うこと。新しいツールは、新しい攻撃対象領域（アタックサーフェス）を意味します。" ], "tools": [ "OWASP Top 10 for LLM Applications — 共通の脅威語彙", "MITRE ATLAS — AIシステムに対して観測された敵対者の戦術と技術", "NIST AI RMFおよびそのジェネレーティブAIプロファイル", "入出力ガードレールおよびバリデーションライブラリ", "サンドボックス化された実行環境および送信（エグレス）プロキシ", "CIに組み込まれた敵対的評価ハーネス" ], "examples": [ "共有受信トレイを読み取り、メールを送信できるエージェント：インジェクションされたメールが、直近の20件のメッセージを外部のアドレスに転送するようエージェントに指示するケース。", "リポジトリトークンを保持するコーディングエージェントが、READMEに隠された指示が含まれる依存関係を指しているケース。", "MCPクライアントがサードパーティのツールサーバーに接続し、そのツールの説明に開発者ではなくモデルを標的とした指示が含まれているケース。" ], "faqs": [ { "q": "より優れたモデルを使用すれば、プロンプトインジェクションは解決しますか？", "a": "いいえ。この脆弱性は構造的なものです。指示とコンテンツがテキストとして同じチャネルを通じて届くためです。優れたモデルは攻撃のコストを上げますが、その影響範囲（ブラストライジアス）を制限できるのはハーネスだけです。" }, { "q": "これはAIガバナンスとどう違うのですか？", "a": "ガバナンスは何が許可され、誰がその責任を負うかを決定します。サイバーディフェンスは、許可されたものが悪用されにくくします。これらはログ、評価、承認などの証跡を共有するため、通常は一緒に構築されます。" }, { "q": "チームはどこから始めるべきですか？", "a": "1つのエージェントに対する脅威モデルを作成し、実行させられ得る最悪の事態をリストアップし、人間の介在なしにそれを実行できないようにします。それ以外はすべて微調整です。" }, { "q": "これは読み取り専用のエージェントにも適用されますか？", "a": "はい、ただし攻撃対象領域は小さくなります。読み取り専用のエージェントであっても、読み取った内容を持ち出すことは可能なため、書き込み可能なツールがない場合でも、コンテキスト境界と送信制御（エグレスコントロール）は依然として重要です。" } ] }, "zh": { "title": "什么是 AI 网络防御？", "summary": "AI 网络防御是保护 AI 系统（模型、智能体、它们调用的工具以及它们访问的数据）免受利用这些系统推理和行为方式的攻击的实践。对于智能体而言，它不是事后添加的层：阻止攻击的控制措施与使智能体正常工作的支撑系统组件完全相同——工具权限、上下文边界、审批关口、可观测性。防御智能体就是构建其支撑系统。", "definition": "AI 网络防御是保护 AI 系统及其运营组织免受针对 AI 自身（其输入、上下文、工具和自主性）攻击的实践，这些防御是通过在模型周围的支撑系统中实施控制，而不是在模型权重中实施控制来实现的。", "takeaways": [ "模型本身很少是攻击面；其周围的支撑系统才是。", "攻击的目标是智能体的输入、记忆、工具和自主性——而不是其参数。", "你无法通过给语言模型打补丁来防御提示词注入。你只能限制被劫持的智能体所能做的事情。", "每项防御性控制同时也是可靠性控制：最小特权、验证、审批关口、审计日志。", "有两个方向共享这一名称：防御 AI 系统，以及使用 AI 进行防御。它们共享工具，但不共享威胁模型。" ], "context": [ "传统应用安全假设代码做决策而数据是惰性的。智能体打破了这一假设：它读取不可信的内容，然后据此做出决策，因此任何文档、网页或工具响应都可能成为潜在的指令。", "这就是企业落地停滞不前的原因。安全审查是智能体从 Demo 走向生产环境最常见的阻碍，因为这种风险是陌生的：系统完全按照设计运行，但仍然会被滥用。" ], "architecture": [ "输入边界——不可信内容被界定并标记为数据，绝不直接拼接进指令通道。", "工具层——每个工具仅携带能使其正常工作的最小凭证，并声明其是否为只读。", "操作关口——不可逆或高价值的操作会暂停以等待人工审批，而不是完全信任模型的判断。", "出口控制——出口目的地被列入白名单，因此数据外泄需要有人故意留出的漏洞。", "可观测性——每次工具调用、其参数和结果都会被记录，因为无法重现的安全事件就是无法结案的事件。", "对抗性评估——注入和滥用用例在 CI 中与功能测试并排运行，因此回归问题会导致构建失败，而不是让客户受损。" ], "components": [ "针对特定智能体的威胁模型", "最小特权工具凭证", "指令与内容之间的信任边界", "针对不可逆操作的人工审批关口", "出口白名单", "防篡改的工具调用审计日志", "对抗性评估套件", "覆盖智能体行为的事件响应流程" ], "pros": [ "控制措施是可审计和可测试的，不像模型层面的保证那样无法从外部验证。", "同样的工作也能带来可靠性：一个无法因恶意删除错误记录的智能体，也同样不会因失误而删除它。", "它直接对应了组织已经面临的义务——欧盟《AI 法案》的鲁棒性和网络安全职责、ISO/IEC 42001、NIST AI RMF。", "它为安全审查提供了具体的审批依据，而这正是打通生产环境的关键。" ], "risks": [ "安全演戏：一个护栏模型在过滤文本，而智能体却仍然持有具备写入权限的 API 密钥。", "过度限制导致智能体无法使用，并迫使用户转向没有任何控制措施的非官方副本。", "假设供应商默认设置是安全的，特别是对于团队中无人阅读过其代码的第三方工具服务器。", "将其视为一次性审查，而不是一个生命周期：新工具意味着新的攻击面。" ], "tools": [ "OWASP LLM 应用十大安全漏洞——共享的风险词汇表", "MITRE ATLAS——针对 AI 系统观察到的对手战术和技术", "NIST AI RMF 及其生成式 AI 配置文件", "输入/输出护栏和验证库", "沙箱执行环境和出口代理", "接入 CI 的对抗性评估支撑系统" ], "examples": [ "一个读取共享收件箱并能发送邮件的智能体：一封被注入的电子邮件指示它将最后二十条消息转发到外部地址。", "一个持有代码仓库 Token 的编码智能体，指向一个其 README 包含隐藏指令的依赖项。", "一个连接到第三方工具服务器的 MCP 客户端，该服务器的工具描述中包含针对模型而非开发者的指令。" ], "faqs": [ { "q": "更强大的模型能解决提示词注入问题吗？", "a": "不能。该漏洞是结构性的：指令和内容通过同一个通道（即文本）传入。更好的模型只是提高了攻击成本；只有支撑系统才能限制其爆炸半径。" }, { "q": "这与 AI 治理有什么不同？", "a": "治理决定了什么是被允许的以及谁为此负责。网络防御则使被允许的事情难以被滥用。它们共享证据（日志、评估、审批），这就是为什么它们通常是一起构建的。" }, { "q": "团队应该从哪里开始？", "a": "为单个智能体编写威胁模型，列出它可能被诱导做出的最糟糕的事情，并在没有人工干预的情况下剥夺其执行该操作的能力。其余的一切都是细化完善。" }, { "q": "这适用于仅有读取权限的智能体吗？", "a": "适用，但攻击面较小。只读智能体仍然可以外泄它读取的内容，因此即使没有工具可以执行写入操作，上下文边界和出口控制仍然至关重要。" } ] } } }, { "slug": "ai-governance", "category": "governance", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/ai-governance", "api": "https://santismm.com/api/knowledge/ai-governance", "canonical_url": "https://santismm.com/en/knowledge/ai-governance", "api_url": "https://santismm.com/api/knowledge/ai-governance", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "paper", "industry_observation" ] }, "references": [ { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" }, { "title": "European Union — AI Act (Regulation 2024/1689)", "url": "https://eur-lex.europa.eu/eli/reg/2024/1689/oj" }, { "title": "ISO/IEC 42001:2023 — AI management systems", "url": "https://www.iso.org/standard/81230.html" } ], "related": [ "enterprise-rag", "agentic-evaluation", "agentic-ai", "harness-engineering" ], "locales": { "en": { "title": "What is AI Governance?", "summary": "AI governance is the set of policies, processes, roles and controls that ensure AI is built and used responsibly, legally and safely. It spans risk management, accountability, transparency, security and compliance across the AI lifecycle. In practice it operationalizes recognized frameworks — the EU AI Act, the NIST AI Risk Management Framework and ISO/IEC 42001 — into concrete controls an organization can implement, evidence and audit.", "definition": "AI governance is the framework of policies, processes, roles and controls an organization uses to manage AI risk and ensure AI systems are responsible, compliant, secure and accountable across their lifecycle.", "takeaways": [ "Governance turns AI principles into enforceable, auditable controls.", "It spans the full lifecycle: data, build, deploy, monitor, retire.", "Major references: EU AI Act, NIST AI RMF, ISO/IEC 42001.", "Agentic AI raises the stakes: autonomy and tool access widen risk.", "Good governance enables adoption; it is not just a brake." ], "context": [ "As AI moves into decisions that affect people and operations, organizations need a way to manage its risks systematically — not ad hoc. Governance provides that: clear ownership, documented risk assessment, controls, monitoring and the evidence to demonstrate compliance.", "Agentic systems sharpen the need. When software can act autonomously and call tools, the questions of authorization, accountability, auditability and human oversight become operational, not theoretical." ], "architecture": [ "A practical governance program has layers: policy and principles; an AI risk catalog and assessment process; controls (access, data handling, evaluation, human oversight, logging); monitoring and incident response; and an audit trail that maps controls to external frameworks.", "Frameworks complement each other. The NIST AI RMF organizes practice around Govern, Map, Measure and Manage. ISO/IEC 42001 defines an auditable AI management system. The EU AI Act sets legal obligations by risk tier. Mature programs map their controls to all three." ], "components": [ "Policy & principles", "AI risk catalog", "Risk assessment process", "Controls (access, data, oversight)", "Evaluation & monitoring", "Incident response", "Audit trail & framework mapping" ], "pros": [ "Manages legal, ethical and operational risk systematically.", "Builds trust with customers, regulators and employees.", "Provides evidence for audits and certifications.", "Enables faster, safer adoption with clear guardrails." ], "risks": [ "Bureaucracy that slows adoption if over-engineered.", "Paper compliance that does not change real behavior.", "Fragmented ownership across legal, security and product.", "Falling behind fast-moving regulation and capabilities." ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "EU AI Act compliance mapping", "Model & system documentation (model cards)", "AI evaluation & monitoring platforms" ], "examples": [ "An AI risk catalog with assessments per use case before deployment.", "Human-in-the-loop approval controls for high-impact agent actions.", "Logging and audit trails mapped to NIST AI RMF functions." ], "faqs": [ { "q": "What frameworks should we follow?", "a": "Commonly the NIST AI Risk Management Framework, ISO/IEC 42001 and, where in scope, the EU AI Act. Mature programs map a single control set to all three." }, { "q": "Is AI governance only about compliance?", "a": "No. Compliance is one part. Governance also covers risk, security, transparency, accountability and operational oversight that enable safe adoption." }, { "q": "How does governance apply to agents?", "a": "Autonomy and tool access add risk, so agentic systems need authorization controls, human oversight for high-impact actions, logging and evaluation." }, { "q": "Does governance slow innovation?", "a": "Done well, it accelerates it: clear guardrails let teams ship with confidence. Done poorly, it becomes bureaucracy. The goal is enforceable, lightweight controls." } ] }, "es": { "title": "¿Qué es la Gobernanza de la IA (AI Governance)?", "summary": "La gobernanza de la IA es el conjunto de políticas, procesos, roles y controles que garantizan que la IA se construya y use de forma responsable, legal y segura. Abarca gestión de riesgos, rendición de cuentas, transparencia, seguridad y cumplimiento a lo largo del ciclo de vida de la IA. En la práctica operacionaliza marcos reconocidos —el Reglamento de IA de la UE, el NIST AI Risk Management Framework e ISO/IEC 42001— en controles concretos que una organización puede implementar, evidenciar y auditar.", "definition": "La gobernanza de la IA es el marco de políticas, procesos, roles y controles que una organización usa para gestionar el riesgo de la IA y asegurar que sus sistemas sean responsables, conformes, seguros y auditables a lo largo de su ciclo de vida.", "takeaways": [ "La gobernanza convierte los principios de IA en controles exigibles y auditables.", "Abarca todo el ciclo de vida: datos, construcción, despliegue, monitorización, retirada.", "Referencias principales: Reglamento de IA de la UE, NIST AI RMF, ISO/IEC 42001.", "La IA agéntica eleva la apuesta: la autonomía y el acceso a herramientas amplían el riesgo.", "Una buena gobernanza habilita la adopción; no es solo un freno." ], "context": [ "A medida que la IA entra en decisiones que afectan a personas y operaciones, las organizaciones necesitan gestionar sus riesgos de forma sistemática, no ad hoc. La gobernanza lo aporta: propiedad clara, evaluación de riesgos documentada, controles, monitorización y la evidencia para demostrar el cumplimiento.", "Los sistemas agénticos agudizan la necesidad. Cuando el software puede actuar de forma autónoma y llamar a herramientas, las cuestiones de autorización, rendición de cuentas, auditabilidad y supervisión humana se vuelven operativas, no teóricas." ], "architecture": [ "Un programa práctico de gobernanza tiene capas: política y principios; un catálogo de riesgos de IA y un proceso de evaluación; controles (acceso, tratamiento de datos, evaluación, supervisión humana, registro); monitorización y respuesta a incidentes; y una traza de auditoría que mapea los controles a marcos externos.", "Los marcos se complementan. El NIST AI RMF organiza la práctica en Gobernar, Mapear, Medir y Gestionar. ISO/IEC 42001 define un sistema de gestión de IA auditable. El Reglamento de IA de la UE fija obligaciones legales por nivel de riesgo. Los programas maduros mapean sus controles a los tres." ], "components": [ "Política y principios", "Catálogo de riesgos de IA", "Proceso de evaluación de riesgos", "Controles (acceso, datos, supervisión)", "Evaluación y monitorización", "Respuesta a incidentes", "Traza de auditoría y mapeo de marcos" ], "pros": [ "Gestiona el riesgo legal, ético y operativo de forma sistemática.", "Genera confianza con clientes, reguladores y empleados.", "Aporta evidencia para auditorías y certificaciones.", "Habilita una adopción más rápida y segura con guardarraíles claros." ], "risks": [ "Burocracia que ralentiza la adopción si se sobreingeniería.", "Cumplimiento de papel que no cambia el comportamiento real.", "Propiedad fragmentada entre legal, seguridad y producto.", "Quedarse atrás frente a una regulación y unas capacidades que cambian rápido." ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "Mapeo de cumplimiento del Reglamento de IA de la UE", "Documentación de modelos y sistemas (model cards)", "Plataformas de evaluación y monitorización de IA" ], "examples": [ "Un catálogo de riesgos de IA con evaluaciones por caso de uso antes del despliegue.", "Controles de aprobación con humano en el bucle para acciones de agente de alto impacto.", "Registro y trazas de auditoría mapeados a las funciones del NIST AI RMF." ], "faqs": [ { "q": "¿Qué marcos deberíamos seguir?", "a": "Habitualmente el NIST AI Risk Management Framework, ISO/IEC 42001 y, cuando aplique, el Reglamento de IA de la UE. Los programas maduros mapean un único conjunto de controles a los tres." }, { "q": "¿La gobernanza de IA es solo cumplimiento?", "a": "No. El cumplimiento es una parte. La gobernanza también cubre riesgo, seguridad, transparencia, rendición de cuentas y supervisión operativa que habilitan una adopción segura." }, { "q": "¿Cómo aplica la gobernanza a los agentes?", "a": "La autonomía y el acceso a herramientas añaden riesgo, así que los sistemas agénticos necesitan controles de autorización, supervisión humana para acciones de alto impacto, registro y evaluación." }, { "q": "¿La gobernanza frena la innovación?", "a": "Bien hecha, la acelera: unos guardarraíles claros permiten desplegar con confianza. Mal hecha, se vuelve burocracia. El objetivo son controles exigibles y ligeros." } ] }, "pt": { "title": "O que é Governança de IA (AI Governance)?", "summary": "A governança de IA é o conjunto de políticas, processos, papéis e controles que garantem que a IA seja construída e usada de forma responsável, legal e segura. Abrange gestão de riscos, prestação de contas, transparência, segurança e conformidade ao longo do ciclo de vida da IA. Na prática operacionaliza marcos reconhecidos — o Regulamento de IA da UE, o NIST AI Risk Management Framework e a ISO/IEC 42001 — em controles concretos que uma organização pode implementar, evidenciar e auditar.", "definition": "A governança de IA é o marco de políticas, processos, papéis e controles que uma organização usa para gerir o risco da IA e assegurar que seus sistemas sejam responsáveis, conformes, seguros e auditáveis ao longo de seu ciclo de vida.", "takeaways": [ "A governança converte os princípios de IA em controles exigíveis e auditáveis.", "Abrange todo o ciclo de vida: dados, construção, implantação, monitoramento, descarte.", "Referências principais: Regulamento de IA da UE, NIST AI RMF, ISO/IEC 42001.", "A IA agêntica eleva a aposta: a autonomia e o acesso a ferramentas ampliam o risco.", "Uma boa governança habilita a adoção; não é só um freio." ], "context": [ "À medida que a IA entra em decisões que afetam pessoas e operações, as organizações precisam gerir seus riscos de forma sistemática, não ad hoc. A governança fornece isso: propriedade clara, avaliação de risco documentada, controles, monitoramento e a evidência para demonstrar conformidade.", "Os sistemas agênticos aguçam a necessidade. Quando o software pode agir de forma autônoma e chamar ferramentas, as questões de autorização, prestação de contas, auditabilidade e supervisão humana se tornam operacionais, não teóricas." ], "architecture": [ "Um programa prático de governança tem camadas: política e princípios; um catálogo de riscos de IA e um processo de avaliação; controles (acesso, tratamento de dados, avaliação, supervisão humana, registro); monitoramento e resposta a incidentes; e uma trilha de auditoria que mapeia os controles a marcos externos.", "Os marcos se complementam. O NIST AI RMF organiza a prática em Governar, Mapear, Medir e Gerir. A ISO/IEC 42001 define um sistema de gestão de IA auditável. O Regulamento de IA da UE fixa obrigações legais por nível de risco. Programas maduros mapeiam seus controles aos três." ], "components": [ "Política e princípios", "Catálogo de riscos de IA", "Processo de avaliação de riscos", "Controles (acesso, dados, supervisão)", "Avaliação e monitoramento", "Resposta a incidentes", "Trilha de auditoria e mapeamento de marcos" ], "pros": [ "Gere o risco legal, ético e operacional de forma sistemática.", "Gera confiança com clientes, reguladores e funcionários.", "Fornece evidência para auditorias e certificações.", "Habilita uma adoção mais rápida e segura com guard-rails claros." ], "risks": [ "Burocracia que freia a adoção se for superengenheirada.", "Conformidade de papel que não muda o comportamento real.", "Propriedade fragmentada entre jurídico, segurança e produto.", "Ficar para trás frente a uma regulação e capacidades que mudam rápido." ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "Mapeamento de conformidade do Regulamento de IA da UE", "Documentação de modelos e sistemas (model cards)", "Plataformas de avaliação e monitoramento de IA" ], "examples": [ "Um catálogo de riscos de IA com avaliações por caso de uso antes da implantação.", "Controles de aprovação com humano no laço para ações de agente de alto impacto.", "Registro e trilhas de auditoria mapeados às funções do NIST AI RMF." ], "faqs": [ { "q": "Quais marcos devemos seguir?", "a": "Comumente o NIST AI Risk Management Framework, a ISO/IEC 42001 e, quando aplicável, o Regulamento de IA da UE. Programas maduros mapeiam um único conjunto de controles aos três." }, { "q": "A governança de IA é só conformidade?", "a": "Não. A conformidade é uma parte. A governança também cobre risco, segurança, transparência, prestação de contas e supervisão operacional que habilitam uma adoção segura." }, { "q": "Como a governança se aplica aos agentes?", "a": "A autonomia e o acesso a ferramentas adicionam risco, então os sistemas agênticos precisam de controles de autorização, supervisão humana para ações de alto impacto, registro e avaliação." }, { "q": "A governança freia a inovação?", "a": "Bem feita, a acelera: guard-rails claros permitem implantar com confiança. Mal feita, vira burocracia. O objetivo são controles exigíveis e leves." } ] }, "fr": { "title": "Qu'est-ce que la gouvernance de l'IA ?", "summary": "La gouvernance de l'IA est l'ensemble des politiques, processus, rôles et contrôles qui garantissent que l'IA est conçue et utilisée de manière responsable, légale et sûre. Elle englobe la gestion des risques, la responsabilité, la transparence, la sécurité et la conformité tout au long du cycle de vie de l'IA. En pratique, elle opérationnalise des cadres reconnus — l'EU AI Act, le NIST AI Risk Management Framework et l'ISO/IEC 42001 — en contrôles concrets qu'une organisation peut mettre en œuvre, prouver et auditer.", "definition": "La gouvernance de l'IA est le cadre de politiques, de processus, de rôles et de contrôles qu'une organisation utilise pour gérer les risques liés à l'IA et garantir que les systèmes d'IA sont responsables, conformes, sécurisés et redevables tout au long de leur cycle de vie.", "takeaways": [ "La gouvernance transforme les principes de l'IA en contrôles applicables et auditables.", "Elle couvre l'ensemble du cycle de vie : données, construction, déploiement, surveillance, retrait.", "Principales références : EU AI Act, NIST AI RMF, ISO/IEC 42001.", "L'IA agentique augmente les enjeux : l'autonomie et l'accès aux outils élargissent les risques.", "Une bonne gouvernance favorise l'adoption ; elle ne constitue pas seulement un frein." ], "context": [ "À mesure que l'IA s'immisce dans des décisions qui affectent les personnes et les opérations, les organisations ont besoin d'un moyen de gérer ses risques de manière systématique — et non ponctuelle. La gouvernance apporte cela : une responsabilité claire, une évaluation documentée des risques, des contrôles, une surveillance et les preuves permettant de démontrer la conformité.", "Les systèmes agentiques renforcent ce besoin. Lorsque les logiciels peuvent agir de manière autonome et appeler des outils, les questions d'autorisation, de responsabilité, d'auditabilité et de supervision humaine deviennent opérationnelles, et non théoriques." ], "architecture": [ "Un programme de gouvernance pratique comporte plusieurs niveaux : politiques et principes ; un catalogue de risques liés à l'IA et un processus d'évaluation ; des contrôles (accès, traitement des données, évaluation, supervision humaine, journalisation) ; une surveillance et une réponse aux incidents ; et une piste d'audit qui associe les contrôles aux cadres externes.", "Les cadres se complètent mutuellement. Le NIST AI RMF organise les pratiques autour de Gouverner, Cartographier, Mesurer et Gérer. L'ISO/IEC 42001 définit un système de gestion de l'IA auditable. L'EU AI Act fixe des obligations légales par niveau de risque. Les programmes matures associent leurs contrôles à ces trois cadres." ], "components": [ "Politiques et principes", "Catalogue de risques liés à l'IA", "Processus d'évaluation des risques", "Contrôles (accès, données, supervision)", "Évaluation et surveillance", "Réponse aux incidents", "Piste d'audit et correspondance avec les cadres" ], "pros": [ "Gère les risques juridiques, éthiques et opérationnels de manière systématique.", "Renforce la confiance auprès des clients, des régulateurs et des employés.", "Fournit des preuves pour les audits et les certifications.", "Permet une adoption plus rapide et plus sûre grâce à des garde-fous clairs." ], "risks": [ "Une bureaucratie qui ralentit l'adoption si elle est surconçue.", "Une conformité purement formelle qui ne change pas les comportements réels.", "Une responsabilité fragmentée entre le juridique, la sécurité et le produit.", "Prendre du retard face à l'évolution rapide des réglementations et des capacités." ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "Cartographie de conformité à l'EU AI Act", "Documentation des modèles et des systèmes (model cards)", "Plateformes d'évaluation et de surveillance de l'IA" ], "examples": [ "Un catalogue de risques de l'IA avec des évaluations par cas d'usage avant le déploiement.", "Des contrôles d'approbation avec intervention humaine (human-in-the-loop) pour les actions d'agents à fort impact.", "La journalisation et les pistes d'audit associées aux fonctions du NIST AI RMF." ], "faqs": [ { "q": "Quels cadres de référence devons-nous suivre ?", "a": "Généralement le NIST AI Risk Management Framework, l'ISO/IEC 42001 et, lorsqu'il s'applique, l'EU AI Act. Les programmes matures associent un ensemble unique de contrôles à ces trois référentiels." }, { "q": "La gouvernance de l'IA se limite-t-elle à la conformité ?", "a": "Non. La conformité n'est qu'une partie. La gouvernance couvre également les risques, la sécurité, la transparence, la responsabilité et la supervision opérationnelle qui permettent une adoption sûre." }, { "q": "Comment la gouvernance s'applique-t-elle aux agents ?", "a": "L'autonomie et l'accès aux outils augmentent les risques ; les systèmes d'agents ont donc besoin de contrôles d'autorisation, d'une supervision humaine pour les actions à fort impact, de journalisation et d'évaluation." }, { "q": "La gouvernance ralentit-elle l'innovation ?", "a": "Bien menée, elle l'accélère : des garde-fous clairs permettent aux équipes de déployer en toute confiance. Mal gérée, elle devient bureaucratique. L'objectif est d'avoir des contrôles légers et applicables." } ] }, "de": { "title": "Was ist AI Governance?", "summary": "AI Governance ist die Gesamtheit der Richtlinien, Prozesse, Rollen und Kontrollen, die sicherstellen, dass KI verantwortungsvoll, rechtmäßig und sicher entwickelt und eingesetzt wird. Sie umfasst Risikomanagement, Rechenschaftspflicht, Transparenz, Sicherheit und Compliance über den gesamten KI-Lebenszyklus hinweg. In der Praxis operationalisiert sie anerkannte Frameworks – den EU AI Act, das NIST AI Risk Management Framework und ISO/IEC 42001 – in konkrete Kontrollen, die eine Organisation implementieren, nachweisen und auditieren kann.", "definition": "AI Governance ist das Framework aus Richtlinien, Prozessen, Rollen und Kontrollen, mit dem eine Organisation KI-Risiken verwaltet und sicherstellt, dass KI-Systeme über ihren gesamten Lebenszyklus hinweg verantwortungsvoll, konform, sicher und rechenschaftspflichtig sind.", "takeaways": [ "Governance macht aus KI-Prinzipien durchsetzbare, auditierbare Kontrollen.", "Sie erstreckt sich über den gesamten Lebenszyklus: Daten, Entwicklung, Bereitstellung, Überwachung, Deaktivierung.", "Wichtige Referenzen: EU AI Act, NIST AI RMF, ISO/IEC 42001.", "Agenten-KI (Agentic AI) erhöht den Einsatz: Autonomie und Tool-Zugriff vergrößern das Risiko.", "Gute Governance ermöglicht die Einführung; sie ist nicht nur eine Bremse." ], "context": [ "Da KI zunehmend Entscheidungen trifft, die Menschen und Betriebsabläufe betreffen, benötigen Organisationen eine Möglichkeit, ihre Risiken systematisch und nicht ad hoc zu verwalten. Governance bietet genau das: klare Verantwortlichkeiten, dokumentierte Risikobewertungen, Kontrollen, Überwachung und die Nachweise zur Belegung der Compliance.", "Agentenbasierte Systeme verschärfen diesen Bedarf. Wenn Software autonom agieren und Tools aufrufen kann, werden die Fragen nach Autorisierung, Rechenschaftspflicht, Auditierbarkeit und menschlicher Aufsicht operativ und nicht mehr nur theoretisch." ], "architecture": [ "Ein praktisches Governance-Programm ist in Schichten unterteilt: Richtlinien und Prinzipien; ein KI-Risikokatalog und ein Bewertungsprozess; Kontrollen (Zugriff, Datenverarbeitung, Evaluation, menschliche Aufsicht, Protokollierung); Überwachung und Incident Response sowie ein Audit-Trail, der Kontrollen externen Frameworks zuordnet.", "Frameworks ergänzen einander. Das NIST AI RMF organisiert die Praxis um Govern, Map, Measure und Manage. ISO/IEC 42001 definiert ein auditierbares KI-Managementsystem. Der EU AI Act legt gesetzliche Verpflichtungen nach Risikostufen fest. Ausgereifte Programme ordnen ihre Kontrollen allen drei Frameworks zu." ], "components": [ "Richtlinien & Prinzipien", "KI-Risikokatalog", "Risikobewertungsprozess", "Kontrollen (Zugriff, Daten, Aufsicht)", "Evaluation & Überwachung", "Incident Response", "Audit-Trail & Framework-Zuordnung" ], "pros": [ "Verwaltet rechtliche, ethische und operative Risiken systematisch.", "Baut Vertrauen bei Kunden, Regulierungsbehörden und Mitarbeitern auf.", "Liefert Nachweise für Audits und Zertifizierungen.", "Ermöglicht eine schnellere und sicherere Einführung durch klare Guardrails." ], "risks": [ "Bürokratie, die die Einführung verlangsamt, wenn sie über-engineered ist.", "Paper-Compliance, die das tatsächliche Verhalten nicht verändert.", "Fragmentierte Zuständigkeiten zwischen Rechtsabteilung, Sicherheit und Produkt.", "Hinter sich schnell entwickelnden Regulierungen und technologischen Möglichkeiten zurückzubleiben." ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "Compliance-Mapping für den EU AI Act", "Modell- und Systemdokumentation (Model Cards)", "Plattformen für KI-Evaluierung und -Monitoring" ], "examples": [ "Ein KI-Risikokatalog mit Bewertungen pro Anwendungsfall vor der Bereitstellung.", "Human-in-the-Loop-Freigabekontrollen für folgenschwere Agenten-Aktionen.", "Protokollierung und Audit-Trails, die den Funktionen des NIST AI RMF zugeordnet sind." ], "faqs": [ { "q": "Welchen Frameworks sollten wir folgen?", "a": "Typischerweise dem NIST AI Risk Management Framework, ISO/IEC 42001 und, sofern anwendbar, dem EU AI Act. Ausgereifte Programme ordnen allen dreien ein einziges Set an Kontrollen (Control Set) zu." }, { "q": "Geht es bei AI Governance nur um Compliance?", "a": "Nein. Compliance ist nur ein Teilbereich. Governance umfasst auch Risiko, Sicherheit, Transparenz, Rechenschaftspflicht und betriebliche Aufsicht, die eine sichere Einführung ermöglichen." }, { "q": "Wie lässt sich Governance auf Agenten anwenden?", "a": "Autonomie und Tool-Zugriff bergen zusätzliche Risiken. Daher benötigen agentische Systeme Autorisierungskontrollen, menschliche Aufsicht bei folgenschweren Aktionen, Protokollierung und Evaluierung." }, { "q": "Verlangsamt Governance die Innovation?", "a": "Richtig umgesetzt beschleunigt sie diese: Klare Guardrails ermöglichen es Teams, Code mit Zuversicht bereitzustellen. Schlecht umgesetzt führt sie zu Bürokratie. Das Ziel sind durchsetzbare, leichtgewichtige Kontrollen." } ] }, "ja": { "title": "AIガバナンスとは？", "summary": "AIガバナンスとは、AIが責任を持って、合法的に、かつ安全に構築および使用されることを保証するための一連のポリシー、プロセス、役割、およびコントロールのことです。これは、AIのライフサイクル全体にわたるリスク管理、説明責任、透明性、セキュリティ、およびコンプライアンスを網羅します。実際には、EU AI法、NIST AIリスク管理フレームワーク（NIST AI RMF）、ISO/IEC 42001などの認知されたフレームワークを、組織が実装、実証、および監査できる具体的なコントロールへと運用化します。", "definition": "AIガバナンスとは、組織がAIリスクを管理し、AIシステムがそのライフサイクル全体を通じて責任を持ち、準拠し、安全で、説明責任を果たせるようにするために使用する、ポリシー、プロセス、役割、およびコントロールの枠組みです。", "takeaways": [ "ガバナンスは、AIの原則を実行可能かつ監査可能なコントロールへと変換します。", "データ、構築、デプロイ、監視、廃棄に至るライフサイクル全体を網羅します。", "主な参照基準：EU AI法、NIST AI RMF、ISO/IEC 42001。", "エージェント型AI（Agentic AI）はリスクを高めます。自律性とツールへのアクセスがリスクを拡大するためです。", "優れたガバナンスは導入を促進するものであり、単なるブレーキではありません。" ], "context": [ "AIが人々や業務に影響を与える意思決定に関与するようになるにつれ、組織はリスクをその場しのぎではなく、体系的に管理する方法を必要としています。ガバナンスは、明確な所有権、文書化されたリスク評価、コントロール、監視、およびコンプライアンスを実証するための証跡を提供することで、それを実現します。", "エージェント型システムはこの必要性をさらに高めます。ソフトウェアが自律的に動作し、ツールを呼び出すことができるようになると、権限付与、説明責任、監査可能性、および人間の監視に関する問題は、理論的なものではなく運用上の課題となります。" ], "architecture": [ "実用的なガバナンスプログラムには、ポリシーと原則、AIリスクカタログと評価プロセス、コントロール（アクセス、データ処理、評価、人間の監視、ログ記録）、監視とインシデント対応、およびコントロールを外部フレームワークにマッピングする監査証跡といったレイヤーが存在します。", "各フレームワークは相互に補完し合います。NIST AI RMFは、ガバナンス（Govern）、マッピング（Map）、測定（Measure）、管理（Manage）を中心に実践を整理しています。ISO/IEC 42001は、監査可能なAI管理システムを定義しています。EU AI法は、リスク層ごとに法的義務を定めています。成熟したプログラムは、自社のコントロールをこれら3つすべてにマッピングします。" ], "components": [ "ポリシーと原則", "AIリスクカタログ", "リスク評価プロセス", "コントロール（アクセス、データ、監視）", "評価と監視", "インシデント対応", "監査証跡とフレームワークのマッピング" ], "pros": [ "法的、倫理的、および運用上のリスクを体系的に管理します。", "顧客、規制当局、および従業員との信頼関係を構築します。", "監査や認証のための証拠を提供します。", "明確なガードレールにより、より迅速かつ安全な導入を可能にします。" ], "risks": [ "過剰に設計された場合に導入を遅らせる官僚主義。", "実際の行動を変えることのない、形骸化したコンプライアンス。", "法務、セキュリティ、プロダクトの間で分断されたオーナーシップ。", "急速に変化する規制や技術力に取り残されること。" ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "EU AI Actコンプライアンスマッピング", "モデルおよびシステムのドキュメント（モデルカード）", "AI評価・モニタリングプラットフォーム" ], "examples": [ "展開前にユースケースごとに評価を行うAIリスクカタログ。", "影響の大きいエージェントのアクションに対するHuman-in-the-loop（人間関与型）の承認コントロール。", "NIST AI RMFの機能にマッピングされたロギングと監査トレイル。" ], "faqs": [ { "q": "どのようなフレームワークに従うべきですか？", "a": "一般的には、NIST AIリスクマネジメントフレームワーク（NIST AI RMF）、ISO/IEC 42001、および適用対象となる場合はEU AI Act（EU AI法）です。成熟したプログラムでは、単一のコントロールセットをこれら3つすべてにマッピングします。" }, { "q": "AIガバナンスはコンプライアンスだけに関するものですか？", "a": "いいえ。コンプライアンスはその一部に過ぎません。ガバナンスは、安全な導入を可能にするリスク、セキュリティ、透明性、説明責任、および運用の監視もカバーします。" }, { "q": "ガバナンスはエージェントにどのように適用されますか？", "a": "自律性とツールへのアクセスはリスクを増大させるため、エージェントシステムには認可コントロール、影響の大きいアクションに対する人間の監視、ロギング、および評価が必要です。" }, { "q": "ガバナンスはイノベーションを遅らせますか？", "a": "適切に行われれば、イノベーションは加速します。明確なガードレールにより、チームは自信を持ってリリースできるようになります。不適切に行われると、単なる官僚主義に陥ります。目標は、実効性のある軽量なコントロールです。" } ] }, "zh": { "title": "什么是 AI 治理？", "summary": "AI 治理是一套确保负责任、合法且安全地构建和使用 AI 的政策、流程、角色和控制措施。它涵盖了整个 AI 生命周期中的风险管理、问责制、透明度、安全性和合规性。在实践中，它将公认的框架（欧盟《AI 法案》、NIST AI 风险管理框架和 ISO/IEC 42001）转化为组织可以实施、证明和审计的具体控制措施。", "definition": "AI 治理是组织用于管理 AI 风险并确保 AI 系统在其整个生命周期中保持负责任、合规、安全和可问责的政策、流程、角色和控制措施框架。", "takeaways": [ "治理将 AI 原则转化为可执行、可审计的控制措施。", "它涵盖了完整的生命周期：数据、构建、部署、监控、退役。", "主要参考标准：欧盟《AI 法案》、NIST AI RMF、ISO/IEC 42001。", "智能体 AI（Agentic AI）提高了风险：自主性和工具访问权限扩大了风险面。", "良好的治理能够促进落地，而不仅仅是刹车。" ], "context": [ "随着 AI 开始参与影响人员和运营的决策，组织需要一种系统化而非临时性的方式来管理其风险。治理提供了这种方式：明确的所有权、文档化的风险评估、控制措施、监控以及证明合规性的证据。", "智能体系统使这一需求更加迫切。当软件能够自主行动并调用工具时，授权、问责、可审计性和人工监督等问题就变成了操作层面的实践，而不再是理论探讨。" ], "architecture": [ "一个实用的治理计划具有多个层级：政策和原则；AI 风险目录和评估流程；控制措施（访问、数据处理、评估、人工监督、日志记录）；监控和事件响应；以及将控制措施映射到外部框架的审计追踪。", "各个框架相辅相成。NIST AI RMF 围绕治理（Govern）、映射（Map）、度量（Measure）和管理（Manage）来组织实践。ISO/IEC 42001 定义了一个可审计的 AI 管理体系。欧盟《AI 法案》按风险等级设定了法律义务。成熟的治理计划会将其控制措施映射到这三者之上。" ], "components": [ "政策与原则", "AI 风险目录", "风险评估流程", "控制措施（访问、数据、监督）", "评估与监控", "事件响应", "审计追踪与框架映射" ], "pros": [ "系统化地管理法律、伦理和运营风险。", "建立与客户、监管机构和员工之间的信任。", "为审计和认证提供证据。", "通过明确的护栏实现更快速、更安全的采用。" ], "risks": [ "如果过度设计，官僚主义会减缓采用速度。", "纸面合规，无法改变实际行为。", "法务、安全和产品部门之间的权责碎片化。", "落后于快速变化的监管和技术能力。" ], "tools": [ "NIST AI RMF", "ISO/IEC 42001", "欧盟 AI 法案合规映射", "模型与系统文档（模型卡片）", "AI 评估与监控平台" ], "examples": [ "部署前针对每个用例进行评估的 AI 风险目录。", "针对高影响智能体行为的人机协同审批控制。", "映射到 NIST AI RMF 功能的日志记录和审计追踪。" ], "faqs": [ { "q": "我们应该遵循哪些框架？", "a": "通常是 NIST AI 风险管理框架、ISO/IEC 42001，以及在适用范围内的欧盟 AI 法案。成熟的项目会将单一控制集映射到这三者。" }, { "q": "AI 治理仅仅关乎合规吗？", "a": "不。合规只是其中一部分。治理还涵盖风险、安全、透明度、问责制和运营监督，以实现安全采用。" }, { "q": "治理如何应用于智能体？", "a": "自主性和工具访问增加了风险，因此智能体系统需要授权控制、对高影响行为的人工监督、日志记录和评估。" }, { "q": "治理会减缓创新吗？", "a": "做好治理反而能加速创新：明确的护栏让团队能够充满信心地发布。如果做得不好，它就会变成官僚主义。目标是实现可执行且轻量级的控制。" } ] } } }, { "slug": "ai-observability", "category": "harness", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/knowledge/ai-observability", "api": "https://santismm.com/api/knowledge/ai-observability", "canonical_url": "https://santismm.com/en/knowledge/ai-observability", "api_url": "https://santismm.com/api/knowledge/ai-observability", "evidence": { "evidenceLevel": "production", "confidenceLevel": "medium", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "references": [ { "title": "OpenTelemetry — Semantic conventions for generative AI", "url": "https://opentelemetry.io/docs/specs/semconv/gen-ai/" }, { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "harness-engineering", "agentic-evaluation", "ai-agent", "ai-governance" ], "locales": { "en": { "title": "What is AI Agent Observability?", "summary": "AI observability is the practice of instrumenting AI systems — especially agents — so you can see what they did and why. It captures traces of each step: prompts, tool calls, retrieved context, model outputs, tokens, latency and cost. Because agents are non-deterministic and multi-step, observability is what makes failures diagnosable and improvement systematic. It is the layer that feeds evaluation and closes the harness-engineering loop.", "definition": "AI observability is the practice of capturing traces, metrics and logs of an AI system's behavior — every prompt, tool call, retrieval, output, token, latency and cost — so its decisions can be understood, debugged and improved.", "takeaways": [ "Observability makes non-deterministic agents debuggable.", "Traces record each step: prompts, tools, context, outputs, cost.", "It feeds evaluation — you improve what you can see and measure.", "Track quality, latency, cost and safety together.", "Emerging standards (OpenTelemetry GenAI) make traces portable." ], "context": [ "Traditional software is deterministic and easy to log. Agents are not: the same input can take different paths, call different tools and produce different outputs. Without tracing, a failure is a black box.", "Observability opens that box. By recording the full trajectory of a run, teams can see where an agent went wrong, why a tool failed, where cost ballooned — and feed those findings into evals and harness changes." ], "architecture": [ "Instrumentation captures spans for each step — model call, tool call, retrieval — with inputs, outputs, tokens, latency and errors, linked into a trace for the whole run. Metrics aggregate quality, cost, latency and failure rates over time.", "OpenTelemetry's GenAI semantic conventions standardize how these traces are structured, so they can flow into general observability backends rather than proprietary silos. Traces also become the raw material for evaluation datasets." ], "components": [ "Tracing (spans per step)", "Metrics (quality, cost, latency)", "Logs", "Token & cost accounting", "Error tracking", "Trace-to-eval pipeline" ], "pros": [ "Turns opaque agent runs into diagnosable traces.", "Surfaces cost, latency and failure hotspots.", "Feeds evaluation and continuous improvement.", "Supports incident response and governance audits." ], "risks": [ "Traces may capture sensitive data needing redaction.", "Instrumentation overhead and storage cost at scale.", "Volume without good queries hides the signal.", "Privacy and retention obligations on logged prompts." ], "tools": [ "OpenTelemetry (GenAI conventions)", "LangSmith", "Langfuse", "Arize / Phoenix", "Standard APM backends" ], "examples": [ "Tracing a failed agent run to the exact tool call that errored.", "Tracking per-task token cost to find an expensive prompt.", "Turning production traces into an evaluation dataset.", "In practice: a 57-day single-operator autonomous deployment (OpenClaw) traced 161 sessions / 2,776 turns from local trajectory traces — 98.8% session success, p50 8.1s and p95 87.6s per turn, ~70% of tokens served from cache, and a blended $15.21 per 1M tokens (cost partially priced, so a floor). Every figure is derived from the agent's own traces." ], "faqs": [ { "q": "Why do agents need observability more than chatbots?", "a": "Agents are multi-step and non-deterministic, so a single answer hides many internal decisions. Without traces of those steps, failures cannot be diagnosed." }, { "q": "How does observability relate to evaluation?", "a": "Observability captures what happened; evaluation judges whether it was good. Traces become the data evals run on, closing the improvement loop." }, { "q": "Is there a standard for AI traces?", "a": "OpenTelemetry's generative-AI semantic conventions are emerging as a portable standard, letting AI traces flow into mainstream observability tooling." }, { "q": "What should you measure?", "a": "Quality (task success), cost (tokens), latency, and safety together — a fast, cheap agent that fails the task is not a good agent." } ] }, "es": { "title": "¿Qué es la Observabilidad de Agentes de IA?", "summary": "La observabilidad de IA es la práctica de instrumentar sistemas de IA —sobre todo agentes— para poder ver qué hicieron y por qué. Captura trazas de cada paso: prompts, llamadas a herramientas, contexto recuperado, salidas del modelo, tokens, latencia y coste. Como los agentes son no deterministas y de varios pasos, la observabilidad es lo que hace diagnosticables los fallos y sistemática la mejora. Es la capa que alimenta la evaluación y cierra el bucle de la ingeniería de harness.", "definition": "La observabilidad de IA es la práctica de capturar trazas, métricas y registros del comportamiento de un sistema de IA —cada prompt, llamada a herramienta, recuperación, salida, token, latencia y coste— para poder entender, depurar y mejorar sus decisiones.", "takeaways": [ "La observabilidad hace depurables a los agentes no deterministas.", "Las trazas registran cada paso: prompts, herramientas, contexto, salidas, coste.", "Alimenta la evaluación: mejoras lo que puedes ver y medir.", "Sigue juntos calidad, latencia, coste y seguridad.", "Estándares emergentes (OpenTelemetry GenAI) hacen portables las trazas." ], "context": [ "El software tradicional es determinista y fácil de loguear. Los agentes no: la misma entrada puede tomar caminos distintos, llamar a herramientas distintas y producir salidas distintas. Sin trazado, un fallo es una caja negra.", "La observabilidad abre esa caja. Al registrar la trayectoria completa de una ejecución, los equipos pueden ver dónde se equivocó un agente, por qué falló una herramienta, dónde se disparó el coste, y llevar esos hallazgos a las evaluaciones y a los cambios de harness." ], "architecture": [ "La instrumentación captura spans por cada paso —llamada al modelo, a herramienta, recuperación— con entradas, salidas, tokens, latencia y errores, enlazados en una traza de toda la ejecución. Las métricas agregan calidad, coste, latencia y tasas de fallo en el tiempo.", "Las convenciones semánticas GenAI de OpenTelemetry estandarizan cómo se estructuran estas trazas, para que fluyan a backends de observabilidad generales en vez de silos propietarios. Las trazas también son la materia prima de los datasets de evaluación." ], "components": [ "Trazado (spans por paso)", "Métricas (calidad, coste, latencia)", "Registros (logs)", "Contabilidad de tokens y coste", "Seguimiento de errores", "Pipeline traza-a-evaluación" ], "pros": [ "Convierte ejecuciones opacas en trazas diagnosticables.", "Saca a la luz puntos calientes de coste, latencia y fallo.", "Alimenta la evaluación y la mejora continua.", "Apoya la respuesta a incidentes y las auditorías de gobernanza." ], "risks": [ "Las trazas pueden capturar datos sensibles que requieren redacción.", "Sobrecarga de instrumentación y coste de almacenamiento a escala.", "Volumen sin buenas consultas oculta la señal.", "Obligaciones de privacidad y retención sobre los prompts registrados." ], "tools": [ "OpenTelemetry (convenciones GenAI)", "LangSmith", "Langfuse", "Arize / Phoenix", "Backends APM estándar" ], "examples": [ "Trazar una ejecución fallida hasta la llamada a herramienta exacta que dio error.", "Seguir el coste de tokens por tarea para encontrar un prompt caro.", "Convertir trazas de producción en un dataset de evaluación.", "En la práctica: un despliegue autónomo mono-operador de 57 días (OpenClaw) trazó 161 sesiones / 2.776 turnos desde trazas locales — 98,8% de éxito por sesión, p50 8,1s y p95 87,6s por turno, ~70% de tokens servidos desde caché y $15,21 mezclado por 1M de tokens (coste parcialmente tarifado, por tanto un suelo). Todas las cifras derivan de las propias trazas del agente." ], "faqs": [ { "q": "¿Por qué los agentes necesitan más observabilidad que los chatbots?", "a": "Los agentes son de varios pasos y no deterministas, así que una sola respuesta esconde muchas decisiones internas. Sin trazas de esos pasos, los fallos no se pueden diagnosticar." }, { "q": "¿Cómo se relaciona la observabilidad con la evaluación?", "a": "La observabilidad captura lo que pasó; la evaluación juzga si fue bueno. Las trazas se convierten en los datos sobre los que corren las evaluaciones, cerrando el bucle de mejora." }, { "q": "¿Hay un estándar para las trazas de IA?", "a": "Las convenciones semánticas de IA generativa de OpenTelemetry están emergiendo como estándar portable, permitiendo que las trazas de IA fluyan al tooling de observabilidad general." }, { "q": "¿Qué hay que medir?", "a": "Calidad (éxito de la tarea), coste (tokens), latencia y seguridad juntos: un agente rápido y barato que falla la tarea no es un buen agente." } ] }, "pt": { "title": "O que é Observabilidade de Agentes de IA?", "summary": "A observabilidade de IA é a prática de instrumentar sistemas de IA — sobretudo agentes — para poder ver o que fizeram e por quê. Captura rastros de cada passo: prompts, chamadas de ferramentas, contexto recuperado, saídas do modelo, tokens, latência e custo. Como os agentes são não determinísticos e de vários passos, a observabilidade é o que torna as falhas diagnosticáveis e a melhoria sistemática. É a camada que alimenta a avaliação e fecha o laço da engenharia de harness.", "definition": "A observabilidade de IA é a prática de capturar rastros, métricas e logs do comportamento de um sistema de IA — cada prompt, chamada de ferramenta, recuperação, saída, token, latência e custo — para poder entender, depurar e melhorar suas decisões.", "takeaways": [ "A observabilidade torna depuráveis os agentes não determinísticos.", "Os rastros registram cada passo: prompts, ferramentas, contexto, saídas, custo.", "Alimenta a avaliação: você melhora o que pode ver e medir.", "Acompanhe juntos qualidade, latência, custo e segurança.", "Padrões emergentes (OpenTelemetry GenAI) tornam os rastros portáveis." ], "context": [ "O software tradicional é determinístico e fácil de logar. Os agentes não: a mesma entrada pode tomar caminhos distintos, chamar ferramentas distintas e produzir saídas distintas. Sem rastreamento, uma falha é uma caixa-preta.", "A observabilidade abre essa caixa. Ao registrar a trajetória completa de uma execução, as equipes podem ver onde um agente errou, por que uma ferramenta falhou, onde o custo disparou, e levar esses achados às avaliações e às mudanças de harness." ], "architecture": [ "A instrumentação captura spans para cada passo — chamada ao modelo, à ferramenta, recuperação — com entradas, saídas, tokens, latência e erros, ligados num rastro de toda a execução. As métricas agregam qualidade, custo, latência e taxas de falha ao longo do tempo.", "As convenções semânticas GenAI do OpenTelemetry padronizam como esses rastros são estruturados, para que fluam a backends de observabilidade gerais em vez de silos proprietários. Os rastros também são a matéria-prima dos datasets de avaliação." ], "components": [ "Rastreamento (spans por passo)", "Métricas (qualidade, custo, latência)", "Logs", "Contabilidade de tokens e custo", "Acompanhamento de erros", "Pipeline rastro-para-avaliação" ], "pros": [ "Transforma execuções opacas em rastros diagnosticáveis.", "Revela pontos críticos de custo, latência e falha.", "Alimenta a avaliação e a melhoria contínua.", "Apoia a resposta a incidentes e as auditorias de governança." ], "risks": [ "Os rastros podem capturar dados sensíveis que exigem redação.", "Sobrecarga de instrumentação e custo de armazenamento em escala.", "Volume sem boas consultas esconde o sinal.", "Obrigações de privacidade e retenção sobre os prompts registrados." ], "tools": [ "OpenTelemetry (convenções GenAI)", "LangSmith", "Langfuse", "Arize / Phoenix", "Backends APM padrão" ], "examples": [ "Rastrear uma execução falha até a chamada de ferramenta exata que deu erro.", "Acompanhar o custo de tokens por tarefa para encontrar um prompt caro.", "Transformar rastros de produção num dataset de avaliação.", "Na prática: uma implantação autônoma de operador único de 57 dias (OpenClaw) rastreou 161 sessões / 2.776 turnos a partir de rastros locais — 98,8% de sucesso por sessão, p50 8,1s e p95 87,6s por turno, ~70% dos tokens servidos do cache e $15,21 combinado por 1M de tokens (custo parcialmente precificado, portanto um piso). Todos os números derivam dos próprios rastros do agente." ], "faqs": [ { "q": "Por que os agentes precisam de mais observabilidade que os chatbots?", "a": "Os agentes são de vários passos e não determinísticos, então uma única resposta esconde muitas decisões internas. Sem rastros desses passos, as falhas não podem ser diagnosticadas." }, { "q": "Como a observabilidade se relaciona com a avaliação?", "a": "A observabilidade captura o que aconteceu; a avaliação julga se foi bom. Os rastros se tornam os dados sobre os quais as avaliações rodam, fechando o laço de melhoria." }, { "q": "Há um padrão para os rastros de IA?", "a": "As convenções semânticas de IA generativa do OpenTelemetry estão emergindo como padrão portável, permitindo que os rastros de IA fluam para o tooling de observabilidade geral." }, { "q": "O que medir?", "a": "Qualidade (sucesso da tarefa), custo (tokens), latência e segurança juntos: um agente rápido e barato que falha a tarefa não é um bom agente." } ] }, "fr": { "title": "Qu'est-ce que l'observabilité des agents d'IA ?", "summary": "L'observabilité de l'IA consiste à instrumenter les systèmes d'IA — en particulier les agents — afin de comprendre ce qu'ils ont fait et pourquoi. Elle capture les traces de chaque étape : prompts, appels d'outils, contexte récupéré, sorties du modèle, jetons, latence et coût. Les agents étant non déterministes et multi-étapes, l'observabilité permet de diagnostiquer les défaillances et d'améliorer le système de manière systématique. C'est la couche qui alimente l'évaluation et ferme la boucle du Harness Engineering.", "definition": "L'observabilité de l'IA consiste à capturer les traces, les métriques et les journaux du comportement d'un système d'IA — chaque prompt, appel d'outil, récupération, sortie, jeton, latence et coût — afin que ses décisions puissent être comprises, déboguées et améliorées.", "takeaways": [ "L'observabilité permet de déboguer les agents non déterministes.", "Les traces enregistrent chaque étape : prompts, outils, contexte, sorties, coût.", "Elle alimente l'évaluation : on améliore ce que l'on peut voir et mesurer.", "Suivez conjointement la qualité, la latence, le coût et la sécurité.", "Les normes émergentes (OpenTelemetry GenAI) rendent les traces portables." ], "context": [ "Les logiciels traditionnels sont déterministes et faciles à journaliser. Ce n'est pas le cas des agents : une même entrée peut emprunter des chemins différents, appeler des outils différents et produire des sorties différentes. Sans traçage, une défaillance reste une boîte noire.", "L'observabilité ouvre cette boîte. En enregistrant la trajectoire complète d'une exécution, les équipes peuvent voir où un agent s'est trompé, pourquoi un outil a échoué, où les coûts se sont envolés — et intégrer ces résultats dans les évaluations et les modifications du harness." ], "architecture": [ "L'instrumentation capture des spans pour chaque étape — appel de modèle, appel d'outil, récupération — avec les entrées, les sorties, les jetons, la latence et les erreurs, reliés au sein d'une trace pour l'ensemble de l'exécution. Les métriques agrègent la qualité, le coût, la latence et les taux d'échec au fil du temps.", "Les conventions sémantiques GenAI d'OpenTelemetry standardisent la structure de ces traces, afin qu'elles puissent être intégrées dans des backends d'observabilité généraux plutôt que dans des silos propriétaires. Les traces deviennent également la matière première des jeux de données d'évaluation." ], "components": [ "Traçage (spans par étape)", "Métriques (qualité, coût, latence)", "Journaux", "Comptabilisation des jetons et des coûts", "Suivi des erreurs", "Pipeline de la trace à l'évaluation" ], "pros": [ "Transforme les exécutions d'agents opaques en traces diagnostiquables.", "Met en évidence les points critiques de coût, de latence et de défaillance.", "Alimente l'évaluation et l'amélioration continue.", "Prend en charge la réponse aux incidents et les audits de gouvernance." ], "risks": [ "Les traces peuvent capturer des données sensibles nécessitant une occultation.", "Surcharge d'instrumentation et coût de stockage à grande échelle.", "Un volume important sans requêtes adaptées masque le signal.", "Obligations de confidentialité et de rétention sur les prompts journalisés." ], "tools": [ "OpenTelemetry (conventions GenAI)", "LangSmith", "Langfuse", "Arize / Phoenix", "Backends APM standards" ], "examples": [ "Tracer une exécution d'agent ayant échoué jusqu'à l'appel d'outil exact à l'origine de l'erreur.", "Suivre le coût en jetons par tâche pour identifier un prompt coûteux.", "Transformer les traces de production en un jeu de données d'évaluation.", "En pratique : un déploiement autonome à opérateur unique de 57 jours (OpenClaw) a tracé 161 sessions / 2 776 tours à partir de traces de trajectoire locales — 98,8 % de réussite des sessions, p50 de 8,1 s et p95 de 87,6 s par tour, environ 70 % de jetons servis depuis le cache, et un coût mixte de 15,21 $ par million de jetons (coût partiellement évalué, constituant donc un seuil minimal). Chaque chiffre est dérivé des propres traces de l'agent." ], "faqs": [ { "q": "Pourquoi les agents ont-ils plus besoin d'observabilité que les chatbots ?", "a": "Les agents sont multi-étapes et non déterministes, de sorte qu'une réponse unique masque de nombreuses décisions internes. Sans traces de ces étapes, les défaillances ne peuvent pas être diagnostiquées." }, { "q": "Quel est le lien entre l'observabilité et l'évaluation ?", "a": "L'observabilité capture ce qui s'est passé ; l'évaluation juge si le résultat est satisfaisant. Les traces deviennent les données sur lesquelles reposent les évaluations, fermant ainsi la boucle d'amélioration." }, { "q": "Existe-t-il une norme pour les traces d'IA ?", "a": "Les conventions sémantiques d'IA générative d'OpenTelemetry s'imposent comme une norme portable, permettant aux traces d'IA de s'intégrer dans les outils d'observabilité grand public." }, { "q": "Que devez-vous mesurer ?", "a": "La qualité (réussite de la tâche), le coût (jetons), la latence et la sécurité conjointement — un agent rapide et économique qui échoue dans sa tâche n'est pas un bon agent." } ] }, "de": { "title": "Was ist AI Agent Observability?", "summary": "AI Observability ist die Praxis der Instrumentierung von KI-Systemen – insbesondere von Agenten –, um nachvollziehbar zu machen, was sie getan haben und warum. Sie erfasst Traces (Spuren) jedes Schritts: Prompts, Tool-Aufrufe, abgerufenen Kontext, Modell-Outputs, Tokens, Latenz und Kosten. Da Agenten nicht-deterministisch arbeiten und mehrere Schritte durchlaufen, macht Observability Fehler diagnostizierbar und Verbesserungen systematisch. Sie ist die Schicht, die die Evaluierung speist und den Kreislauf des Harness Engineering schließt.", "definition": "AI Observability ist die Praxis der Erfassung von Traces, Metriken und Logs des Verhaltens eines KI-Systems – jedes Prompts, Tool-Aufrufs, Abrufs, Outputs, Tokens sowie der Latenz und Kosten –, damit dessen Entscheidungen verstanden, debuggt und verbessert werden können.", "takeaways": [ "Observability macht nicht-deterministische Agenten debuggbar.", "Traces zeichnen jeden Schritt auf: Prompts, Tools, Kontext, Outputs, Kosten.", "Sie speist die Evaluierung – man verbessert, was man sehen und messen kann.", "Erfassen Sie Qualität, Latenz, Kosten und Sicherheit gemeinsam.", "Sich etablierende Standards (OpenTelemetry GenAI) machen Traces portabel." ], "context": [ "Traditionelle Software ist deterministisch und leicht zu protokollieren. Agenten sind es nicht: Dieselbe Eingabe kann unterschiedliche Pfade einschlagen, verschiedene Tools aufrufen und unterschiedliche Ergebnisse liefern. Ohne Tracing bleibt ein Fehler eine Blackbox.", "Observability öffnet diese Box. Durch die Aufzeichnung des vollständigen Verlaufs eines Durchlaufs können Teams sehen, wo ein Agent einen Fehler gemacht hat, warum ein Tool fehlgeschlagen ist oder wo die Kosten explodiert sind – und diese Erkenntnisse in Evals und Änderungen am Harness einfließen lassen." ], "architecture": [ "Die Instrumentierung erfasst Spans für jeden Schritt – Modellaufruf, Tool-Aufruf, Abruf – mit Eingaben, Ausgaben, Tokens, Latenz und Fehlern, verknüpft zu einem Trace für den gesamten Durchlauf. Metriken aggregieren Qualität, Kosten, Latenz und Fehlerraten im Zeitverlauf.", "Die semantischen GenAI-Konventionen von OpenTelemetry standardisieren die Strukturierung dieser Traces, sodass sie in allgemeine Observability-Backends statt in proprietäre Silos fließen können. Traces werden zudem zum Rohmaterial für Evaluierungsdatensätze." ], "components": [ "Tracing (Spans pro Schritt)", "Metriken (Qualität, Kosten, Latenz)", "Logs", "Token- und Kostenabrechnung", "Fehler-Tracking", "Trace-to-Eval-Pipeline" ], "pros": [ "Verwandelt undurchsichtige Agenten-Durchläufe in diagnostizierbare Traces.", "Deckt Hotspots bei Kosten, Latenz und Fehlern auf.", "Speist die Evaluierung und kontinuierliche Verbesserung.", "Unterstützt Incident Response und Governance-Audits." ], "risks": [ "Traces können sensible Daten erfassen, die geschwärzt werden müssen.", "Instrumentierungs-Overhead und Speicherkosten bei hoher Skalierung.", "Hohes Datenvolumen ohne gute Abfragen verbirgt das eigentliche Signal.", "Datenschutz- und Aufbewahrungspflichten für protokollierte Prompts." ], "tools": [ "OpenTelemetry (GenAI-Konventionen)", "LangSmith", "Langfuse", "Arize / Phoenix", "Standard-APM-Backends" ], "examples": [ "Zurückverfolgen eines fehlgeschlagenen Agenten-Durchlaufs bis zum genauen Tool-Aufruf, der den Fehler verursacht hat.", "Verfolgen der Token-Kosten pro Aufgabe, um einen teuren Prompt zu finden.", "Umwandeln von Produktions-Traces in einen Evaluierungsdatensatz.", "In der Praxis: Ein 57-tägiges autonomes Deployment mit einem einzigen Operator (OpenClaw) erfasste 161 Sitzungen / 2.776 Turns aus lokalen Trajektorien-Traces – 98,8 % Sitzungserfolg, p50 von 8,1 s und p95 von 87,6 s pro Turn, ca. 70 % der Tokens aus dem Cache bedient und gemischte Kosten von 15,21 $ pro 1 Mio. Tokens (Kosten teilweise geschätzt, daher eine Untergrenze). Jede Zahl leitet sich aus den eigenen Traces des Agenten ab." ], "faqs": [ { "q": "Warum benötigen Agenten dringender Observability als Chatbots?", "a": "Agenten arbeiten mehrstufig und nicht-deterministisch, sodass eine einzige Antwort viele interne Entscheidungen verbirgt. Ohne Traces dieser Schritte können Fehler nicht diagnostiziert werden." }, { "q": "Wie hängen Observability und Evaluierung zusammen?", "a": "Observability erfasst, was passiert ist; Evaluierung beurteilt, ob es gut war. Traces werden zu den Daten, auf denen Evals ausgeführt werden, wodurch sich der Verbesserungskreislauf schließt." }, { "q": "Gibt es einen Standard für KI-Traces?", "a": "Die semantischen Generative-AI-Konventionen von OpenTelemetry etablieren sich als portabler Standard, mit dem KI-Traces in gängige Observability-Tools einfließen können." }, { "q": "Was sollte man messen?", "a": "Qualität (Erfolg der Aufgabe), Kosten (Tokens), Latenz und Sicherheit zusammen – ein schneller, günstiger Agent, der an der Aufgabe scheitert, ist kein guter Agent." } ] }, "ja": { "title": "AIエージェントのオブザーバビリティとは何ですか？", "summary": "AIオブザーバビリティとは、AIシステム（特にエージェント）をインストルメンテーションし、何を実行したか、そしてその理由を可視化する手法です。プロンプト、ツール呼び出し、取得されたコンテキスト、モデルの出力、トークン、レイテンシ、コストなど、各ステップのトレースをキャプチャします。エージェントは非決定的かつマルチステップであるため、オブザーバビリティこそが障害の診断を可能にし、体系的な改善を実現します。これは評価にデータを供給し、ハーネスエンジニアリング (Harness Engineering) のループを閉じるレイヤーです。", "definition": "AIオブザーバビリティとは、AIシステムの挙動（すべてのプロンプト、ツール呼び出し、リトリーバル、出力、トークン、レイテンシ、コスト）のトレース、メトリクス、ログをキャプチャし、その意思決定を理解、デバッグ、改善できるようにする手法です。", "takeaways": [ "オブザーバビリティにより、非決定的なエージェントのデバッグが可能になります。", "トレースは、プロンプト、ツール、コンテキスト、出力、コストといった各ステップを記録します。", "評価にデータを供給します。可視化し測定できるものこそが改善可能です。", "品質、レイテンシ、コスト、安全性を統合して追跡します。", "新たな標準（OpenTelemetry GenAI）により、トレースのポータビリティが向上します。" ], "context": [ "従来のソフトウェアは決定的であり、ログの記録も容易です。しかし、エージェントは異なります。同じ入力であっても異なる経路をたどり、異なるツールを呼び出し、異なる出力を生成することがあります。トレースがなければ、障害はブラックボックスのままです。", "オブザーバビリティはそのブラックボックスを開きます。実行の全軌跡を記録することで、チームはエージェントがどこで誤ったのか、なぜツールが失敗したのか、どこでコストが膨らんだのかを把握し、それらの知見を評価（evals）やハーネスの変更に反映させることができます。" ], "architecture": [ "インストルメンテーションは、モデル呼び出し、ツール呼び出し、リトリーバルといった各ステップのスパンを、入力、出力、トークン、レイテンシ、エラーとともにキャプチャし、実行全体のトレースにリンクします。メトリクスは、品質、コスト、レイテンシ、失敗率を時系列で集計します。", "OpenTelemetryのGenAIセマンティックコンベンションは、これらのトレースの構造を標準化し、独自のサイロではなく一般的なオブザーバビリティバックエンドに流し込めるようにします。また、トレースは評価データセットの原材料にもなります。" ], "components": [ "トレーシング（ステップごとのスパン）", "メトリクス（品質、コスト、レイテンシ）", "ログ", "トークンとコストの集計", "エラートラッキング", "トレースから評価へのパイプライン" ], "pros": [ "不透明なエージェントの実行を、診断可能なトレースに変換します。", "コスト、レイテンシ、障害のホットスポットを顕在化させます。", "評価と継続的な改善にデータを供給します。", "インシデント対応やガバナンス監査をサポートします。" ], "risks": [ "トレースに墨消し（マスキング）が必要な機密データが含まれる可能性があります。", "大規模運用におけるインストルメンテーションのオーバーヘッドとストレージコスト。", "適切なクエリがない大量のデータは、重要なシグナルを埋もれさせます。", "ログに記録されたプロンプトに対するプライバシーおよび保持の義務。" ], "tools": [ "OpenTelemetry（GenAIコンベンション）", "LangSmith", "Langfuse", "Arize / Phoenix", "標準的なAPMバックエンド" ], "examples": [ "失敗したエージェントの実行を、エラーが発生した正確なツール呼び出しまでトレースすること。", "タスクごとのトークンコストを追跡し、高コストなプロンプトを特定すること。", "本番環境のトレースを評価データセットに変換すること。", "実践例：単一オペレーターによる57日間の自律型デプロイメント（OpenClaw）において、ローカルの軌跡トレースから161セッション/2,776ターンを追跡。セッション成功率98.8%、1ターンあたりp50が8.1秒、p95が87.6秒、トークンの約70%がキャッシュから提供され、100万トークンあたりのブレンドコストは15.21ドル（一部のコストのみ計上されているため最低値）。すべての数値はエージェント自身のトレースから導出されています。" ], "faqs": [ { "q": "なぜエージェントにはチャットボット以上のオブザーバビリティが必要なのですか？", "a": "エージェントはマルチステップかつ非決定的であるため、単一の回答の裏に多くの内部的な意思決定が隠されています。それらのステップのトレースがなければ、障害を診断することはできません。" }, { "q": "オブザーバビリティは評価とどのように関係していますか？", "a": "オブザーバビリティは何が起きたかをキャプチャし、評価はそれが適切であったかを判断します。トレースは評価（evals）が実行されるデータとなり、改善のループを閉じます。" }, { "q": "AIトレースの標準はありますか？", "a": "OpenTelemetryの生成AI（generative-AI）セマンティックコンベンションがポータブルな標準として台頭しつつあり、AIトレースを主要なオブザーバビリティツールに流し込めるようになっています。" }, { "q": "何を測定すべきですか？", "a": "品質（タスクの成功）、コスト（トークン）、レイテンシ、安全性を統合して測定します。タスクに失敗する、高速で安価なエージェントは優れたエージェントとは言えません。" } ] }, "zh": { "title": "什么是 AI 智能体可观测性？", "summary": "AI 可观测性是指对 AI 系统（尤其是智能体）进行插桩的实践，以便您能够了解它们做了什么以及原因。它捕获每一步的追踪：提示词、工具调用、检索到的上下文、模型输出、Token、延迟和成本。由于智能体具有非确定性和多步骤特征，可观测性使故障诊断和系统性改进成为可能。它是为评估提供数据并闭环 Harness Engineering（智能体支撑系统工程）的层。", "definition": "AI 可观测性是指捕获 AI 系统行为的追踪、指标和日志的实践——包括每一次提示词、工具调用、检索、输出、Token、延迟和成本——以便理解、调试和改进其决策。", "takeaways": [ "可观测性使非确定性智能体变得可调试。", "追踪记录了每一步：提示词、工具、上下文、输出、成本。", "它为评估提供数据——你只能改进你能看到和衡量的内容。", "统一追踪质量、延迟、成本和安全性。", "新兴标准（OpenTelemetry GenAI）使追踪具备可移植性。" ], "context": [ "传统软件是确定性的，易于记录日志。智能体则不然：相同的输入可能会走不同的路径、调用不同的工具并产生不同的输出。如果没有追踪，故障就是一个黑盒子。", "可观测性打开了这个黑盒子。通过记录运行的完整轨迹，团队可以看到智能体在哪里出错、工具为什么失败、成本在哪里激增，并将这些发现反馈到评估和支撑系统变更中。" ], "architecture": [ "插桩捕获每一步的 Span——模型调用、工具调用、检索——包括输入、输出、Token、延迟和错误，并将其链接到整个运行的追踪中。指标则随时间聚合质量、成本、延迟和失败率。", "OpenTelemetry 的 GenAI 语义约定标准化了这些追踪的结构，使其能够流入通用的可观测性后端，而不是局限于专有的孤岛。追踪也成为了评估数据集的原材料。" ], "components": [ "追踪（每一步的 Span）", "指标（质量、成本、延迟）", "日志", "Token 与成本核算", "错误跟踪", "追踪到评估流水线" ], "pros": [ "将不透明的智能体运行转化为可诊断的追踪。", "显现成本、延迟和失败热点。", "为评估和持续改进提供数据。", "支持事件响应和治理审计。" ], "risks": [ "追踪可能会捕获需要脱敏的敏感数据。", "大规模情况下的插桩开销和存储成本。", "缺乏良好查询的海量数据会掩盖关键信号。", "记录提示词的隐私和保留义务。" ], "tools": [ "OpenTelemetry（GenAI 约定）", "LangSmith", "Langfuse", "Arize / Phoenix", "标准 APM 后端" ], "examples": [ "将失败的智能体运行追踪到具体出错的工具调用。", "跟踪每个任务的 Token 成本以找出高成本的提示词。", "将生产环境的追踪转化为评估数据集。", "实践案例：一个为期 57 天的单操作员自主部署（OpenClaw），通过本地轨迹追踪记录了 161 个会话 / 2,776 轮交互——会话成功率达 98.8%，每轮交互的 p50 延迟为 8.1 秒，p95 延迟为 87.6 秒，约 70% 的 Token 来自缓存服务，混合成本为每 100 万个 Token 15.21 美元（部分成本为估算，因此是底线值）。每个数据均源自该智能体自身的追踪。" ], "faqs": [ { "q": "为什么智能体比聊天机器人更需要可观测性？", "a": "智能体具有多步骤和非确定性特征，因此单一的回答会隐藏许多内部决策。如果没有这些步骤的追踪，就无法诊断故障。" }, { "q": "可观测性与评估有什么关系？", "a": "可观测性捕获发生的事情；评估判断其好坏。追踪成为运行评估的数据，从而闭环改进流程。" }, { "q": "AI 追踪有标准吗？", "a": "OpenTelemetry 的生成式 AI 语义约定正逐渐成为一种可移植的标准，使 AI 追踪能够流入主流的可观测性工具中。" }, { "q": "应该衡量什么？", "a": "统一衡量质量（任务成功率）、成本（Token）、延迟和安全性——一个速度快、成本低但任务失败的智能体并不是一个好的智能体。" } ] } } }, { "slug": "context-engineering", "category": "harness", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/context-engineering", "api": "https://santismm.com/api/knowledge/context-engineering", "canonical_url": "https://santismm.com/en/knowledge/context-engineering", "api_url": "https://santismm.com/api/knowledge/context-engineering", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "Anthropic — Effective context engineering for AI agents (2025)", "url": "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents" }, { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" } ], "related": [ "harness-engineering", "prompt-engineering", "agent-memory", "enterprise-rag" ], "locales": { "en": { "title": "What is Context Engineering?", "summary": "Context engineering is the discipline of deciding what information enters a model's limited context window at each step — and what stays out. As agents run over many steps, naively stuffing everything into context degrades quality and cost. Context engineering curates the right instructions, retrieved knowledge, tool results and memory so the model has exactly what it needs, when it needs it. It is a core part of harness engineering.", "definition": "Context engineering is the practice of curating, compressing and sequencing the information placed in a model's context window so it has the most relevant signal — and the least noise — at each step.", "takeaways": [ "Context is a scarce resource; what you leave out matters as much as what you include.", "More context is not better — irrelevant tokens degrade quality and raise cost.", "Techniques: retrieval, summarization, compaction, and structured memory.", "It generalizes prompt engineering from one prompt to a whole agent run.", "It is a core layer of the harness around a model." ], "context": [ "Every model has a finite context window, and quality degrades when it is filled with low-signal content. In single-turn use this is manageable, but agents accumulate history, tool outputs and retrieved documents across many steps, quickly overwhelming the window.", "Context engineering treats the window as a budget to be managed deliberately: keep the durable instructions, retrieve only what is relevant now, summarize or compact the rest, and store long-term state outside the window in memory." ], "architecture": [ "Core moves: select (retrieve only relevant passages), compress (summarize prior steps), compact (drop or fold stale turns), and externalize (push long-term state to a memory store, pulling it back on demand).", "In an agent loop, context is reassembled each step from layered sources: stable system instructions, task state, relevant retrieved knowledge, recent tool results and selected long-term memories — ordered so the most important signal is most salient." ], "components": [ "System instructions", "Task state", "Retrieved knowledge", "Tool results", "Long-term memory", "Summaries / compaction" ], "pros": [ "Keeps quality high as tasks grow long.", "Controls token cost and latency.", "Reduces distraction and hallucination from noise.", "Enables long-horizon agents within finite context." ], "risks": [ "Over-aggressive compression can drop needed information.", "Poor retrieval injects irrelevant or wrong context.", "Complexity in deciding what to keep each step.", "Bugs here surface as subtle quality regressions." ], "tools": [ "Retrieval / RAG pipelines", "Summarization models", "Memory stores", "Context-management frameworks (e.g. LangGraph)" ], "examples": [ "Summarizing earlier agent steps so the window stays focused on the current subtask.", "Retrieving only the policy section relevant to a question instead of the whole manual.", "Storing a user's preferences in memory and recalling them only when relevant." ], "faqs": [ { "q": "How is context engineering different from prompt engineering?", "a": "Prompt engineering crafts a single instruction. Context engineering manages the full set of information in the window across an entire agent run — retrieval, memory, tool results and compression included." }, { "q": "Why not just use a bigger context window?", "a": "Larger windows help but do not eliminate the problem: quality and cost degrade as windows fill with low-signal tokens. Curation still wins." }, { "q": "How does it relate to RAG and memory?", "a": "RAG and memory are sources of context; context engineering decides what from them actually enters the window, when, and in what form." }, { "q": "Is it part of harness engineering?", "a": "Yes. Context management is one of the core layers of the harness that turns model capability into reliable agent behavior." } ] }, "es": { "title": "¿Qué es la Ingeniería de Contexto (Context Engineering)?", "summary": "La ingeniería de contexto es la disciplina de decidir qué información entra en la ventana de contexto limitada de un modelo en cada paso, y qué se queda fuera. Como los agentes se ejecutan en muchos pasos, meter todo ingenuamente en el contexto degrada calidad y coste. La ingeniería de contexto cura las instrucciones, el conocimiento recuperado, los resultados de herramientas y la memoria adecuados para que el modelo tenga justo lo que necesita cuando lo necesita. Es una parte central de la ingeniería de harness.", "definition": "La ingeniería de contexto es la práctica de curar, comprimir y secuenciar la información que se coloca en la ventana de contexto de un modelo para que tenga la señal más relevante —y el menor ruido— en cada paso.", "takeaways": [ "El contexto es un recurso escaso; lo que dejas fuera importa tanto como lo que incluyes.", "Más contexto no es mejor: los tokens irrelevantes degradan calidad y suben el coste.", "Técnicas: recuperación, resumen, compactación y memoria estructurada.", "Generaliza la ingeniería de prompts de un prompt a toda una ejecución de agente.", "Es una capa central del harness alrededor del modelo." ], "context": [ "Todo modelo tiene una ventana de contexto finita, y la calidad se degrada cuando se llena de contenido de baja señal. En uso de un solo turno es manejable, pero los agentes acumulan historial, salidas de herramientas y documentos recuperados a lo largo de muchos pasos, saturando rápido la ventana.", "La ingeniería de contexto trata la ventana como un presupuesto a gestionar de forma deliberada: conservar las instrucciones duraderas, recuperar solo lo relevante ahora, resumir o compactar el resto y guardar el estado a largo plazo fuera de la ventana en memoria." ], "architecture": [ "Movimientos clave: seleccionar (recuperar solo pasajes relevantes), comprimir (resumir pasos previos), compactar (descartar o plegar turnos obsoletos) y externalizar (llevar el estado a largo plazo a un almacén de memoria y traerlo bajo demanda).", "En un bucle de agente, el contexto se reensambla en cada paso desde fuentes en capas: instrucciones de sistema estables, estado de la tarea, conocimiento recuperado relevante, resultados recientes de herramientas y memorias a largo plazo seleccionadas, ordenadas para que la señal más importante sea la más saliente." ], "components": [ "Instrucciones de sistema", "Estado de la tarea", "Conocimiento recuperado", "Resultados de herramientas", "Memoria a largo plazo", "Resúmenes / compactación" ], "pros": [ "Mantiene alta la calidad cuando las tareas se alargan.", "Controla el coste de tokens y la latencia.", "Reduce la distracción y la alucinación por ruido.", "Habilita agentes de horizonte largo dentro de un contexto finito." ], "risks": [ "Una compresión demasiado agresiva puede descartar información necesaria.", "Una recuperación pobre inyecta contexto irrelevante o erróneo.", "Complejidad al decidir qué conservar en cada paso.", "Los errores aquí aparecen como regresiones sutiles de calidad." ], "tools": [ "Pipelines de recuperación / RAG", "Modelos de resumen", "Almacenes de memoria", "Frameworks de gestión de contexto (p. ej. LangGraph)" ], "examples": [ "Resumir pasos anteriores del agente para que la ventana siga enfocada en la subtarea actual.", "Recuperar solo la sección de la política relevante a una pregunta en vez de todo el manual.", "Guardar las preferencias de un usuario en memoria y recordarlas solo cuando son relevantes." ], "faqs": [ { "q": "¿En qué se diferencia de la ingeniería de prompts?", "a": "La ingeniería de prompts crea una sola instrucción. La ingeniería de contexto gestiona todo el conjunto de información en la ventana a lo largo de una ejecución de agente, incluyendo recuperación, memoria, resultados de herramientas y compresión." }, { "q": "¿Por qué no usar simplemente una ventana de contexto más grande?", "a": "Las ventanas más grandes ayudan pero no eliminan el problema: la calidad y el coste se degradan al llenarse de tokens de baja señal. La curación sigue ganando." }, { "q": "¿Cómo se relaciona con RAG y la memoria?", "a": "RAG y la memoria son fuentes de contexto; la ingeniería de contexto decide qué de ellas entra realmente en la ventana, cuándo y en qué forma." }, { "q": "¿Es parte de la ingeniería de harness?", "a": "Sí. La gestión de contexto es una de las capas centrales del harness que convierte la capacidad del modelo en comportamiento fiable del agente." } ] }, "pt": { "title": "O que é Engenharia de Contexto (Context Engineering)?", "summary": "A engenharia de contexto é a disciplina de decidir qual informação entra na janela de contexto limitada de um modelo a cada passo, e o que fica de fora. Como os agentes rodam em muitos passos, enfiar tudo ingenuamente no contexto degrada qualidade e custo. A engenharia de contexto cura as instruções, o conhecimento recuperado, os resultados de ferramentas e a memória adequados para que o modelo tenha exatamente o que precisa quando precisa. É uma parte central da engenharia de harness.", "definition": "A engenharia de contexto é a prática de curar, comprimir e sequenciar a informação colocada na janela de contexto de um modelo para que ele tenha o sinal mais relevante — e o menor ruído — a cada passo.", "takeaways": [ "O contexto é um recurso escasso; o que você deixa de fora importa tanto quanto o que inclui.", "Mais contexto não é melhor: tokens irrelevantes degradam a qualidade e elevam o custo.", "Técnicas: recuperação, resumo, compactação e memória estruturada.", "Generaliza a engenharia de prompts de um prompt para toda uma execução de agente.", "É uma camada central do harness em torno do modelo." ], "context": [ "Todo modelo tem uma janela de contexto finita, e a qualidade se degrada quando ela é preenchida com conteúdo de baixo sinal. No uso de um único turno é gerenciável, mas os agentes acumulam histórico, saídas de ferramentas e documentos recuperados ao longo de muitos passos, saturando rápido a janela.", "A engenharia de contexto trata a janela como um orçamento a gerir de forma deliberada: manter as instruções duráveis, recuperar só o relevante agora, resumir ou compactar o resto e guardar o estado de longo prazo fora da janela na memória." ], "architecture": [ "Movimentos centrais: selecionar (recuperar só trechos relevantes), comprimir (resumir passos anteriores), compactar (descartar ou dobrar turnos obsoletos) e externalizar (levar o estado de longo prazo a um armazenamento de memória e trazê-lo sob demanda).", "Num laço de agente, o contexto é remontado a cada passo a partir de fontes em camadas: instruções de sistema estáveis, estado da tarefa, conhecimento recuperado relevante, resultados recentes de ferramentas e memórias de longo prazo selecionadas, ordenados para que o sinal mais importante seja o mais saliente." ], "components": [ "Instruções de sistema", "Estado da tarefa", "Conhecimento recuperado", "Resultados de ferramentas", "Memória de longo prazo", "Resumos / compactação" ], "pros": [ "Mantém a qualidade alta quando as tarefas se alongam.", "Controla o custo de tokens e a latência.", "Reduz a distração e a alucinação por ruído.", "Habilita agentes de horizonte longo dentro de um contexto finito." ], "risks": [ "Uma compressão agressiva demais pode descartar informação necessária.", "Uma recuperação ruim injeta contexto irrelevante ou errado.", "Complexidade ao decidir o que manter a cada passo.", "Bugs aqui aparecem como regressões sutis de qualidade." ], "tools": [ "Pipelines de recuperação / RAG", "Modelos de resumo", "Armazenamentos de memória", "Frameworks de gestão de contexto (ex.: LangGraph)" ], "examples": [ "Resumir passos anteriores do agente para a janela seguir focada na subtarefa atual.", "Recuperar só a seção da política relevante a uma pergunta em vez de todo o manual.", "Guardar as preferências de um usuário na memória e lembrá-las só quando relevantes." ], "faqs": [ { "q": "Qual a diferença para a engenharia de prompts?", "a": "A engenharia de prompts cria uma única instrução. A engenharia de contexto gere todo o conjunto de informação na janela ao longo de uma execução de agente, incluindo recuperação, memória, resultados de ferramentas e compressão." }, { "q": "Por que não usar simplesmente uma janela de contexto maior?", "a": "Janelas maiores ajudam mas não eliminam o problema: qualidade e custo se degradam ao se encherem de tokens de baixo sinal. A curadoria ainda vence." }, { "q": "Como se relaciona com RAG e memória?", "a": "RAG e memória são fontes de contexto; a engenharia de contexto decide o que delas realmente entra na janela, quando e em que forma." }, { "q": "É parte da engenharia de harness?", "a": "Sim. A gestão de contexto é uma das camadas centrais do harness que converte a capacidade do modelo em comportamento confiável do agente." } ] }, "fr": { "title": "Qu'est-ce que l'ingénierie de contexte ?", "summary": "L'ingénierie de contexte est la discipline qui consiste à décider quelles informations entrent dans la fenêtre de contexte limitée d'un modèle à chaque étape — et lesquelles en sont exclues. À mesure que les agents enchaînent les étapes, intégrer naïvement toutes les données dans le contexte nuit à la qualité et augmente les coûts. L'ingénierie de contexte sélectionne les bonnes instructions, les connaissances récupérées, les résultats d'outils et la mémoire afin que le modèle dispose exactement de ce dont il a besoin, au moment où il en a besoin. C'est un élément central du Harness Engineering.", "definition": "L'ingénierie de contexte consiste à sélectionner, compresser et ordonner les informations placées dans la fenêtre de contexte d'un modèle afin qu'il dispose du signal le plus pertinent — et du moins de bruit possible — à chaque étape.", "takeaways": [ "Le contexte est une ressource rare ; ce que vous excluez importe autant que ce que vous incluez.", "Un contexte plus large n'est pas nécessairement préférable : les jetons non pertinents dégradent la qualité et augmentent les coûts.", "Techniques : récupération, résumé, compaction et mémoire structurée.", "Elle généralise le prompt engineering d'un simple prompt à l'ensemble de l'exécution d'un agent.", "C'est une couche essentielle du harness autour d'un modèle." ], "context": [ "Chaque modèle dispose d'une fenêtre de contexte finie, et la qualité se dégrade lorsqu'elle est remplie de contenus à faible signal. C'est gérable pour une utilisation à tour unique, mais les agents accumulent l'historique, les sorties d'outils et les documents récupérés au fil de nombreuses étapes, submergeant rapidement la fenêtre.", "L'ingénierie de contexte traite la fenêtre comme un budget à gérer délibérément : conserver les instructions durables, ne récupérer que ce qui est pertinent à l'instant T, résumer ou compacter le reste, et stocker l'état à long terme en dehors de la fenêtre, dans la mémoire." ], "architecture": [ "Actions clés : sélectionner (récupérer uniquement les passages pertinents), compresser (résumer les étapes précédentes), compacter (supprimer ou replier les tours obsolètes) et externaliser (transférer l'état à long terme vers un stockage de mémoire, pour le récupérer à la demande).", "Dans une boucle d'agent, le contexte est réassemblé à chaque étape à partir de sources superposées : instructions système stables, état de la tâche, connaissances pertinentes récupérées, résultats d'outils récents et souvenirs à long terme sélectionnés — ordonnés de manière à ce que le signal le plus important soit le plus saillant." ], "components": [ "Instructions système", "État de la tâche", "Connaissances récupérées", "Résultats des outils", "Mémoire à long terme", "Résumés / compaction" ], "pros": [ "Maintient une qualité élevée à mesure que les tâches s'allongent.", "Contrôle le coût en jetons et la latence.", "Réduit les distractions et les hallucinations dues au bruit.", "Permet aux agents à long horizon de fonctionner dans un contexte fini." ], "risks": [ "Une compression trop agressive peut faire perdre des informations nécessaires.", "Une mauvaise récupération injecte un contexte non pertinent ou erroné.", "Complexité de la décision sur ce qu'il faut conserver à chaque étape.", "Les bugs à ce niveau se traduisent par de subtiles régressions de qualité." ], "tools": [ "Pipelines de récupération / RAG", "Modèles de résumé", "Magasins de mémoire", "Frameworks de gestion de contexte (ex. LangGraph)" ], "examples": [ "Résumer les étapes précédentes de l'agent pour que la fenêtre reste concentrée sur la sous-tâche en cours.", "Récupérer uniquement la section de la politique pertinente pour une question plutôt que l'intégralité du manuel.", "Stocker les préférences d'un utilisateur en mémoire et ne les rappeler que lorsque c'est pertinent." ], "faqs": [ { "q": "En quoi le context engineering diffère-t-il du prompt engineering ?", "a": "Le prompt engineering conçoit une instruction unique. Le context engineering gère l'ensemble des informations de la fenêtre tout au long de l'exécution d'un agent — y compris la récupération, la mémoire, les résultats des outils et la compression." }, { "q": "Pourquoi ne pas simplement utiliser une fenêtre de contexte plus grande ?", "a": "Les fenêtres plus grandes aident, mais n'éliminent pas le problème : la qualité se dégrade et le coût augmente à mesure que les fenêtres se remplissent de jetons à faible signal. La curation reste indispensable." }, { "q": "Quel est le rapport avec le RAG et la mémoire ?", "a": "Le RAG et la mémoire sont des sources de contexte ; le context engineering décide de ce qui entre réellement dans la fenêtre, quand et sous quelle forme." }, { "q": "Cela fait-il partie de Harness Engineering ?", "a": "Oui. La gestion du contexte est l'une des couches fondamentales du harness qui transforme la capacité du modèle en un comportement d'agent fiable." } ] }, "de": { "title": "Was ist Context Engineering?", "summary": "Context Engineering ist die Disziplin der Entscheidung, welche Informationen in jedem Schritt in das begrenzte Kontextfenster eines Modells gelangen – und welche draußen bleiben. Da Agenten über viele Schritte hinweg laufen, verschlechtert das naive Einfügen aller Daten in den Kontext Qualität und Kosten. Context Engineering kuratiert die richtigen Anweisungen, das abgerufene Wissen, Tool-Ergebnisse und den Speicher, sodass das Modell genau das hat, was es braucht, wenn es gebraucht wird. Es ist ein Kernbestandteil des Harness Engineering.", "definition": "Context Engineering ist die Praxis des Kuratierens, Komprimierens und Sequenzierens der im Kontextfenster eines Modells platzierten Informationen, sodass es bei jedem Schritt das relevanteste Signal – und das geringste Rauschen – erhält.", "takeaways": [ "Kontext ist eine knappe Ressource; was man weglässt, ist ebenso wichtig wie das, was man einbezieht.", "Mehr Kontext ist nicht besser – irrelevante Tokens verschlechtern die Qualität und erhöhen die Kosten.", "Techniken: Retrieval, Zusammenfassung, Kompaktierung und strukturierter Speicher.", "Es verallgemeinert Prompt Engineering von einem einzelnen Prompt auf einen gesamten Agenten-Durchlauf.", "Es ist eine Kernschicht des Harness um ein Modell." ], "context": [ "Jedes Modell hat ein begrenztes Kontextfenster, und die Qualität sinkt, wenn es mit Inhalten mit geringem Signalwert gefüllt wird. Bei der Nutzung in einem einzigen Turn ist dies handhabbar, aber Agenten sammeln über viele Schritte hinweg Verlauf, Tool-Ausgaben und abgerufene Dokumente an, was das Fenster schnell überfordert.", "Context Engineering behandelt das Fenster als ein Budget, das bewusst verwaltet werden muss: Dauerhafte Anweisungen beibehalten, nur das abrufen, was jetzt relevant ist, den Rest zusammenfassen oder kompaktieren und den Langzeitstatus außerhalb des Fensters im Speicher ablegen." ], "architecture": [ "Kernschritte: Auswählen (nur relevante Passagen abrufen), Komprimieren (vorherige Schritte zusammenfassen), Kompaktieren (veraltete Turns verwerfen oder einklappen) und Externalisieren (Langzeitstatus in einen Speicher verschieben und bei Bedarf wieder abrufen).", "In einem Agenten-Loop wird der Kontext bei jedem Schritt aus verschiedenen Schichten neu zusammengesetzt: stabilen Systemanweisungen, Aufgabenstatus, relevantem abgerufenen Wissen, aktuellen Tool-Ergebnissen und ausgewählten Langzeiterinnerungen – so geordnet, dass das wichtigste Signal am deutlichsten hervortritt." ], "components": [ "Systemanweisungen", "Aufgabenstatus", "Abgerufenes Wissen", "Tool-Ergebnisse", "Langzeitgedächtnis", "Zusammenfassungen / Kompaktierung" ], "pros": [ "Hält die Qualität hoch, wenn Aufgaben länger werden.", "Kontrolliert Token-Kosten und Latenz.", "Reduziert Ablenkung und Halluzinationen durch Rauschen.", "Ermöglicht Agenten mit langem Zeithorizont innerhalb eines begrenzten Kontextes." ], "risks": [ "Zu aggressive Komprimierung kann benötigte Informationen verwerfen.", "Schlechtes Retrieval schleust irrelevanten oder falschen Kontext ein.", "Komplexität bei der Entscheidung, was in jedem Schritt behalten werden soll.", "Fehler an dieser Stelle äußern sich als subtile Qualitätsverschlechterungen." ], "tools": [ "Retrieval- / RAG-Pipelines", "Zusammenfassungsmodelle", "Memory-Speicher", "Kontextmanagement-Frameworks (z. B. LangGraph)" ], "examples": [ "Zusammenfassen früherer Agentenschritte, damit das Fenster auf die aktuelle Teilaufgabe fokussiert bleibt.", "Abrufen nur des für eine Frage relevanten Richtlinienabschnitts anstelle des gesamten Handbuchs.", "Speichern der Präferenzen eines Benutzers im Gedächtnis und Abrufen dieser nur bei Relevanz." ], "faqs": [ { "q": "Wie unterscheidet sich Context Engineering von Prompt Engineering?", "a": "Prompt Engineering entwirft eine einzelne Anweisung. Context Engineering verwaltet die gesamte Informationsmenge im Fenster über einen kompletten Agenten-Durchlauf hinweg – einschließlich Retrieval, Memory, Tool-Ergebnissen und Komprimierung." }, { "q": "Warum nicht einfach ein größeres Kontextfenster verwenden?", "a": "Größere Fenster helfen, beseitigen das Problem jedoch nicht: Qualität und Kosten verschlechtern sich, wenn sich Fenster mit Token mit geringem Signalgehalt füllen. Kuratierung gewinnt weiterhin." }, { "q": "Wie hängt es mit RAG und Memory zusammen?", "a": "RAG und Memory sind Kontextquellen; Context Engineering entscheidet, was davon tatsächlich wann und in welcher Form in das Fenster gelangt." }, { "q": "Ist es Teil von Harness Engineering?", "a": "Ja. Kontextmanagement ist eine der Kernschichten des Harness, die Modellfähigkeiten in zuverlässiges Agentenverhalten umwandelt." } ] }, "ja": { "title": "コンテキストエンジニアリングとは何ですか？", "summary": "コンテキストエンジニアリングとは、モデルの限られたコンテキストウィンドウに各ステップでどの情報を入れ、どの情報を除外するかを決定する技術分野です。エージェントが多くのステップを実行する際、単純にすべてをコンテキストに詰め込むと、品質が低下しコストが増大します。コンテキストエンジニアリングは、適切な指示、取得された知識、ツールの結果、およびメモリを厳選し、モデルが必要な時に必要なものを正確に得られるようにします。これはハーネスエンジニアリングの中核となる部分です。", "definition": "コンテキストエンジニアリングとは、モデルのコンテキストウィンドウに配置される情報を厳選、圧縮、順序付けし、各ステップで最も関連性の高いシグナルを配置し、ノイズを最小限に抑える手法です。", "takeaways": [ "コンテキストは希少なリソースです。何を除外するかは、何を含めるかと同様に重要です。", "コンテキストは多ければよいというものではありません。無関係なトークンは品質を低下させ、コストを上昇させます。", "手法：リトリーバル、要約、コンパクト化、および構造化メモリ。", "単一のプロンプトからエージェントの実行全体へと、プロンプトエンジニアリングを一般化します。", "モデルを取り囲むハーネスのコアレイヤーです。" ], "context": [ "すべてのモデルには有限のコンテキストウィンドウがあり、シグナルの弱いコンテンツで満たされると品質が低下します。シングルターンの使用では対処可能ですが、エージェントは多くのステップにわたって履歴、ツールの出力、取得されたドキュメントを蓄積するため、すぐにウィンドウが溢れてしまいます。", "コンテキストエンジニアリングは、ウィンドウを計画的に管理すべき予算として扱います。永続的な指示を保持し、現在関連のあるものだけを取得し、残りを要約またはコンパクト化し、長期的な状態はウィンドウの外のメモリに保存します。" ], "architecture": [ "主なアプローチ：選択（関連する一節のみを取得）、圧縮（前のステップを要約）、コンパクト化（古いターンを破棄または折りたたむ）、外部化（長期的な状態をメモリ領域にプッシュし、必要に応じてプルバックする）。", "エージェントのループにおいて、コンテキストは各ステップで、固定のシステム指示、タスクの状態、関連する取得された知識、最近のツールの結果、選択された長期メモリといった階層化されたソースから再構成され、最も重要なシグナルが最も目立つように順序付けられます。" ], "components": [ "システム指示", "タスクの状態", "取得された知識", "ツール結果", "長期記憶", "要約 / 圧縮" ], "pros": [ "タスクが長期化しても高い品質を維持します。", "トークンコストとレイテンシーを抑制します。", "ノイズによる混乱やハルシネーションを低減します。", "有限のコンテキスト内で、長期的なタスクを実行するエージェント（long-horizon agents）を実現します。" ], "risks": [ "過度な圧縮により、必要な情報が欠落する可能性があります。", "検索の精度が低いと、無関係なコンテキストや誤ったコンテキストが混入します。", "各ステップで何を保持すべきかを決定する際の複雑さ。", "ここでのバグは、わずかな品質低下として表面化します。" ], "tools": [ "検索 / RAGパイプライン", "要約モデル", "メモリ・ストア", "コンテキスト管理フレームワーク（例：LangGraph）" ], "examples": [ "エージェントの以前のステップを要約し、コンテキストウィンドウが現在のサブタスクに集中できるようにします。", "マニュアル全体ではなく、質問に関連するポリシーのセクションのみを検索します。", "ユーザーの好みをメモリに保存し、関連性がある場合にのみ呼び出します。" ], "faqs": [ { "q": "コンテキストエンジニアリングはプロンプトエンジニアリングとどう違うのですか？", "a": "プロンプトエンジニアリングは単一の指示を作成します。一方、コンテキストエンジニアリングは、検索、メモリ、ツール結果、圧縮などを含め、エージェントの実行全体を通じてウィンドウ内のすべての情報を管理します。" }, { "q": "単にコンテキストウィンドウを大きくするだけではだめなのですか？", "a": "ウィンドウを大きくすることは役立ちますが、根本的な解決にはなりません。ウィンドウがシグナルの低いトークンで埋まると、品質が低下しコストが増加します。依然として、情報のキュレーションが有効です。" }, { "q": "RAGやメモリとはどのように関係していますか？", "a": "RAGやメモリはコンテキストのソースです。コンテキストエンジニアリングは、それらから「何を」「いつ」「どのような形式で」実際にウィンドウに投入するかを決定します。" }, { "q": "これはハーネスエンジニアリング (Harness Engineering) の一部ですか？", "a": "はい。コンテキスト管理は、モデルの能力を信頼性の高いエージェントの動作へと変換するハーネスのコアレイヤーの1つです。" } ] }, "zh": { "title": "什么是上下文工程？", "summary": "上下文工程是一门决定在每一步中哪些信息进入模型有限的上下文窗口，以及哪些信息被排除在外的学科。随着智能体运行多个步骤，盲目地将所有内容塞入上下文中会降低质量并增加成本。上下文工程通过策划正确的指令、检索到的知识、工具结果和记忆，使模型在需要时恰好拥有其所需的内容。它是 Harness Engineering 的核心部分。", "definition": "上下文工程是指策划、压缩和排序放入模型上下文窗口中的信息的实践，以便它在每一步都拥有最相关的信号和最少的噪音。", "takeaways": [ "上下文是一种稀缺资源；你排除的内容与你包含的内容同样重要。", "更多的上下文并不意味着更好——无关的 Token 会降低质量并增加成本。", "技术包括：检索、摘要、精简和结构化记忆。", "它将提示词工程从单一提示词推广到整个智能体运行过程。", "它是模型周围支撑系统的核心层。" ], "context": [ "每个模型都有有限的上下文窗口，当其中充斥着低信号内容时，质量就会下降。在单轮交互中，这是可以控制的，但智能体会跨多个步骤累积历史记录、工具输出和检索到的文档，从而迅速使窗口过载。", "上下文工程将窗口视为需要刻意管理的预算：保留持久指令，仅检索当前相关的内容，对其余内容进行摘要或精简，并将长期状态存储在窗口之外的记忆中。" ], "architecture": [ "核心动作：选择（仅检索相关段落）、压缩（对先前步骤进行摘要）、精简（丢弃或折叠陈旧的轮次）以及外部化（将长期状态推送到记忆库中，并根据需要拉回）。", "在智能体循环中，上下文在每一步都从分层源中重新组装：稳定的系统指令、任务状态、相关的检索知识、最近的工具结果以及选定的长期记忆——并进行排序，使最重要的信号最显著。" ], "components": [ "系统指令", "任务状态", "检索到的知识", "工具结果", "长期记忆", "摘要 / 压缩" ], "pros": [ "随着任务变长，仍能保持高质量。", "控制 Token 成本和延迟。", "减少噪声带来的干扰和幻觉。", "在有限的上下文内实现长程智能体。" ], "risks": [ "过度压缩可能会遗漏所需信息。", "检索效果差会引入无关或错误的上下文。", "在每一步决定保留什么内容具有复杂性。", "此处的缺陷会表现为隐蔽的质量退化。" ], "tools": [ "检索 / RAG 流水线", "摘要模型", "记忆存储", "上下文管理框架（例如 LangGraph）" ], "examples": [ "对智能体先前的步骤进行摘要，使窗口保持专注于当前的子任务。", "仅检索与问题相关的政策章节，而不是整本手册。", "将用户的偏好存储在记忆中，并仅在相关时进行召回。" ], "faqs": [ { "q": "上下文工程与提示词工程有什么区别？", "a": "提示词工程构建的是单条指令。而上下文工程则管理整个智能体运行过程中窗口内的完整信息集——包括检索、记忆、工具结果和压缩。" }, { "q": "为什么不直接使用更大的上下文窗口？", "a": "更大的窗口有所帮助，但无法消除问题：随着窗口被低信号 Token 填满，质量和成本都会恶化。精细筛选依然是更好的选择。" }, { "q": "它与 RAG 和记忆有什么关系？", "a": "RAG 和记忆是上下文的来源；上下文工程决定其中哪些内容在何时以何种形式真正进入窗口。" }, { "q": "它是 Harness Engineering（智能体支撑系统工程）的一部分吗？", "a": "是的。上下文管理是该支撑系统的核心层之一，它将模型能力转化为可靠的智能体行为。" } ] } } }, { "slug": "embeddings", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/embeddings", "api": "https://santismm.com/api/knowledge/embeddings", "canonical_url": "https://santismm.com/en/knowledge/embeddings", "api_url": "https://santismm.com/api/knowledge/embeddings", "evidence": { "evidenceLevel": "benchmark", "confidenceLevel": "high", "sourceType": [ "benchmark", "paper" ] }, "references": [ { "title": "Reimers & Gurevych — Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks (2019)", "url": "https://arxiv.org/abs/1908.10084" }, { "title": "Mikolov et al. — Efficient Estimation of Word Representations (word2vec, 2013)", "url": "https://arxiv.org/abs/1301.3781" } ], "related": [ "enterprise-rag", "foundation-models", "fine-tuning", "agentic-ai" ], "locales": { "en": { "title": "What are Embeddings & Vector Search?", "summary": "An embedding is a numeric vector that represents the meaning of text (or images, audio, code) so that semantically similar items sit close together in vector space. Vector search finds the nearest embeddings to a query, enabling search by meaning rather than keywords. Embeddings are the backbone of retrieval-augmented generation, semantic search, clustering and recommendation.", "definition": "An embedding is a dense numeric vector that encodes the meaning of a piece of data, positioned so that similar items are close in vector space; vector search retrieves the nearest embeddings to a query.", "takeaways": [ "Embeddings turn meaning into vectors; similar things sit close together.", "Vector search retrieves by semantic similarity, not exact keywords.", "They power RAG, semantic search, clustering and recommendation.", "Hybrid search (vector + keyword) usually beats either alone.", "Chunking and the embedding model choice drive retrieval quality." ], "context": [ "Computers compare numbers, not meaning. Embeddings bridge that gap: an embedding model maps text to a vector such that 'cancel my subscription' and 'how do I unsubscribe' land near each other, even with no shared words.", "This is what makes semantic retrieval possible. Instead of matching keywords, a system embeds the query and finds the closest stored vectors — the foundation of how RAG and modern search retrieve relevant content." ], "architecture": [ "Indexing: content is split into chunks, each passed through an embedding model to produce a vector, then stored in a vector index. Querying: the query is embedded and the index returns the nearest vectors by a similarity metric (e.g. cosine).", "Production systems add a re-ranker to refine the top results, combine vector search with keyword search (hybrid), and filter by metadata and permissions. Quality depends heavily on chunking and the embedding model." ], "components": [ "Embedding model", "Chunking", "Vector index / database", "Similarity metric (cosine)", "Re-ranker", "Hybrid (keyword) search" ], "pros": [ "Search by meaning, robust to wording.", "Cross-lingual and multimodal matching.", "The backbone of RAG and semantic search.", "Cheap to query at scale once indexed." ], "risks": [ "Poor chunking degrades every downstream result.", "Embedding model mismatch hurts relevance.", "Vectors can leak sensitive info; secure the store.", "Pure vector search can miss exact-match needs (use hybrid)." ], "tools": [ "Embedding models (OpenAI, Cohere, open-source)", "Vector databases (pgvector, Pinecone, Vertex AI Vector Search)", "Re-rankers", "Hybrid search engines" ], "examples": [ "Semantic search over a help center that matches intent, not keywords.", "Retrieving relevant passages to ground a RAG answer.", "Clustering support tickets by topic using their embeddings." ], "faqs": [ { "q": "How are embeddings different from keywords?", "a": "Keyword search matches exact words; embeddings match meaning, so paraphrases and synonyms still retrieve the right content." }, { "q": "What is vector search?", "a": "Finding the stored embeddings nearest to a query embedding by a similarity metric like cosine distance — search by semantic closeness." }, { "q": "Why combine vector and keyword search?", "a": "Vectors excel at meaning but can miss exact terms (codes, names). Hybrid search blends both for the best recall and precision." }, { "q": "Do embeddings power RAG?", "a": "Yes. RAG embeds documents and queries, retrieves the nearest chunks by vector search, and grounds the model's answer in them." } ] }, "es": { "title": "¿Qué son los Embeddings y la Búsqueda Vectorial?", "summary": "Un embedding es un vector numérico que representa el significado de un texto (o imágenes, audio, código) de modo que los elementos semánticamente similares quedan cerca en el espacio vectorial. La búsqueda vectorial encuentra los embeddings más cercanos a una consulta, permitiendo buscar por significado en vez de por palabras clave. Los embeddings son la columna vertebral de la generación aumentada por recuperación, la búsqueda semántica, el clustering y la recomendación.", "definition": "Un embedding es un vector numérico denso que codifica el significado de un dato, situado de forma que los elementos similares quedan cerca en el espacio vectorial; la búsqueda vectorial recupera los embeddings más cercanos a una consulta.", "takeaways": [ "Los embeddings convierten el significado en vectores; lo similar queda cerca.", "La búsqueda vectorial recupera por similitud semántica, no por palabras exactas.", "Sustentan el RAG, la búsqueda semántica, el clustering y la recomendación.", "La búsqueda híbrida (vector + palabras clave) suele superar a cada una sola.", "El chunking y la elección del modelo de embeddings determinan la calidad." ], "context": [ "Los ordenadores comparan números, no significado. Los embeddings salvan esa brecha: un modelo de embeddings mapea texto a un vector de modo que 'cancela mi suscripción' y 'cómo me doy de baja' caen cerca, aun sin palabras compartidas.", "Esto es lo que hace posible la recuperación semántica. En vez de casar palabras clave, el sistema embebe la consulta y encuentra los vectores almacenados más cercanos: la base de cómo el RAG y la búsqueda moderna recuperan contenido relevante." ], "architecture": [ "Indexación: el contenido se divide en chunks, cada uno pasa por un modelo de embeddings para producir un vector y se guarda en un índice vectorial. Consulta: la consulta se embebe y el índice devuelve los vectores más cercanos por una métrica de similitud (p. ej. coseno).", "Los sistemas en producción añaden un re-ranker para refinar los mejores resultados, combinan búsqueda vectorial con búsqueda por palabras clave (híbrida) y filtran por metadatos y permisos. La calidad depende mucho del chunking y del modelo de embeddings." ], "components": [ "Modelo de embeddings", "Chunking", "Índice / base de datos vectorial", "Métrica de similitud (coseno)", "Re-ranker", "Búsqueda híbrida (palabras clave)" ], "pros": [ "Búsqueda por significado, robusta a la redacción.", "Coincidencia translingüe y multimodal.", "La columna vertebral del RAG y la búsqueda semántica.", "Barata de consultar a escala una vez indexada." ], "risks": [ "Un chunking pobre degrada todo resultado posterior.", "Un modelo de embeddings inadecuado daña la relevancia.", "Los vectores pueden filtrar info sensible; asegura el almacén.", "La búsqueda vectorial pura puede fallar en coincidencias exactas (usa híbrida)." ], "tools": [ "Modelos de embeddings (OpenAI, Cohere, open source)", "Bases de datos vectoriales (pgvector, Pinecone, Vertex AI Vector Search)", "Re-rankers", "Motores de búsqueda híbrida" ], "examples": [ "Búsqueda semántica en un centro de ayuda que casa la intención, no las palabras.", "Recuperar pasajes relevantes para fundamentar una respuesta RAG.", "Agrupar tickets de soporte por tema usando sus embeddings." ], "faqs": [ { "q": "¿En qué se diferencian los embeddings de las palabras clave?", "a": "La búsqueda por palabras clave casa palabras exactas; los embeddings casan significado, así que paráfrasis y sinónimos siguen recuperando el contenido correcto." }, { "q": "¿Qué es la búsqueda vectorial?", "a": "Encontrar los embeddings almacenados más cercanos al embedding de una consulta por una métrica como la distancia coseno: búsqueda por cercanía semántica." }, { "q": "¿Por qué combinar búsqueda vectorial y por palabras clave?", "a": "Los vectores destacan en significado pero pueden fallar en términos exactos (códigos, nombres). La búsqueda híbrida combina ambas para mejor recall y precisión." }, { "q": "¿Los embeddings sustentan el RAG?", "a": "Sí. El RAG embebe documentos y consultas, recupera los chunks más cercanos por búsqueda vectorial y fundamenta en ellos la respuesta del modelo." } ] }, "pt": { "title": "O que são Embeddings e Busca Vetorial?", "summary": "Um embedding é um vetor numérico que representa o significado de um texto (ou imagens, áudio, código) de modo que itens semanticamente similares ficam próximos no espaço vetorial. A busca vetorial encontra os embeddings mais próximos de uma consulta, permitindo buscar por significado em vez de palavras-chave. Os embeddings são a espinha dorsal da geração aumentada por recuperação, da busca semântica, do clustering e da recomendação.", "definition": "Um embedding é um vetor numérico denso que codifica o significado de um dado, posicionado de forma que itens similares ficam próximos no espaço vetorial; a busca vetorial recupera os embeddings mais próximos de uma consulta.", "takeaways": [ "Embeddings transformam significado em vetores; o similar fica próximo.", "A busca vetorial recupera por similaridade semântica, não por palavras exatas.", "Sustentam o RAG, a busca semântica, o clustering e a recomendação.", "A busca híbrida (vetor + palavras-chave) costuma superar cada uma sozinha.", "O chunking e a escolha do modelo de embeddings determinam a qualidade." ], "context": [ "Os computadores comparam números, não significado. Os embeddings preenchem essa lacuna: um modelo de embeddings mapeia texto a um vetor de modo que 'cancele minha assinatura' e 'como eu me descadastro' caem próximos, mesmo sem palavras em comum.", "Isso é o que torna possível a recuperação semântica. Em vez de casar palavras-chave, o sistema embeda a consulta e encontra os vetores armazenados mais próximos: a base de como o RAG e a busca moderna recuperam conteúdo relevante." ], "architecture": [ "Indexação: o conteúdo é dividido em chunks, cada um passa por um modelo de embeddings para produzir um vetor e é guardado num índice vetorial. Consulta: a consulta é embedada e o índice devolve os vetores mais próximos por uma métrica de similaridade (ex.: cosseno).", "Os sistemas em produção adicionam um re-ranker para refinar os melhores resultados, combinam busca vetorial com busca por palavras-chave (híbrida) e filtram por metadados e permissões. A qualidade depende muito do chunking e do modelo de embeddings." ], "components": [ "Modelo de embeddings", "Chunking", "Índice / banco de dados vetorial", "Métrica de similaridade (cosseno)", "Re-ranker", "Busca híbrida (palavras-chave)" ], "pros": [ "Busca por significado, robusta à redação.", "Correspondência translíngue e multimodal.", "A espinha dorsal do RAG e da busca semântica.", "Barata de consultar em escala uma vez indexada." ], "risks": [ "Um chunking ruim degrada todo resultado posterior.", "Um modelo de embeddings inadequado prejudica a relevância.", "Os vetores podem vazar info sensível; proteja o armazenamento.", "A busca vetorial pura pode falhar em correspondências exatas (use híbrida)." ], "tools": [ "Modelos de embeddings (OpenAI, Cohere, open source)", "Bancos de dados vetoriais (pgvector, Pinecone, Vertex AI Vector Search)", "Re-rankers", "Motores de busca híbrida" ], "examples": [ "Busca semântica numa central de ajuda que casa a intenção, não as palavras.", "Recuperar trechos relevantes para fundamentar uma resposta RAG.", "Agrupar chamados de suporte por tema usando seus embeddings." ], "faqs": [ { "q": "Como os embeddings diferem das palavras-chave?", "a": "A busca por palavras-chave casa palavras exatas; os embeddings casam significado, então paráfrases e sinônimos ainda recuperam o conteúdo correto." }, { "q": "O que é busca vetorial?", "a": "Encontrar os embeddings armazenados mais próximos do embedding de uma consulta por uma métrica como a distância cosseno: busca por proximidade semântica." }, { "q": "Por que combinar busca vetorial e por palavras-chave?", "a": "Os vetores se destacam em significado mas podem falhar em termos exatos (códigos, nomes). A busca híbrida combina ambas para melhor recall e precisão." }, { "q": "Os embeddings sustentam o RAG?", "a": "Sim. O RAG embeda documentos e consultas, recupera os chunks mais próximos por busca vetorial e fundamenta neles a resposta do modelo." } ] }, "fr": { "title": "Que sont les embeddings et la recherche vectorielle ?", "summary": "Un embedding est un vecteur numérique qui représente la signification d'un texte (ou d'images, d'audio, de code) de sorte que les éléments sémantiquement similaires soient proches dans l'espace vectoriel. La recherche vectorielle trouve les embeddings les plus proches d'une requête, permettant une recherche par sens plutôt que par mots-clés. Les embeddings constituent l'épine dorsale de la génération augmentée de récupération (RAG), de la recherche sémantique, du clustering et de la recommandation.", "definition": "Un embedding est un vecteur numérique dense qui encode la signification d'une donnée, positionné de manière à ce que les éléments similaires soient proches dans l'espace vectoriel ; la recherche vectorielle récupère les embeddings les plus proches d'une requête.", "takeaways": [ "Les embeddings transforment le sens en vecteurs ; les éléments similaires se situent à proximité les uns des autres.", "La recherche vectorielle effectue la récupération par similarité sémantique, et non par mots-clés exacts.", "Ils alimentent le RAG, la recherche sémantique, le clustering et la recommandation.", "La recherche hybride (vectorielle + mots-clés) surpasse généralement l'une ou l'autre méthode utilisée seule.", "Le découpage (chunking) et le choix du modèle d'embedding déterminent la qualité de la récupération." ], "context": [ "Les ordinateurs comparent des nombres, pas des significations. Les embeddings comblent cet écart : un modèle d'embedding associe un texte à un vecteur de sorte que « annuler mon abonnement » et « comment me désabonner » se retrouvent proches l'un de l'autre, même sans aucun mot commun.", "C'est ce qui rend possible la récupération sémantique. Au lieu de faire correspondre des mots-clés, un système génère l'embedding de la requête et trouve les vecteurs stockés les plus proches — le fondement même de la manière dont le RAG et la recherche moderne récupèrent du contenu pertinent." ], "architecture": [ "Indexation : le contenu est découpé en blocs (chunks), chacun passant par un modèle d'embedding pour produire un vecteur, puis stocké dans un index vectoriel. Requêtage : la requête est convertie en embedding et l'index renvoie les vecteurs les plus proches selon une métrique de similarité (ex. cosinus).", "Les systèmes de production ajoutent un outil de re-classement (re-ranker) pour affiner les meilleurs résultats, combinent la recherche vectorielle avec la recherche par mots-clés (hybride) et filtrent par métadonnées et autorisations. La qualité dépend fortement du découpage (chunking) et du modèle d'embedding." ], "components": [ "Modèle d'embedding", "Découpage (chunking)", "Index / base de données vectorielle", "Métrique de similarité (cosinus)", "Outil de re-classement (re-ranker)", "Recherche hybride (mots-clés)" ], "pros": [ "Recherche par sens, robuste face aux variations de formulation.", "Correspondance multilingue et multimodale.", "L'épine dorsale du RAG et de la recherche sémantique.", "Peu coûteux à interroger à grande échelle une fois indexé." ], "risks": [ "Un mauvais découpage (chunking) dégrade tous les résultats en aval.", "Une inadéquation du modèle d'embedding nuit à la pertinence.", "Les vecteurs peuvent divulguer des informations sensibles ; sécurisez le stockage.", "La recherche vectorielle pure peut passer à côté des besoins de correspondance exacte (utilisez l'hybride)." ], "tools": [ "Modèles d'embedding (OpenAI, Cohere, open-source)", "Bases de données vectorielles (pgvector, Pinecone, Vertex AI Vector Search)", "Outils de re-classement (re-rankers)", "Moteurs de recherche hybride" ], "examples": [ "Recherche sémantique dans un centre d'aide qui correspond à l'intention, et non aux mots-clés.", "Récupération de passages pertinents pour ancrer une réponse RAG.", "Regroupement (clustering) de tickets d'assistance par sujet à l'aide de leurs embeddings." ], "faqs": [ { "q": "En quoi les embeddings diffèrent-ils des mots-clés ?", "a": "La recherche par mots-clés correspond à des mots exacts ; les embeddings correspondent au sens, de sorte que les paraphrases et les synonymes permettent tout de même de récupérer le bon contenu." }, { "q": "Qu'est-ce que la recherche vectorielle ?", "a": "Trouver les embeddings stockés les plus proches de l'embedding d'une requête à l'aide d'une métrique de similarité comme la distance cosinus — une recherche par proximité sémantique." }, { "q": "Pourquoi combiner recherche vectorielle et recherche par mots-clés ?", "a": "Les vecteurs excellent pour le sens mais peuvent manquer des termes exacts (codes, noms). La recherche hybride combine les deux pour obtenir le meilleur rappel et la meilleure précision." }, { "q": "Les embeddings alimentent-ils le RAG ?", "a": "Oui. Le RAG convertit les documents et les requêtes en embeddings, récupère les blocs les plus proches par recherche vectorielle et y ancre la réponse du modèle." } ] }, "de": { "title": "Was sind Embeddings & Vektorsuche?", "summary": "Ein Embedding ist ein numerischer Vektor, der die Bedeutung von Text (oder Bildern, Audio, Code) so darstellt, dass semantisch ähnliche Elemente im Vektorraum nahe beieinander liegen. Die Vektorsuche findet die einer Suchanfrage am nächsten liegenden Embeddings und ermöglicht so eine Suche nach Bedeutung statt nach Schlüsselwörtern. Embeddings sind das Rückgrat von Retrieval-Augmented Generation, semantischer Suche, Clustering und Empfehlungen.", "definition": "Ein Embedding ist ein dichter numerischer Vektor, der die Bedeutung eines Datenelements codiert und so positioniert ist, dass ähnliche Elemente im Vektorraum nahe beieinander liegen; die Vektorsuche ruft die einer Suchanfrage am nächsten liegenden Embeddings ab.", "takeaways": [ "Embeddings verwandeln Bedeutung in Vektoren; Ähnliches liegt nah beieinander.", "Die Vektorsuche ruft Ergebnisse nach semantischer Ähnlichkeit ab, nicht nach exakten Schlüsselwörtern.", "Sie bilden die Basis für RAG, semantische Suche, Clustering und Empfehlungen.", "Hybride Suche (Vektor + Schlüsselwort) ist meist besser als jede Methode für sich allein.", "Chunking und die Wahl des Embedding-Modells bestimmen die Retrieval-Qualität." ], "context": [ "Computer vergleichen Zahlen, keine Bedeutungen. Embeddings schließen diese Lücke: Ein Embedding-Modell bildet Text so auf einen Vektor ab, dass „Abonnement kündigen“ und „Wie melde ich mich ab“ nahe beieinander liegen, selbst wenn sie keine gemeinsamen Wörter enthalten.", "Dies ermöglicht semantisches Retrieval. Anstatt Schlüsselwörter abzugleichen, bettet ein System die Suchanfrage ein und findet die am nächsten liegenden gespeicherten Vektoren – die Grundlage dafür, wie RAG und moderne Suchen relevante Inhalte abrufen." ], "architecture": [ "Indizierung: Inhalte werden in Chunks aufgeteilt, die jeweils ein Embedding-Modell durchlaufen, um einen Vektor zu erzeugen, und dann in einem Vektorindex gespeichert werden. Abfrage: Die Suchanfrage wird eingebettet und der Index gibt die am nächsten liegenden Vektoren anhand einer Ähnlichkeitsmetrik (z. B. Kosinus) zurück.", "Produktionssysteme fügen einen Re-Ranker hinzu, um die Top-Ergebnisse zu verfeinern, kombinieren Vektorsuche mit Keyword-Suche (hybrid) und filtern nach Metadaten und Berechtigungen. Die Qualität hängt stark vom Chunking und dem Embedding-Modell ab." ], "components": [ "Embedding-Modell", "Chunking", "Vektorindex / -datenbank", "Ähnlichkeitsmetrik (Kosinus)", "Re-Ranker", "Hybride (Keyword-)Suche" ], "pros": [ "Suche nach Bedeutung, robust gegenüber Formulierungen.", "Sprachübergreifender und multimodaler Abgleich.", "Das Rückgrat von RAG und semantischer Suche.", "Nach der Indizierung kostengünstig im großen Maßstab abfragbar." ], "risks": [ "Schlechtes Chunking verschlechtert jedes nachgelagerte Ergebnis.", "Ein unpassendes Embedding-Modell beeinträchtigt die Relevanz.", "Vektoren können sensible Informationen preisgeben; sichern Sie den Speicher.", "Reine Vektorsuche kann Anforderungen an exakte Übereinstimmungen verfehlen (hybride Suche nutzen)." ], "tools": [ "Embedding-Modelle (OpenAI, Cohere, Open-Source)", "Vektordatenbanken (pgvector, Pinecone, Vertex AI Vector Search)", "Re-Ranker", "Hybride Suchmaschinen" ], "examples": [ "Semantische Suche in einem Hilfe-Center, die Absichten statt Schlüsselwörter abgleicht.", "Abrufen relevanter Passagen zur Fundierung einer RAG-Antwort.", "Clustering von Support-Tickets nach Thema mithilfe ihrer Embeddings." ], "faqs": [ { "q": "Wie unterscheiden sich Embeddings von Schlüsselwörtern?", "a": "Die Keyword-Suche gleicht exakte Wörter ab; Embeddings gleichen Bedeutungen ab, sodass Paraphrasen und Synonyme dennoch die richtigen Inhalte abrufen." }, { "q": "Was ist Vektorsuche?", "a": "Das Finden der gespeicherten Embeddings, die einem Query-Embedding am nächsten liegen, mithilfe einer Ähnlichkeitsmetrik wie der Kosinus-Distanz – Suche nach semantischer Nähe." }, { "q": "Warum sollte man Vektor- und Keyword-Suche kombinieren?", "a": "Vektoren sind hervorragend darin, Bedeutungen zu erfassen, können aber exakte Begriffe (Codes, Namen) verfehlen. Die hybride Suche kombiniert beides für bestmöglichen Recall und Präzision." }, { "q": "Basiert RAG auf Embeddings?", "a": "Ja. RAG bettet Dokumente und Suchanfragen ein, ruft die am nächsten liegenden Chunks per Vektorsuche ab und fundiert die Antwort des Modells darauf." } ] }, "ja": { "title": "埋め込み（Embeddings）とベクトル検索とは何ですか？", "summary": "埋め込み（Embedding）とは、テキスト（または画像、音声、コード）の意味を表現する数値ベクトルであり、意味的に類似したアイテムがベクトル空間上で近くに配置されるようにします。ベクトル検索は、クエリに最も近い埋め込みを見つけることで、キーワードではなく意味による検索を可能にします。埋め込みは、検索拡張生成（RAG）、セマンティック検索、クラスタリング、レコメンデーションの基盤となっています。", "definition": "埋め込みとは、データの一片の意味をエンコードした密な数値ベクトルであり、類似したアイテムがベクトル空間上で近くに配置されるように位置決めされます。ベクトル検索は、クエリに最も近い埋め込みを検索します。", "takeaways": [ "埋め込みは意味をベクトルに変換します。類似したものは近くに配置されます。", "ベクトル検索は、完全一致するキーワードではなく、セマンティックな類似性に基づいて検索します。", "これらは、RAG、セマンティック検索、クラスタリング、レコメンデーションを強力にサポートします。", "ハイブリッド検索（ベクトル＋キーワード）は、通常、どちらか一方のみを使用する場合よりも優れた結果をもたらします。", "チャンク分割と埋め込みモデルの選択が、検索品質を左右します。" ], "context": [ "コンピューターは意味ではなく数値を比較します。埋め込みはそのギャップを埋めるものです。埋め込みモデルはテキストをベクトルにマッピングするため、共通の単語がなくても「サブスクリプションをキャンセルする」と「退会方法を教えてください」が近くに配置されます。", "これにより、セマンティック検索が可能になります。システムはキーワードをマッチングする代わりに、クエリを埋め込み、保存されている最も近いベクトルを見つけます。これが、RAGや最新の検索システムが関連コンテンツを検索する仕組みの基礎となっています。" ], "architecture": [ "インデックス作成：コンテンツはチャンクに分割され、それぞれが埋め込みモデルを通過してベクトルを生成し、ベクトルインデックスに保存されます。クエリ実行：クエリが埋め込まれ、インデックスは類似度指標（コサイン類似度など）に基づいて最も近いベクトルを返します。", "本番システムでは、リランカーを追加して上位の結果を絞り込み、ベクトル検索とキーワード検索を組み合わせ（ハイブリッド）、メタデータや権限でフィルタリングします。品質は、チャンク分割と埋め込みモデルに大きく依存します。" ], "components": [ "埋め込みモデル", "チャンク分割", "ベクトルインデックス / データベース", "類似度指標（コサイン類似度）", "リランカー", "ハイブリッド（キーワード）検索" ], "pros": [ "意味による検索が可能で、言い回しの違いに強い。", "多言語およびマルチモーダルなマッチングに対応。", "RAGやセマンティック検索の基盤。", "一度インデックスを作成すれば、大規模なクエリを低コストで実行可能。" ], "risks": [ "不適切なチャンク分割は、下流のすべての結果を悪化させます。", "埋め込みモデルの不一致は、関連性を損ないます。", "ベクトルから機密情報が漏洩する可能性があります。ストアを保護してください。", "純粋なベクトル検索では、完全一致のニーズを見落とす可能性があります（ハイブリッド検索を使用してください）。" ], "tools": [ "埋め込みモデル（OpenAI、Cohere、オープンソース）", "ベクトルデータベース（pgvector、Pinecone、Vertex AI Vector Search）", "リランカー", "ハイブリッド検索エンジン" ], "examples": [ "キーワードではなく意図にマッチする、ヘルプセンター全体のセマンティック検索。", "RAGの回答を根拠付けるために、関連する一節を検索。", "埋め込みを使用して、サポートチケットをトピックごとにクラスタリング。" ], "faqs": [ { "q": "埋め込みはキーワードとどう違うのですか？", "a": "キーワード検索は正確な単語をマッチングしますが、埋め込みは意味をマッチングするため、言い換えや類義語であっても適切なコンテンツを検索できます。" }, { "q": "ベクトル検索とは何ですか？", "a": "コサイン距離などの類似度指標によって、クエリの埋め込みに最も近い、保存された埋め込みを見つけることです。つまり、意味的な近さによる検索です。" }, { "q": "なぜベクトル検索とキーワード検索を組み合わせるのですか？", "a": "ベクトルは意味の把握に優れていますが、正確な用語（コードや名前など）を見落とすことがあります。ハイブリッド検索は、再現率と適合率を最大化するために両方を組み合わせます。" }, { "q": "埋め込みはRAGを強力にサポートしますか？", "a": "はい。RAGはドキュメントとクエリを埋め込み、ベクトル検索によって最も近いチャンクを検索し、それらに基づいてモデルの回答を根拠付けます。" } ] }, "zh": { "title": "什么是 Embeddings 与向量搜索？", "summary": "Embedding（嵌入）是一个数值向量，用于表示文本（或图像、音频、代码）的含义，从而使语义相似的项在向量空间中彼此接近。向量搜索用于查找与查询最接近的 Embedding，从而实现按含义而非关键词进行搜索。Embedding 是检索增强生成（RAG）、语义搜索、聚类和推荐的核心支柱。", "definition": "Embedding 是一种稠密数值向量，用于对数据片段的含义进行编码，其位置使得相似的项在向量空间中彼此接近；向量搜索则用于检索与查询最接近的 Embedding。", "takeaways": [ "Embedding 将含义转化为向量；相似的事物在空间中彼此接近。", "向量搜索通过语义相似度进行检索，而非精确的关键词。", "它们为 RAG、语义搜索、聚类和推荐提供支持。", "混合搜索（向量 + 关键词）的效果通常优于其中任何一种单一方式。", "分块（Chunking）和 Embedding 模型的选择决定了检索质量。" ], "context": [ "计算机比较的是数字，而非含义。Embedding 弥合了这一差距：Embedding 模型将文本映射为向量，使得“取消我的订阅”和“如何退订”即使没有共同的词，也会落在彼此临近的位置。", "这正是语义检索成为可能的原因。系统不再匹配关键词，而是对查询进行 Embedding，并找到最接近的已存储向量——这是 RAG 和现代搜索检索相关内容的基础。" ], "architecture": [ "索引：内容被拆分为分块（Chunks），每个分块通过 Embedding 模型生成一个向量，然后存储在向量索引中。查询：对查询进行 Embedding，索引通过相似度度量（例如余弦相似度）返回最接近的向量。", "生产系统会添加重排器（Re-ranker）以优化最靠前的结果，将向量搜索与关键词搜索相结合（混合搜索），并根据元数据和权限进行过滤。质量在很大程度上取决于分块和 Embedding 模型。" ], "components": [ "Embedding 模型", "分块（Chunking）", "向量索引 / 数据库", "相似度度量（余弦）", "重排器（Re-ranker）", "混合（关键词）搜索" ], "pros": [ "按含义搜索，对措辞具有鲁棒性。", "跨语言和多模态匹配。", "RAG 和语义搜索的支柱。", "一旦建立索引，大规模查询的成本非常低。" ], "risks": [ "糟糕的分块会降低所有下游结果的质量。", "Embedding 模型不匹配会损害相关性。", "向量可能会泄露敏感信息；请确保存储安全。", "纯向量搜索可能会遗漏精确匹配的需求（请使用混合搜索）。" ], "tools": [ "Embedding 模型（OpenAI、Cohere、开源模型）", "向量数据库（pgvector、Pinecone、Vertex AI Vector Search）", "重排器", "混合搜索引擎" ], "examples": [ "在帮助中心进行语义搜索，匹配的是意图而非关键词。", "检索相关段落以作为 RAG 回答的依据。", "利用工单的 Embedding 按主题对支持工单进行聚类。" ], "faqs": [ { "q": "Embedding 与关键词有什么区别？", "a": "关键词搜索匹配的是精确的词语；Embedding 匹配的是含义，因此即使使用释义和同义词，仍能检索到正确的内容。" }, { "q": "什么是向量搜索？", "a": "通过余弦距离等相似度度量，查找与查询 Embedding 最接近的已存储 Embedding——即按语义接近度进行搜索。" }, { "q": "为什么要将向量搜索和关键词搜索结合起来？", "a": "向量擅长表达含义，但可能会遗漏精确的术语（代码、名称）。混合搜索融合了这两者，以获得最佳的召回率和准确率。" }, { "q": "Embedding 是 RAG 的核心吗？", "a": "是的。RAG 对文档 and 查询进行 Embedding，通过向量搜索检索最接近的分块，并以此作为模型回答的依据。" } ] } } }, { "slug": "enterprise-rag", "category": "pattern", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/enterprise-rag", "api": "https://santismm.com/api/knowledge/enterprise-rag", "canonical_url": "https://santismm.com/en/knowledge/enterprise-rag", "api_url": "https://santismm.com/api/knowledge/enterprise-rag", "evidence": { "evidenceLevel": "benchmark", "confidenceLevel": "high", "sourceType": [ "benchmark", "paper", "industry_observation" ] }, "references": [ { "title": "Lewis et al. — Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (2020)", "url": "https://arxiv.org/abs/2005.11401" }, { "title": "Model Context Protocol — Resources", "url": "https://modelcontextprotocol.io" } ], "related": [ "agentic-ai", "model-context-protocol", "ai-governance", "ai-agent" ], "locales": { "en": { "title": "What is Enterprise RAG?", "summary": "Enterprise RAG (retrieval-augmented generation) is the pattern of grounding a model's answers in an organization's own documents, retrieved at query time, instead of relying on the model's parametric memory. It lets a company use private, current and governed knowledge — policies, manuals, tickets, contracts — without retraining a model, while keeping access control, citations and auditability that enterprises require.", "definition": "Enterprise RAG is a pattern that retrieves relevant passages from an organization's governed knowledge sources and supplies them to a model as context, so answers are grounded, current and citable.", "takeaways": [ "RAG grounds answers in retrieved documents, reducing hallucination.", "It uses private and fresh knowledge without retraining.", "Retrieval quality (chunking + embeddings) drives answer quality.", "Enterprise-grade RAG adds access control, citations and audit.", "Becomes agentic when the system decides when and what to retrieve." ], "context": [ "A base model only knows what it learned during training. Enterprise knowledge is private, changing and access-controlled. RAG bridges that gap by fetching the right passages at query time and grounding the answer in them.", "The enterprise difference is governance: who is allowed to see which documents, where the answer's sources came from, and whether the whole interaction can be audited. RAG that ignores these is a prototype, not a production system." ], "architecture": [ "Ingestion: documents are parsed, split into self-contained chunks, embedded and stored in a vector index (often alongside keyword search). Retrieval: a query is embedded, the nearest chunks are fetched, optionally re-ranked and filtered by permissions. Generation: the model answers using those chunks and cites them.", "Quality hinges on the unglamorous parts: clean parsing, sensible chunking, hybrid (vector + keyword) retrieval, re-ranking, and permission filtering. Well-structured source content makes every one of these steps easier." ], "components": [ "Ingestion & chunking", "Embeddings", "Vector / hybrid index", "Retriever & re-ranker", "Permission filter", "Generator (LLM)", "Citation layer" ], "pros": [ "Grounded, citable, up-to-date answers.", "Uses private knowledge without retraining.", "Respects access control and auditability.", "Cheaper and faster to update than fine-tuning." ], "risks": [ "Poor chunking or retrieval yields wrong or irrelevant context.", "Stale or unpermissioned data leaks into answers.", "Citations can be plausible but unsupported if not verified.", "Retrieval latency and cost at scale." ], "tools": [ "Vector databases (e.g. pgvector, Pinecone, Vertex AI Vector Search)", "Embedding models", "Re-rankers", "Hybrid search engines", "MCP resource servers" ], "examples": [ "An internal assistant answering HR policy questions with cited passages.", "A support agent retrieving product docs to resolve tickets.", "A legal assistant surfacing relevant clauses with source links." ], "faqs": [ { "q": "Is RAG better than fine-tuning?", "a": "They solve different problems. RAG injects fresh, governed knowledge at query time; fine-tuning adapts behavior or style. They are often combined." }, { "q": "Why does chunking matter so much?", "a": "Retrieval works on chunks. Self-contained, well-structured chunks retrieve cleanly; fragmented ones return noise. Chunk quality largely sets RAG quality." }, { "q": "What makes RAG enterprise-grade?", "a": "Access control on retrieval, source citations, auditability, freshness, and evaluation — not just a vector store plus a model." }, { "q": "When does RAG become agentic?", "a": "When retrieval is one step in a multi-step loop where the system decides whether, when and what to retrieve, rather than always retrieving once." } ] }, "es": { "title": "¿Qué es el RAG empresarial (Enterprise RAG)?", "summary": "El RAG empresarial (generación aumentada por recuperación) es el patrón de fundamentar las respuestas de un modelo en los propios documentos de la organización, recuperados en el momento de la consulta, en lugar de depender de la memoria paramétrica del modelo. Permite usar conocimiento privado, actual y gobernado —políticas, manuales, tickets, contratos— sin reentrenar un modelo, manteniendo el control de acceso, las citas y la auditabilidad que exigen las empresas.", "definition": "El RAG empresarial es un patrón que recupera pasajes relevantes de las fuentes de conocimiento gobernadas de una organización y los entrega a un modelo como contexto, para que las respuestas estén fundamentadas, actualizadas y sean citables.", "takeaways": [ "El RAG fundamenta las respuestas en documentos recuperados, reduciendo la alucinación.", "Usa conocimiento privado y fresco sin reentrenar.", "La calidad de recuperación (chunking + embeddings) determina la calidad de la respuesta.", "El RAG de grado empresarial añade control de acceso, citas y auditoría.", "Se vuelve agéntico cuando el sistema decide cuándo y qué recuperar." ], "context": [ "Un modelo base solo sabe lo que aprendió durante el entrenamiento. El conocimiento empresarial es privado, cambiante y con control de acceso. El RAG salva esa brecha recuperando los pasajes adecuados en el momento de la consulta y fundamentando la respuesta en ellos.", "La diferencia empresarial es la gobernanza: quién puede ver qué documentos, de dónde vienen las fuentes de la respuesta y si toda la interacción puede auditarse. Un RAG que ignora esto es un prototipo, no un sistema en producción." ], "architecture": [ "Ingesta: los documentos se parsean, se dividen en chunks autocontenidos, se embeben y se guardan en un índice vectorial (a menudo junto a búsqueda por palabras clave). Recuperación: la consulta se embebe, se traen los chunks más cercanos, se re-rankean y se filtran por permisos. Generación: el modelo responde usando esos chunks y los cita.", "La calidad depende de las partes poco glamurosas: parseo limpio, chunking sensato, recuperación híbrida (vector + palabras clave), re-ranking y filtrado por permisos. Un contenido fuente bien estructurado facilita cada uno de esos pasos." ], "components": [ "Ingesta y chunking", "Embeddings", "Índice vectorial / híbrido", "Recuperador y re-ranker", "Filtro de permisos", "Generador (LLM)", "Capa de citas" ], "pros": [ "Respuestas fundamentadas, citables y actualizadas.", "Usa conocimiento privado sin reentrenar.", "Respeta el control de acceso y la auditabilidad.", "Más barato y rápido de actualizar que el fine-tuning." ], "risks": [ "Un chunking o recuperación pobres dan contexto erróneo o irrelevante.", "Datos desactualizados o sin permisos se filtran en las respuestas.", "Las citas pueden ser plausibles pero no respaldadas si no se verifican.", "Latencia y coste de recuperación a escala." ], "tools": [ "Bases de datos vectoriales (p. ej. pgvector, Pinecone, Vertex AI Vector Search)", "Modelos de embeddings", "Re-rankers", "Motores de búsqueda híbrida", "Servidores de recursos MCP" ], "examples": [ "Un asistente interno que responde preguntas de políticas de RRHH con pasajes citados.", "Un agente de soporte que recupera documentación de producto para resolver tickets.", "Un asistente legal que muestra cláusulas relevantes con enlaces a la fuente." ], "faqs": [ { "q": "¿El RAG es mejor que el fine-tuning?", "a": "Resuelven problemas distintos. El RAG inyecta conocimiento fresco y gobernado en el momento de la consulta; el fine-tuning adapta comportamiento o estilo. A menudo se combinan." }, { "q": "¿Por qué importa tanto el chunking?", "a": "La recuperación opera sobre chunks. Los chunks autocontenidos y bien estructurados se recuperan limpiamente; los fragmentados devuelven ruido. La calidad del chunk fija en gran medida la del RAG." }, { "q": "¿Qué hace a un RAG de grado empresarial?", "a": "Control de acceso en la recuperación, citas de fuentes, auditabilidad, frescura y evaluación, no solo un almacén vectorial más un modelo." }, { "q": "¿Cuándo se vuelve agéntico el RAG?", "a": "Cuando la recuperación es un paso de un bucle de varios pasos en el que el sistema decide si, cuándo y qué recuperar, en vez de recuperar siempre una vez." } ] }, "pt": { "title": "O que é RAG empresarial (Enterprise RAG)?", "summary": "O RAG empresarial (geração aumentada por recuperação) é o padrão de fundamentar as respostas de um modelo nos próprios documentos da organização, recuperados no momento da consulta, em vez de depender da memória paramétrica do modelo. Permite usar conhecimento privado, atual e governado — políticas, manuais, chamados, contratos — sem retreinar um modelo, mantendo o controle de acesso, as citações e a auditabilidade que as empresas exigem.", "definition": "O RAG empresarial é um padrão que recupera trechos relevantes das fontes de conhecimento governadas de uma organização e os fornece a um modelo como contexto, para que as respostas sejam fundamentadas, atuais e citáveis.", "takeaways": [ "O RAG fundamenta as respostas em documentos recuperados, reduzindo a alucinação.", "Usa conhecimento privado e fresco sem retreinar.", "A qualidade da recuperação (chunking + embeddings) determina a qualidade da resposta.", "O RAG de nível empresarial adiciona controle de acesso, citações e auditoria.", "Torna-se agêntico quando o sistema decide quando e o que recuperar." ], "context": [ "Um modelo base só sabe o que aprendeu durante o treinamento. O conhecimento empresarial é privado, mutável e com controle de acesso. O RAG preenche essa lacuna recuperando os trechos adequados no momento da consulta e fundamentando a resposta neles.", "A diferença empresarial é a governança: quem pode ver quais documentos, de onde vieram as fontes da resposta e se toda a interação pode ser auditada. Um RAG que ignora isso é um protótipo, não um sistema em produção." ], "architecture": [ "Ingestão: os documentos são parseados, divididos em chunks autocontidos, embedados e guardados num índice vetorial (muitas vezes junto à busca por palavras-chave). Recuperação: a consulta é embedada, os chunks mais próximos são trazidos, re-ranqueados e filtrados por permissões. Geração: o modelo responde usando esses chunks e os cita.", "A qualidade depende das partes pouco glamourosas: parsing limpo, chunking sensato, recuperação híbrida (vetor + palavras-chave), re-ranking e filtragem por permissões. Um conteúdo-fonte bem estruturado facilita cada um desses passos." ], "components": [ "Ingestão e chunking", "Embeddings", "Índice vetorial / híbrido", "Recuperador e re-ranker", "Filtro de permissões", "Gerador (LLM)", "Camada de citações" ], "pros": [ "Respostas fundamentadas, citáveis e atualizadas.", "Usa conhecimento privado sem retreinar.", "Respeita o controle de acesso e a auditabilidade.", "Mais barato e rápido de atualizar que o fine-tuning." ], "risks": [ "Um chunking ou recuperação ruins dão contexto errado ou irrelevante.", "Dados desatualizados ou sem permissões vazam nas respostas.", "As citações podem ser plausíveis mas não comprovadas se não forem verificadas.", "Latência e custo de recuperação em escala." ], "tools": [ "Bancos de dados vetoriais (ex.: pgvector, Pinecone, Vertex AI Vector Search)", "Modelos de embeddings", "Re-rankers", "Motores de busca híbrida", "Servidores de recursos MCP" ], "examples": [ "Um assistente interno que responde perguntas de políticas de RH com trechos citados.", "Um agente de suporte que recupera documentação de produto para resolver chamados.", "Um assistente jurídico que mostra cláusulas relevantes com links para a fonte." ], "faqs": [ { "q": "O RAG é melhor que o fine-tuning?", "a": "Resolvem problemas distintos. O RAG injeta conhecimento fresco e governado no momento da consulta; o fine-tuning adapta comportamento ou estilo. Muitas vezes são combinados." }, { "q": "Por que o chunking importa tanto?", "a": "A recuperação opera sobre chunks. Chunks autocontidos e bem estruturados são recuperados de forma limpa; os fragmentados retornam ruído. A qualidade do chunk define em grande parte a do RAG." }, { "q": "O que torna um RAG de nível empresarial?", "a": "Controle de acesso na recuperação, citações de fontes, auditabilidade, frescor e avaliação, não só um armazenamento vetorial mais um modelo." }, { "q": "Quando o RAG se torna agêntico?", "a": "Quando a recuperação é um passo de um laço de vários passos em que o sistema decide se, quando e o que recuperar, em vez de recuperar sempre uma vez." } ] }, "fr": { "title": "Qu'est-ce que le RAG d'entreprise ?", "summary": "Le RAG d'entreprise (génération augmentée de récupération) est le modèle consistant à ancrer les réponses d'un modèle dans les propres documents d'une organisation, récupérés au moment de la requête, plutôt que de s'appuyer sur la mémoire paramétrique du modèle. Il permet à une entreprise d'utiliser des connaissances privées, actuelles et gouvernées — politiques, manuels, tickets, contrats — sans réentraîner le modèle, tout en conservant le contrôle d'accès, les citations et l'auditabilité requis par les entreprises.", "definition": "Le RAG d'entreprise est un modèle qui récupère des passages pertinents à partir des sources de connaissances gouvernées d'une organisation et les fournit à un modèle en tant que contexte, afin que les réponses soient ancrées, actuelles et citables.", "takeaways": [ "Le RAG ancre les réponses dans les documents récupérés, réduisant ainsi les hallucinations.", "Il utilise des connaissances privées et récentes sans réentraînement.", "La qualité de la récupération (découpage + embeddings) détermine la qualité des réponses.", "Le RAG de classe entreprise ajoute le contrôle d'accès, les citations et l'audit.", "Devient agentique lorsque le système décide quand et quoi récupérer." ], "context": [ "Un modèle de base ne sait que ce qu'il a appris lors de son entraînement. Les connaissances de l'entreprise sont privées, évolutives et soumises à un contrôle d'accès. Le RAG comble cet écart en récupérant les bons passages au moment de la requête et en y ancrant la réponse.", "La différence pour l'entreprise réside dans la gouvernance : qui est autorisé à voir quels documents, d'où proviennent les sources de la réponse et si l'ensemble de l'interaction peut être audité. Un RAG qui ignore ces aspects est un prototype, pas un système de production." ], "architecture": [ "Ingestion : les documents sont analysés, découpés en blocs autonomes, convertis en embeddings et stockés dans un index vectoriel (souvent combiné à une recherche par mots-clés). Récupération : la requête est convertie en embedding, les blocs les plus proches sont récupérés, éventuellement re-classés et filtrés selon les autorisations. Génération : le modèle répond à l'aide de ces blocs et les cite.", "La qualité repose sur des aspects moins prestigieux : une analyse propre, un découpage cohérent, une récupération hybride (vectorielle + mots-clés), un re-classement et un filtrage des autorisations. Un contenu source bien structuré facilite chacune de ces étapes." ], "components": [ "Ingestion et découpage (chunking)", "Embeddings", "Index vectoriel / hybride", "Moteur de récupération et de re-classement (retriever & re-ranker)", "Filtre d'autorisations", "Générateur (LLM)", "Couche de citation" ], "pros": [ "Réponses ancrées, citables et à jour.", "Utilise des connaissances privées sans réentraînement.", "Respecte le contrôle d'accès et l'auditabilité.", "Plus économique et plus rapide à mettre à jour que le fine-tuning." ], "risks": [ "Un mauvais découpage (chunking) ou une mauvaise récupération produit un contexte erroné ou non pertinent.", "Des données obsolètes ou sans autorisation s'infiltrent dans les réponses.", "Les citations peuvent être plausibles mais non étayées si elles ne sont pas vérifiées.", "Latence de récupération et coût à grande échelle." ], "tools": [ "Bases de données vectorielles (par ex. pgvector, Pinecone, Vertex AI Vector Search)", "Modèles d'embedding", "Re-rankers", "Moteurs de recherche hybrides", "Serveurs de ressources MCP" ], "examples": [ "Un assistant interne répondant aux questions sur les politiques RH avec des passages cités.", "Un agent de support récupérant la documentation produit pour résoudre des tickets.", "Un assistant juridique faisant ressortir les clauses pertinentes avec des liens vers les sources." ], "faqs": [ { "q": "Le RAG est-il meilleur que le fine-tuning ?", "a": "Ils résolvent des problèmes différents. Le RAG injecte des connaissances fraîches et gouvernées au moment de la requête ; le fine-tuning adapte le comportement ou le style. Ils sont souvent combinés." }, { "q": "Pourquoi le découpage (chunking) est-il si important ?", "a": "La récupération fonctionne sur des fragments (chunks). Des fragments autonomes et bien structurés sont récupérés proprement ; les fragments fragmentés renvoient du bruit. La qualité du découpage détermine en grande partie la qualité du RAG." }, { "q": "Qu'est-ce qui rend le RAG de niveau entreprise ?", "a": "Le contrôle d'accès lors de la récupération, les citations de sources, l'auditabilité, la fraîcheur et l'évaluation — et pas seulement un stockage vectoriel associé à un modèle." }, { "q": "Quand le RAG devient-il agentique ?", "a": "Lorsque la récupération est une étape dans une boucle multi-étapes où le système décide si, quand et quoi récupérer, plutôt que de toujours effectuer une récupération unique." } ] }, "de": { "title": "Was ist Enterprise RAG?", "summary": "Enterprise RAG (Retrieval-Augmented Generation) ist das Entwurfsmuster, bei dem die Antworten eines Modells auf den eigenen Dokumenten einer Organisation fundiert werden, die zum Zeitpunkt der Abfrage abgerufen werden, anstatt sich auf das parametrische Gedächtnis des Modells zu verlassen. Es ermöglicht einem Unternehmen, privates, aktuelles und kontrolliertes Wissen – Richtlinien, Handbücher, Tickets, Verträge – ohne erneutes Training eines Modells zu nutzen, während gleichzeitig die von Unternehmen geforderten Zugriffskontrollen, Zitate und Auditierbarkeit gewahrt bleiben.", "definition": "Enterprise RAG ist ein Entwurfsmuster, das relevante Passagen aus den kontrollierten Wissensquellen einer Organisation abruft und sie einem Modell als Kontext zur Verfügung stellt, sodass Antworten fundiert, aktuell und zitierfähig sind.", "takeaways": [ "RAG fundiert Antworten in abgerufenen Dokumenten und reduziert so Halluzinationen.", "Es nutzt privates und aktuelles Wissen ohne erneutes Training.", "Die Retrieval-Qualität (Chunking + Embeddings) bestimmt die Antwortqualität.", "Enterprise-RAG bietet zusätzlich Zugriffskontrolle, Zitate und Audits.", "Wird agentisch, wenn das System entscheidet, wann und was abgerufen werden soll." ], "context": [ "Ein Basismodell weiß nur, was es während des Trainings gelernt hat. Unternehmenswissen ist privat, verändert sich ständig und unterliegt Zugriffskontrollen. RAG schließt diese Lücke, indem es zum Zeitpunkt der Abfrage die richtigen Passagen abruft und die Antwort darauf fundiert.", "Der Unterschied im Enterprise-Bereich liegt in der Governance: Wer darf welche Dokumente sehen, woher stammen die Quellen der Antwort und ob die gesamte Interaktion auditiert werden kann. Ein RAG, das dies ignoriert, ist ein Prototyp, kein Produktionssystem." ], "architecture": [ "Ingestion: Dokumente werden geparst, in inhaltlich geschlossene Chunks aufgeteilt, eingebettet und in einem Vektorindex gespeichert (oft zusammen mit einer Keyword-Suche). Retrieval: Eine Suchanfrage wird eingebettet, die am nächsten liegenden Chunks werden abgerufen, optional neu bewertet (Re-Ranking) und nach Berechtigungen gefiltert. Generation: Das Modell antwortet unter Verwendung dieser Chunks und zitiert sie.", "Die Qualität hängt von den weniger glanzvollen Teilen ab: sauberes Parsing, sinnvolles Chunking, hybrides (Vektor- + Keyword-)Retrieval, Re-Ranking und Berechtigungsfilterung. Gut strukturierte Quellinhalte erleichtern jeden dieser Schritte." ], "components": [ "Ingestion & Chunking", "Embeddings", "Vektor- / Hybrid-Index", "Retriever & Re-Ranker", "Berechtigungsfilter", "Generator (LLM)", "Zitierungsebene" ], "pros": [ "Fundierte, zitierfähige und aktuelle Antworten.", "Nutzt privates Wissen ohne erneutes Training.", "Berücksichtigt Zugriffskontrolle und Auditierbarkeit.", "Günstiger und schneller zu aktualisieren als Fine-tuning." ], "risks": [ "Mangelhaftes Chunking oder Retrieval führt zu falschem oder irrelevantem Kontext.", "Veraltete oder nicht autorisierte Daten gelangen in die Antworten.", "Zitate können plausibel, aber ohne Überprüfung unbelegt sein.", "Retrieval-Latenz und Kosten bei hoher Skalierung." ], "tools": [ "Vektordatenbanken (z. B. pgvector, Pinecone, Vertex AI Vector Search)", "Embedding-Modelle", "Re-Ranker", "Hybride Suchmaschinen", "MCP-Ressourcenserver" ], "examples": [ "Ein interner Assistent, der Fragen zu HR-Richtlinien mit zitierten Textstellen beantwortet.", "Ein Support-Agent, der Produktdokumentationen abruft, um Tickets zu lösen.", "Ein Rechtsassistent, der relevante Klauseln mit Quellenlinks bereitstellt." ], "faqs": [ { "q": "Ist RAG besser als Fine-tuning?", "a": "Sie lösen unterschiedliche Probleme. RAG speist zum Abfragezeitpunkt aktuelles, kontrolliertes Wissen ein; Fine-tuning passt das Verhalten oder den Stil an. Beide werden oft kombiniert." }, { "q": "Warum ist Chunking so wichtig?", "a": "Das Retrieval arbeitet auf Chunks. In sich geschlossene, gut strukturierte Chunks lassen sich sauber abrufen; fragmentierte Chunks führen zu Rauschen. Die Chunk-Qualität bestimmt maßgeblich die RAG-Qualität." }, { "q": "Was macht RAG unternehmenstauglich?", "a": "Zugriffskontrolle beim Retrieval, Quellenzitate, Auditierbarkeit, Aktualität und Evaluierung – nicht nur ein Vektorspeicher plus ein Modell." }, { "q": "Wann wird RAG agentisch?", "a": "Wenn das Retrieval ein Schritt in einer mehrstufigen Schleife ist, in der das System decides entscheidet, ob, wann und was abgerufen werden soll, anstatt immer nur einmal abzurufen." } ] }, "ja": { "title": "エンタープライズRAGとは何ですか？", "summary": "エンタープライズRAG（検索拡張生成）は、モデルのパラメータメモリに依存するのではなく、クエリ実行時に検索された組織独自のドキュメントに基づいてモデルの回答を根拠付けるパターンです。これにより、企業はモデルを再トレーニングすることなく、ポリシー、マニュアル、チケット、契約書などのプライベートで最新の、かつガバナンスの効いた知識を利用できると同時に、企業が必要とするアクセス制御、引用、監査可能性を維持できます。", "definition": "エンタープライズRAGは、組織のガバナンスが効いた知識ソースから関連する一節を検索し、コンテキストとしてモデルに提供することで、回答の根拠を明確にし、最新かつ引用可能にするパターンです。", "takeaways": [ "RAGは検索されたドキュメントに基づいて回答を根拠付け、ハルシネーションを低減します。", "再トレーニングを行うことなく、プライベートで最新の知識を利用できます。", "検索品質（チャンク分割＋埋め込み）が回答の品質を左右します。", "エンタープライズグレードのRAGは、アクセス制御、引用、監査機能を追加します。", "システムが「いつ」「何を」検索するかを決定するようになると、エージェント型（agentic）になります。" ], "context": [ "ベースモデルは、トレーニング中に学習したことしか知りません。企業の知識はプライベートで、常に変化し、アクセス制御されています。RAGは、クエリ実行時に適切な一節を取得し、それに基づいて回答を根拠付けることで、そのギャップを埋めます。", "エンタープライズにおける違いはガバナンスにあります。誰がどのドキュメントの閲覧を許可されているか、回答のソースがどこから来ているか、そしてインタラクション全体を監査できるかどうかです。これらを無視したRAGは、本番システムではなくプロトタイプにすぎません。" ], "architecture": [ "インジェスト：ドキュメントが解析され、自己完結型のチャンクに分割され、埋め込まれてベクトルインデックスに保存されます（多くの場合、キーワード検索と併用されます）。検索：クエリが埋め込まれ、最も近いチャンクが取得され、必要に応じて再ランク付けされ、権限によってフィルタリングされます。生成：モデルはそれらのチャンクを使用して回答し、それらを引用します。", "品質は、クリーンな解析、適切なチャンク分割、ハイブリッド（ベクトル＋キーワード）検索、再ランク付け、権限フィルタリングといった、地味な部分にかかっています。適切に構造化されたソースコンテンツは、これらのすべてのステップを容易にします。" ], "components": [ "インジェストとチャンク分割", "埋め込み", "ベクトル / ハイブリッドインデックス", "リトリーバー＆リランカー", "権限フィルター", "ジェネレーター（LLM）", "引用レイヤー" ], "pros": [ "グラウンディングされた、引用可能で最新の回答。", "再学習なしでプライベートな知識を利用可能。", "アクセス制御と監査可能性を遵守。", "ファインチューニングよりも低コストかつ迅速に更新可能。" ], "risks": [ "不適切なチャンク分割や検索により、誤ったコンテキストや無関係なコンテキストが生成される。", "古いデータや権限のないデータが回答に漏洩する。", "検証されない場合、引用がもっともらしく見えても根拠がない可能性がある。", "大規模運用時における検索のレイテンシとコスト。" ], "tools": [ "ベクトルデータベース（例：pgvector、Pinecone、Vertex AI Vector Search）", "埋め込みモデル", "リランカー", "ハイブリッド検索エンジン", "MCPリソースサーバー" ], "examples": [ "引用箇所を提示しながら人事ポリシーに関する質問に回答する社内アシスタント。", "チケットを解決するために製品ドキュメントを検索するサポートエージェント。", "ソースへのリンク付きで関連する条項を提示する法務アシスタント。" ], "faqs": [ { "q": "RAGはファインチューニングよりも優れていますか？", "a": "これらは異なる課題を解決するものです。RAGはクエリ実行時に最新の管理された知識を注入し、ファインチューニングは振る舞いやスタイルを適応させます。これらはしばしば組み合わせて使用されます。" }, { "q": "なぜチャンク分割がそれほど重要なのでしょうか？", "a": "検索はチャンク単位で機能します。自己完結型で適切に構造化されたチャンクは正確に検索されますが、断片化されたチャンクはノイズを返します。チャンクの品質がRAGの品質を大きく左右します。" }, { "q": "何がRAGをエンタープライズグレードにするのでしょうか？", "a": "単にベクトルストアとモデルを組み合わせるだけでなく、検索時のアクセス制御、ソースの引用、監査可能性、最新性、および評価が備わっていることです。" }, { "q": "RAGはどのような場合にエージェント型（Agentic）になりますか？", "a": "常に1回だけ検索するのではなく、システムが検索の要否、タイミング、対象を判断するマルチステップのループにおいて、検索がその一ステップとなる場合です。" } ] }, "zh": { "title": "什么是企业级 RAG？", "summary": "企业级 RAG（检索增强生成）是一种在查询时检索组织自身的文档，并以此作为模型回答依据的模式，而不是依赖模型的参数化记忆。它允许企业在不重新训练模型的情况下，使用私有、最新且受治理的知识（如政策、手册、工单、合同），同时保持企业所需的访问控制、引用和可审计性。", "definition": "企业级 RAG 是一种从组织受治理的知识源中检索相关段落，并将其作为上下文提供给模型的模式，从而使回答有据可依、保持最新且可引用。", "takeaways": [ "RAG 以检索到的文档作为回答依据，从而减少幻觉。", "它无需重新训练即可使用私有且最新的知识。", "检索质量（分块 + Embedding）决定了回答质量。", "企业级 RAG 增加了访问控制、引用和审计功能。", "当系统决定何时检索以及检索什么内容时，它就具备了智能体特征。" ], "context": [ "基础模型只知道它在训练期间学到的知识。而企业知识是私有的、动态变化的且受访问控制的。RAG 通过在查询时获取正确的段落并以此作为回答的依据，弥合了这一差距。", "企业级的区别在于治理：谁被允许查看哪些文档、回答的来源出自哪里，以及整个交互过程是否可以被审计。忽略这些要素的 RAG 只是原型，而非生产系统。" ], "architecture": [ "摄取：对文档进行解析，拆分为自包含的分块，进行 Embedding 并存储在向量索引中（通常与关键词搜索并存）。检索：对查询进行 Embedding，获取最接近的分块，并可选择进行重排和权限过滤。生成：模型使用这些分块进行回答并进行引用。", "质量取决于那些看似不起眼的部分：干净的解析、合理的分块、混合（向量 + 关键词）检索、重排以及权限过滤。结构良好的源内容会让这些步骤中的每一步都变得更加轻松。" ], "components": [ "摄取与分块", "Embeddings", "向量 / 混合索引", "检索器与重排器", "权限过滤器", "生成器（LLM）", "引用层" ], "pros": [ "有据可依、可引用且最新的回答。", "无需重新训练即可使用私有知识。", "遵循访问控制和可审计性。", "比微调更便宜、更新更快。" ], "risks": [ "糟糕的分块或检索会导致错误或不相关的上下文。", "陈旧或未授权的数据泄露到回答中。", "如果不进行验证，引用内容可能看似合理但实际上缺乏支持。", "大规模情况下的检索延迟和成本。" ], "tools": [ "向量数据库（例如 pgvector、Pinecone、Vertex AI Vector Search）", "Embedding 模型", "重排器", "混合搜索引擎", "MCP 资源服务器" ], "examples": [ "一个通过引用段落来回答人力资源（HR）政策问题的内部助手。", "一个通过检索产品文档来解决工单的支持智能体。", "一个提供相关条款及来源链接的法律助手。" ], "faqs": [ { "q": "RAG 比微调更好吗？", "a": "它们解决不同的问题。RAG 在查询时注入新鲜且受治理的知识；微调则用于调整行为或风格。它们通常结合使用。" }, { "q": "为什么分块如此重要？", "a": "检索是基于分块进行的。内容自包含、结构良好的分块能实现干净的检索；而碎片化的分块则会返回噪音。分块质量在很大程度上决定了 RAG 的质量。" }, { "q": "是什么让 RAG 达到企业级水平？", "a": "检索上的访问控制、来源引用、可审计性、新鲜度以及评估——而不仅仅是一个向量存储加上一个模型。" }, { "q": "RAG 何时会具有智能体特征？", "a": "当检索成为多步循环中的一个步骤，且系统能够自主决定是否检索、何时检索以及检索什么，而不是总是只进行一次固定检索时。" } ] } } }, { "slug": "fine-tuning", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/fine-tuning", "api": "https://santismm.com/api/knowledge/fine-tuning", "canonical_url": "https://santismm.com/en/knowledge/fine-tuning", "api_url": "https://santismm.com/api/knowledge/fine-tuning", "evidence": { "evidenceLevel": "benchmark", "confidenceLevel": "high", "sourceType": [ "benchmark", "paper" ] }, "references": [ { "title": "Hu et al. — LoRA: Low-Rank Adaptation of Large Language Models (2021)", "url": "https://arxiv.org/abs/2106.09685" }, { "title": "Ouyang et al. — Training language models to follow instructions with human feedback (InstructGPT, 2022)", "url": "https://arxiv.org/abs/2203.02155" } ], "related": [ "foundation-models", "enterprise-rag", "prompt-engineering", "embeddings" ], "locales": { "en": { "title": "What is Fine-tuning?", "summary": "Fine-tuning continues training a pretrained model on a smaller, targeted dataset to specialize its behavior, style or domain knowledge. It is far cheaper than pretraining and changes the model's weights — unlike prompting or retrieval, which leave the model unchanged. Use it to lock in a consistent format, tone or skill; use retrieval instead when you need fresh or private facts.", "definition": "Fine-tuning is the process of further training a pretrained model on a focused dataset to adapt its weights toward a specific behavior, style, format or domain.", "takeaways": [ "Fine-tuning updates model weights; prompting and RAG do not.", "Best for consistent behavior, style or format — not for fresh facts.", "Parameter-efficient methods (LoRA) make it cheap and practical.", "RLHF is a form of fine-tuning using human preferences.", "Default to prompting and retrieval first; fine-tune when they plateau." ], "context": [ "A pretrained foundation model is a generalist. Fine-tuning narrows it: shown enough examples of the target behavior, the model internalizes it, so you no longer need to specify it in every prompt.", "It is one of three adaptation levers, alongside prompting and retrieval. The art is choosing the right one: fine-tune for how the model should behave, retrieve for what it should know." ], "architecture": [ "Full fine-tuning updates all weights — powerful but expensive. Parameter-efficient fine-tuning (PEFT), notably LoRA, trains small adapter weights while freezing the base, capturing most of the benefit at a fraction of the cost.", "Instruction tuning and RLHF are specialized fine-tuning stages that turn a raw base model into a helpful, aligned assistant. Quality of the dataset matters far more than its size." ], "components": [ "Pretrained base model", "Curated training dataset", "Training objective", "PEFT / LoRA adapters", "Evaluation set" ], "pros": [ "Bakes in consistent behavior, style or format.", "Reduces prompt length and per-call cost.", "Can teach narrow skills a base model lacks.", "PEFT makes it affordable and fast." ], "risks": [ "Does not add fresh or private facts — use retrieval for that.", "Risk of catastrophic forgetting or overfitting.", "Needs a quality, well-labeled dataset and an eval set.", "Couples you to a model version; migration costs on upgrades." ], "tools": [ "LoRA / PEFT libraries", "Provider fine-tuning APIs", "RLHF / preference-tuning pipelines", "Evaluation suites" ], "examples": [ "Fine-tuning a model to always output a strict company JSON format.", "Teaching a consistent brand voice for generated copy.", "Adapting a model to a specialized domain's terminology." ], "faqs": [ { "q": "Fine-tuning or RAG?", "a": "Fine-tune to change how the model behaves (style, format, skill); use retrieval (RAG) to give it fresh or private knowledge. They are complementary, not competing." }, { "q": "Is fine-tuning expensive?", "a": "Full fine-tuning can be, but parameter-efficient methods like LoRA train tiny adapters and make it cheap and fast for most use cases." }, { "q": "What is RLHF?", "a": "Reinforcement learning from human feedback is a fine-tuning stage that uses human preference judgments to make a model more helpful, harmless and honest." }, { "q": "When should I fine-tune?", "a": "After prompting and retrieval plateau. If you can solve it with a better prompt or relevant context, do that first — it is cheaper and more flexible." } ] }, "es": { "title": "¿Qué es el Fine-tuning (Ajuste fino)?", "summary": "El fine-tuning continúa el entrenamiento de un modelo preentrenado con un conjunto de datos más pequeño y dirigido para especializar su comportamiento, estilo o conocimiento de dominio. Es mucho más barato que el preentrenamiento y cambia los pesos del modelo, a diferencia del prompting o la recuperación, que lo dejan intacto. Úsalo para fijar un formato, tono o habilidad consistentes; usa recuperación cuando necesites hechos frescos o privados.", "definition": "El fine-tuning es el proceso de seguir entrenando un modelo preentrenado con un conjunto de datos enfocado para adaptar sus pesos hacia un comportamiento, estilo, formato o dominio específico.", "takeaways": [ "El fine-tuning actualiza los pesos del modelo; el prompting y el RAG no.", "Mejor para comportamiento, estilo o formato consistentes, no para hechos frescos.", "Los métodos eficientes en parámetros (LoRA) lo hacen barato y práctico.", "El RLHF es una forma de fine-tuning que usa preferencias humanas.", "Empieza por prompting y recuperación; haz fine-tuning cuando se estanquen." ], "context": [ "Un modelo fundacional preentrenado es un generalista. El fine-tuning lo estrecha: tras ver suficientes ejemplos del comportamiento objetivo, el modelo lo interioriza, así que ya no hace falta especificarlo en cada prompt.", "Es una de las tres palancas de adaptación, junto al prompting y la recuperación. El arte está en elegir la adecuada: fine-tuning para cómo debe comportarse el modelo, recuperación para qué debe saber." ], "architecture": [ "El fine-tuning completo actualiza todos los pesos: potente pero caro. El fine-tuning eficiente en parámetros (PEFT), notablemente LoRA, entrena pequeños pesos adaptadores congelando la base, capturando casi todo el beneficio a una fracción del coste.", "El instruction tuning y el RLHF son etapas especializadas de fine-tuning que convierten un modelo base bruto en un asistente útil y alineado. La calidad del dataset importa mucho más que su tamaño." ], "components": [ "Modelo base preentrenado", "Dataset de entrenamiento curado", "Objetivo de entrenamiento", "Adaptadores PEFT / LoRA", "Conjunto de evaluación" ], "pros": [ "Fija un comportamiento, estilo o formato consistentes.", "Reduce la longitud del prompt y el coste por llamada.", "Puede enseñar habilidades estrechas que la base no tiene.", "PEFT lo hace asequible y rápido." ], "risks": [ "No añade hechos frescos o privados: usa recuperación para eso.", "Riesgo de olvido catastrófico o sobreajuste.", "Necesita un dataset de calidad bien etiquetado y un set de evaluación.", "Te acopla a una versión de modelo; coste de migración al actualizar." ], "tools": [ "Librerías LoRA / PEFT", "APIs de fine-tuning de proveedores", "Pipelines de RLHF / ajuste por preferencias", "Suites de evaluación" ], "examples": [ "Hacer fine-tuning para que un modelo emita siempre un formato JSON estricto de la empresa.", "Enseñar una voz de marca consistente para textos generados.", "Adaptar un modelo a la terminología de un dominio especializado." ], "faqs": [ { "q": "¿Fine-tuning o RAG?", "a": "Haz fine-tuning para cambiar cómo se comporta el modelo (estilo, formato, habilidad); usa recuperación (RAG) para darle conocimiento fresco o privado. Son complementarios, no rivales." }, { "q": "¿El fine-tuning es caro?", "a": "El completo puede serlo, pero métodos eficientes como LoRA entrenan adaptadores diminutos y lo hacen barato y rápido para la mayoría de casos." }, { "q": "¿Qué es el RLHF?", "a": "El aprendizaje por refuerzo con feedback humano es una etapa de fine-tuning que usa juicios de preferencia humana para hacer un modelo más útil, inofensivo y honesto." }, { "q": "¿Cuándo debería hacer fine-tuning?", "a": "Cuando el prompting y la recuperación se estancan. Si puedes resolverlo con un mejor prompt o contexto relevante, hazlo primero: es más barato y flexible." } ] }, "pt": { "title": "O que é Fine-tuning (Ajuste fino)?", "summary": "O fine-tuning continua o treinamento de um modelo pré-treinado com um conjunto de dados menor e direcionado para especializar seu comportamento, estilo ou conhecimento de domínio. É muito mais barato que o pré-treinamento e muda os pesos do modelo, ao contrário do prompting ou da recuperação, que o deixam intacto. Use-o para fixar um formato, tom ou habilidade consistentes; use recuperação quando precisar de fatos frescos ou privados.", "definition": "O fine-tuning é o processo de seguir treinando um modelo pré-treinado com um conjunto de dados focado para adaptar seus pesos rumo a um comportamento, estilo, formato ou domínio específico.", "takeaways": [ "O fine-tuning atualiza os pesos do modelo; o prompting e o RAG não.", "Melhor para comportamento, estilo ou formato consistentes, não para fatos frescos.", "Métodos eficientes em parâmetros (LoRA) o tornam barato e prático.", "O RLHF é uma forma de fine-tuning que usa preferências humanas.", "Comece por prompting e recuperação; faça fine-tuning quando estagnarem." ], "context": [ "Um modelo de fundação pré-treinado é um generalista. O fine-tuning o estreita: após ver exemplos suficientes do comportamento alvo, o modelo o internaliza, então não é mais preciso especificá-lo em cada prompt.", "É uma das três alavancas de adaptação, junto ao prompting e à recuperação. A arte está em escolher a adequada: fine-tuning para como o modelo deve se comportar, recuperação para o que deve saber." ], "architecture": [ "O fine-tuning completo atualiza todos os pesos: potente mas caro. O fine-tuning eficiente em parâmetros (PEFT), notavelmente o LoRA, treina pequenos pesos adaptadores congelando a base, capturando quase todo o benefício a uma fração do custo.", "O instruction tuning e o RLHF são etapas especializadas de fine-tuning que transformam um modelo base bruto num assistente útil e alinhado. A qualidade do dataset importa muito mais que seu tamanho." ], "components": [ "Modelo base pré-treinado", "Dataset de treinamento curado", "Objetivo de treinamento", "Adaptadores PEFT / LoRA", "Conjunto de avaliação" ], "pros": [ "Fixa um comportamento, estilo ou formato consistentes.", "Reduz o comprimento do prompt e o custo por chamada.", "Pode ensinar habilidades estreitas que a base não tem.", "PEFT o torna acessível e rápido." ], "risks": [ "Não adiciona fatos frescos ou privados: use recuperação para isso.", "Risco de esquecimento catastrófico ou sobreajuste.", "Precisa de um dataset de qualidade bem rotulado e um conjunto de avaliação.", "Acopla você a uma versão de modelo; custo de migração ao atualizar." ], "tools": [ "Bibliotecas LoRA / PEFT", "APIs de fine-tuning de provedores", "Pipelines de RLHF / ajuste por preferências", "Suítes de avaliação" ], "examples": [ "Fazer fine-tuning para um modelo emitir sempre um formato JSON estrito da empresa.", "Ensinar uma voz de marca consistente para textos gerados.", "Adaptar um modelo à terminologia de um domínio especializado." ], "faqs": [ { "q": "Fine-tuning ou RAG?", "a": "Faça fine-tuning para mudar como o modelo se comporta (estilo, formato, habilidade); use recuperação (RAG) para dar-lhe conhecimento fresco ou privado. São complementares, não rivais." }, { "q": "O fine-tuning é caro?", "a": "O completo pode ser, mas métodos eficientes como o LoRA treinam adaptadores minúsculos e o tornam barato e rápido para a maioria dos casos." }, { "q": "O que é RLHF?", "a": "O aprendizado por reforço com feedback humano é uma etapa de fine-tuning que usa julgamentos de preferência humana para tornar um modelo mais útil, inofensivo e honesto." }, { "q": "Quando devo fazer fine-tuning?", "a": "Quando o prompting e a recuperação estagnam. Se você pode resolver com um prompt melhor ou contexto relevante, faça isso primeiro: é mais barato e flexível." } ] }, "fr": { "title": "Qu'est-ce que le fine-tuning ?", "summary": "Le fine-tuning poursuit l'entraînement d'un modèle préentraîné sur un ensemble de données plus restreint et ciblé afin de spécialiser son comportement, son style ou ses connaissances sectorielles. Il est bien moins coûteux que le préentraînement et modifie les poids du modèle — contrairement au prompting ou à la récupération, qui laissent le modèle inchangé. Utilisez-le pour figer un format, un ton ou une compétence cohérente ; utilisez plutôt la récupération lorsque vous avez besoin de faits récents ou privés.", "definition": "Le fine-tuning est le processus consistant à poursuivre l'entraînement d'un modèle préentraîné sur un ensemble de données ciblé afin d'adapter ses poids à un comportement, un style, un format ou un domaine spécifique.", "takeaways": [ "Le fine-tuning met à jour les poids du modèle ; ce n'est pas le cas du prompting et du RAG.", "Idéal pour un comportement, un style ou un format cohérent — pas pour des faits récents.", "Les méthodes à efficacité paramétrique (LoRA) le rendent économique et pratique.", "Le RLHF est une forme de fine-tuning utilisant les préférences humaines.", "Privilégiez d'abord le prompting et la récupération ; passez au fine-tuning lorsqu'ils atteignent un plateau." ], "context": [ "Un modèle de fondation préentraîné est généraliste. Le fine-tuning le spécialise : en lui présentant suffisamment d'exemples du comportement cible, le modèle l'assimile, de sorte que vous n'avez plus besoin de le spécifier dans chaque prompt.", "C'est l'un des trois leviers d'adaptation, aux côtés du prompting et de la récupération. Tout l'art consiste à choisir le bon : le fine-tuning pour la façon dont le modèle doit se comporter, la récupération pour ce qu'il doit savoir." ], "architecture": [ "Le fine-tuning complet met à jour tous les poids — puissant mais coûteux. Le fine-tuning à efficacité paramétrique (PEFT), notamment LoRA, entraîne de petits poids d'adaptateurs tout en gelant la base, capturant la majeure partie des avantages pour une fraction du coût.", "L'instruction tuning et le RLHF sont des étapes de fine-tuning spécialisées qui transforment un modèle de base brut en un assistant utile et aligné. La qualité du jeu de données importe bien plus que sa taille." ], "components": [ "Modèle de base préentraîné", "Jeu de données d'entraînement sélectionné", "Objectif d'entraînement", "Adaptateurs PEFT / LoRA", "Ensemble d'évaluation" ], "pros": [ "Intègre un comportement, un style ou un format cohérent.", "Réduit la longueur des prompts et le coût par appel.", "Peut enseigner des compétences pointues qui manquent à un modèle de base.", "Le PEFT le rend abordable et rapide." ], "risks": [ "N'ajoute pas de faits récents ou privés — utilisez la récupération pour cela.", "Risque d'oubli catastrophique ou de surapprentissage (overfitting).", "Nécessite un jeu de données de qualité, bien étiqueté, et un ensemble d'évaluation.", "Vous lie à une version de modèle ; coûts de migration lors des mises à niveau." ], "tools": [ "Bibliothèques LoRA / PEFT", "API de fine-tuning des fournisseurs", "Pipelines de RLHF / d'ajustement des préférences", "Suites d'évaluation" ], "examples": [ "Fine-tuner un modèle pour qu'il produise toujours un format JSON d'entreprise strict.", "Enseigner une voix de marque cohérente pour les textes générés.", "Adapter un modèle à la terminologie d'un domaine spécialisé." ], "faqs": [ { "q": "Fine-tuning ou RAG ?", "a": "Utilisez le fine-tuning pour modifier le comportement du modèle (style, format, compétence) ; utilisez la récupération (RAG) pour lui apporter des connaissances fraîches ou privées. Ils sont complémentaires et non concurrents." }, { "q": "Le fine-tuning est-il coûteux ?", "a": "Le fine-tuning complet peut l'être, mais les méthodes à efficacité paramétrique comme LoRA entraînent de minuscules adaptateurs et le rendent économique et rapide pour la plupart des cas d'usage." }, { "q": "Qu'est-ce que le RLHF ?", "a": "L'apprentissage par renforcement à partir des commentaires humains (RLHF) est une étape de fine-tuning qui utilise les jugements de préférence humaine pour rendre un modèle plus utile, inoffensif et honnête." }, { "q": "Quand devrais-je faire du fine-tuning ?", "a": "Après que le prompting et la récupération ont atteint un plateau. Si vous pouvez résoudre le problème avec un meilleur prompt ou un contexte pertinent, faites-le d'abord — c'est plus économique et plus flexible." } ] }, "de": { "title": "Was ist Fine-tuning?", "summary": "Fine-tuning setzt das Training eines vortrainierten Modells auf einem kleineren, zielgerichteten Datensatz fort, um dessen Verhalten, Stil oder Domänenwissen zu spezialisieren. Es ist weitaus günstiger als das Vortraining und ändert die Gewichte des Modells – im Gegensatz zu Prompting oder Retrieval, die das Modell unverändert lassen. Nutzen Sie es, um ein konsistentes Format, einen bestimmten Tonfall oder eine Fähigkeit zu etablieren; nutzen Sie stattdessen Retrieval, wenn Sie aktuelle oder private Fakten benötigen.", "definition": "Fine-tuning ist der Prozess des weiteren Trainings eines vortrainierten Modells auf einem fokussierten Datensatz, um dessen Gewichte an ein bestimmtes Verhalten, einen Stil, ein Format oder eine Domäne anzupassen.", "takeaways": [ "Fine-tuning aktualisiert die Modellgewichte; Prompting und RAG tun dies nicht.", "Bestens geeignet für konsistentes Verhalten, Stil oder Format – nicht für aktuelle Fakten.", "Parametereffiziente Methoden (LoRA) machen es kostengünstig und praktisch.", "RLHF ist eine Form des Fine-tunings, die auf menschlichen Präferenzen basiert.", "Nutzen Sie standardmäßig zuerst Prompting und Retrieval; führen Sie ein Fine-tuning durch, wenn diese an ihre Grenzen stoßen." ], "context": [ "Ein vortrainiertes Foundation Model ist ein Generalist. Fine-tuning schränkt es ein: Wenn dem Modell genügend Beispiele für das Zielverhalten gezeigt werden, verinnerlicht es dieses, sodass Sie es nicht mehr in jedem Prompt angeben müssen.", "Es ist einer von drei Anpassungshebeln, neben Prompting und Retrieval. Die Kunst besteht darin, den richtigen Hebel zu wählen: Fine-tuning für das Verhalten des Modells, Retrieval für das, was es wissen soll." ], "architecture": [ "Vollständiges Fine-tuning aktualisiert alle Gewichte – leistungsstark, aber teuer. Parametereffizientes Fine-tuning (PEFT), insbesondere LoRA, trainiert kleine Adaptergewichte, während die Basis eingefroren bleibt, und bietet so den Großteil des Nutzens zu einem Bruchteil der Kosten.", "Instruction Tuning und RLHF are spezialisierte Fine-tuning-Phasen, die ein rohes Basismodell in einen hilfreichen, ausgerichteten Assistenten verwandeln. Die Qualität des Datensatzes ist weitaus wichtiger als seine Größe." ], "components": [ "Vortrainiertes Basismodell", "Kuratierter Trainingsdatensatz", "Trainingsziel", "PEFT- / LoRA-Adapter", "Evaluierungsset" ], "pros": [ "Verankert konsistentes Verhalten, Stil oder Format fest im Modell.", "Reduziert die Prompt-Länge und die Kosten pro Aufruf.", "Kann spezifische Fähigkeiten vermitteln, die einem Basismodell fehlen.", "PEFT macht es erschwinglich und schnell." ], "risks": [ "Fügt keine aktuellen oder privaten Fakten hinzu – nutzen Sie dafür Retrieval.", "Risiko von katastrophalem Vergessen oder Overfitting.", "Erfordert einen qualitativ hochwertigen, gut gelabelten Datensatz und ein Evaluierungsset.", "Bindet Sie an eine bestimmte Modellversion; Migrationskosten bei Upgrades." ], "tools": [ "LoRA- / PEFT-Bibliotheken", "Fine-tuning-APIs von Anbietern", "RLHF- / Preference-Tuning-Pipelines", "Evaluierungs-Suites" ], "examples": [ "Fine-tuning eines Modells, um immer ein striktes Unternehmens-JSON-Format auszugeben.", "Vermitteln einer konsistenten Markenstimme für generierte Texte.", "Anpassen eines Modells an die Terminologie einer spezialisierten Domäne." ], "faqs": [ { "q": "Fine-tuning oder RAG?", "a": "Nutzen Sie Fine-tuning, um das Verhalten des Modells zu ändern (Stil, Format, Fähigkeit); nutzen Sie Retrieval (RAG), um ihm aktuelles oder privates Wissen bereitzustellen. Sie ergänzen sich gegenseitig und stehen nicht in Konkurrenz." }, { "q": "Ist Fine-tuning teuer?", "a": "Vollständiges Fine-tuning kann teuer sein, aber parametereffiziente Methoden wie LoRA trainieren winzige Adapter und machen es für die meisten Anwendungsfälle kostengünstig und schnell." }, { "q": "Was ist RLHF?", "a": "Reinforcement Learning from Human Feedback (Bestärkendes Lernen aus menschlichem Feedback) ist eine Fine-tuning-Phase, die menschliche Präferenzbewertungen nutzt, um ein Modell hilfreicher, harmloser und ehrlicher zu machen." }, { "q": "Wann sollte ich ein Fine-tuning durchführen?", "a": "Sobald Prompting und Retrieval an ihre Grenzen stoßen. Wenn Sie das Problem mit einem besseren Prompt oder relevantem Kontext lösen können, tun Sie das zuerst – das ist kostengünstiger und flexibler." } ] }, "ja": { "title": "ファインチューニングとは？", "summary": "ファインチューニングとは、事前学習済みモデルをより小さく的を絞ったデータセットで追加学習させ、その振る舞い、スタイル、またはドメイン知識を特化させる手法です。事前学習よりもはるかに低コストであり、プロンプティングや検索（これらはモデルを変更しません）とは異なり、モデルの重みを変更します。一貫したフォーマット、トーン、またはスキルを固定したい場合に適しています。最新の事実やプライベートな事実が必要な場合は、代わりに検索を使用してください。", "definition": "ファインチューニングとは、事前学習済みモデルを特定のデータセットで追加学習させ、特定の振る舞い、スタイル、フォーマット、またはドメインに向けて重みを適応させるプロセスです。", "takeaways": [ "ファインチューニングはモデルの重みを更新しますが、プロンプティングやRAGは更新しません。", "一貫した振る舞い、スタイル、またはフォーマットに最適であり、最新の事実の追加には適していません。", "パラメータ効率の良い手法（LoRAなど）により、低コストかつ実用的に実行できます。", "RLHFは、人間の好みに基づくファインチューニングの一種です。", "まずはプロンプティングと検索を優先し、それらが限界に達したときにファインチューニングを行います。" ], "context": [ "事前学習済みの基盤モデルはジェネラリストです。ファインチューニングはそれを絞り込みます。ターゲットとなる振る舞いの例を十分に提示することで、モデルがそれを内面化するため、すべてのプロンプトでそれを指定する必要がなくなります。", "これは、プロンプティングや検索と並ぶ、3つの適応手段の1つです。重要なのは適切な手段を選択することです。モデルがどのように振る舞うべきかにはファインチューニングを、モデルが何を知るべきかには検索を使用します。" ], "architecture": [ "フルファインチューニングはすべての重みを更新するため、強力ですが高コストです。パラメータ効率の良いファインチューニング（PEFT）、特にLoRAは、ベースモデルを凍結したまま小さなアダプターの重みを学習させることで、わずかなコストで大部分のメリットを享受できます。", "指示チューニング（Instruction tuning）やRLHFは、生のベースモデルを役立つ、アライメントされたアシスタントへと変換する、特化したファインチューニングの段階です。データセットの規模よりも、その品質がはるかに重要です。" ], "components": [ "事前学習済みベースモデル", "厳選された学習データセット", "学習目的", "PEFT / LoRAアダプター", "評価セット" ], "pros": [ "一貫した振る舞い、スタイル、またはフォーマットを組み込めます。", "プロンプトの長さを短縮し、呼び出しあたりのコストを削減します。", "ベースモデルに欠けている特定のスキルを学習させることができます。", "PEFTにより、低コストかつ迅速に実行可能です。" ], "risks": [ "最新の事実やプライベートな事実は追加されません。そのためには検索を使用してください。", "破滅的忘却や過学習のリスクがあります。", "高品質で適切にラベル付けされたデータセットと評価セットが必要です。", "特定のモデルバージョンに依存するため、アップグレード時における移行コストが発生します。" ], "tools": [ "LoRA / PEFTライブラリ", "プロバイダーのファインチューニングAPI", "RLHF / 嗜好チューニング（preference-tuning）パイプライン", "評価スイート" ], "examples": [ "厳格な社内JSONフォーマットを常に出力するようにモデルをファインチューニングする。", "生成されるコピーに対して一貫したブランドボイスを学習させる。", "専門分野の用語にモデルを適応させる。" ], "faqs": [ { "q": "ファインチューニングとRAGのどちらを選ぶべきですか？", "a": "モデルの振る舞い（スタイル、フォーマット、スキル）を変更するにはファインチューニングを、最新またはプライベートな知識を与えるには検索（RAG）を使用します。これらは競合するものではなく、相互に補完し合うものです。" }, { "q": "ファインチューニングは高コストですか？", "a": "フルファインチューニングは高コストになる可能性がありますが、LoRAのようなパラメータ効率の良い手法は極小のアダプターを学習させるため、ほとんどのユースケースにおいて低コストかつ迅速に実行できます。" }, { "q": "What is RLHF?", "a": "人間のフィードバックからの強化学習（RLHF）とは、人間の好みの判断を利用して、モデルをより有用で、無害で、誠実なものにするためのファインチューニングの段階です。" }, { "q": "どのような場合にファインチューニングを行うべきですか？", "a": "プロンプティングと検索が限界に達した後です。より優れたプロンプトや関連するコンテキストで解決できる場合は、まずそれを実行してください。その方が低コストで柔軟性があります。" } ] }, "zh": { "title": "什么是微调？", "summary": "微调是在较小且有针对性的数据集上继续训练预训练模型，以使其行为、风格或领域知识专业化。它比预训练便宜得多，并且会改变模型的权重——这与提示（prompting）或检索不同，后者不会改变模型。使用微调可以锁定一致的格式、语气或技能；当您需要新鲜或私有的事实时，请改用检索。", "definition": "微调是在特定数据集上进一步训练预训练模型的过程，以调整其权重以适应特定的行为、风格、格式或领域。", "takeaways": [ "微调会更新模型权重；提示和 RAG 则不会。", "最适合保持一致的行为、风格或格式——不适用于获取新鲜事实。", "参数高效方法（LoRA）使其成本低廉且实用。", "RLHF 是一种利用人类偏好进行微调的形式。", "首先默认使用提示和检索；当它们遇到瓶颈时再进行微调。" ], "context": [ "预训练的基础模型是一个通用模型。微调可以缩小其范围：通过展示足够多的目标行为示例，模型会将其内化，因此您不再需要在每个提示中都进行指定。", "它是与提示和检索并列的三大适配杠杆之一。其艺术在于选择合适的手段：针对模型应该如何表现进行微调，针对模型应该知道什么进行检索。" ], "architecture": [ "全量微调会更新所有权重——功能强大但成本高昂。参数高效微调（PEFT），特别是 LoRA，在冻结基座模型的同时训练微小的适配器权重，以极低的成本获取了大部分收益。", "指令微调和 RLHF 是特定的微调阶段，可将原始基座模型转化为有用且对齐的助手。数据集的质量远比其规模重要。" ], "components": [ "预训练基座模型", "精选训练数据集", "训练目标", "PEFT / LoRA 适配器", "评估集" ], "pros": [ "固化一致的行为、风格或格式。", "减少提示长度和每次调用的成本。", "可以传授基座模型所缺乏的特定技能。", "PEFT 使其成本低廉且快速。" ], "risks": [ "不会添加新鲜或私有的事实——对此请使用检索。", "存在灾难性遗忘或过拟合的风险。", "需要高质量、标注良好的数据集和评估集。", "与特定模型版本绑定；升级时存在迁移成本。" ], "tools": [ "LoRA / PEFT 库", "服务商微调 API", "RLHF / 偏好微调流水线", "评估套件" ], "examples": [ "微调模型以始终输出严格的公司 JSON 格式。", "为生成的文案传授一致的品牌声调。", "使模型适应专业领域的术语。" ], "faqs": [ { "q": "微调还是 RAG？", "a": "通过微调来改变模型的行为方式（风格、格式、技能）；使用检索（RAG）为其提供新鲜或私有的知识。它们是互补的，而不是竞争关系。" }, { "q": "微调昂贵吗？", "a": "全量微调可能很贵，但像 LoRA 这样的参数高效方法通过训练微小的适配器，使大多数用例的微调变得便宜且快速。" }, { "q": "什么是 RLHF？", "a": "人类反馈强化学习是一种微调阶段，它利用人类的偏好判断使模型更加有用、无害和诚实。" }, { "q": "我应该在什么时候进行微调？", "a": "在提示和检索遇到瓶颈之后。如果您可以通过更好的提示或相关的上下文来解决问题，请先这样做——这更便宜且更灵活。" } ] } } }, { "slug": "foundation-models", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/foundation-models", "api": "https://santismm.com/api/knowledge/foundation-models", "canonical_url": "https://santismm.com/en/knowledge/foundation-models", "api_url": "https://santismm.com/api/knowledge/foundation-models", "evidence": { "evidenceLevel": "benchmark", "confidenceLevel": "high", "sourceType": [ "benchmark", "paper" ] }, "references": [ { "title": "Bommasani et al. — On the Opportunities and Risks of Foundation Models (2021)", "url": "https://arxiv.org/abs/2108.07258" }, { "title": "Vaswani et al. — Attention Is All You Need (2017)", "url": "https://arxiv.org/abs/1706.03762" } ], "related": [ "fine-tuning", "embeddings", "agentic-ai", "harness-engineering", "reasoning-models" ], "locales": { "en": { "title": "What are Foundation Models?", "summary": "A foundation model is a large model pretrained on broad data at scale that can be adapted to a wide range of downstream tasks. Large language models (LLMs) and large multimodal models are the canonical examples. The term, coined at Stanford in 2021, captures a shift: instead of training a bespoke model per task, organizations build on a shared, general-purpose base — then specialize it through prompting, retrieval or fine-tuning.", "definition": "A foundation model is a large, general-purpose model pretrained on broad data that serves as a base which can be adapted — via prompting, retrieval or fine-tuning — to many downstream tasks.", "takeaways": [ "Foundation models are general bases adapted to many tasks.", "LLMs and multimodal models are the leading examples.", "Most are built on the transformer architecture.", "Capabilities emerge with scale of data, parameters and compute.", "You adapt them by prompting, retrieval (RAG) or fine-tuning — rarely by training from scratch." ], "context": [ "Before foundation models, teams trained narrow models for each task. The foundation-model paradigm flips this: one large model is pretrained once on broad data, then reused everywhere. That reuse is why a handful of models now underpin most AI products.", "It also concentrates capability — and risk. Because so much is built on a few bases, their biases, failures and security properties propagate downstream, which is part of why governance and evaluation matter." ], "architecture": [ "Pretraining: a model with millions to trillions of parameters learns general patterns from massive datasets, typically with self-supervised objectives like next-token prediction. The transformer's attention mechanism makes this scalable.", "Adaptation: the same base is specialized for use — zero/few-shot prompting, retrieval-augmented generation for fresh or private knowledge, or fine-tuning for behavior and domain. Agents wrap the model in tools and a harness." ], "components": [ "Transformer architecture", "Pretraining data & objective", "Parameters (weights)", "Tokenizer", "Adaptation layer (prompt / RAG / fine-tune)" ], "pros": [ "One base reused across many tasks.", "Strong general capability out of the box.", "Rapid adaptation without training from scratch.", "Multimodal variants span text, image, audio and more." ], "risks": [ "Concentrated risk: flaws propagate to everything built on them.", "Costly to pretrain; few organizations can.", "Inherit biases and gaps from training data.", "Knowledge is frozen at training time without retrieval." ], "tools": [ "Frontier LLMs (Claude, GPT, Gemini)", "Open-weight models (Llama, Mistral)", "Multimodal models", "Model hosting / inference platforms" ], "examples": [ "Using one LLM for summarization, classification and drafting across an org.", "Adapting a base model to a domain with retrieval instead of retraining.", "Building an agent on a frontier model plus tools and memory." ], "faqs": [ { "q": "Is a foundation model the same as an LLM?", "a": "An LLM is the most common type of foundation model, specialized to language. Foundation models also include multimodal and other general-purpose models." }, { "q": "Why are they called 'foundation' models?", "a": "Because they serve as a shared base that many applications are built on, rather than a model trained for a single task." }, { "q": "Do I need to train one?", "a": "Almost never. Pretraining is extremely costly; nearly all value comes from adapting an existing base via prompting, retrieval or fine-tuning." }, { "q": "How do agents relate to foundation models?", "a": "An agent uses a foundation model as its reasoning core, wrapped in tools, memory and a control loop — the harness — to take actions." } ] }, "es": { "title": "¿Qué son los Modelos Fundacionales (Foundation Models)?", "summary": "Un modelo fundacional es un modelo grande preentrenado a escala con datos amplios que puede adaptarse a una gran variedad de tareas posteriores. Los modelos de lenguaje (LLM) y los multimodales son los ejemplos canónicos. El término, acuñado en Stanford en 2021, captura un cambio: en lugar de entrenar un modelo a medida por tarea, las organizaciones construyen sobre una base general compartida y luego la especializan mediante prompting, recuperación o fine-tuning.", "definition": "Un modelo fundacional es un modelo grande y de propósito general, preentrenado con datos amplios, que sirve de base adaptable —vía prompting, recuperación o fine-tuning— a muchas tareas posteriores.", "takeaways": [ "Los modelos fundacionales son bases generales adaptadas a muchas tareas.", "Los LLM y los modelos multimodales son los ejemplos principales.", "La mayoría se construyen sobre la arquitectura transformer.", "Las capacidades emergen con la escala de datos, parámetros y cómputo.", "Se adaptan por prompting, recuperación (RAG) o fine-tuning; rara vez entrenando desde cero." ], "context": [ "Antes de los modelos fundacionales, los equipos entrenaban modelos estrechos para cada tarea. El paradigma fundacional lo invierte: un modelo grande se preentrena una vez con datos amplios y se reutiliza en todas partes. Esa reutilización es la razón por la que un puñado de modelos sustenta hoy la mayoría de productos de IA.", "También concentra capacidad y riesgo. Como tanto se construye sobre unas pocas bases, sus sesgos, fallos y propiedades de seguridad se propagan aguas abajo, parte de por qué importan la gobernanza y la evaluación." ], "architecture": [ "Preentrenamiento: un modelo con millones a billones de parámetros aprende patrones generales de conjuntos de datos masivos, normalmente con objetivos autosupervisados como la predicción del siguiente token. La atención del transformer lo hace escalable.", "Adaptación: la misma base se especializa para su uso —prompting zero/few-shot, RAG para conocimiento fresco o privado, o fine-tuning para comportamiento y dominio. Los agentes envuelven el modelo en herramientas y un harness." ], "components": [ "Arquitectura transformer", "Datos y objetivo de preentrenamiento", "Parámetros (pesos)", "Tokenizador", "Capa de adaptación (prompt / RAG / fine-tune)" ], "pros": [ "Una base reutilizada en muchas tareas.", "Fuerte capacidad general de fábrica.", "Adaptación rápida sin entrenar desde cero.", "Las variantes multimodales abarcan texto, imagen, audio y más." ], "risks": [ "Riesgo concentrado: los fallos se propagan a todo lo construido sobre ellos.", "Costoso de preentrenar; pocas organizaciones pueden.", "Heredan sesgos y lagunas de los datos de entrenamiento.", "El conocimiento queda congelado en el momento del entrenamiento sin recuperación." ], "tools": [ "LLM frontera (Claude, GPT, Gemini)", "Modelos de pesos abiertos (Llama, Mistral)", "Modelos multimodales", "Plataformas de hosting / inferencia" ], "examples": [ "Usar un LLM para resumir, clasificar y redactar en toda una organización.", "Adaptar un modelo base a un dominio con recuperación en vez de reentrenar.", "Construir un agente sobre un modelo frontera más herramientas y memoria." ], "faqs": [ { "q": "¿Un modelo fundacional es lo mismo que un LLM?", "a": "Un LLM es el tipo más común de modelo fundacional, especializado en lenguaje. Los modelos fundacionales también incluyen multimodales y otros de propósito general." }, { "q": "¿Por qué se llaman 'fundacionales'?", "a": "Porque sirven de base compartida sobre la que se construyen muchas aplicaciones, en lugar de un modelo entrenado para una sola tarea." }, { "q": "¿Necesito entrenar uno?", "a": "Casi nunca. El preentrenamiento es extremadamente costoso; casi todo el valor viene de adaptar una base existente vía prompting, recuperación o fine-tuning." }, { "q": "¿Cómo se relacionan los agentes con los modelos fundacionales?", "a": "Un agente usa un modelo fundacional como núcleo de razonamiento, envuelto en herramientas, memoria y un bucle de control —el harness— para tomar acciones." } ] }, "pt": { "title": "O que são Modelos de Fundação (Foundation Models)?", "summary": "Um modelo de fundação é um modelo grande pré-treinado em escala com dados amplos que pode ser adaptado a uma ampla variedade de tarefas posteriores. Os modelos de linguagem (LLMs) e os multimodais são os exemplos canônicos. O termo, cunhado em Stanford em 2021, captura uma mudança: em vez de treinar um modelo sob medida por tarefa, as organizações constroem sobre uma base geral compartilhada e depois a especializam via prompting, recuperação ou fine-tuning.", "definition": "Um modelo de fundação é um modelo grande e de propósito geral, pré-treinado com dados amplos, que serve de base adaptável — via prompting, recuperação ou fine-tuning — a muitas tarefas posteriores.", "takeaways": [ "Os modelos de fundação são bases gerais adaptadas a muitas tarefas.", "Os LLMs e os modelos multimodais são os exemplos principais.", "A maioria é construída sobre a arquitetura transformer.", "As capacidades emergem com a escala de dados, parâmetros e computação.", "São adaptados por prompting, recuperação (RAG) ou fine-tuning; raramente treinando do zero." ], "context": [ "Antes dos modelos de fundação, as equipes treinavam modelos estreitos para cada tarefa. O paradigma de fundação inverte isso: um modelo grande é pré-treinado uma vez com dados amplos e reutilizado em todo lugar. Essa reutilização é a razão pela qual um punhado de modelos sustenta hoje a maioria dos produtos de IA.", "Também concentra capacidade e risco. Como tanto se constrói sobre poucas bases, seus vieses, falhas e propriedades de segurança se propagam para baixo, parte do porquê governança e avaliação importam." ], "architecture": [ "Pré-treinamento: um modelo com milhões a trilhões de parâmetros aprende padrões gerais de conjuntos de dados massivos, normalmente com objetivos autossupervisionados como a previsão do próximo token. A atenção do transformer torna isso escalável.", "Adaptação: a mesma base é especializada para uso — prompting zero/few-shot, RAG para conhecimento fresco ou privado, ou fine-tuning para comportamento e domínio. Os agentes envolvem o modelo em ferramentas e um harness." ], "components": [ "Arquitetura transformer", "Dados e objetivo de pré-treinamento", "Parâmetros (pesos)", "Tokenizador", "Camada de adaptação (prompt / RAG / fine-tune)" ], "pros": [ "Uma base reutilizada em muitas tarefas.", "Forte capacidade geral de fábrica.", "Adaptação rápida sem treinar do zero.", "As variantes multimodais abrangem texto, imagem, áudio e mais." ], "risks": [ "Risco concentrado: as falhas se propagam a tudo o que é construído sobre eles.", "Custoso de pré-treinar; poucas organizações conseguem.", "Herdam vieses e lacunas dos dados de treinamento.", "O conhecimento fica congelado no momento do treinamento sem recuperação." ], "tools": [ "LLMs de fronteira (Claude, GPT, Gemini)", "Modelos de pesos abertos (Llama, Mistral)", "Modelos multimodais", "Plataformas de hosting / inferência" ], "examples": [ "Usar um LLM para resumir, classificar e redigir em toda uma organização.", "Adaptar um modelo base a um domínio com recuperação em vez de retreinar.", "Construir um agente sobre um modelo de fronteira mais ferramentas e memória." ], "faqs": [ { "q": "Um modelo de fundação é o mesmo que um LLM?", "a": "Um LLM é o tipo mais comum de modelo de fundação, especializado em linguagem. Os modelos de fundação também incluem multimodais e outros de propósito geral." }, { "q": "Por que são chamados de 'fundação'?", "a": "Porque servem de base compartilhada sobre a qual muitas aplicações são construídas, em vez de um modelo treinado para uma única tarefa." }, { "q": "Preciso treinar um?", "a": "Quase nunca. O pré-treinamento é extremamente custoso; quase todo o valor vem de adaptar uma base existente via prompting, recuperação ou fine-tuning." }, { "q": "Como os agentes se relacionam com os modelos de fundação?", "a": "Um agente usa um modelo de fundação como núcleo de raciocínio, envolvido em ferramentas, memória e um laço de controle — o harness — para tomar ações." } ] }, "fr": { "title": "Que sont les modèles de fondation ?", "summary": "Un modèle de fondation est un grand modèle préentraîné à grande échelle sur des données larges, qui peut être adapté à un large éventail de tâches en aval. Les grands modèles de langage (LLM) et les grands modèles multimodaux en sont les exemples canoniques. Le terme, inventé à Stanford en 2021, traduit un changement de paradigme : au lieu d'entraîner un modèle sur mesure par tâche, les organisations s'appuient sur une base partagée et généraliste, puis la spécialisent par le prompting, la récupération ou le fine-tuning.", "definition": "Un modèle de fondation est un grand modèle généraliste préentraîné sur des données larges qui sert de base pouvant être adaptée — via le prompting, la récupération ou le fine-tuning — à de nombreuses tâches en aval.", "takeaways": [ "Les modèles de fondation sont des bases générales adaptées à de nombreuses tâches.", "Les LLM et les modèles multimodaux en sont les principaux exemples.", "La plupart reposent sur l'architecture transformer.", "Les capacités émergent avec l'échelle des données, des paramètres et de la puissance de calcul.", "Vous les adaptez par prompting, récupération (RAG) ou fine-tuning — rarement en les entraînant à partir de zéro." ], "context": [ "Avant les modèles de fondation, les équipes entraînaient des modèles étroits pour chaque tâche. Le paradigme des modèles de fondation inverse cela : un grand modèle est préentraîné une fois sur des données larges, puis réutilisé partout. C'est cette réutilisation qui explique pourquoi une poignée de modèles sous-tendent aujourd'hui la plupart des produits d'IA.", "Cela concentre également les capacités — et les risques. Comme une grande partie des systèmes repose sur quelques bases, leurs biais, défaillances et propriétés de sécurité se propagent en aval, ce qui explique en partie pourquoi la gouvernance et l'évaluation sont si importantes." ], "architecture": [ "Préentraînement : un modèle doté de millions à des milliers de milliards de paramètres apprend des motifs généraux à partir de jeux de données massifs, généralement avec des objectifs auto-supervisés comme la prédiction du token suivant. Le mécanisme d'attention du transformer rend ce processus évolutif.", "Adaptation : la même base est spécialisée pour l'utilisation — prompting zero/few-shot, génération augmentée par récupération (RAG) pour des connaissances fraîches ou privées, ou fine-tuning pour le comportement et le domaine. Les agents enveloppent le modèle dans des outils et un harness." ], "components": [ "Architecture transformer", "Données et objectif de préentraînement", "Paramètres (poids)", "Tokenizer", "Couche d'adaptation (prompt / RAG / fine-tuning)" ], "pros": [ "Une base unique réutilisée pour de nombreuses tâches.", "Forte capacité générale prête à l'emploi.", "Adaptation rapide sans entraînement à partir de zéro.", "Les variantes multimodales couvrent le texte, l'image, l'audio et plus encore." ], "risks": [ "Risque concentré : les failles se propagent à tout ce qui est construit sur ces bases.", "Coûteux à pré-entraîner ; peu d'organisations peuvent le faire.", "Héritent des biais et des lacunes des données d'entraînement.", "Les connaissances sont figées au moment de l'entraînement sans récupération." ], "tools": [ "LLM de pointe (Claude, GPT, Gemini)", "Modèles à poids ouverts (Llama, Mistral)", "Modèles multimodaux", "Plateformes d'hébergement / d'inférence de modèles" ], "examples": [ "Utiliser un seul LLM pour le résumé, la classification et la rédaction au sein d'une organisation.", "Adapter un modèle de base à un domaine spécifique grâce à la récupération plutôt qu'au réentraînement.", "Construire un agent sur un modèle de pointe avec des outils et de la mémoire." ], "faqs": [ { "q": "Un modèle de fondation est-il la même chose qu'un LLM ?", "a": "Un LLM est le type de modèle de fondation le plus courant, spécialisé dans le langage. Les modèles de fondation incluent également des modèles multimodaux et d'autres modèles à usage général." }, { "q": "Pourquoi les appelle-t-on modèles de « fondation » ?", "a": "Parce qu'ils servent de base commune sur laquelle de nombreuses applications sont construites, plutôt que d'être un modèle entraîné pour une tâche unique." }, { "q": "Dois-je en entraîner un ?", "a": "Presque jamais. Le pré-entraînement est extrêmement coûteux ; la quasi-totalité de la valeur provient de l'adaptation d'une base existante via le prompting, la récupération ou le fine-tuning." }, { "q": "Quel est le lien entre les agents et les modèles de fondation ?", "a": "Un agent utilise un modèle de fondation comme cœur de raisonnement, enveloppé d'outils, de mémoire et d'une boucle de contrôle — le harness — pour entreprendre des actions." } ] }, "de": { "title": "Was sind Foundation Models?", "summary": "Ein Foundation Model ist ein großes Modell, das in großem Maßstab auf breit gefächerten Daten vortrainiert wurde und an eine Vielzahl von nachgelagerten Aufgaben angepasst werden kann. Große Sprachmodelle (LLMs) und große multimodale Modelle sind die klassischen Beispiele. Der Begriff, der 2021 in Stanford geprägt wurde, beschreibt einen Wandel: Anstatt für jede Aufgabe ein maßgeschneidertes Modell zu trainieren, bauen Organisationen auf einer gemeinsamen, universellen Basis auf – und spezialisieren diese dann durch Prompting, Retrieval oder Fine-tuning.", "definition": "Ein Foundation Model ist ein großes, universelles Modell, das auf breit gefächerten Daten vortrainiert wurde und als Basis dient, die – über Prompting, Retrieval oder Fine-tuning – an viele nachgelagerte Aufgaben angepasst werden kann.", "takeaways": [ "Foundation Models sind universelle Basen, die an viele Aufgaben angepasst werden.", "LLMs und multimodale Modelle sind die führenden Beispiele.", "Die meisten basieren auf der Transformer-Architektur.", "Fähigkeiten entstehen mit der Skalierung von Daten, Parametern und Rechenleistung.", "Sie passen sie durch Prompting, Retrieval (RAG) oder Fine-tuning an – selten durch Training von Grund auf." ], "context": [ "Vor den Foundation Models trainierten Teams spezialisierte Modelle für jede einzelne Aufgabe. Das Foundation-Model-Paradigma kehrt dies um: Ein großes Modell wird einmal auf breit gefächerten Daten vortrainiert und dann überall wiederverwendet. Diese Wiederverwendung ist der Grund, warum heute eine Handvoll Modelle die Basis für die meisten KI-Produkte bilden.", "Es konzentriert auch Fähigkeiten – und Risiken. Da so viel auf wenigen Basen aufbaut, übertragen sich deren Vorurteile, Fehler und Sicherheitseigenschaften auf nachgelagerte Anwendungen, weshalb Governance und Evaluierung so wichtig sind." ], "architecture": [ "Pretraining (Vortraining): Ein Modell mit Millionen bis Billionen von Parametern lernt allgemeine Muster aus riesigen Datensätzen, typischerweise mit selbstüberwachten Zielen wie der Next-Token-Prediction. Der Attention-Mechanismus des Transformers macht dies skalierbar.", "Adaptation (Anpassung): Dieselbe Basis wird für die Nutzung spezialisiert – durch Zero-/Few-Shot-Prompting, Retrieval-Augmented Generation für aktuelles oder privates Wissen oder Fine-tuning für Verhalten und Domäne. Agenten betten das Modell in Tools und ein Harness ein." ], "components": [ "Transformer-Architektur", "Vortrainingsdaten & -ziel", "Parameter (Gewichte)", "Tokenizer", "Anpassungsebene (Prompt / RAG / Fine-tuning)" ], "pros": [ "Eine einzige Basis, die für viele Aufgaben wiederverwendet wird.", "Starke allgemeine Fähigkeiten direkt einsatzbereit.", "Schnelle Anpassung ohne Training von Grund auf.", "Multimodale Varianten decken Text, Bild, Audio und mehr ab." ], "risks": [ "Konzentriertes Risiko: Fehler übertragen sich auf alles, was darauf aufbaut.", "Kostspielig im Pretraining; nur wenige Organisationen können dies leisten.", "Übernehmen Biases und Lücken aus den Trainingsdaten.", "Das Wissen ist ohne Retrieval auf den Zeitpunkt des Trainings beschränkt." ], "tools": [ "Frontier-LLMs (Claude, GPT, Gemini)", "Open-Weight-Modelle (Llama, Mistral)", "Multimodale Modelle", "Modell-Hosting- / Inferenz-Plattformen" ], "examples": [ "Nutzung eines einzigen LLMs für Zusammenfassung, Klassifizierung und Entwurfserstellung im gesamten Unternehmen.", "Anpassung eines Basismodells an eine Domäne mittels Retrieval statt durch erneutes Training.", "Entwicklung eines Agenten auf Basis eines Frontier-Modells, ergänzt um Tools und Speicher (Memory)." ], "faqs": [ { "q": "Ist ein Foundation Model dasselbe wie ein LLM?", "a": "Ein LLM ist die am weitesten verbreitete Art von Foundation Model, spezialisiert auf Sprache. Foundation Models umfassen jedoch auch multimodale und andere Allzweckmodelle." }, { "q": "Warum werden sie „Foundation Models“ genannt?", "a": "Weil sie als gemeinsame Basis dienen, auf der viele Anwendungen aufbauen, anstatt ein für eine einzelne Aufgabe trainiertes Modell zu sein." }, { "q": "Muss ich selbst eines trainieren?", "a": "Fast nie. Das Pretraining ist extrem kostspielig; fast der gesamte Wert entsteht durch die Anpassung einer bestehenden Basis mittels Prompting, Retrieval oder Fine-Tuning." }, { "q": "Wie hängen Agenten mit Foundation Models zusammen?", "a": "Ein Agent nutzt ein Foundation Model als seinen logischen Kern (Reasoning Core), eingebettet in Tools, Speicher und eine Kontrollschleife – das Harness –, um Aktionen auszuführen." } ] }, "ja": { "title": "基盤モデルとは？", "summary": "基盤モデル（Foundation Model）とは、広範なデータを用いて大規模に事前学習され、幅広いダウンストリームタスクに適応できる大規模なモデルのことです。大規模言語モデル（LLM）や大規模マルチモーダルモデルがその代表例です。2021年にスタンフォード大学で提唱されたこの用語は、タスクごとに専用のモデルを学習させるのではなく、共有された汎用的なベースを基盤として構築し、プロンプティング、検索、またはファインチューニングを通じて特化させるというパラダイムシフトを捉えています。", "definition": "基盤モデルとは、広範なデータで事前学習された大規模な汎用モデルであり、プロンプティング、検索、またはファインチューニングを介して、多くのダウンストリームタスクに適応可能なベースとして機能するものです。", "takeaways": [ "基盤モデルは、多くのタスクに適応される汎用的なベースです。", "LLMやマルチモーダルモデルがその代表例です。", "ほとんどがTransformerアーキテクチャに基づいて構築されています。", "データ、パラメータ、および計算資源の規模に応じて、能力が創発します。", "これらはプロンプティング、検索（RAG）、またはファインチューニングによって適応させます。ゼロから学習させることはほとんどありません。" ], "context": [ "基盤モデルが登場する前は、チームはタスクごとに特化したモデルを学習させていました。基盤モデルのパラダイムはこれを覆します。1つの大規模なモデルを広範なデータで一度だけ事前学習させ、それをあらゆる場所で再利用します。この再利用性こそが、現在、一握りのモデルがほとんどのAI製品を支えている理由です。", "また、能力とリスクも集中します。非常に多くのものが少数のベースの上に構築されているため、それらのバイアス、不具合、セキュリティ特性がダウンストリームに伝播します。これが、ガバナンスと評価が重要である理由の一部です。" ], "architecture": [ "事前学習：数百万から数兆のパラメータを持つモデルが、通常は次のトークンの予測といった自己教師あり学習の目的を用いて、大規模なデータセットから一般的なパターンを学習します。Transformerのアテンション機構により、これがスケーラブルになります。", "適応：同じベースが用途に合わせて特化されます。これには、ゼロショット/フューショットプロンプティング、最新またはプライベートな知識のための検索拡張生成（RAG）、あるいは振る舞いやドメインのためのファインチューニングが含まれます。エージェントは、ツールとハーネスでモデルをラップします。" ], "components": [ "Transformerアーキテクチャ", "事前学習データと学習目的", "パラメータ（重み）", "トークナイザー", "適応レイヤー（プロンプト / RAG / ファインチューニング）" ], "pros": [ "1つのベースを多くのタスクで再利用可能。", "特別な調整なしで、すぐに強力な汎用能力を発揮。", "ゼロから学習させることなく、迅速に適応可能。", "テキスト、画像、音声などにまたがるマルチモーダルなバリアント。" ], "risks": [ "リスクの集中：欠陥がそれらを基盤とするすべてのものに伝播する。", "事前学習のコストが高く、対応できる組織は限られている。", "学習データに起因するバイアスや欠落を引き継ぐ。", "検索（retrieval）を行わない限り、知識は学習時点の状態で固定される。" ], "tools": [ "フロンティアLLM（Claude、GPT、Gemini）", "オープンウェイトモデル（Llama、Mistral）", "マルチモーダルモデル", "モデルホスティング／推論プラットフォーム" ], "examples": [ "組織全体で、要約、分類、下書き作成に単一のLLMを使用する。", "再学習ではなく、検索（retrieval）を用いてベースモデルを特定のドメインに適応させる。", "フロンティアモデルにツールとメモリを組み合わせてエージェントを構築する。" ], "faqs": [ { "q": "基盤モデルはLLMと同じものですか？", "a": "LLMは言語に特化した最も一般的な基盤モデルの一種です。基盤モデルには、マルチモーダルモデルやその他の汎用モデルも含まれます。" }, { "q": "なぜ「基盤（foundation）」モデルと呼ばれるのですか？", "a": "単一のタスク向けに学習されたモデルではなく、多くのアプリケーションが構築される共通の土台（ベース）として機能するためです。" }, { "q": "自分でモデルを学習させる必要はありますか？", "a": "ほとんどの場合、その必要はありません。事前学習には極めて高いコストがかかります。価値のほぼすべては、プロンプティング、検索（retrieval）、またはファインチューニングを通じて、既存のベースモデルを適応させることから生まれます。" }, { "q": "エージェントと基盤モデルはどのような関係にありますか？", "a": "エージェントは、基盤モデルを推論のコアとして使用し、それをツール、メモリ、および制御ループ（ハーネス）で包み込むことで、アクションを実行します。" } ] }, "zh": { "title": "什么是基础模型？", "summary": "基础模型是在大规模广泛数据上进行预训练的大型模型，可以适应广泛的下游任务。大语言模型（LLM）和大型多模态模型是典型的例子。该术语由斯坦福大学于 2021 年提出，体现了一种转变：组织不再针对每个任务训练定制模型，而是构建在共享的通用基座之上——然后通过提示、检索或微调使其专业化。", "definition": "基础模型是在广泛数据上预训练的大型通用模型，作为一个基座，可以通过提示、检索或微调来适应许多下游任务。", "takeaways": [ "基础模型是适用于许多任务的通用基座。", "LLM 和多模态模型是领先的示例。", "大多数构建在 Transformer 架构之上。", "能力随着数据、参数和计算规模的增长而涌现。", "您可以通过提示、检索（RAG）或微调来适配它们——极少需要从头开始训练。" ], "context": [ "在基础模型出现之前，团队针对每个任务训练窄域模型。基础模型范式颠覆了这一点：一个大型模型在广泛的数据上进行一次预训练，然后随处复用。这种复用正是目前少数几个模型支撑着大多数 AI 产品的原因。", "它也集中了能力——以及风险。因为有如此多的东西构建在少数几个基座之上，它们的偏见、故障和安全属性会传播到下游，这也是治理和评估如此重要的部分原因。" ], "architecture": [ "预训练：一个拥有数百万到数万亿参数的模型从海量数据集中学习通用模式，通常采用自监督目标（如预测下一个 token）。Transformer 的注意力机制使这一过程具备可扩展性。", "适配：对相同的基座进行专业化处理以供使用——零样本/少样本提示、针对新鲜或私有知识的检索增强生成，或针对行为和领域的微调。智能体将模型封装在工具和支撑系统（harness）中。" ], "components": [ "Transformer 架构", "预训练数据与目标", "参数（权重）", "分词器", "适配层（提示 / RAG / 微调）" ], "pros": [ "一个基座可跨多个任务复用。", "开箱即用的强大通用能力。", "无需从头训练即可快速适配。", "多模态变体涵盖文本、图像、音频等。" ], "risks": [ "集中风险：缺陷会传播到构建在它们之上的所有事物。", "预训练成本高昂；极少有组织有能力进行。", "继承了训练数据中的偏见和缺陷。", "若不引入检索，知识将停留在训练时状态。" ], "tools": [ "前沿 LLM（Claude、GPT、Gemini）", "开放权重模型（Llama、Mistral）", "多模态模型", "模型托管/推理平台" ], "examples": [ "在整个组织中使用单一 LLM 进行总结、分类和草拟。", "通过检索而非重新训练，使基础模型适应特定领域。", "基于前沿模型构建智能体，并结合工具和记忆。" ], "faqs": [ { "q": "基础模型和 LLM 是一回事吗？", "a": "LLM 是最常见的基础模型类型，专注于语言。基础模型还包括多模态和其他通用模型。" }, { "q": "为什么它们被称为“基础”模型？", "a": "因为它们作为一个共享基础，许多应用程序都构建在其之上，而不是针对单一任务训练的模型。" }, { "q": "我需要自己训练一个吗？", "a": "几乎不需要。预训练成本极其高昂；几乎所有的价值都来自于通过提示词、检索或微调来调整现有的基础模型。" }, { "q": "智能体与基础模型有什么关系？", "a": "智能体将基础模型作为其推理核心，并包裹在工具、记忆和控制循环（即支撑系统/harness）中以执行操作。" } ] } } }, { "slug": "guardrails", "category": "governance", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/guardrails", "api": "https://santismm.com/api/knowledge/guardrails", "canonical_url": "https://santismm.com/en/knowledge/guardrails", "api_url": "https://santismm.com/api/knowledge/guardrails", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "prompt-injection", "ai-governance", "human-in-the-loop", "ai-observability", "ai-cyberdefense", "agentic-threat-model" ], "locales": { "en": { "title": "What are AI Guardrails?", "summary": "Guardrails are runtime controls that constrain what goes into and comes out of an AI system, keeping its behavior safe, on-policy and compliant. They check and filter inputs and outputs, validate tool actions, block disallowed content and enforce limits — sitting around the model as a safety layer. Guardrails are a primary, operational control in AI governance and a key defense against misuse and prompt injection.", "definition": "AI guardrails are runtime safeguards that validate, filter or constrain a model's inputs, outputs and actions to keep its behavior safe, compliant and within defined policy.", "takeaways": [ "Guardrails act at runtime on inputs, outputs and actions.", "They enforce safety, policy and compliance, not model quality.", "Types: input filtering, output validation, action allow-lists, limits.", "A core defense against misuse and prompt injection.", "Guardrails complement — they do not replace — evaluation and oversight." ], "context": [ "A model alone has no enforceable boundaries; it will attempt whatever the prompt elicits. Guardrails add those boundaries operationally: deterministic or model-based checks that sit between the user, the model and the systems it can touch.", "They are how governance policies become live controls. A policy that says 'never expose PII' or 'never execute payments without approval' is realized as a guardrail that actually checks and blocks at runtime." ], "architecture": [ "Input guardrails screen prompts (e.g. for injection, policy violations, PII). Output guardrails validate responses (format, safety, factual constraints, PII redaction). Action guardrails gate tool calls with permissions and allow-lists. Rate, scope and budget limits cap blast radius.", "Guardrails can be deterministic (rules, schemas, regex, allow-lists) or model-based (a classifier or LLM judge). They pair with observability to log violations and with human-in-the-loop approval for high-impact actions." ], "components": [ "Input filtering", "Output validation / redaction", "Action allow-lists & permissions", "Rate & scope limits", "Policy classifiers", "Violation logging" ], "pros": [ "Enforces safety and policy at runtime, not just in guidance.", "Reduces misuse, unsafe output and injection impact.", "Operationalizes governance and compliance requirements.", "Bounds the blast radius of agent actions." ], "risks": [ "Over-blocking harms usefulness (false positives).", "Under-blocking creates a false sense of safety.", "Model-based guardrails add latency and cost.", "They are not a complete defense; combine with oversight and evals." ], "tools": [ "Guardrail frameworks (e.g. NeMo Guardrails, Guardrails AI)", "Content moderation / safety classifiers", "Schema & input validation", "Permission & policy engines", "Observability for violations" ], "examples": [ "Redacting personal data from a model's output before it is shown.", "Blocking a tool call that falls outside an allow-list of safe actions.", "Rejecting responses that do not match a required JSON schema." ], "faqs": [ { "q": "Are guardrails the same as alignment?", "a": "No. Alignment shapes the model's intrinsic behavior during training; guardrails are external runtime controls around the deployed system. They are complementary." }, { "q": "Do guardrails stop prompt injection?", "a": "They reduce its impact — input screening and action allow-lists help — but no guardrail fully prevents injection. Use layered defenses plus human approval for sensitive actions." }, { "q": "Deterministic or model-based guardrails?", "a": "Both. Deterministic checks (schemas, allow-lists) are cheap and reliable for clear rules; model-based checks handle nuanced content at the cost of latency." }, { "q": "How do guardrails fit AI governance?", "a": "They are the operational layer: the runtime controls that turn governance policies into enforced behavior, evidenced through logging and audit." } ] }, "es": { "title": "¿Qué son los Guardarraíles de IA (Guardrails)?", "summary": "Los guardarraíles son controles en tiempo de ejecución que acotan lo que entra y sale de un sistema de IA, manteniendo su comportamiento seguro, conforme a la política y al cumplimiento. Comprueban y filtran entradas y salidas, validan acciones de herramientas, bloquean contenido no permitido e imponen límites, situándose alrededor del modelo como capa de seguridad. Son un control primario y operativo en la gobernanza de IA y una defensa clave contra el mal uso y la inyección de prompts.", "definition": "Los guardarraíles de IA son salvaguardas en tiempo de ejecución que validan, filtran o acotan las entradas, salidas y acciones de un modelo para mantener su comportamiento seguro, conforme y dentro de la política definida.", "takeaways": [ "Los guardarraíles actúan en tiempo de ejecución sobre entradas, salidas y acciones.", "Imponen seguridad, política y cumplimiento, no la calidad del modelo.", "Tipos: filtrado de entrada, validación de salida, listas de permitidos de acciones, límites.", "Una defensa central contra el mal uso y la inyección de prompts.", "Complementan —no reemplazan— la evaluación y la supervisión." ], "context": [ "Un modelo por sí solo no tiene límites exigibles; intentará lo que el prompt provoque. Los guardarraíles añaden esos límites de forma operativa: comprobaciones deterministas o basadas en modelo que se sitúan entre el usuario, el modelo y los sistemas que puede tocar.", "Son la forma en que las políticas de gobernanza se vuelven controles vivos. Una política que dice 'nunca exponer datos personales' o 'nunca ejecutar pagos sin aprobación' se materializa como un guardarraíl que realmente comprueba y bloquea en tiempo de ejecución." ], "architecture": [ "Los guardarraíles de entrada filtran prompts (p. ej. inyección, violaciones de política, datos personales). Los de salida validan respuestas (formato, seguridad, restricciones factuales, redacción de datos personales). Los de acción acotan las llamadas a herramientas con permisos y listas de permitidos. Los límites de tasa, alcance y presupuesto contienen el radio de impacto.", "Pueden ser deterministas (reglas, esquemas, regex, listas de permitidos) o basados en modelo (un clasificador o juez LLM). Se combinan con observabilidad para registrar violaciones y con aprobación con humano en el bucle para acciones de alto impacto." ], "components": [ "Filtrado de entrada", "Validación / redacción de salida", "Listas de permitidos y permisos de acción", "Límites de tasa y alcance", "Clasificadores de política", "Registro de violaciones" ], "pros": [ "Impone seguridad y política en ejecución, no solo en la guía.", "Reduce el mal uso, la salida insegura y el impacto de la inyección.", "Operacionaliza requisitos de gobernanza y cumplimiento.", "Acota el radio de impacto de las acciones del agente." ], "risks": [ "El sobrebloqueo daña la utilidad (falsos positivos).", "El infrabloqueo crea una falsa sensación de seguridad.", "Los guardarraíles basados en modelo añaden latencia y coste.", "No son una defensa completa; combínalos con supervisión y evaluaciones." ], "tools": [ "Frameworks de guardarraíles (p. ej. NeMo Guardrails, Guardrails AI)", "Clasificadores de moderación / seguridad", "Validación de esquemas y entradas", "Motores de permisos y políticas", "Observabilidad de violaciones" ], "examples": [ "Redactar datos personales de la salida de un modelo antes de mostrarla.", "Bloquear una llamada a herramienta fuera de una lista de acciones seguras.", "Rechazar respuestas que no cumplen un esquema JSON requerido." ], "faqs": [ { "q": "¿Los guardarraíles son lo mismo que la alineación?", "a": "No. La alineación moldea el comportamiento intrínseco del modelo durante el entrenamiento; los guardarraíles son controles externos en ejecución alrededor del sistema desplegado. Son complementarios." }, { "q": "¿Los guardarraíles detienen la inyección de prompts?", "a": "Reducen su impacto —el filtrado de entrada y las listas de permitidos ayudan— pero ningún guardarraíl la previene por completo. Usa defensas por capas más aprobación humana para acciones sensibles." }, { "q": "¿Guardarraíles deterministas o basados en modelo?", "a": "Ambos. Las comprobaciones deterministas (esquemas, listas) son baratas y fiables para reglas claras; las basadas en modelo manejan contenido con matices a costa de latencia." }, { "q": "¿Cómo encajan los guardarraíles en la gobernanza de IA?", "a": "Son la capa operativa: los controles en ejecución que convierten las políticas de gobernanza en comportamiento exigido, evidenciado mediante registro y auditoría." } ] }, "pt": { "title": "O que são Guard-rails de IA (Guardrails)?", "summary": "Os guard-rails são controles em tempo de execução que limitam o que entra e sai de um sistema de IA, mantendo seu comportamento seguro, em conformidade com a política e a regulação. Verificam e filtram entradas e saídas, validam ações de ferramentas, bloqueiam conteúdo não permitido e impõem limites, situando-se ao redor do modelo como camada de segurança. São um controle primário e operacional na governança de IA e uma defesa-chave contra o mau uso e a injeção de prompts.", "definition": "Os guard-rails de IA são salvaguardas em tempo de execução que validam, filtram ou limitam as entradas, saídas e ações de um modelo para manter seu comportamento seguro, conforme e dentro da política definida.", "takeaways": [ "Os guard-rails atuam em tempo de execução sobre entradas, saídas e ações.", "Impõem segurança, política e conformidade, não a qualidade do modelo.", "Tipos: filtragem de entrada, validação de saída, listas de permitidos de ações, limites.", "Uma defesa central contra o mau uso e a injeção de prompts.", "Complementam — não substituem — a avaliação e a supervisão." ], "context": [ "Um modelo sozinho não tem limites exigíveis; tentará o que o prompt provocar. Os guard-rails adicionam esses limites de forma operacional: verificações determinísticas ou baseadas em modelo que se situam entre o usuário, o modelo e os sistemas que ele pode tocar.", "São a forma como as políticas de governança se tornam controles vivos. Uma política que diz 'nunca expor dados pessoais' ou 'nunca executar pagamentos sem aprovação' se materializa como um guard-rail que realmente verifica e bloqueia em tempo de execução." ], "architecture": [ "Os guard-rails de entrada filtram prompts (ex.: injeção, violações de política, dados pessoais). Os de saída validam respostas (formato, segurança, restrições factuais, redação de dados pessoais). Os de ação limitam as chamadas de ferramentas com permissões e listas de permitidos. Os limites de taxa, escopo e orçamento contêm o raio de impacto.", "Podem ser determinísticos (regras, esquemas, regex, listas de permitidos) ou baseados em modelo (um classificador ou juiz LLM). Combinam-se com observabilidade para registrar violações e com aprovação com humano no laço para ações de alto impacto." ], "components": [ "Filtragem de entrada", "Validação / redação de saída", "Listas de permitidos e permissões de ação", "Limites de taxa e escopo", "Classificadores de política", "Registro de violações" ], "pros": [ "Impõe segurança e política em execução, não só na orientação.", "Reduz o mau uso, a saída insegura e o impacto da injeção.", "Operacionaliza requisitos de governança e conformidade.", "Limita o raio de impacto das ações do agente." ], "risks": [ "O bloqueio em excesso prejudica a utilidade (falsos positivos).", "O bloqueio insuficiente cria uma falsa sensação de segurança.", "Os guard-rails baseados em modelo adicionam latência e custo.", "Não são uma defesa completa; combine-os com supervisão e avaliações." ], "tools": [ "Frameworks de guard-rails (ex.: NeMo Guardrails, Guardrails AI)", "Classificadores de moderação / segurança", "Validação de esquemas e entradas", "Motores de permissões e políticas", "Observabilidade de violações" ], "examples": [ "Redigir dados pessoais da saída de um modelo antes de exibi-la.", "Bloquear uma chamada de ferramenta fora de uma lista de ações seguras.", "Rejeitar respostas que não cumprem um esquema JSON exigido." ], "faqs": [ { "q": "Os guard-rails são o mesmo que alinhamento?", "a": "Não. O alinhamento molda o comportamento intrínseco do modelo durante o treinamento; os guard-rails são controles externos em execução ao redor do sistema implantado. São complementares." }, { "q": "Os guard-rails detêm a injeção de prompts?", "a": "Reduzem seu impacto — a filtragem de entrada e as listas de permitidos ajudam — mas nenhum guard-rail a previne por completo. Use defesas em camadas mais aprovação humana para ações sensíveis." }, { "q": "Guard-rails determinísticos ou baseados em modelo?", "a": "Ambos. As verificações determinísticas (esquemas, listas) são baratas e confiáveis para regras claras; as baseadas em modelo lidam com conteúdo com nuances ao custo de latência." }, { "q": "Como os guard-rails se encaixam na governança de IA?", "a": "São a camada operacional: os controles em execução que convertem as políticas de governança em comportamento exigido, evidenciado por registro e auditoria." } ] }, "fr": { "title": "Que sont les garde-fous (guardrails) de l'IA ?", "summary": "Les garde-fous sont des contrôles au moment de l'exécution (runtime) qui limitent ce qui entre et sort d'un système d'IA, garantissant un comportement sûr, conforme aux politiques et réglementations. Ils vérifient et filtrent les entrées et les sorties, valident les actions des outils, bloquent les contenus non autorisés et imposent des limites, agissant comme une couche de sécurité autour du modèle. Les garde-fous constituent un contrôle opérationnel de premier plan dans la gouvernance de l'IA et une défense clé contre les abus et l'injection de prompts.", "definition": "Les garde-fous de l'IA sont des protections au moment de l'exécution qui valident, filtrent ou limitent les entrées, les sorties et les actions d'un modèle afin de maintenir son comportement sûr, conforme et respectueux des politiques définies.", "takeaways": [ "Les garde-fous agissent au moment de l'exécution sur les entrées, les sorties et les actions.", "Ils garantissent la sécurité, la conformité et le respect des politiques, et non la qualité du modèle.", "Types : filtrage des entrées, validation des sorties, listes d'autorisation d'actions, limites.", "Une défense essentielle contre les abus et l'injection de prompts.", "Les garde-fous complètent l'évaluation et la surveillance, mais ne les remplacent pas." ], "context": [ "Un modèle seul n'a pas de limites applicables ; il tentera de répondre à tout ce que le prompt suscite. Les garde-fous ajoutent ces limites de manière opérationnelle : des vérifications déterministes ou basées sur des modèles qui s'interposent entre l'utilisateur, le modèle et les systèmes avec lesquels il peut interagir.", "C'est ainsi que les politiques de gouvernance deviennent des contrôles actifs. Une politique stipulant « ne jamais exposer de données personnelles (PII) » ou « ne jamais exécuter de paiements sans approbation » se concrétise sous la forme d'un garde-fou qui vérifie et bloque réellement au moment de l'exécution." ], "architecture": [ "Les garde-fous d'entrée filtrent les prompts (par exemple, pour détecter les injections, les violations de politiques, les PII). Les garde-fous de sortie valident les réponses (format, sécurité, contraintes factuelles, masquage des PII). Les garde-fous d'action contrôlent les appels d'outils à l'aide d'autorisations et de listes d'autorisation. Les limites de débit, de portée et de budget restreignent le rayon d'impact (blast radius).", "Les garde-fous peuvent être déterministes (règles, schémas, regex, listes d'autorisation) ou basés sur des modèles (un classificateur ou un LLM juge). Ils s'associent à l'observabilité pour consigner les violations et à l'approbation humaine (human-in-the-loop) pour les actions à fort impact." ], "components": [ "Filtrage des entrées", "Validation / masquage des sorties", "Listes d'autorisation d'actions et autorisations", "Limites de débit et de portée", "Classificateurs de politiques", "Journalisation des violations" ], "pros": [ "Applique la sécurité et les politiques au moment de l'exécution, et pas seulement sous forme de directives.", "Réduit les abus, les sorties non sécurisées et l'impact des injections.", "Opérationnalise les exigences de gouvernance et de conformité.", "Limite le rayon d'impact (blast radius) des actions des agents." ], "risks": [ "Un blocage excessif nuit à l'utilité (faux positifs).", "Un blocage insuffisant crée un faux sentiment de sécurité.", "Les garde-fous basés sur des modèles ajoutent de la latence et des coûts.", "Ils ne constituent pas une défense complète ; combinez-les avec de la surveillance et des évaluations (evals)." ], "tools": [ "Frameworks de garde-fous (par ex. NeMo Guardrails, Guardrails AI)", "Modération de contenu / classificateurs de sécurité", "Validation de schéma et d'entrée", "Moteurs d'autorisation et de politiques", "Observabilité pour les violations" ], "examples": [ "Masquer les données personnelles de la sortie d'un modèle avant qu'elle ne soit affichée.", "Bloquer un appel d'outil qui ne figure pas dans une liste d'autorisation d'actions sûres.", "Rejeter les réponses qui ne correspondent pas à un schéma JSON requis." ], "faqs": [ { "q": "Les garde-fous sont-ils identiques à l'alignement ?", "a": "Non. L'alignement façonne le comportement intrinsèque du modèle pendant l'entraînement ; les garde-fous sont des contrôles externes au moment de l'exécution autour du système déployé. Ils sont complémentaires." }, { "q": "Les garde-fous empêchent-ils l'injection de prompts ?", "a": "Ils réduisent son impact — le filtrage des entrées et les listes d'autorisation d'actions y contribuent — mais aucun garde-fou ne prévient totalement l'injection. Utilisez des défenses multicouches ainsi qu'une approbation humaine pour les actions sensibles." }, { "q": "Garde-fous déterministes ou basés sur des modèles ?", "a": "Les deux. Les vérifications déterministes (schémas, listes d'autorisation) sont peu coûteuses et fiables pour des règles claires ; les vérifications basées sur des modèles gèrent les contenus nuancés au détriment de la latence." }, { "q": "Comment les garde-fous s'intègrent-ils dans la gouvernance de l'IA ?", "a": "Ils constituent la couche opérationnelle : les contrôles au moment de l'exécution qui transforment les politiques de gouvernance en comportements appliqués, attestés par la journalisation et l'audit." } ] }, "de": { "title": "Was sind AI Guardrails?", "summary": "Guardrails sind Laufzeitkontrollen, die die Ein- und Ausgaben eines KI-Systems einschränken, um dessen Verhalten sicher, richtlinienkonform (on-policy) und compliant zu halten. Sie prüfen und filtern Inputs und Outputs, validieren Tool-Aktionen, blockieren unzulässige Inhalte und setzen Limits durch – sie legen sich als Sicherheitsebene um das Modell. Guardrails sind eine primäre, operative Kontrolle in der AI Governance und eine zentrale Verteidigungslinie gegen Missbrauch und Prompt Injection.", "definition": "AI Guardrails sind Schutzmaßnahmen zur Laufzeit, die die Inputs, Outputs und Aktionen eines Modells validieren, filtern oder einschränken, um sein Verhalten sicher, compliant und innerhalb definierter Richtlinien zu halten.", "takeaways": [ "Guardrails wirken zur Laufzeit auf Inputs, Outputs und Aktionen.", "Sie setzen Sicherheit, Richtlinien und Compliance durch, nicht die Modellqualität.", "Typen: Input-Filterung, Output-Validierung, Aktions-Allowlists, Limits.", "Eine zentrale Verteidigungslinie gegen Missbrauch und Prompt Injection.", "Guardrails ergänzen Evaluierung und Aufsicht – sie ersetzen sie nicht." ], "context": [ "Ein Modell allein hat keine durchsetzbaren Grenzen; es versucht alles auszuführen, was der Prompt hervorruft. Guardrails fügen diese Grenzen operativ hinzu: deterministische oder modellbasierte Prüfungen, die sich zwischen dem Benutzer, dem Modell und den Systemen befinden, die es erreichen kann.", "Durch sie werden Governance-Richtlinien zu aktiven Kontrollen. Eine Richtlinie wie „personenbezogene Daten (PII) niemals offenlegen“ oder „Zahlungen niemals ohne Genehmigung ausführen“ wird als Guardrail realisiert, die zur Laufzeit tatsächlich prüft und blockiert." ], "architecture": [ "Input-Guardrails überprüfen Prompts (z. B. auf Injection, Richtlinienverstöße, PII). Output-Guardrails validieren Antworten (Format, Sicherheit, sachliche Einschränkungen, PII-Schwärzung). Aktions-Guardrails steuern Tool-Aufrufe über Berechtigungen und Allowlists. Raten-, Umfangs- und Budgetbegrenzungen deckeln den Schadensradius (Blast Radius).", "Guardrails können deterministisch (Regeln, Schemata, Regex, Allowlists) oder modellbasiert (ein Klassifikator oder LLM-Judge) sein. Sie arbeiten mit Observability zusammen, um Verstöße zu protokollieren, sowie mit Human-in-the-Loop-Freigaben für folgenschwere Aktionen." ], "components": [ "Input-Filterung", "Output-Validierung / Schwärzung", "Aktions-Allowlists & Berechtigungen", "Raten- & Umfangsbegrenzungen", "Richtlinien-Klassifikatoren", "Protokollierung von Verstößen" ], "pros": [ "Setzt Sicherheit und Richtlinien zur Laufzeit durch, nicht nur in Leitlinien.", "Reduziert Missbrauch, unsichere Outputs und die Auswirkungen von Injections.", "Operationalisiert Governance- und Compliance-Anforderungen.", "Begrenzt den Schadensradius von Agenten-Aktionen." ], "risks": [ "Übermäßiges Blockieren beeinträchtigt den Nutzen (False Positives).", "Unzureichendes Blockieren wiegt in falscher Sicherheit.", "Modellbasierte Guardrails erhöhen Latenz und Kosten.", "Sie sind keine vollständige Verteidigung; sie sollten mit Aufsicht und Evals kombiniert werden." ], "tools": [ "Guardrail-Frameworks (z. B. NeMo Guardrails, Guardrails AI)", "Inhaltsmoderation / Sicherheits-Klassifikatoren", "Schema- & Input-Validierung", "Berechtigungs- & Richtlinien-Engines", "Observability für Verstöße" ], "examples": [ "Schwärzen personenbezogener Daten im Output eines Modells, bevor dieser angezeigt wird.", "Blockieren eines Tool-Aufrufs, der außerhalb einer Allowlist sicherer Aktionen liegt.", "Zurückweisen von Antworten, die nicht einem erforderlichen JSON-Schema entsprechen." ], "faqs": [ { "q": "Sind Guardrails dasselbe wie Alignment?", "a": "Nein. Alignment prägt das intrinsische Verhalten des Modells während des Trainings; Guardrails sind externe Laufzeitkontrollen um das bereitgestellte System herum. Sie ergänzen einander." }, { "q": "Verhindern Guardrails Prompt Injection?", "a": "Sie reduzieren die Auswirkungen – Input-Überprüfung und Aktions-Allowlists helfen –, aber keine Guardrail verhindert Injection vollständig. Nutzen Sie mehrschichtige Verteidigungsmaßnahmen sowie menschliche Freigaben für sensible Aktionen." }, { "q": "Deterministische oder modellbasierte Guardrails?", "a": "Beides. Deterministische Prüfungen (Schemata, Allowlists) sind kostengünstig und zuverlässig für klare Regeln; modellbasierte Prüfungen verarbeiten nuancierte Inhalte auf Kosten der Latenz." }, { "q": "Wie fügen sich Guardrails in die AI Governance ein?", "a": "Sie sind die operative Ebene: die Laufzeitkontrollen, die Governance-Richtlinien in erzwungenes Verhalten umsetzen, nachweisbar durch Protokollierung und Audits." } ] }, "ja": { "title": "AIガードレールとは何ですか？", "summary": "ガードレールとは、AIシステムへの入力と出力を制限し、その動作を安全、ポリシー準拠、かつコンプライアンスに則った状態に保つためのランタイム制御です。モデルの周囲に安全レイヤーとして配置され、入出力のチェックとフィルタリング、ツールアクションの検証、不許可コンテンツのブロック、制限の適用などを行います。ガードレールは、AIガバナンスにおける主要な運用管理手段であり、悪用やプロンプトインジェクションに対する重要な防御策です。", "definition": "AIガードレールとは、モデルの入力、出力、およびアクションを検証、フィルタリング、または制限することで、その動作を安全かつコンプライアンスに準拠させ、定義されたポリシー内に収めるためのランタイム保護手段です。", "takeaways": [ "ガードレールは、実行時（ランタイム）に入力、出力、およびアクションに対して作用します。", "これらはモデルの品質ではなく、安全性、ポリシー、およびコンプライアンスを強制するものです。", "種類：入力フィルタリング、出力検証、アクションの許可リスト、制限。", "悪用やプロンプトインジェクションに対する中核的な防御策。", "ガードレールは評価や監視を補完するものであり、それらを代替するものではありません。" ], "context": [ "モデル単体には強制力のある境界が存在しないため、プロンプトが誘発するあらゆる処理を試みようとします。ガードレールは、ユーザー、モデル、およびモデルがアクセス可能なシステムの間に配置される、決定論的またはモデルベースのチェック機能として、運用上の境界を追加します。", "これらは、ガバナンスポリシーを実効性のある制御へと変換する手段です。「個人情報（PII）を絶対に公開しない」や「承認なしに支払いを実行しない」といったポリシーは、実行時に実際にチェックとブロックを行うガードレールとして具現化されます。" ], "architecture": [ "入力ガードレールはプロンプトをスクリーニングします（例：インジェクション、ポリシー違反、PIIの検出）。出力ガードレールは応答を検証します（フォーマット、安全性、事実に基づく制約、PIIの墨消し）。アクションガードレールは、権限や許可リストを用いてツール呼び出しを制御します。レート、スコープ、予算の制限により、影響範囲（ブラストライジアス）を抑制します。", "ガードレールには、決定論的なもの（ルール、スキーマ、正規表現、許可リスト）と、モデルベースのもの（分類器やLLMジャッジ）があります。これらは、違反を記録するオブザーバビリティや、影響の大きいアクションに対するHuman-in-the-Loop（人間による承認）と組み合わせて運用されます。" ], "components": [ "入力フィルタリング", "出力検証／墨消し（Redaction）", "アクションの許可リストと権限", "レートおよびスコープ制限", "ポリシー分類器", "違反ログの記録" ], "pros": [ "ガイドライン上だけでなく、実行時に安全性とポリシーを強制します。", "悪用、不安全な出力、およびインジェクションの影響を軽減します。", "ガバナンスとコンプライアンスの要件を運用可能な形にします。", "エージェントのアクションによる影響範囲を制限します。" ], "risks": [ "過剰なブロック（偽陽性）は有用性を損ないます。", "ブロックの不足（偽陰性）は、誤った安全感を生み出します。", "モデルベースのガードレールは、レイテンシとコストを増加させます。", "これらは完全な防御策ではありません。監視や評価（evals）と組み合わせる必要があります。" ], "tools": [ "ガードレールフレームワーク（例：NeMo Guardrails、Guardrails AI）", "コンテンツモデレーション／安全性分類器", "スキーマおよび入力検証", "権限およびポリシーエンジン", "違反に対するオブザーバビリティ" ], "examples": [ "モデルの出力を表示する前に、そこから個人データを墨消し（削除）する。", "安全なアクションの許可リストから外れたツール呼び出しをブロックする。", "要求されたJSONスキーマに一致しない応答を拒否する。" ], "faqs": [ { "q": "ガードレールはアライメントと同じものですか？", "a": "いいえ。アライメントは学習中にモデルの本質的な動作を形成するものであるのに対し、ガードレールはデプロイされたシステムの周囲に配置される外部のランタイム制御です。これらは相互に補完し合う関係にあります。" }, { "q": "ガードレールはプロンプトインジェクションを防げますか？", "a": "入力スクリーニングやアクションの許可リストは効果があり、影響を軽減することはできますが、プロンプトインジェクションを完全に防げるガードレールは存在しません。多層防御に加え、機密性の高いアクションには人間による承認を組み合わせて使用してください。" }, { "q": "決定論的ガードレールとモデルベースのガードレールのどちらを使用すべきですか？", "a": "両方です。決定論的チェック（スキーマ、許可リスト）は、明確なルールに対して低コストかつ信頼性が高くなります。モデルベースのチェックは、レイテンシの増加と引き換えに、ニュアンスを含む複雑なコンテンツを処理できます。" }, { "q": "ガードレールはAIガバナンスにどのように適合しますか？", "a": "ガードレールは運用レイヤーに位置します。つまり、ガバナンスポリシーを強制力のある動作へと変換し、ログ記録や監査を通じてその証跡を残すためのランタイム制御です。" } ] }, "zh": { "title": "什么是 AI 护栏？", "summary": "护栏是运行时控制机制，用于约束 AI 系统的输入和输出，确保其行为安全、符合策略且合规。它们检查并过滤输入和输出、验证工具操作、拦截不合规内容并强制执行限制——作为安全层环绕在模型周围。护栏是 AI 治理中的主要运营控制手段，也是防范滥用和提示词注入的关键防线。", "definition": "AI 护栏是运行时安全保护机制，通过验证、过滤或约束模型的输入、输出和操作，确保其行为安全、合规且处于定义的策略范围内。", "takeaways": [ "护栏在运行时对输入、输出和操作起作用。", "它们强制执行安全、策略和合规性，而非模型质量。", "类型：输入过滤、输出验证、操作白名单、限制。", "防范滥用和提示词注入的核心防线。", "护栏是评估和监督的补充，而非替代方案。" ], "context": [ "模型本身没有可强制执行的边界；它会尝试提示词诱导的任何内容。护栏在运营层面上增加了这些边界：介于用户、模型以及模型可触及系统之间的确定性或基于模型的检查。", "它们是将治理策略转化为实时控制的方式。例如，“绝不泄露 PII”或“未经批准绝不执行付款”的策略，可以通过在运行时进行实际检查和拦截的护栏来实现。" ], "architecture": [ "输入护栏筛选提示词（例如，针对注入、策略违规、PII）。输出护栏验证响应（格式、安全性、事实约束、PII 脱敏）。操作护栏通过权限和白名单限制工具调用。速率、范围和预算限制则用于控制爆炸半径。", "护栏可以是确定性的（规则、Schema、正则表达式、白名单），也可以是基于模型的（分类器或 LLM 裁判）。它们与可观测性相结合以记录违规行为，并与高影响操作的人机协同（human-in-the-loop）审批相结合。" ], "components": [ "输入过滤", "输出验证/脱敏", "操作白名单与权限", "速率与范围限制", "策略分类器", "违规日志记录" ], "pros": [ "在运行时强制执行安全和策略，而不仅仅是在指南中。", "减少滥用、不安全输出和注入的影响。", "使治理和合规要求落地运营。", "限制智能体操作的爆炸半径。" ], "risks": [ "过度拦截会损害实用性（误报）。", "拦截不足会产生虚假的安全感。", "基于模型的护栏会增加延迟和成本。", "它们并非万无一失的防线；需与监督和评估相结合。" ], "tools": [ "护栏框架（例如 NeMo Guardrails、Guardrails AI）", "内容审核/安全分类器", "Schema 与输入验证", "权限与策略引擎", "违规行为的可观测性" ], "examples": [ "在展示模型输出之前，对其进行个人数据脱敏。", "拦截超出安全操作白名单范围的工具调用。", "拒绝不符合所需 JSON Schema 的响应。" ], "faqs": [ { "q": "护栏和对齐（alignment）是一回事吗？", "a": "不是。对齐是在训练期间塑造模型的内在行为；而护栏是围绕已部署系统的外部运行时控制。两者相辅相成。" }, { "q": "护栏能阻止提示词注入吗？", "a": "它们可以减轻其影响——输入筛选和操作白名单会有所帮助——但没有任何护栏能完全阻止注入。对于敏感操作，请使用分层防御并结合人工审批。" }, { "q": "确定性护栏还是基于模型的护栏？", "a": "两者兼有。确定性检查（Schema、白名单）对于明确的规则而言成本低且可靠；基于模型的检查可以处理微妙的内容，但代价是增加延迟。" }, { "q": "护栏如何融入 AI 治理？", "a": "它们是运营层：通过日志记录和审计来证明，将治理策略转化为强制执行行为的运行时控制。" } ] } } }, { "slug": "harness-engineering", "category": "harness", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/harness-engineering", "api": "https://santismm.com/api/knowledge/harness-engineering", "canonical_url": "https://santismm.com/en/knowledge/harness-engineering", "api_url": "https://santismm.com/api/knowledge/harness-engineering", "evidence": { "evidenceLevel": "theoretical", "confidenceLevel": "medium", "sourceType": [ "personal_experience", "industry_observation" ] }, "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" }, { "title": "Santiago Santa María — The Stopwatch and the Exam", "url": "https://articles.santismm.com/the-stopwatch-and-the-exam/" } ], "related": [ "agentic-ai", "ai-agent", "context-engineering", "agent-memory", "ai-observability", "multi-agent-architecture", "agentic-evaluation" ], "locales": { "en": { "title": "What is Harness Engineering?", "summary": "Harness engineering is the emerging discipline of designing and optimizing the scaffolding around an AI model — the prompts, tools, memory, environment, control loop and guardrails — so the model performs reliably on real tasks. Its core premise: as base models converge in raw capability, competitive advantage shifts from the model itself to the harness built around it. The same model can pass or fail a task depending almost entirely on its harness.", "definition": "Harness engineering is the practice of designing, building and optimizing the scaffolding (tools, memory, prompts, environment and control loop) that turns a model's raw capability into reliable, goal-directed action.", "takeaways": [ "The harness is everything around the model that converts capability into action.", "As frontier models converge, the harness becomes the main lever of differentiation.", "Tool design, context management and memory often matter more than model choice.", "Harnesses must be observable and evaluated — you cannot improve what you cannot measure.", "Harness engineering is to agents what platform engineering is to cloud applications." ], "context": [ "Benchmarks long measured a model's capability in isolation. But in production, a model never acts alone: it acts through a harness. Give a strong model a poor harness and it fails; give a modest model an excellent harness and it succeeds. That gap is where harness engineering lives.", "The term names a shift in where engineering effort and competitive advantage sit. When everyone can call a comparable frontier model, the durable advantage is the system around it: the quality of the tools, the memory, the context strategy, the evaluation loop and the guardrails." ], "architecture": [ "A harness has recurring layers: the prompt/instruction layer; the tool layer (what the model can do and how cleanly those tools are described); the memory layer (short-term context plus long-term stores); the environment (the systems the agent acts on); the control loop (how outputs become actions and observations return); and the cross-cutting layers of guardrails, observability and evaluation.", "Good harness engineering treats each layer as a design surface. Tools are written for a model to use, not just for a developer to read. Context is curated rather than dumped. Memory is structured. Every run is traced so failures can be diagnosed and fed back into evals." ], "components": [ "Instruction / prompt layer", "Tooling", "Memory systems", "Environment", "Control loop / orchestration", "Guardrails", "Observability", "Evaluation" ], "pros": [ "Turns the same model into a far more reliable system.", "A durable advantage that survives model upgrades and swaps.", "Makes failures diagnosable through observability and evals.", "Lets teams improve agents systematically, not by prompt luck." ], "risks": [ "Complexity: more moving parts to build, secure and maintain.", "Over-engineering harnesses that simpler patterns would solve.", "Tight coupling to a model's quirks can create migration cost.", "Without evaluation, harness changes are guesswork." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse (observability)" ], "examples": [ "Rewriting a vague tool description so the model calls it correctly, lifting task success without touching the model.", "Adding a memory store so an agent stops repeating work across a long task.", "Introducing an evaluation harness that catches a regression before it ships." ], "faqs": [ { "q": "Why does harness engineering matter now?", "a": "Because frontier models are converging. When raw capability is broadly available, the differentiator becomes the harness — the engineered system that turns that capability into dependable work." }, { "q": "Is harness engineering the same as prompt engineering?", "a": "No. Prompt engineering is one layer of the harness. Harness engineering also covers tools, memory, environment, the control loop, guardrails, observability and evaluation." }, { "q": "How is it different from agentic harness engineering?", "a": "Agentic harness engineering applies the same discipline specifically to autonomous, multi-step agents and their long-horizon needs (memory, tools, feedback loops)." }, { "q": "What skills does it require?", "a": "Software and platform engineering, evaluation/measurement, systems design, security, and a working understanding of how models behave." }, { "q": "How do you know a harness is good?", "a": "By measuring it. A good harness is observable and evaluated against task-based benchmarks, so improvements are demonstrated rather than assumed." } ] }, "es": { "title": "¿Qué es la Ingeniería de Harness (Harness Engineering)?", "summary": "La ingeniería de harness es la disciplina emergente de diseñar y optimizar el andamiaje alrededor de un modelo de IA —prompts, herramientas, memoria, entorno, bucle de control y guardarraíles— para que el modelo rinda de forma fiable en tareas reales. Su premisa central: a medida que los modelos base convergen en capacidad bruta, la ventaja competitiva se desplaza del modelo al harness que lo rodea. El mismo modelo puede aprobar o fallar una tarea casi por completo según su harness.", "definition": "La ingeniería de harness es la práctica de diseñar, construir y optimizar el andamiaje (herramientas, memoria, prompts, entorno y bucle de control) que convierte la capacidad bruta de un modelo en acción fiable y dirigida a objetivos.", "takeaways": [ "El harness es todo lo que rodea al modelo y convierte capacidad en acción.", "A medida que los modelos frontera convergen, el harness se vuelve la principal palanca de diferenciación.", "El diseño de herramientas, la gestión de contexto y la memoria suelen importar más que el modelo elegido.", "Los harness deben ser observables y evaluados: no se mejora lo que no se mide.", "La ingeniería de harness es a los agentes lo que la ingeniería de plataforma a las aplicaciones cloud." ], "context": [ "Los benchmarks midieron durante mucho tiempo la capacidad de un modelo de forma aislada. Pero en producción un modelo nunca actúa solo: actúa a través de un harness. Dale a un modelo fuerte un harness pobre y falla; dale a un modelo modesto un harness excelente y triunfa. En esa brecha vive la ingeniería de harness.", "El término nombra un desplazamiento en dónde están el esfuerzo de ingeniería y la ventaja competitiva. Cuando todos pueden llamar a un modelo frontera comparable, la ventaja duradera es el sistema que lo rodea: la calidad de las herramientas, la memoria, la estrategia de contexto, el bucle de evaluación y los guardarraíles." ], "architecture": [ "Un harness tiene capas recurrentes: la capa de instrucción/prompt; la capa de herramientas (qué puede hacer el modelo y con qué limpieza se describen esas herramientas); la capa de memoria (contexto a corto plazo más almacenes a largo plazo); el entorno (los sistemas sobre los que actúa el agente); el bucle de control (cómo las salidas se vuelven acciones y vuelven las observaciones); y las capas transversales de guardarraíles, observabilidad y evaluación.", "La buena ingeniería de harness trata cada capa como una superficie de diseño. Las herramientas se escriben para que las use un modelo, no solo para que las lea un desarrollador. El contexto se cura en lugar de volcarse. La memoria se estructura. Cada ejecución se traza para diagnosticar fallos y realimentar las evaluaciones." ], "components": [ "Capa de instrucción / prompt", "Herramientas (tooling)", "Sistemas de memoria", "Entorno", "Bucle de control / orquestación", "Guardarraíles", "Observabilidad", "Evaluación" ], "pros": [ "Convierte el mismo modelo en un sistema mucho más fiable.", "Una ventaja duradera que sobrevive a actualizaciones y cambios de modelo.", "Hace los fallos diagnosticables mediante observabilidad y evaluaciones.", "Permite mejorar agentes de forma sistemática, no por suerte en el prompt." ], "risks": [ "Complejidad: más piezas que construir, asegurar y mantener.", "Sobreingeniería de harness que patrones más simples resolverían.", "El acoplamiento a las peculiaridades de un modelo puede crear coste de migración.", "Sin evaluación, los cambios de harness son conjeturas." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse (observabilidad)" ], "examples": [ "Reescribir una descripción de herramienta ambigua para que el modelo la llame bien, subiendo el éxito sin tocar el modelo.", "Añadir un almacén de memoria para que un agente deje de repetir trabajo en una tarea larga.", "Introducir un harness de evaluación que detecta una regresión antes de publicarla." ], "faqs": [ { "q": "¿Por qué importa ahora la ingeniería de harness?", "a": "Porque los modelos frontera están convergiendo. Cuando la capacidad bruta es ampliamente accesible, el diferenciador pasa a ser el harness: el sistema de ingeniería que convierte esa capacidad en trabajo fiable." }, { "q": "¿Es lo mismo que la ingeniería de prompts?", "a": "No. La ingeniería de prompts es una capa del harness. La ingeniería de harness abarca además herramientas, memoria, entorno, bucle de control, guardarraíles, observabilidad y evaluación." }, { "q": "¿En qué se diferencia de la ingeniería de harness agéntico?", "a": "La ingeniería de harness agéntico aplica la misma disciplina específicamente a agentes autónomos de varios pasos y sus necesidades de horizonte largo (memoria, herramientas, bucles de feedback)." }, { "q": "¿Qué habilidades requiere?", "a": "Ingeniería de software y de plataforma, evaluación/medición, diseño de sistemas, seguridad y una comprensión práctica de cómo se comportan los modelos." }, { "q": "¿Cómo sé si un harness es bueno?", "a": "Midiéndolo. Un buen harness es observable y se evalúa contra benchmarks basados en tareas, de modo que las mejoras se demuestran en vez de suponerse." } ] }, "pt": { "title": "O que é Engenharia de Harness (Harness Engineering)?", "summary": "A engenharia de harness é a disciplina emergente de projetar e otimizar o andaime ao redor de um modelo de IA — prompts, ferramentas, memória, ambiente, laço de controle e guard-rails — para que o modelo tenha desempenho confiável em tarefas reais. Sua premissa central: à medida que os modelos base convergem em capacidade bruta, a vantagem competitiva se desloca do modelo para o harness à sua volta. O mesmo modelo pode passar ou falhar numa tarefa quase inteiramente conforme seu harness.", "definition": "A engenharia de harness é a prática de projetar, construir e otimizar o andaime (ferramentas, memória, prompts, ambiente e laço de controle) que converte a capacidade bruta de um modelo em ação confiável e orientada a objetivos.", "takeaways": [ "O harness é tudo o que rodeia o modelo e converte capacidade em ação.", "À medida que os modelos de fronteira convergem, o harness se torna a principal alavanca de diferenciação.", "O design de ferramentas, a gestão de contexto e a memória costumam importar mais que o modelo escolhido.", "Os harnesses devem ser observáveis e avaliados: não se melhora o que não se mede.", "A engenharia de harness está para os agentes assim como a engenharia de plataforma está para as aplicações cloud." ], "context": [ "Os benchmarks mediram por muito tempo a capacidade de um modelo de forma isolada. Mas em produção um modelo nunca age sozinho: age através de um harness. Dê a um modelo forte um harness ruim e ele falha; dê a um modelo modesto um harness excelente e ele tem sucesso. Nessa lacuna vive a engenharia de harness.", "O termo nomeia um deslocamento de onde estão o esforço de engenharia e a vantagem competitiva. Quando todos podem chamar um modelo de fronteira comparável, a vantagem durável é o sistema ao seu redor: a qualidade das ferramentas, a memória, a estratégia de contexto, o laço de avaliação e os guard-rails." ], "architecture": [ "Um harness tem camadas recorrentes: a camada de instrução/prompt; a camada de ferramentas (o que o modelo pode fazer e com que clareza essas ferramentas são descritas); a camada de memória (contexto de curto prazo mais armazenamentos de longo prazo); o ambiente (os sistemas sobre os quais o agente age); o laço de controle (como as saídas viram ações e as observações retornam); e as camadas transversais de guard-rails, observabilidade e avaliação.", "A boa engenharia de harness trata cada camada como uma superfície de design. As ferramentas são escritas para um modelo usar, não só para um desenvolvedor ler. O contexto é curado em vez de despejado. A memória é estruturada. Cada execução é rastreada para diagnosticar falhas e realimentar as avaliações." ], "components": [ "Camada de instrução / prompt", "Ferramentas (tooling)", "Sistemas de memória", "Ambiente", "Laço de controle / orquestração", "Guard-rails", "Observabilidade", "Avaliação" ], "pros": [ "Transforma o mesmo modelo em um sistema muito mais confiável.", "Uma vantagem durável que sobrevive a atualizações e trocas de modelo.", "Torna as falhas diagnosticáveis por meio de observabilidade e avaliações.", "Permite melhorar agentes de forma sistemática, não por sorte no prompt." ], "risks": [ "Complexidade: mais peças para construir, proteger e manter.", "Superengenharia de harness que padrões mais simples resolveriam.", "O acoplamento às peculiaridades de um modelo pode criar custo de migração.", "Sem avaliação, as mudanças de harness são suposições." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse (observabilidade)" ], "examples": [ "Reescrever uma descrição de ferramenta ambígua para o modelo chamá-la corretamente, elevando o sucesso sem tocar no modelo.", "Adicionar um armazenamento de memória para um agente parar de repetir trabalho numa tarefa longa.", "Introduzir um harness de avaliação que detecta uma regressão antes de publicá-la." ], "faqs": [ { "q": "Por que a engenharia de harness importa agora?", "a": "Porque os modelos de fronteira estão convergindo. Quando a capacidade bruta é amplamente acessível, o diferencial passa a ser o harness: o sistema de engenharia que converte essa capacidade em trabalho confiável." }, { "q": "É o mesmo que engenharia de prompts?", "a": "Não. A engenharia de prompts é uma camada do harness. A engenharia de harness abrange ainda ferramentas, memória, ambiente, laço de controle, guard-rails, observabilidade e avaliação." }, { "q": "Como se diferencia da engenharia de harness agêntico?", "a": "A engenharia de harness agêntico aplica a mesma disciplina especificamente a agentes autônomos de vários passos e suas necessidades de horizonte longo (memória, ferramentas, laços de feedback)." }, { "q": "Que habilidades exige?", "a": "Engenharia de software e de plataforma, avaliação/medição, design de sistemas, segurança e uma compreensão prática de como os modelos se comportam." }, { "q": "Como sei se um harness é bom?", "a": "Medindo-o. Um bom harness é observável e avaliado contra benchmarks baseados em tarefas, de modo que as melhorias são demonstradas em vez de presumidas." } ] }, "fr": { "title": "Qu'est-ce que le Harness Engineering ?", "summary": "Le Harness Engineering est la discipline émergente de conception et d'optimisation de l'échafaudage (scaffolding) autour d'un modèle d'IA — les prompts, les outils, la mémoire, l'environnement, la boucle de contrôle et les garde-fous — afin que le modèle fonctionne de manière fiable sur des tâches réelles. Son principe fondamental : à mesure que les modèles de base convergent en termes de capacités brutes, l'avantage concurrentiel se déplace du modèle lui-même vers le harness construit autour de lui. Un même modèle peut réussir ou échouer une tâche en fonction presque entièrement de son harness.", "definition": "Le Harness Engineering est la pratique consistant à concevoir, construire et optimiser l'échafaudage (outils, mémoire, prompts, environnement et boucle de contrôle) qui transforme la capacité brute d'un modèle en une action fiable et orientée vers un objectif.", "takeaways": [ "Le harness est tout ce qui entoure le modèle et convertit sa capacité en action.", "À mesure que les modèles de pointe convergent, le harness devient le principal levier de différenciation.", "La conception des outils, la gestion du contexte et la mémoire importent souvent plus que le choix du modèle.", "Les harnesses doivent être observables et évalués — on ne peut pas améliorer ce qu'on ne peut pas mesurer.", "Le Harness Engineering est aux agents ce que le platform engineering est aux applications cloud." ], "context": [ "Les benchmarks ont longtemps mesuré la capacité d'un modèle de manière isolée. Mais en production, un modèle n'agit jamais seul : il agit à travers un harness. Donnez à un modèle performant un harness médiocre et il échouera ; donnez à un modèle modeste un excellent harness et il réussira. C'est dans cet écart que réside le Harness Engineering.", "Ce terme désigne un déplacement de l'effort d'ingénierie et de l'avantage concurrentiel. Lorsque tout le monde peut faire appel à un modèle de pointe comparable, l'avantage durable réside dans le système qui l'entoure : la qualité des outils, la mémoire, la stratégie de contexte, la boucle d'évaluation et les garde-fous." ], "architecture": [ "Un harness comporte des couches récurrentes : la couche de prompt/d'instruction ; la couche d'outils (ce que le modèle peut faire et la clarté avec laquelle ces outils sont décrits) ; la couche de mémoire (contexte à court terme et stockage à long terme) ; l'environnement (les systèmes sur lesquels l'agent agit) ; la boucle de contrôle (comment les sorties deviennent des actions et comment les observations reviennent) ; et les couches transversales de garde-fous, d'observabilité et d'évaluation.", "Un bon Harness Engineering traite chaque couche comme une surface de conception. Les outils sont écrits pour être utilisés par un modèle, et pas seulement pour être lus par un développeur. Le contexte est structuré plutôt que simplement déversé. La mémoire est structurée. Chaque exécution est tracée afin que les défaillances puissent être diagnostiquées et réinjectées dans les évaluations (evals)." ], "components": [ "Couche d'instruction / de prompt", "Outillage", "Systèmes de mémoire", "Environnement", "Boucle de contrôle / orchestration", "Garde-fous", "Observabilité", "Évaluation" ], "pros": [ "Transforme le même modèle en un système beaucoup plus fiable.", "Un avantage durable qui survit aux mises à niveau et aux remplacements de modèles.", "Rend les défaillances diagnostiquables grâce à l'observabilité et aux évaluations.", "Permet aux équipes d'améliorer les agents de manière systématique, et non par la simple chance du prompt." ], "risks": [ "Complexité : plus de pièces mobiles à construire, sécuriser et maintenir.", "Sur-ingénierie de harnesses que des patterns plus simples permettraient de résoudre.", "Un couplage étroit avec les particularités d'un modèle peut générer des coûts de migration.", "Sans évaluation, les modifications du harness relèvent de la conjecture." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse (observabilité)" ], "examples": [ "Réécrire la description vague d'un outil pour que le modèle l'appelle correctement, améliorant ainsi le taux de réussite des tâches sans toucher au modèle.", "Ajouter un stockage de mémoire pour qu'un agent cesse de répéter le même travail sur une tâche longue.", "Introduire un harness d'évaluation qui détecte une régression avant son déploiement." ], "faqs": [ { "q": "Pourquoi le Harness Engineering est-il important aujourd'hui ?", "a": "Parce que les modèles de pointe convergent. Lorsque la capacité brute est largement disponible, le facteur de différenciation devient le harness — le système conçu pour transformer cette capacité en un travail fiable." }, { "q": "Le Harness Engineering est-il identique au prompt engineering ?", "a": "Non. Le prompt engineering n'est qu'une couche du harness. Le Harness Engineering englobe également les outils, la mémoire, l'environnement, la boucle de contrôle, les garde-fous, l'observabilité et l'évaluation." }, { "q": "En quoi diffère-t-il de l'agentic harness engineering ?", "a": "L'agentic harness engineering applique la même discipline spécifiquement aux agents autonomes multi-étapes et à leurs besoins à long terme (mémoire, outils, boucles de rétroaction)." }, { "q": "Quelles compétences cela requiert-il ?", "a": "Ingénierie logicielle et de plateforme, évaluation/mesure, conception de systèmes, sécurité, et une compréhension pratique du comportement des modèles." }, { "q": "Comment savoir si un harness est performant ?", "a": "En le mesurant. Un bon harness est observable et évalué par rapport à des benchmarks basés sur des tâches, de sorte que les améliorations soient démontrées plutôt que supposées." } ] }, "de": { "title": "Was ist Harness Engineering?", "summary": "Harness Engineering ist die entstehende Disziplin des Entwurfs und der Optimierung des Gerüsts (Scaffolding) um ein KI-Modell herum – die Prompts, Tools, Speicher, Umgebung, Kontrollschleife und Guardrails –, damit das Modell bei realen Aufgaben zuverlässig funktioniert. Die Kernannahme: Da sich Basismodelle in ihrer reinen Leistungsfähigkeit angleichen, verlagert sich der Wettbewerbsvorteil vom Modell selbst auf das darum herum aufgebaute Harness. Dasselbe Modell kann eine Aufgabe fast ausschließlich in Abhängigkeit von seinem Harness erfolgreich bewältigen oder daran scheitern.", "definition": "Harness Engineering ist die Praxis des Entwurfs, des Aufbaus und der Optimierung des Gerüsts (Tools, Speicher, Prompts, Umgebung und Kontrollschleife), das die reine Leistungsfähigkeit eines Modells in zuverlässiges, zielgerichtetes Handeln umwandelt.", "takeaways": [ "Das Harness ist alles um das Modell herum, was Leistungsfähigkeit in Handeln umwandelt.", "Da sich Frontier-Modelle angleichen, wird das Harness zum Haupthebel für die Differenzierung.", "Tool-Design, Kontextmanagement und Speicher sind oft wichtiger als die Wahl des Modells.", "Harnesses müssen beobachtbar (observable) sein und evaluiert werden – man kann nicht verbessern, was man nicht messen kann.", "Harness Engineering verhält sich zu Agenten wie Platform Engineering zu Cloud-Anwendungen." ], "context": [ "Benchmarks haben lange Zeit die Leistungsfähigkeit eines Modells isoliert gemessen. Doch in der Produktion agiert ein Modell nie allein: Es agiert über ein Harness. Gibt man einem starken Modell ein schlechtes Harness, scheitert es; gibt man einem mäßigen Modell ein hervorragendes Harness, ist es erfolgreich. In dieser Lücke bewegt sich das Harness Engineering.", "Der Begriff bezeichnet eine Verschiebung des Schwerpunkts von Entwicklungsaufwand und Wettbewerbsvorteil. Wenn jeder ein vergleichbares Frontier-Modell aufrufen kann, liegt der dauerhafte Vorteil im System darum herum: in der Qualität der Tools, dem Speicher, der Kontextstrategie, der Evaluierungsschleife und den Guardrails." ], "architecture": [ "Ein Harness besteht aus wiederkehrenden Ebenen: der Prompt-/Instruktionsebene, der Tool-Ebene (was das Modell tun kann und wie sauber diese Tools beschrieben sind), der Speicherebene (Kurzzeitkontext plus Langzeitspeicher), der Umgebung (die Systeme, auf denen der Agent agiert), der Kontrollschleife (wie Outputs zu Aktionen werden und Beobachtungen zurückkehren) sowie den übergreifenden Ebenen aus Guardrails, Observability und Evaluierung.", "Gutes Harness Engineering behandelt jede Ebene als Gestaltungsfläche. Tools werden so geschrieben, dass ein Modell sie nutzen kann, nicht nur ein Entwickler sie versteht. Kontext wird kuratiert statt einfach abgelegt. Speicher wird strukturiert. Jeder Durchlauf wird aufgezeichnet (traced), damit Fehler diagnostiziert und in die Evals zurückgeführt werden können." ], "components": [ "Instruktions- / Prompt-Ebene", "Tooling", "Speichersysteme", "Umgebung", "Kontrollschleife / Orchestrierung", "Guardrails", "Observability", "Evaluierung" ], "pros": [ "Verwandelt dasselbe Modell in ein weitaus zuverlässigeres System.", "Ein dauerhafter Vorteil, der Modell-Upgrades und -Wechsel übersteht.", "Macht Fehler durch Observability und Evals diagnostizierbar.", "Ermöglicht es Teams, Agenten systematisch zu verbessern, statt sich auf Prompt-Glück zu verlassen." ], "risks": [ "Komplexität: Mehr bewegliche Teile, die erstellt, abgesichert und gewartet werden müssen.", "Over-Engineering von Harnesses, die durch einfachere Muster gelöst werden könnten.", "Eine enge Kopplung an die Eigenheiten eines Modells kann Migrationskosten verursachen.", "Ohne Evaluierung sind Änderungen am Harness reine Mutmaßung." ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse (Observability)" ], "examples": [ "Umschreiben einer vagen Tool-Beschreibung, damit das Modell sie korrekt aufruft, was den Aufgabenerfolg steigert, ohne das Modell selbst anzupassen.", "Hinzufügen eines Arbeitsspeichers (Memory Store), damit ein Agent aufhört, Arbeitsschritte bei einer langen Aufgabe zu wiederholen.", "Einführung eines Evaluierungs-Harness, das eine Regression abfängt, bevor sie ausgeliefert wird." ], "faqs": [ { "q": "Warum ist Harness Engineering jetzt wichtig?", "a": "Weil Frontier-Modelle konvergieren. Wenn die reine Leistungsfähigkeit allgemein verfügbar ist, wird das Harness zum Differenzierungsmerkmal – das entwickelte System, das diese Leistungsfähigkeit in verlässliche Arbeit umwandelt." }, { "q": "Ist Harness Engineering dasselbe wie Prompt Engineering?", "a": "Nein. Prompt Engineering ist nur eine Ebene des Harness. Harness Engineering umfasst auch Tools, Memory, Umgebung, den Control Loop, Guardrails, Observability und Evaluierung." }, { "q": "Wie unterscheidet es sich von agentischem Harness Engineering?", "a": "Agentisches Harness Engineering wendet dieselbe Disziplin speziell auf autonome, mehrstufige Agenten und deren langfristige Anforderungen (Memory, Tools, Feedback-Loops) an." }, { "q": "Welche Fähigkeiten sind dafür erforderlich?", "a": "Software- und Plattform-Engineering, Evaluierung/Messung, Systemdesign, Sicherheit und ein praktisches Verständnis des Modellverhaltens." }, { "q": "Woran erkennt man ein gutes Harness?", "a": "Indem man es misst. Ein gutes Harness ist beobachtbar (observable) und wird anhand aufgabenbasierter Benchmarks evaluiert, sodass Verbesserungen nachgewiesen und nicht bloß angenommen werden." } ] }, "ja": { "title": "ハーネスエンジニアリング (Harness Engineering) とは何ですか？", "summary": "ハーネスエンジニアリングとは、AIモデルの周囲にある足場（プロンプト、ツール、メモリ、環境、制御ループ、ガードレールなど）を設計および最適化し、モデルが実際のタスクで確実に機能するようにするための新しい分野です。その核心となる前提は、ベースモデルの生の能力が収束していくにつれ、競争優位性はモデル自体からその周囲に構築されるハーネスへと移行するということです。同じモデルであっても、タスクの成否はほぼ完全にそのハーネスに依存します。", "definition": "ハーネスエンジニアリングとは、モデルの生の能力を、信頼性の高い目標指向のアクションへと変換するための足場（ツール、メモリ、プロンプト、環境、および制御ループ）を設計、構築、および最適化する実践のことです。", "takeaways": [ "ハーネスとは、能力をアクションに変換する、モデルの周囲にあるすべてのものを指します。", "フロンティアモデルの能力が収束するにつれ、ハーネスが差別化の主な手段となります。", "多くの場合、モデルの選択よりも、ツールの設計、コンテキスト管理、およびメモリの方が重要になります。", "ハーネスは観察可能（オブザーバブル）であり、評価可能でなければなりません。測定できないものを改善することはできないからです。", "ハーネスエンジニアリングとエージェントの関係は、プラットフォームエンジニアリングとクラウドアプリケーションの関係に相当します。" ], "context": [ "ベンチマークは長らく、モデル単体の能力を測定してきました。しかし本番環境では、モデルが単独で動作することはありません。モデルは常にハーネスを介して動作します。強力なモデルに貧弱なハーネスを組み合わせれば失敗し、控えめなモデルに優れたハーネスを組み合わせれば成功します。このギャップこそが、ハーネスエンジニアリングが真価を発揮する領域です。", "この用語は、エンジニアリングの取り組みと競争優位性がどこに存在するかのシフトを表しています。誰もが同等のフロンティアモデルを呼び出せる状況において、持続的な優位性をもたらすのはモデルを取り巻くシステム、すなわちツールの品質、メモリ、コンテキスト戦略、評価ループ、そしてガードレールです。" ], "architecture": [ "ハーネスには、繰り返し現れるいくつかのレイヤーがあります。プロンプト／指示レイヤー、ツールレイヤー（モデルが実行できること、およびそれらのツールがどれだけ明確に記述されているか）、メモリレイヤー（短期的なコンテキストと長期的なストレージ）、環境（エージェントが作用するシステム）、制御ループ（出力がどのようにアクションになり、観察結果がどのように戻るか）、そしてガードレール、オブザーバビリティ、評価といった横断的なレイヤーです。", "優れたハーネスエンジニアリングでは、各レイヤーを設計対象（デザインサーフェス）として扱います。ツールは、開発者が読むためだけでなく、モデルが使用するために作成されます。コンテキストは単に流し込まれるのではなく、キュレーションされます。メモリは構造化されます。すべての実行がトレースされるため、失敗を診断して評価（evals）にフィードバックすることができます。" ], "components": [ "指示／プロンプトレイヤー", "ツーリング", "メモリシステム", "環境", "制御ループ／オーケストレーション", "ガードレール", "オブザーバビリティ", "評価" ], "pros": [ "同じモデルを、はるかに信頼性の高いシステムへと変えます。", "モデルのアップグレードや入れ替えを経ても維持される、持続的な強み。", "オブザーバビリティと評価（evals）を通じて、障害の診断を可能にします。", "プロンプトの偶然の成否に頼るのではなく、チームが体系的にエージェントを改善できるようにします。" ], "risks": [ "複雑性：構築、セキュリティ確保、保守が必要な可動パーツが増加します。", "よりシンプルなパターンで解決できるにもかかわらず、ハーネスを過剰設計（オーバーエンジニアリング）してしまうこと。", "モデル固有の癖に密結合することで、移行コストが発生する可能性があります。", "評価がなければ、ハーネスの変更は当て推量になってしまいます。" ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse（オブザーバビリティ）" ], "examples": [ "曖昧なツールの説明を書き換えてモデルが正しく呼び出せるようにし、モデル自体に手を加えることなくタスクの成功率を向上させます。", "メモリストアを追加することで、エージェントが長期にわたるタスクの中で同じ作業を繰り返すのを防ぎます。", "評価ハーネスを導入し、出荷前にデグレード（リグレッション）を検知します。" ], "faqs": [ { "q": "なぜ今、ハーネスエンジニアリング (Harness Engineering) が重要なのでしょうか？", "a": "フロンティアモデルの性能が収束しつつあるからです。生の能力が広く利用可能になると、差別化要因はハーネス、つまりその能力を信頼性の高い実務へと変換するエンジニアリングされたシステムになります。" }, { "q": "ハーネスエンジニアリングはプロンプトエンジニアリングと同じですか？", "a": "いいえ。プロンプトエンジニアリングはハーネスの1つのレイヤーに過ぎません。ハーネスエンジニアリングは、ツール、メモリ、環境、制御ループ、ガードレール、オブザーバビリティ、そして評価までをカバーします。" }, { "q": "エージェント型ハーネスエンジニアリングとはどのように違うのですか？", "a": "エージェント型ハーネスエンジニアリングは、同じ規律を特に自律的でマルチステップなエージェントと、その長期的なニーズ（メモリ、ツール、フィードバックループ）に適用するものです。" }, { "q": "どのようなスキルが必要ですか？", "a": "ソフトウェアおよびプラットフォームエンジニアリング、評価・測定、システム設計、セキュリティ、そしてモデルがどのように動作するかに関する実用的な理解が必要です。" }, { "q": "ハーネスが優れているかどうかは、どうすれば分かりますか？", "a": "測定することによって分かります。優れたハーネスはオブザーバビリティを備え、タスクベースのベンチマークに対して評価されるため、改善は仮定されるものではなく、実証されるものになります。" } ] }, "zh": { "title": "什么是 Harness Engineering（智能体支撑系统工程）？", "summary": "Harness Engineering 是一门新兴学科，旨在设计和优化 AI 模型周围的脚手架——提示词、工具、记忆、环境、控制循环和护栏——以便模型在实际任务中可靠地运行。其核心前提是：随着基础模型在原始能力上趋于一致，竞争优势正从模型本身转向围绕其构建的支撑系统（harness）。同一个模型在执行某项任务时是成功还是失败，几乎完全取决于其支撑系统。", "definition": "Harness Engineering 是指设计、构建和优化脚手架（工具、记忆、提示词、环境和控制循环）的实践，旨在将模型的原始能力转化为可靠的、目标导向的操作。", "takeaways": [ "支撑系统（harness）是模型周围将能力转化为行动的一切要素。", "随着前沿模型趋于一致，支撑系统成为差异化的主要杠杆。", "工具设计、上下文管理和记忆往往比模型选择更重要。", "支撑系统必须是可观测且可评估的——无法衡量，就无法改进。", "Harness Engineering 之于智能体，犹如平台工程之于云应用程序。" ], "context": [ "长期以来，基准测试一直在孤立地衡量模型的能力。但在生产环境中，模型绝非单独行动：它通过支撑系统发挥作用。给一个强大的模型配备一个糟糕的支撑系统，它就会失败；给一个普通的模型配备一个优秀的支撑系统，它就能成功。这一差距正是 Harness Engineering 的意义所在。", "该术语命名了工程重心和竞争优势所在的转变。当每个人都能调用相当的前沿模型时，持久的优势在于其周围的系统：工具的质量、记忆、上下文策略、评估循环和护栏。" ], "architecture": [ "支撑系统具有循环往复的层级：提示词/指令层；工具层（模型能做什么以及这些工具的描述有多清晰）；记忆层（短期上下文加上长期存储）；环境（智能体操作的系统）；控制循环（输出如何转化为操作以及观测结果如何返回）；以及护栏、可观测性和评估等交叉层。", "优秀的 Harness Engineering 将每一层都视为设计表面。工具是为模型使用而编写的，而不仅仅是为了让开发人员阅读。上下文是精心策划的，而不是随意倾倒。记忆是结构化的。每一次运行都会被追踪，以便诊断失败并反馈到评估中。" ], "components": [ "指令/提示词层", "工具集", "记忆系统", "环境", "控制循环/编排", "护栏", "可观测性", "评估" ], "pros": [ "将同一个模型转化为一个可靠得多的系统。", "一种持久的优势，在模型升级和更换后依然有效。", "通过可观测性和评估（evals）使故障可诊断。", "让团队能够系统化地改进智能体，而不是靠碰运气调整提示词。" ], "risks": [ "复杂性：需要构建、保护和维护更多的活动部件。", "过度设计支撑系统（harness），而实际上更简单的模式就能解决问题。", "与特定模型特性的紧密耦合可能会带来迁移成本。", "缺乏评估时，对支撑系统（harness）的修改只能靠猜测。" ], "tools": [ "LangGraph", "Claude Agent SDK", "OpenAI Agents SDK", "Model Context Protocol (MCP)", "LangSmith / Langfuse（可观测性）" ], "examples": [ "重写模糊的工具描述以使模型能够正确调用，在不触及模型本身的情况下提升任务成功率。", "添加内存存储，使智能体在执行长任务时不再重复工作。", "引入评估支撑系统（evaluation harness），在发布前捕获性能回退。" ], "faqs": [ { "q": "为什么 Harness Engineering（智能体支撑系统工程）在当下如此重要？", "a": "因为前沿模型正在趋同。当基础能力被广泛获取时，差异化因素就变成了支撑系统（harness）——即把这种能力转化为可靠工作的工程化系统。" }, { "q": "Harness Engineering 与提示词工程（prompt engineering）是一回事吗？", "a": "不。提示词工程只是支撑系统（harness）的一层。Harness Engineering 还涵盖了工具、内存、环境、控制循环、护栏（guardrails）、可观测性和评估。" }, { "q": "它与智能体 Harness Engineering 有何不同？", "a": "智能体 Harness Engineering 将相同的规范专门应用于自主、多步骤的智能体及其长期需求（内存、工具、反馈循环）。" }, { "q": "它需要哪些技能？", "a": "软件与平台工程、评估/测量、系统设计、安全，以及对模型行为方式的实际理解。" }, { "q": "如何判断一个支撑系统（harness）是优秀的？", "a": "通过测量。一个优秀的支撑系统是可观测的，并能针对基于任务的基准进行评估，从而使改进得以证实，而非凭空假设。" } ] } } }, { "slug": "human-in-the-loop", "category": "pattern", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/human-in-the-loop", "api": "https://santismm.com/api/knowledge/human-in-the-loop", "canonical_url": "https://santismm.com/en/knowledge/human-in-the-loop", "api_url": "https://santismm.com/api/knowledge/human-in-the-loop", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "European Union — AI Act, Article 14 (Human oversight)", "url": "https://artificialintelligenceact.eu/article/14/" }, { "title": "NIST — AI Risk Management Framework (AI RMF 1.0)", "url": "https://www.nist.gov/itl/ai-risk-management-framework" } ], "related": [ "ai-governance", "agentic-ai", "ai-agent", "agentic-evaluation" ], "locales": { "en": { "title": "What is the Human-in-the-Loop Pattern?", "summary": "Human-in-the-loop (HITL) is a design pattern where a person reviews, approves or corrects an AI system's output before it takes effect — especially for high-impact actions. Instead of full autonomy, the agent proposes and a human disposes. It is a primary control for managing risk in agentic systems and a recurring requirement in AI governance frameworks like the EU AI Act and NIST AI RMF.", "definition": "Human-in-the-loop is a pattern in which a human reviews, approves, edits or rejects an AI system's proposed output or action before it is executed, inserting human judgment at defined decision points.", "takeaways": [ "The agent proposes; a human approves, edits or rejects.", "Apply it to high-impact, irreversible or sensitive actions.", "It trades some autonomy and speed for control and trust.", "Governance frameworks often require human oversight by design.", "Approvals and overrides should be logged for auditability." ], "context": [ "Full autonomy is risky when actions are costly, irreversible or regulated. HITL inserts a checkpoint: the AI does the work and a human makes the final call, capturing most of the efficiency while keeping accountability with a person.", "It is also a trust-building and adoption strategy. Teams often start with tight human review, then widen autonomy as evaluation shows the system is reliable for a given task." ], "architecture": [ "Patterns: human-in-the-loop (a person approves each high-impact action), human-on-the-loop (a person monitors and can intervene), and human-over-the-loop (periodic review and policy setting). The right level depends on the action's risk.", "Implementation needs an approval interface, clear context for the reviewer, the ability to edit or reject, fallback behavior on timeout, and logging of every decision for audit." ], "components": [ "Decision checkpoints", "Approval interface", "Reviewer context", "Edit / override", "Escalation & fallback", "Audit log" ], "pros": [ "Catches errors before they cause harm.", "Keeps accountability with a human.", "Supports compliance and governance requirements.", "Builds trust and enables gradual autonomy." ], "risks": [ "Adds latency and limits throughput.", "Rubber-stamping: reviewers approve without real scrutiny.", "Alert fatigue degrades the quality of oversight.", "Over-applying it negates the value of automation." ], "tools": [ "Approval / workflow systems", "Agent frameworks with interrupt steps (e.g. LangGraph)", "Audit logging", "Case-management UIs" ], "examples": [ "An agent drafting a refund that a human approves before it is issued.", "A content agent whose output a person reviews before publishing.", "An ops agent that pauses for sign-off before a production change." ], "faqs": [ { "q": "When should you use human-in-the-loop?", "a": "For actions that are high-impact, irreversible, sensitive or regulated, where the cost of an error outweighs the latency of review." }, { "q": "What is the difference between in-the-loop and on-the-loop?", "a": "In-the-loop means a human approves each action before it executes; on-the-loop means a human monitors and can intervene, but the system acts on its own by default." }, { "q": "Does HITL conflict with autonomy?", "a": "It bounds autonomy deliberately. Many systems start with heavy review and widen autonomy as evaluation demonstrates reliability for a task." }, { "q": "Is it required by regulation?", "a": "Human oversight is a recurring requirement — for example the EU AI Act mandates effective human oversight for high-risk AI systems." } ] }, "es": { "title": "¿Qué es el Patrón Human-in-the-Loop?", "summary": "Human-in-the-loop (HITL) es un patrón de diseño en el que una persona revisa, aprueba o corrige la salida de un sistema de IA antes de que surta efecto, sobre todo en acciones de alto impacto. En lugar de autonomía total, el agente propone y un humano dispone. Es un control primario para gestionar el riesgo en sistemas agénticos y un requisito recurrente en marcos de gobernanza como el Reglamento de IA de la UE y el NIST AI RMF.", "definition": "Human-in-the-loop es un patrón en el que un humano revisa, aprueba, edita o rechaza la salida o acción propuesta por un sistema de IA antes de ejecutarse, insertando el juicio humano en puntos de decisión definidos.", "takeaways": [ "El agente propone; un humano aprueba, edita o rechaza.", "Aplícalo a acciones de alto impacto, irreversibles o sensibles.", "Cambia algo de autonomía y velocidad por control y confianza.", "Los marcos de gobernanza suelen exigir supervisión humana por diseño.", "Las aprobaciones y anulaciones deben registrarse para la auditabilidad." ], "context": [ "La autonomía total es arriesgada cuando las acciones son costosas, irreversibles o reguladas. HITL inserta un punto de control: la IA hace el trabajo y un humano toma la decisión final, capturando casi toda la eficiencia mientras la responsabilidad queda en una persona.", "También es una estrategia de confianza y adopción. Los equipos suelen empezar con revisión humana estricta y luego ampliar la autonomía a medida que la evaluación muestra que el sistema es fiable para una tarea dada." ], "architecture": [ "Patrones: human-in-the-loop (una persona aprueba cada acción de alto impacto), human-on-the-loop (una persona monitoriza y puede intervenir) y human-over-the-loop (revisión periódica y fijación de políticas). El nivel adecuado depende del riesgo de la acción.", "La implementación necesita una interfaz de aprobación, contexto claro para el revisor, capacidad de editar o rechazar, comportamiento de respaldo ante timeout, y registro de cada decisión para auditoría." ], "components": [ "Puntos de decisión", "Interfaz de aprobación", "Contexto para el revisor", "Edición / anulación", "Escalado y respaldo", "Registro de auditoría" ], "pros": [ "Detecta errores antes de que causen daño.", "Mantiene la responsabilidad en un humano.", "Apoya requisitos de cumplimiento y gobernanza.", "Genera confianza y habilita una autonomía gradual." ], "risks": [ "Añade latencia y limita el rendimiento.", "Aprobación automática: revisores que aprueban sin escrutinio real.", "La fatiga de alertas degrada la calidad de la supervisión.", "Aplicarlo en exceso anula el valor de la automatización." ], "tools": [ "Sistemas de aprobación / workflow", "Frameworks de agentes con pasos de interrupción (p. ej. LangGraph)", "Registro de auditoría", "Interfaces de gestión de casos" ], "examples": [ "Un agente que redacta un reembolso que un humano aprueba antes de emitirse.", "Un agente de contenido cuya salida una persona revisa antes de publicar.", "Un agente de operaciones que se pausa para una firma antes de un cambio en producción." ], "faqs": [ { "q": "¿Cuándo usar human-in-the-loop?", "a": "Para acciones de alto impacto, irreversibles, sensibles o reguladas, donde el coste de un error supera a la latencia de la revisión." }, { "q": "¿Cuál es la diferencia entre in-the-loop y on-the-loop?", "a": "In-the-loop significa que un humano aprueba cada acción antes de ejecutarse; on-the-loop significa que un humano monitoriza y puede intervenir, pero el sistema actúa por su cuenta por defecto." }, { "q": "¿HITL choca con la autonomía?", "a": "La acota de forma deliberada. Muchos sistemas empiezan con revisión fuerte y amplían la autonomía a medida que la evaluación demuestra fiabilidad en una tarea." }, { "q": "¿Lo exige la regulación?", "a": "La supervisión humana es un requisito recurrente; por ejemplo, el Reglamento de IA de la UE exige una supervisión humana efectiva para los sistemas de IA de alto riesgo." } ] }, "pt": { "title": "O que é o Padrão Human-in-the-Loop?", "summary": "Human-in-the-loop (HITL) é um padrão de design em que uma pessoa revisa, aprova ou corrige a saída de um sistema de IA antes de surtir efeito, sobretudo em ações de alto impacto. Em vez de autonomia total, o agente propõe e um humano dispõe. É um controle primário para gerir o risco em sistemas agênticos e um requisito recorrente em marcos de governança como o Regulamento de IA da UE e o NIST AI RMF.", "definition": "Human-in-the-loop é um padrão em que um humano revisa, aprova, edita ou rejeita a saída ou ação proposta por um sistema de IA antes de ser executada, inserindo o julgamento humano em pontos de decisão definidos.", "takeaways": [ "O agente propõe; um humano aprova, edita ou rejeita.", "Aplique-o a ações de alto impacto, irreversíveis ou sensíveis.", "Troca alguma autonomia e velocidade por controle e confiança.", "Os marcos de governança costumam exigir supervisão humana por design.", "As aprovações e anulações devem ser registradas para a auditabilidade." ], "context": [ "A autonomia total é arriscada quando as ações são custosas, irreversíveis ou reguladas. O HITL insere um ponto de controle: a IA faz o trabalho e um humano toma a decisão final, capturando quase toda a eficiência enquanto a responsabilidade fica com uma pessoa.", "É também uma estratégia de confiança e adoção. As equipes costumam começar com revisão humana estrita e depois ampliar a autonomia conforme a avaliação mostra que o sistema é confiável para uma dada tarefa." ], "architecture": [ "Padrões: human-in-the-loop (uma pessoa aprova cada ação de alto impacto), human-on-the-loop (uma pessoa monitora e pode intervir) e human-over-the-loop (revisão periódica e definição de políticas). O nível adequado depende do risco da ação.", "A implementação precisa de uma interface de aprovação, contexto claro para o revisor, capacidade de editar ou rejeitar, comportamento de fallback em timeout, e registro de cada decisão para auditoria." ], "components": [ "Pontos de decisão", "Interface de aprovação", "Contexto para o revisor", "Edição / anulação", "Escalonamento e fallback", "Registro de auditoria" ], "pros": [ "Detecta erros antes que causem dano.", "Mantém a responsabilidade com um humano.", "Apoia requisitos de conformidade e governança.", "Gera confiança e habilita uma autonomia gradual." ], "risks": [ "Adiciona latência e limita a vazão.", "Aprovação automática: revisores que aprovam sem escrutínio real.", "A fadiga de alertas degrada a qualidade da supervisão.", "Aplicá-lo em excesso anula o valor da automação." ], "tools": [ "Sistemas de aprovação / workflow", "Frameworks de agentes com passos de interrupção (ex.: LangGraph)", "Registro de auditoria", "Interfaces de gestão de casos" ], "examples": [ "Um agente que redige um reembolso que um humano aprova antes de ser emitido.", "Um agente de conteúdo cuja saída uma pessoa revisa antes de publicar.", "Um agente de operações que pausa para uma assinatura antes de uma mudança em produção." ], "faqs": [ { "q": "Quando usar human-in-the-loop?", "a": "Para ações de alto impacto, irreversíveis, sensíveis ou reguladas, em que o custo de um erro supera a latência da revisão." }, { "q": "Qual a diferença entre in-the-loop e on-the-loop?", "a": "In-the-loop significa que um humano aprova cada ação antes de executar; on-the-loop significa que um humano monitora e pode intervir, mas o sistema age por conta própria por padrão." }, { "q": "O HITL conflita com a autonomia?", "a": "Limita-a de forma deliberada. Muitos sistemas começam com revisão forte e ampliam a autonomia conforme a avaliação demonstra confiabilidade numa tarefa." }, { "q": "É exigido por regulação?", "a": "A supervisão humana é um requisito recorrente; por exemplo, o Regulamento de IA da UE exige supervisão humana efetiva para sistemas de IA de alto risco." } ] }, "fr": { "title": "Qu'est-ce que le pattern Human-in-the-Loop ?", "summary": "Le Human-in-the-loop (HITL) est un design pattern dans lequel une personne examine, approuve ou corrige les résultats d'un système d'IA avant qu'ils ne prennent effet — en particulier pour les actions à fort impact. Au lieu d'une autonomie totale, l'agent propose et l'humain dispose. C'est un moyen de contrôle essentiel pour gérer les risques dans les systèmes d'agents et une exigence récurrente dans les cadres de gouvernance de l'IA tels que l'EU AI Act et le NIST AI RMF.", "definition": "Le Human-in-the-loop est un pattern dans lequel un humain examine, approuve, modifie ou rejette la proposition de résultat ou d'action d'un système d'IA avant son exécution, intégrant ainsi le jugement humain à des points de décision définis.", "takeaways": [ "L'agent propose ; un humain approuve, modifie ou rejette.", "Appliquez-le aux actions à fort impact, irréversibles ou sensibles.", "Il troque une partie de l'autonomie et de la rapidité contre du contrôle et de la confiance.", "Les cadres de gouvernance exigent souvent une surveillance humaine dès la conception.", "Les approbations et les contournements doivent être enregistrés pour des raisons d'auditabilité." ], "context": [ "L'autonomie totale est risquée lorsque les actions sont coûteuses, irréversibles ou réglementées. Le HITL insère un point de contrôle : l'IA fait le travail et un humain prend la décision finale, capturant ainsi l'essentiel de l'efficacité tout en maintenant la responsabilité chez une personne.", "C'est également une stratégie de renforcement de la confiance et d'adoption. Les équipes commencent souvent par un examen humain rigoureux, puis élargissent l'autonomie à mesure que l'évaluation montre que le système est fiable pour une tâche donnée." ], "architecture": [ "Patterns : human-in-the-loop (une personne approuve chaque action à fort impact), human-on-the-loop (une personne surveille et peut intervenir) et human-over-the-loop (examen périodique et définition des politiques). Le niveau approprié dépend du risque de l'action.", "L'implémentation nécessite une interface d'approbation, un contexte clair pour le réviseur, la possibilité de modifier ou de rejeter, un comportement de repli en cas de dépassement de délai et l'enregistrement de chaque décision pour audit." ], "components": [ "Points de contrôle des décisions", "Interface d'approbation", "Contexte pour le réviseur", "Modification / contournement", "Escalade et repli", "Journal d'audit" ], "pros": [ "Détecte les erreurs avant qu'elles ne causent des dommages.", "Maintient la responsabilité chez un humain.", "Prend en charge les exigences de conformité et de gouvernance.", "Renforce la confiance et permet une autonomie progressive." ], "risks": [ "Ajoute de la latence et limite le débit.", "Validation aveugle : les réviseurs approuvent sans véritable examen.", "La fatigue des alertes dégrade la qualité de la surveillance.", "Une application excessive annule la valeur de l'automatisation." ], "tools": [ "Systèmes d'approbation / de workflow", "Frameworks d'agents avec étapes d'interruption (par ex. LangGraph)", "Journalisation d'audit", "Interfaces de gestion des cas" ], "examples": [ "Un agent rédigeant un remboursement qu'un humain approuve avant qu'il ne soit émis.", "Un agent de contenu dont le résultat est examiné par une personne avant publication.", "Un agent d'exploitation qui s'interrompt pour obtenir une validation avant une modification en production." ], "faqs": [ { "q": "Quand faut-il utiliser le human-in-the-loop ?", "a": "Pour les actions à fort impact, irréversibles, sensibles ou réglementées, où le coût d'une erreur l'emporte sur la latence de l'examen." }, { "q": "Quelle est la différence entre in-the-loop et on-the-loop ?", "a": "In-the-loop signifie qu'un humain approuve chaque action avant son exécution ; on-the-loop signifie qu'un humain surveille et peut intervenir, mais que le système agit de lui-même par défaut." }, { "q": "Le HITL entre-t-il en conflit avec l'autonomie ?", "a": "Il limite délibérément l'autonomie. De nombreux systèmes commencent par un examen rigoureux et élargissent l'autonomie à mesure que l'évaluation démontre la fiabilité pour une tâche." }, { "q": "Est-ce exigé par la réglementation ?", "a": "La surveillance humaine est une exigence récurrente — par exemple, l'EU AI Act impose une surveillance humaine efficace pour les systèmes d'IA à haut risque." } ] }, "de": { "title": "Was ist das Human-in-the-Loop-Pattern?", "summary": "Human-in-the-Loop (HITL) ist ein Entwurfsmuster, bei dem eine Person die Ausgabe eines KI-Systems überprüft, genehmigt oder korrigiert, bevor sie wirksam wird – insbesondere bei folgenschweren Aktionen. Anstelle von vollständiger Autonomie schlägt der Agent vor und der Mensch entscheidet. Es ist eine der wichtigsten Kontrollmaßnahmen zur Risikominimierung in agentischen Systemen und eine wiederkehrende Anforderung in KI-Governance-Frameworks wie dem EU AI Act und dem NIST AI RMF.", "definition": "Human-in-the-Loop ist ein Muster, bei dem ein Mensch die vorgeschlagene Ausgabe oder Aktion eines KI-Systems überprüft, genehmigt, bearbeitet oder ablehnt, bevor sie ausgeführt wird, wodurch an definierten Entscheidungspunkten menschliches Urteilsvermögen eingebracht wird.", "takeaways": [ "Der Agent schlägt vor; ein Mensch genehmigt, bearbeitet oder lehnt ab.", "Wenden Sie es bei folgenschweren, unumkehrbaren oder sensiblen Aktionen an.", "Es tauscht ein Stück Autonomie und Geschwindigkeit gegen Kontrolle und Vertrauen ein.", "Governance-Frameworks erfordern oft von vornherein eine menschliche Aufsicht (Human Oversight by Design).", "Genehmigungen und Überschreibungen sollten zur Überprüfbarkeit protokolliert werden." ], "context": [ "Vollständige Autonomie ist riskant, wenn Aktionen kostspielig, unumkehrbar oder reguliert sind. HITL führt einen Kontrollpunkt ein: Die KI erledigt die Arbeit und ein Mensch trifft die endgültige Entscheidung. So bleibt der Großteil der Effizienz erhalten, während die Verantwortung bei einer Person liegt.", "Es ist zudem eine Strategie zur Vertrauensbildung und Einführung. Teams beginnen oft mit einer strengen menschlichen Überprüfung und erweitern die Autonomie, sobald die Evaluierung zeigt, dass das System für eine bestimmte Aufgabe zuverlässig ist." ], "architecture": [ "Muster: Human-in-the-Loop (eine Person genehmigt jede folgenschwere Aktion), Human-on-the-Loop (eine Person überwacht und kann eingreifen) und Human-over-the-Loop (regelmäßige Überprüfung und Richtlinienfestlegung). Die richtige Stufe hängt vom Risiko der Aktion ab.", "Die Implementierung erfordert eine Genehmigungsschnittstelle, klaren Kontext für den Prüfer, die Möglichkeit zur Bearbeitung oder Ablehnung, ein Fallback-Verhalten bei Zeitüberschreitung und die Protokollierung jeder Entscheidung für Audits." ], "components": [ "Entscheidungskontrollpunkte", "Genehmigungsschnittstelle", "Prüferkontext", "Bearbeiten / Überschreiben", "Eskalation & Fallback", "Audit-Log" ], "pros": [ "Fängt Fehler ab, bevor sie Schaden anrichten.", "Belässt die Verantwortung bei einem Menschen.", "Unterstützt Compliance- und Governance-Anforderungen.", "Baut Vertrauen auf und ermöglicht schrittweise Autonomie." ], "risks": [ "Erhöht die Latenz und schränkt den Durchsatz ein.", "Abstempeln (Rubber-Stamping): Prüfer genehmigen ohne echte Kontrolle.", "Alarmmüdigkeit beeinträchtigt die Qualität der Aufsicht.", "Eine übermäßige Anwendung hebt den Wert der Automatisierung auf." ], "tools": [ "Genehmigungs- / Workflow-Systeme", "Agenten-Frameworks mit Unterbrechungsschritten (z. B. LangGraph)", "Audit-Protokollierung", "Case-Management-Benutzeroberflächen" ], "examples": [ "Ein Agent entwirft eine Rückerstattung, die ein Mensch genehmigt, bevor sie ausgestellt wird.", "Ein Content-Agent, dessen Ausgabe eine Person vor der Veröffentlichung überprüft.", "Ein Ops-Agent, der vor einer Produktionsänderung für eine Freigabe pausiert." ], "faqs": [ { "q": "Wann sollte man Human-in-the-Loop einsetzen?", "a": "Für Aktionen, die folgenschwer, unumkehrbar, sensibel oder reguliert sind, bei denen die Kosten eines Fehlers die Latenz der Überprüfung überwiegen." }, { "q": "Was ist der Unterschied zwischen In-the-Loop und On-the-Loop?", "a": "In-the-Loop bedeutet, dass ein Mensch jede Aktion genehmigt, bevor sie ausgeführt wird; On-the-Loop bedeutet, dass ein Mensch überwacht und eingreifen kann, das System jedoch standardmäßig selbstständig agiert." }, { "q": "Steht HITL im Widerspruch zur Autonomie?", "a": "Es grenzt die Autonomie bewusst ein. Viele Systeme beginnen mit einer strengen Überprüfung und erweitern die Autonomie, sobald die Evaluierung die Zuverlässigkeit für eine Aufgabe nachweist." }, { "q": "Ist es gesetzlich vorgeschrieben?", "a": "Menschliche Aufsicht ist eine wiederkehrende Anforderung – beispielsweise schreibt der EU AI Act eine wirksame menschliche Aufsicht für hochriskante KI-Systeme vor." } ] }, "ja": { "title": "Human-in-the-Loop パターンとは何ですか？", "summary": "Human-in-the-Loop（HITL）は、特に影響の大きいアクションにおいて、AIシステムの出力が有効になる前に人間がレビュー、承認、または修正を行う設計パターンです。完全な自律性の代わりに、エージェントが提案し、人間が決定します。これはエージェント型システムにおけるリスク管理の主要なコントロールであり、EU AI法やNIST AI RMFなどのAIガバナンスフレームワークで繰り返し求められる要件です。", "definition": "Human-in-the-loopとは、AIシステムが提案した出力やアクションが実行される前に、人間がレビュー、承認、編集、または却下を行うパターンであり、定義された意思決定ポイントに人間の判断を介在させるものです。", "takeaways": [ "エージェントが提案し、人間が承認、編集、または却下します。", "影響が大きく、不可逆的、または機密性の高いアクションに適用します。", "自律性とスピードをある程度犠牲にする代わりに、コントロールと信頼性を得ることができます。", "ガバナンスフレームワークでは、設計段階からの人間による監視（human oversight by design）が求められることがよくあります。", "監査性を確保するため、承認やオーバーライドはログに記録する必要があります。" ], "context": [ "アクションに多大なコストがかかる場合、不可逆的な場合、または規制対象である場合、完全な自律性はリスクを伴います。HITLはチェックポイントを挿入します。AIが作業を行い、人間が最終決定を下すことで、説明責任を人間に留めながら、効率性の大部分を享受できます。", "これは信頼構築と導入促進のための戦略でもあります。チームは多くの場合、厳格な人間によるレビューから開始し、評価によって特定のタスクに対するシステムの信頼性が示されるにつれて、自律性の範囲を広げていきます。" ], "architecture": [ "パターンには、human-in-the-loop（人間が影響の大きい各アクションを承認する）、human-on-the-loop（人間が監視し、介入できる）、human-over-the-loop（定期的なレビューとポリシー設定を行う）があります。適切なレベルは、アクションのリスクによって異なります。", "実装には、承認インターフェース、レビュー担当者向けの明確なコンテキスト、編集または却下を行う機能、タイムアウト時のフォールバック動作、および監査のためのすべての決定のログ記録が必要です。" ], "components": [ "意思決定チェックポイント", "承認インターフェース", "レビュー担当者向けコンテキスト", "編集 / オーバーライド", "エスカレーションとフォールバック", "監査ログ" ], "pros": [ "被害が発生する前にエラーを検知します。", "説明責任を人間に留めます。", "コンプライアンスおよびガバナンスの要件をサポートします。", "信頼を構築し、段階的な自律性を可能にします。" ], "risks": [ "レイテンシを追加し、スループットを制限します。", "形骸化（ラバースタンプ）：レビュー担当者が十分に精査せずに承認してしまうこと。", "アラート疲れにより、監視の質が低下します。", "過剰に適用すると、自動化の価値が損なわれます。" ], "tools": [ "承認 / ワークフローシステム", "割り込みステップを備えたエージェントフレームワーク（例：LangGraph）", "監査ログ記録", "ケース管理UI" ], "examples": [ "エージェントが返金のドラフトを作成し、発行前に人間が承認する。", "コンテンツ作成エージェントの出力を、公開前に人間がレビューする。", "運用エージェントが、本番環境への変更前に承認を得るために一時停止する。" ], "faqs": [ { "q": "どのような場合にhuman-in-the-loopを使用すべきですか？", "a": "エラーのコストがレビューのレイテンシを上回るような、影響が大きく、不可逆的、機密性が高い、または規制対象となるアクションに対して使用します。" }, { "q": "in-the-loopとon-the-loopの違いは何ですか？", "a": "in-the-loopは、アクションが実行される前に人間が毎回承認することを意味します。on-the-loopは、人間が監視し介入することはできますが、デフォルトではシステムが自律的に動作することを意味します。" }, { "q": "HITLは自律性と矛盾しますか？", "a": "意図的に自律性を制限します。多くのシステムは厳格なレビューから開始し、評価によってタスクに対する信頼性が実証されるにつれて、自律性を広げていきます。" }, { "q": "規制によって義務付けられていますか？", "a": "人間による監視は繰り返し求められる要件です。例えば、EU AI法は高リスクAIシステムに対して効果的な人間による監視を義務付けています。" } ] }, "zh": { "title": "什么是人机回环（Human-in-the-Loop）模式？", "summary": "人机回环（Human-in-the-loop, HITL）是一种设计模式，其中由人员在 AI 系统的输出生效之前对其进行审查、批准或纠正——特别是针对高影响力的操作。智能体负责提议，人类负责决策，而不是完全自主。它是管理智能体系统风险的主要控制手段，也是欧盟《AI 法案》和 NIST AI RMF 等 AI 治理框架中的常见要求。", "definition": "人机回环是一种设计模式，其中人类在 AI 系统提议的输出或操作执行之前对其进行审查、批准、编辑或拒绝，从而在定义的决策点引入人类判断。", "takeaways": [ "智能体提议；人类批准、编辑或拒绝。", "将其应用于高影响力、不可逆或敏感的操作。", "它牺牲了一定的自主性和速度，以换取控制力和信任。", "治理框架通常在设计上就要求人类监督。", "批准和覆盖（overrides）操作应予以记录以备审计。" ], "context": [ "当操作成本高昂、不可逆或受到监管时，完全自主是存在风险的。HITL 引入了一个检查点：AI 完成工作，人类做出最终决定，在保留大部分效率的同时，将责任保留在人身上。", "它也是一种建立信任和促进采纳的策略。团队通常从严格的人工审查开始，然后随着评估表明系统在特定任务上可靠，逐步扩大自主权。" ], "architecture": [ "模式：人机回环（human-in-the-loop，由人员批准每个高影响力操作）、人机旁路（human-on-the-loop，由人员进行监控并可进行干预）以及人机监管（human-over-the-loop，定期审查和策略制定）。合适的级别取决于操作的风险。", "实现需要一个审批界面、供审查者参考的清晰上下文、编辑或拒绝的能力、超时后的回退行为，以及记录每个决策以供审计。" ], "components": [ "决策检查点", "审批界面", "审查者上下文", "编辑 / 覆盖", "升级与回退", "审计日志" ], "pros": [ "在错误造成危害之前将其捕获。", "将责任保留在人身上。", "支持合规与治理要求。", "建立信任并实现逐步自主。" ], "risks": [ "增加延迟并限制吞吐量。", "走过场：审查者未经实质性审查就予以批准。", "警报疲劳会降低监督质量。", "过度应用会否定自动化的价值。" ], "tools": [ "审批 / 工作流系统", "具有中断步骤的智能体框架（例如 LangGraph）", "审计日志记录", "案例管理 UI" ], "examples": [ "智能体起草退款，由人工在发放前进行批准。", "内容智能体，其输出在发布前由人工进行审查。", "运维智能体，在进行生产环境变更前暂停以等待签核。" ], "faqs": [ { "q": "什么时候应该使用人机回环？", "a": "适用于高影响力、不可逆、敏感或受监管的操作，在这些操作中，错误的成本超过了审查带来的延迟。" }, { "q": "in-the-loop（人机回环）和 on-the-loop（人机旁路）有什么区别？", "a": "In-the-loop 意味着人类在每个操作执行前进行批准；on-the-loop 意味着人类进行监控并可以干预，但系统默认自主运行。" }, { "q": "HITL 与自主性冲突吗？", "a": "它刻意限制了自主性的边界。许多系统在开始时会进行严格审查，并随着评估证明其在某项任务上的可靠性而逐步扩大自主权。" }, { "q": "监管对此有要求吗？", "a": "人类监督是一项常见要求——例如，欧盟《AI 法案》强制要求对高风险 AI 系统实施有效的人类监督。" } ] } } }, { "slug": "mcp-security", "category": "governance", "updated": "2026-08-22", "version": "1.0", "url": "https://santismm.com/en/knowledge/mcp-security", "api": "https://santismm.com/api/knowledge/mcp-security", "canonical_url": "https://santismm.com/en/knowledge/mcp-security", "api_url": "https://santismm.com/api/knowledge/mcp-security", "evidence": { "evidenceLevel": "production", "confidenceLevel": "high", "sourceType": [ "production_system", "personal_experience", "industry_observation" ] }, "references": [ { "title": "Model Context Protocol — Specification", "url": "https://modelcontextprotocol.io/" }, { "title": "OWASP — Top 10 for LLM Applications", "url": "https://genai.owasp.org/llm-top-10/" }, { "title": "OWASP — LLM01: Prompt Injection", "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/" }, { "title": "MITRE ATLAS — Adversarial Threat Landscape for AI Systems", "url": "https://atlas.mitre.org/" } ], "related": [ "model-context-protocol", "ai-cyberdefense", "agentic-threat-model", "tool-use", "guardrails", "prompt-injection", "harness-engineering" ], "locales": { "en": { "title": "What is MCP Security?", "summary": "MCP security is what stops a Model Context Protocol server from becoming the easiest way into a system. The protocol standardises how agents discover and call tools; it does not decide who may call them, what they may reach, or what happens when a tool description turns hostile. Those decisions live in the server: authentication, origin and transport validation, narrowly scoped tools, rate limits and an audit trail.", "definition": "MCP security is the set of controls applied to a Model Context Protocol server and its clients — authentication and authorisation, origin and transport validation, tool scoping, input and output handling, rate limiting and auditing — so that exposing capabilities to an AI agent does not expose the systems behind them.", "takeaways": [ "MCP standardises the plumbing, not the trust: every server decides its own posture.", "A tool description is untrusted input to the model — it can instruct, and it can change after approval.", "Local stdio servers and remote HTTP servers have different threat models; the dangerous mistakes differ.", "Origin checks and rate limits belong in the server, because clients are not under your control.", "'Read-only' is a property of the implementation, never of the tool's name." ], "context": [ "MCP gives an agent a uniform way to discover and invoke capabilities. That uniformity is both the value and the risk: one client can be pointed at many servers, and each server is a fresh trust decision made — in practice — by whoever pasted a URL into a config file.", "Two deployment shapes dominate. A local stdio server runs with the user's own privileges on their machine: there is no network boundary, so the questions are what it can read and whether it phones home. A remote HTTP server is a public endpoint: the questions become who is calling, from where, how often, and whether a browser can be tricked into calling it on a user's behalf.", "We operate one of each shape for this knowledge base — a public HTTP endpoint and a published stdio package — so the controls below are described as they are implemented rather than as a generic checklist." ], "architecture": [ "Decide the exposure first: public read-only capability, authenticated capability, or local-only. Everything else follows from that answer, and most incidents come from a server that never made it.", "Validate the transport before doing any work. For HTTP servers, check the Origin header against an allowlist and reject browser-initiated cross-site calls before a handler runs — DNS rebinding and CSRF-style abuse both arrive that way.", "Keep the server stateless wherever the protocol allows it. No session store means no session fixation, no cross-request contamination and no state to leak between callers.", "Scope tools narrowly. One tool, one capability, no verbs that change with an argument — a 'query' tool that can also write is a privilege escalation waiting for the right parameter.", "Rate limit per caller and answer with a real 429 and Retry-After. An agent that retries is normal traffic; an agent that retries without limits is a denial-of-service tool pointed at your own backend.", "Log every call with enough shape to reconstruct abuse — tool, outcome, latency, caller identity — and nothing that turns the log itself into the breach.", "Treat every tool result as untrusted content on the way back. A server that proxies external data is an indirect prompt-injection channel by construction." ], "components": [ "Authentication: none for genuinely public read data, a token or OAuth for anything else — with the decision documented, because 'no auth' must be a choice rather than an oversight.", "Origin and host validation for remote servers, derived from measured traffic rather than assumed from a web-app default.", "Per-tool authorisation: what this caller may invoke, not merely whether they may connect.", "Input validation at the tool boundary, with the same rigour as a public API — because that is what it is.", "Output shaping: return the minimum the caller needs; never pass raw upstream payloads straight through.", "Rate limiting and quotas, with headers correct enough that well-behaved clients back off on their own.", "Audit logging and metrics, retained long enough to investigate and aggregated enough to be safe to keep.", "Supply-chain hygiene for the server itself: pinned dependencies, reviewed updates, published provenance so clients can tell they are talking to the server you built." ], "pros": [ "A well-scoped MCP server is a smaller attack surface than the ad-hoc integration it replaces: one protocol, one audit point, one place to revoke.", "Statelessness and narrow tools make the server cheap to reason about — the security review fits on a page.", "Standard errors and rate-limit headers make client behaviour predictable, which is itself a defensive property.", "Because everything crosses one boundary, measurement comes free: abuse and use appear in the same logs and look different." ], "risks": [ "Tool rug pulls: a server that behaves at approval time and changes its tool descriptions later, once the client has stopped asking.", "Over-broad local servers: a stdio server holding the user's filesystem and credentials is a full agent capability with no network boundary to catch it.", "Confused deputy: the server holds credentials the caller does not, so anyone who reaches it inherits its reach.", "Silent public exposure: a remote server deployed with no auth, no origin check and no rate limit is discoverable and free to abuse.", "Injection relay: tool output taken from third-party sources and handed to the model as if it were trusted instruction." ], "tools": [ "The MCP specification and its transport security guidance — the baseline every server should be able to answer against.", "Origin allowlists and CORS configuration applied before application code runs.", "Rate-limiting stores (Redis or equivalent) keyed by a hashed caller identity rather than a raw IP.", "Structured request logs and latency metrics, so abuse and cost are visible in the same view.", "OWASP Top 10 for LLM Applications, for the injection and excessive-agency classes that MCP servers amplify.", "Registry listings and signed publishes, so clients can verify the server they install is the one you shipped." ], "examples": [ "This knowledge base exposes a public, read-only HTTP MCP endpoint. It is stateless by design, so no session can be fixated or replayed; the tools return only published content; and every call is rate limited per hashed caller with a real 429 and Retry-After.", "Before writing an Origin rule for that endpoint we measured its own traffic first: almost every request carried no Origin header at all, none carried null, and every request that did carry one came from this site. The rule that shipped follows the measurement — reject browser-origin calls from anywhere else, allow the header-less agent traffic that is the actual audience — instead of a policy copied from a web-app default.", "The stdio package published for the same knowledge base runs locally with no credentials and no filesystem access, because all it needs is an outbound call to the public endpoint. A local server that needs nothing should be given nothing." ], "faqs": [ { "q": "Does MCP make agents safer or less safe?", "a": "Safer per integration, riskier in aggregate. One protocol means one place to review and revoke — but it also lowers the cost of connecting an agent to another system, and every connection is a new trust decision someone has to make." }, { "q": "Do I need authentication on a read-only server?", "a": "Not necessarily, if the data is genuinely public. You still need rate limiting and an audit trail: public does not mean free, and an unlimited public endpoint is an amplifier pointed at your own infrastructure." }, { "q": "Why check the Origin header if agents do not send one?", "a": "Precisely because they do not. The header-less traffic is the legitimate audience; a request that does carry a foreign Origin is a browser acting on someone else's behalf, which is exactly the case worth rejecting." }, { "q": "What is a tool rug pull, and how do I defend against it?", "a": "A server that presents benign tool descriptions when the user approves it and changes them afterwards. The defences are pinning the server version, re-validating descriptions when they change, and not granting a remote server capabilities you would not grant a code dependency." } ] }, "es": { "title": "¿Qué es la Seguridad en MCP?", "summary": "La seguridad en MCP es lo que impide que un servidor de Model Context Protocol se convierta en la vía más fácil de entrar a un sistema. El protocolo estandariza cómo los agentes descubren e invocan herramientas; no decide quién puede invocarlas, a qué pueden llegar ni qué pasa cuando la descripción de una herramienta se vuelve hostil. Esas decisiones viven en el servidor: autenticación, validación de origen y transporte, herramientas de alcance estrecho, límites de tasa y traza de auditoría.", "definition": "La seguridad en MCP es el conjunto de controles aplicados a un servidor de Model Context Protocol y a sus clientes —autenticación y autorización, validación de origen y transporte, acotación de herramientas, tratamiento de entradas y salidas, límites de tasa y auditoría— para que exponer capacidades a un agente de IA no signifique exponer los sistemas que hay detrás.", "takeaways": [ "MCP estandariza la fontanería, no la confianza: cada servidor decide su propia postura.", "La descripción de una herramienta es entrada no confiable para el modelo: puede instruir y puede cambiar después de haber sido aprobada.", "Los servidores locales por stdio y los remotos por HTTP tienen modelos de amenaza distintos; los errores peligrosos son otros.", "Las comprobaciones de origen y los límites de tasa van en el servidor, porque los clientes no están bajo tu control.", "«Solo lectura» es una propiedad de la implementación, nunca del nombre de la herramienta." ], "context": [ "MCP da al agente una forma uniforme de descubrir e invocar capacidades. Esa uniformidad es a la vez el valor y el riesgo: un mismo cliente puede apuntar a muchos servidores, y cada servidor es una decisión de confianza nueva que en la práctica toma quien pega una URL en un fichero de configuración.", "Dominan dos formas de despliegue. Un servidor local por stdio corre con los privilegios del propio usuario en su máquina: no hay frontera de red, así que las preguntas son qué puede leer y si llama a casa. Un servidor remoto por HTTP es un endpoint público: las preguntas pasan a ser quién llama, desde dónde, con qué frecuencia y si se puede engañar a un navegador para que llame en nombre de un usuario.", "Para esta base de conocimiento operamos una de cada forma —un endpoint HTTP público y un paquete stdio publicado—, así que los controles que siguen se describen tal y como están implementados, no como una lista genérica." ], "architecture": [ "Decide primero la exposición: capacidad pública de solo lectura, capacidad autenticada o solo local. Todo lo demás se deriva de esa respuesta, y la mayoría de incidentes vienen de un servidor que nunca la tomó.", "Valida el transporte antes de hacer trabajo. En servidores HTTP, comprueba la cabecera Origin contra una lista de permitidos y rechaza las llamadas cross-site iniciadas por navegador antes de que corra ningún handler: el DNS rebinding y el abuso tipo CSRF llegan por ahí.", "Mantén el servidor sin estado siempre que el protocolo lo permita. Sin almacén de sesión no hay fijación de sesión, ni contaminación entre peticiones, ni estado que filtrar entre llamantes.", "Acota las herramientas. Una herramienta, una capacidad, sin verbos que cambien según un argumento: una herramienta de «consulta» que además escribe es una escalada de privilegios esperando el parámetro adecuado.", "Limita la tasa por llamante y responde con un 429 real y Retry-After. Un agente que reintenta es tráfico normal; un agente que reintenta sin límite es una herramienta de denegación de servicio apuntando a tu propio backend.", "Registra cada llamada con la forma suficiente para reconstruir un abuso —herramienta, resultado, latencia, identidad del llamante— y nada que convierta el propio log en la brecha.", "Trata todo resultado de herramienta como contenido no confiable en el camino de vuelta. Un servidor que hace de proxy de datos externos es, por construcción, un canal de inyección indirecta." ], "components": [ "Autenticación: ninguna para datos de lectura genuinamente públicos, token u OAuth para cualquier otra cosa, con la decisión documentada, porque «sin auth» tiene que ser una elección y no un descuido.", "Validación de origen y host en servidores remotos, derivada de tráfico medido y no supuesta desde el valor por defecto de una aplicación web.", "Autorización por herramienta: qué puede invocar este llamante, no solo si puede conectarse.", "Validación de entrada en la frontera de la herramienta, con el mismo rigor que en una API pública, porque eso es lo que es.", "Modelado de la salida: devuelve el mínimo que el llamante necesita; nunca dejes pasar payloads crudos de sistemas de arriba.", "Límites de tasa y cuotas, con cabeceras lo bastante correctas como para que los clientes bien educados se retiren solos.", "Logs de auditoría y métricas, retenidos lo suficiente para investigar y agregados lo suficiente para ser seguros de conservar.", "Higiene de cadena de suministro del propio servidor: dependencias fijadas, actualizaciones revisadas y publicación con procedencia, para que el cliente pueda saber que habla con el servidor que construiste." ], "pros": [ "Un servidor MCP bien acotado es una superficie de ataque menor que la integración ad hoc que sustituye: un protocolo, un punto de auditoría, un sitio donde revocar.", "La ausencia de estado y las herramientas estrechas hacen que el servidor sea barato de razonar: la revisión de seguridad cabe en una página.", "Errores estándar y cabeceras de límite de tasa hacen predecible el comportamiento del cliente, lo que ya es en sí una propiedad defensiva.", "Como todo cruza una sola frontera, la medición sale gratis: el abuso y el uso aparecen en los mismos logs y se distinguen." ], "risks": [ "Rug pull de herramientas: un servidor que se comporta en el momento de la aprobación y cambia sus descripciones después, cuando el cliente ya ha dejado de preguntar.", "Servidores locales demasiado amplios: un servidor stdio con el sistema de ficheros y las credenciales del usuario es una capacidad de agente completa sin frontera de red que la detenga.", "Diputado confundido: el servidor tiene credenciales que el llamante no tiene, así que quien llegue a él hereda su alcance.", "Exposición pública silenciosa: un servidor remoto desplegado sin autenticación, sin comprobación de origen y sin límite de tasa es descubrible y gratis de abusar.", "Relé de inyección: salida de herramienta tomada de terceros y entregada al modelo como si fuera instrucción de confianza." ], "tools": [ "La especificación de MCP y su guía de seguridad de transporte: la línea base que todo servidor debería poder responder.", "Listas de origen permitido y configuración de CORS aplicadas antes de que corra el código de aplicación.", "Almacenes de límite de tasa (Redis o equivalente) indexados por una identidad de llamante hasheada en lugar de una IP en claro.", "Logs de petición estructurados y métricas de latencia, para ver abuso y coste en la misma vista.", "OWASP Top 10 para aplicaciones LLM, por las clases de inyección y exceso de agencia que un servidor MCP amplifica.", "Fichas en registros y publicaciones firmadas, para que el cliente pueda verificar que el servidor que instala es el que publicaste." ], "examples": [ "Esta base de conocimiento expone un endpoint MCP HTTP público y de solo lectura. Es sin estado por diseño, así que ninguna sesión puede fijarse ni reproducirse; las herramientas devuelven únicamente contenido publicado; y cada llamada está limitada por llamante hasheado, con un 429 real y Retry-After.", "Antes de escribir la regla de Origin de ese endpoint medimos su propio tráfico: casi ninguna petición traía cabecera Origin, ninguna traía null y todas las que sí la traían venían de este sitio. La regla que se desplegó sigue a la medición —rechazar llamadas con origen de navegador desde cualquier otro sitio y permitir el tráfico de agentes sin cabecera, que es la audiencia real— en lugar de copiar la política por defecto de una aplicación web.", "El paquete stdio publicado para esta misma base de conocimiento corre en local sin credenciales y sin acceso al sistema de ficheros, porque lo único que necesita es una llamada saliente al endpoint público. A un servidor local que no necesita nada, no hay que darle nada." ], "faqs": [ { "q": "¿MCP hace a los agentes más seguros o menos?", "a": "Más seguros por integración, más arriesgados en conjunto. Un solo protocolo significa un solo sitio donde revisar y revocar, pero también abarata conectar un agente a otro sistema, y cada conexión es una decisión de confianza nueva que alguien tiene que tomar." }, { "q": "¿Necesito autenticación en un servidor de solo lectura?", "a": "No necesariamente, si los datos son genuinamente públicos. Lo que sí necesitas es límite de tasa y traza de auditoría: público no significa gratis, y un endpoint público sin límites es un amplificador apuntando a tu propia infraestructura." }, { "q": "¿Por qué comprobar la cabecera Origin si los agentes no la envían?", "a": "Precisamente porque no la envían. El tráfico sin cabecera es la audiencia legítima; una petición que sí trae un Origin ajeno es un navegador actuando en nombre de otra persona, que es justo el caso que conviene rechazar." }, { "q": "¿Qué es un rug pull de herramientas y cómo me defiendo?", "a": "Un servidor que presenta descripciones inocuas cuando el usuario lo aprueba y las cambia después. Las defensas son fijar la versión del servidor, revalidar las descripciones cuando cambian y no conceder a un servidor remoto capacidades que no concederías a una dependencia de código." } ] }, "pt": { "title": "O que é Segurança em MCP?", "summary": "Segurança em MCP é o que impede que um servidor de Model Context Protocol se torne o caminho mais fácil para dentro de um sistema. O protocolo padroniza como agentes descobrem e invocam ferramentas; ele não decide quem pode invocá-las, o que elas alcançam, nem o que acontece quando a descrição de uma ferramenta fica hostil. Essas decisões vivem no servidor: autenticação, validação de origem e transporte, ferramentas de escopo estreito, limites de taxa e trilha de auditoria.", "definition": "Segurança em MCP é o conjunto de controles aplicados a um servidor de Model Context Protocol e a seus clientes — autenticação e autorização, validação de origem e transporte, escopo de ferramentas, tratamento de entradas e saídas, limitação de taxa e auditoria — para que expor capacidades a um agente de IA não signifique expor os sistemas por trás delas.", "takeaways": [ "MCP padroniza o encanamento, não a confiança: cada servidor decide sua própria postura.", "A descrição de uma ferramenta é entrada não confiável para o modelo: ela pode instruir e pode mudar depois de aprovada.", "Servidores locais por stdio e remotos por HTTP têm modelos de ameaça diferentes; os erros perigosos são outros.", "Verificações de origem e limites de taxa ficam no servidor, porque os clientes não estão sob o seu controle.", "“Somente leitura” é uma propriedade da implementação, nunca do nome da ferramenta." ], "context": [ "O MCP dá ao agente uma forma uniforme de descobrir e invocar capacidades. Essa uniformidade é ao mesmo tempo o valor e o risco: um mesmo cliente pode apontar para muitos servidores, e cada servidor é uma decisão de confiança nova, tomada na prática por quem colou uma URL num arquivo de configuração.", "Duas formas de implantação dominam. Um servidor local por stdio roda com os privilégios do próprio usuário na máquina dele: não há fronteira de rede, então as perguntas são o que ele pode ler e se ele liga para casa. Um servidor remoto por HTTP é um endpoint público: as perguntas passam a ser quem chama, de onde, com que frequência e se um navegador pode ser enganado para chamar em nome de um usuário.", "Para esta base de conhecimento operamos uma de cada forma — um endpoint HTTP público e um pacote stdio publicado —, então os controles a seguir são descritos como estão implementados, e não como uma lista genérica." ], "architecture": [ "Decida primeiro a exposição: capacidade pública somente leitura, capacidade autenticada ou apenas local. Todo o resto decorre dessa resposta, e a maioria dos incidentes vem de um servidor que nunca a tomou.", "Valide o transporte antes de fazer trabalho. Em servidores HTTP, verifique o cabeçalho Origin contra uma lista de permitidos e rejeite chamadas cross-site iniciadas por navegador antes de qualquer handler rodar: DNS rebinding e abuso no estilo CSRF chegam por aí.", "Mantenha o servidor sem estado sempre que o protocolo permitir. Sem armazenamento de sessão não há fixação de sessão, nem contaminação entre requisições, nem estado a vazar entre chamadores.", "Restrinja o escopo das ferramentas. Uma ferramenta, uma capacidade, sem verbos que mudam conforme um argumento: uma ferramenta de “consulta” que também escreve é uma escalada de privilégio esperando o parâmetro certo.", "Limite a taxa por chamador e responda com um 429 real e Retry-After. Um agente que tenta de novo é tráfego normal; um agente que tenta sem limite é uma ferramenta de negação de serviço apontada para o seu próprio backend.", "Registre cada chamada com forma suficiente para reconstruir um abuso — ferramenta, resultado, latência, identidade do chamador — e nada que transforme o próprio log na brecha.", "Trate todo resultado de ferramenta como conteúdo não confiável no caminho de volta. Um servidor que faz proxy de dados externos é, por construção, um canal de injeção indireta." ], "components": [ "Autenticação: nenhuma para dados de leitura genuinamente públicos, token ou OAuth para qualquer outra coisa, com a decisão documentada, porque “sem auth” precisa ser uma escolha e não um descuido.", "Validação de origem e host em servidores remotos, derivada de tráfego medido e não presumida a partir do padrão de uma aplicação web.", "Autorização por ferramenta: o que este chamador pode invocar, não apenas se ele pode se conectar.", "Validação de entrada na fronteira da ferramenta, com o mesmo rigor de uma API pública — porque é isso que ela é.", "Modelagem da saída: devolva o mínimo de que o chamador precisa; nunca repasse payloads crus de sistemas a montante.", "Limites de taxa e cotas, com cabeçalhos corretos o bastante para que clientes bem-educados recuem sozinhos.", "Logs de auditoria e métricas, retidos o suficiente para investigar e agregados o suficiente para serem seguros de guardar.", "Higiene de cadeia de suprimentos do próprio servidor: dependências fixadas, atualizações revisadas e publicação com procedência, para que o cliente saiba que está falando com o servidor que você construiu." ], "pros": [ "Um servidor MCP bem delimitado é uma superfície de ataque menor do que a integração ad hoc que substitui: um protocolo, um ponto de auditoria, um lugar para revogar.", "A ausência de estado e as ferramentas estreitas tornam o servidor barato de raciocinar: a revisão de segurança cabe em uma página.", "Erros padronizados e cabeçalhos de limite de taxa tornam o comportamento do cliente previsível, o que já é em si uma propriedade defensiva.", "Como tudo cruza uma única fronteira, a medição sai de graça: abuso e uso aparecem nos mesmos logs e se distinguem." ], "risks": [ "Rug pull de ferramentas: um servidor que se comporta no momento da aprovação e muda suas descrições depois, quando o cliente já parou de perguntar.", "Servidores locais amplos demais: um servidor stdio com o sistema de arquivos e as credenciais do usuário é uma capacidade de agente completa, sem fronteira de rede para contê-la.", "Deputado confuso: o servidor detém credenciais que o chamador não tem, então quem chegar até ele herda o alcance dele.", "Exposição pública silenciosa: um servidor remoto implantado sem autenticação, sem verificação de origem e sem limite de taxa é descobrível e gratuito de abusar.", "Relé de injeção: saída de ferramenta obtida de terceiros e entregue ao modelo como se fosse instrução confiável." ], "tools": [ "A especificação do MCP e sua orientação de segurança de transporte: a linha de base que todo servidor deveria conseguir responder.", "Listas de origem permitida e configuração de CORS aplicadas antes de o código da aplicação rodar.", "Armazenamentos de limite de taxa (Redis ou equivalente) indexados por identidade de chamador com hash, em vez de IP em claro.", "Logs de requisição estruturados e métricas de latência, para ver abuso e custo na mesma visão.", "OWASP Top 10 para aplicações LLM, pelas classes de injeção e excesso de agência que um servidor MCP amplifica.", "Fichas em registries e publicações assinadas, para que o cliente verifique que o servidor instalado é o que você publicou." ], "examples": [ "Esta base de conhecimento expõe um endpoint MCP HTTP público e somente leitura. Ele é sem estado por design, então nenhuma sessão pode ser fixada ou reproduzida; as ferramentas devolvem apenas conteúdo publicado; e cada chamada é limitada por chamador com hash, com um 429 real e Retry-After.", "Antes de escrever a regra de Origin desse endpoint, medimos o tráfego dele: quase nenhuma requisição trazia cabeçalho Origin, nenhuma trazia null e todas as que traziam vinham deste site. A regra publicada segue a medição — rejeitar chamadas com origem de navegador de qualquer outro lugar e permitir o tráfego de agentes sem cabeçalho, que é o público real — em vez de copiar a política padrão de uma aplicação web.", "O pacote stdio publicado para esta mesma base roda localmente sem credenciais e sem acesso ao sistema de arquivos, porque tudo de que precisa é uma chamada de saída ao endpoint público. A um servidor local que não precisa de nada, não se dá nada." ], "faqs": [ { "q": "O MCP torna os agentes mais seguros ou menos seguros?", "a": "Mais seguros por integração, mais arriscados no agregado. Um único protocolo significa um único lugar para revisar e revogar — mas também barateia conectar um agente a outro sistema, e cada conexão é uma decisão de confiança nova que alguém precisa tomar." }, { "q": "Preciso de autenticação em um servidor somente leitura?", "a": "Não necessariamente, se os dados forem genuinamente públicos. Você ainda precisa de limite de taxa e trilha de auditoria: público não significa gratuito, e um endpoint público sem limites é um amplificador apontado para a sua própria infraestrutura." }, { "q": "Por que verificar o cabeçalho Origin se os agentes não o enviam?", "a": "Justamente porque não enviam. O tráfego sem cabeçalho é o público legítimo; uma requisição que traz um Origin alheio é um navegador agindo em nome de outra pessoa, que é exatamente o caso que vale a pena rejeitar." }, { "q": "O que é um rug pull de ferramentas e como me defendo?", "a": "Um servidor que apresenta descrições inofensivas quando o usuário o aprova e as altera depois. As defesas são fixar a versão do servidor, revalidar as descrições quando elas mudam e não conceder a um servidor remoto capacidades que você não concederia a uma dependência de código." } ] }, "fr": { "title": "Qu'est-ce que la sécurité MCP ?", "summary": "La sécurité MCP est ce qui empêche un serveur Model Context Protocol de devenir la porte d'entrée la plus facile dans un système. Le protocole standardise la manière dont les agents découvrent et appellent les outils ; il ne décide pas de qui peut les appeler, de ce qu'ils peuvent atteindre, ni de ce qui se passe lorsqu'une description d'outil devient hostile. Ces décisions incombent au serveur : authentification, validation de l'origine et du transport, outils à portée restreinte, limites de débit et piste d'audit.", "definition": "La sécurité MCP est l'ensemble des contrôles appliqués à un serveur Model Context Protocol et à ses clients — authentification et autorisation, validation de l'origine et du transport, définition de la portée des outils, gestion des entrées et des sorties, limitation du débit et audit — afin que l'exposition de capacités à un agent d'IA n'expose pas les systèmes sous-jacents.", "takeaways": [ "Le MCP standardise la plomberie, pas la confiance : chaque serveur décide de sa propre posture.", "La description d'un outil est une entrée non fiable pour le modèle — elle peut donner des instructions et peut changer après approbation.", "Les serveurs stdio locaux et les serveurs HTTP distants ont des modèles de menace différents ; les erreurs dangereuses diffèrent.", "Les vérifications d'origine et les limites de débit relèvent du serveur, car les clients ne sont pas sous votre contrôle.", "Le 'lecture seule' est une propriété de l'implémentation, jamais du nom de l'outil." ], "context": [ "Le MCP offre à un agent un moyen uniforme de découvrir et d'invoquer des capacités. Cette uniformité constitue à la fois la valeur et le risque : un client peut être orienté vers de nombreux serveurs, et chaque serveur représente une nouvelle décision de confiance prise — en pratique — par quiconque a collé une URL dans un fichier de configuration.", "Deux types de déploiement prédominent. Un serveur stdio local s'exécute avec les propres privilèges de l'utilisateur sur sa machine : il n'y a pas de frontière réseau, les questions portent donc sur ce qu'il peut lire et s'il communique avec l'extérieur. Un serveur HTTP distant est un point de terminaison public : les questions deviennent alors qui appelle, d'où, à quelle fréquence, et si un navigateur peut être trompé pour l'appeler au nom d'un utilisateur.", "Nous exploitons un modèle de chaque type pour cette base de connaissances — un point de terminaison HTTP public et un package stdio publié — de sorte que les contrôles ci-dessous sont décrits tels qu'ils sont implémentés plutôt que sous forme de liste de contrôle générique." ], "architecture": [ "Déterminez d'abord le niveau d'exposition : accès public en lecture seule, accès authentifié ou local uniquement. Tout le reste découle de cette réponse, et la plupart des incidents proviennent d'un serveur qui n'a jamais franchi cette étape.", "Validez le transport avant d'effectuer toute opération. Pour les serveurs HTTP, comparez l'en-tête Origin à une liste d'autorisation et rejetez les appels intersites initiés par le navigateur avant l'exécution d'un gestionnaire — le rebind DNS et les abus de type CSRF surviennent tous deux de cette manière.", "Maintenez le serveur sans état (stateless) partout où le protocole le permet. L'absence de stockage de session élimine la fixation de session, la contamination entre requêtes et la fuite d'état entre les appelants.", "Restreignez strictement la portée des outils. Un outil, une fonctionnalité, pas de verbes qui changent selon un argument — un outil de « requête » qui peut également écrire est une élévation de privilèges qui n'attend que le bon paramètre.", "Limitez le débit par appelant et répondez avec un véritable code 429 et un en-tête Retry-After. Un agent qui réessaie constitue un trafic normal ; un agent qui réessaie sans limite est un outil de déni de service dirigé contre votre propre backend.", "Enregistrez chaque appel avec suffisamment de structure pour reconstituer les abus — outil, résultat, latence, identité de l'appelant — et rien qui ne transforme le journal lui-même en faille de sécurité.", "Traisez chaque résultat d'outil comme du contenu non approuvé lors du retour. Un serveur qui sert de proxy pour des données externes constitue, par construction, un canal d'injection de prompt indirect." ], "components": [ "Authentification : aucune pour les données de lecture véritablement publiques, un jeton ou OAuth pour tout le reste — avec une décision documentée, car l'absence d'authentification doit être un choix et non un oubli.", "Validation de l'origine et de l'hôte pour les serveurs distants, dérivée du trafic mesuré plutôt que supposée à partir des valeurs par défaut d'une application web.", "Autorisation par outil : ce que cet appelant est autorisé à invoquer, et non pas seulement s'il est autorisé à se connecter.", "Validation des entrées à la limite de l'outil, avec la même rigeur que pour une API publique — car c'est exactement ce dont il s'agit.", "Mise en forme des sorties : renvoyez le strict minimum requis par l'appelant ; ne transmettez jamais directement les charges utiles brutes en amont.", "Limitation du débit et quotas, avec des en-têtes suffisamment précis pour que les clients bien configurés ralentissent d'eux-mêmes.", "Journaux d'audit et métriques, conservés suffisamment longtemps pour permettre les investigations et suffisamment agrégés pour être stockés en toute sécurité.", "Hygiène de la chaîne d'approvisionnement pour le serveur lui-même : dépendances figées, mises à jour examinées, provenance publiée afin que les clients puissent vérifier qu'ils communiquent bien avec le serveur que vous avez construit." ], "pros": [ "Un serveur MCP bien délimité présente une surface d'attaque plus restreinte que l'intégration ad hoc qu'il remplace : un seul protocole, un seul point d'audit, un seul endroit pour révoquer les accès.", "L'absence d'état et la spécialisation étroite des outils facilitent l'analyse du serveur — l'évaluation de sécurité tient sur une seule page.", "Les erreurs standardisées et les en-têtes de limitation de débit rendent le comportement des clients prévisible, ce qui constitue en soi une propriété défensive.", "Puisque tout franchit une seule et même frontière, la mesure est immédiate : l'utilisation normale et les abus apparaissent dans les mêmes journaux et se distinguent facilement." ], "risks": [ "Changements de comportement d'outils (« tool rug pulls ») : un serveur qui se comporte correctement au moment de l'approbation et modifie la description de ses outils plus tard, une fois que le client a cessé de vérifier.", "Serveurs locaux trop permissifs : un serveur stdio détenant le système de fichiers et les identifiants de l'utilisateur offre une capacité d'agent complète sans aucune frontière réseau pour l'intercepter.", "Député confus (« confused deputy ») : le serveur détient des identifiants que l'appelant n'a pas, de sorte que quiconque y accède hérite de sa portée.", "Exposition publique silencieuse : un serveur distant déployé sans authentification, sans vérification d'origine et sans limitation de débit est facilement détectable et exposé aux abus.", "Relais d'injection : la sortie d'un outil provenant de sources tierces est transmise au modèle comme s'il s'agissait d'une instruction de confiance." ], "tools": [ "La spécification MCP et ses directives de sécurité de transport — la référence à laquelle chaque serveur devrait pouvoir se conformer.", "Listes d'autorisation d'origine et configuration CORS appliquées avant l'exécution du code de l'application.", "Stockages de limitation de débit (Redis ou équivalent) indexés par un hachage de l'identité de l'appelant plutôt que par une adresse IP brute.", "Journaux de requêtes structurés et métriques de latence, afin que les abus et les coûts soient visibles dans la même vue.", "Le Top 10 OWASP pour les applications LLM, pour les catégories d'injection et d'agentivité excessive que les serveurs MCP amplifient.", "Inscriptions au registre et publications signées, afin que les clients puissent vérifier que le serveur qu'ils installent est bien celui que vous avez livré." ], "examples": [ "Cette base de connaissances expose un point de terminaison HTTP MCP public en lecture seule. Elle est sans état par conception, de sorte qu'aucune session ne peut être fixée ou rejouée ; les outils ne renvoient que du contenu publié ; et chaque appel est limité en débit par appelant haché avec un véritable code 429 et un en-tête Retry-After.", "Avant d'écrire une règle d'origine (Origin) pour ce point de terminaison, nous avons d'abord mesuré son propre trafic : presque toutes les requêtes ne comportaient aucun en-tête Origin, aucune ne comportait la valeur null, et chaque requête qui en comportait un provenait de ce site. La règle déployée suit cette mesure — rejeter les appels provenant de navigateurs tiers, autoriser le trafic d'agents sans en-tête qui constitue l'audience réelle — plutôt que d'appliquer une politique copiée par défaut depuis une application web.", "Le package stdio publié pour cette même base de connaissances s'exécute localement sans identifiants ni accès au système de fichiers, car il n'a besoin que d'un appel sortant vers le point de terminaison public. Un serveur local qui n'a besoin de rien ne doit rien recevoir." ], "faqs": [ { "q": "Le protocole MCP rend-il les agents plus ou moins sûrs ?", "a": "Plus sûr par intégration, plus risqué globalement. Un seul protocole signifie un seul endroit pour examiner et révoquer les accès — mais cela réduit également le coût de connexion d'un agent à un autre système, et chaque connexion représente une nouvelle décision de confiance à prendre." }, { "q": "Ai-je besoin d'une authentification sur un serveur en lecture seule ?", "a": "Pas nécessairement, si les données sont véritablement publiques. Vous avez tout de même besoin d'une limitation de débit et d'une piste d'audit : public ne signifie pas gratuit, et un point de terminaison public non limité est un amplificateur dirigé contre votre propre infrastructure." }, { "q": "Pourquoi vérifier l'en-tête Origin si les agents n'en envoient pas ?", "a": "Précisément parce qu'ils n'en envoient pas. Le trafic sans en-tête constitue l'audience légitime ; une requête qui comporte une origine (Origin) étrangère provient d'un navigateur agissant pour le compte de quelqu'un d'autre, ce qui est exactement le cas qu'il convient de rejeter." }, { "q": "Qu'est-ce qu'un changement de comportement d'outil (« tool rug pull ») et comment s'en prémunir ?", "a": "Il s'agit d'un serveur qui présente des descriptions d'outils inoffensives lorsque l'utilisateur l'approuve, puis les modifie par la suite. Les défenses consistent à figer la version du serveur, à revalider les descriptions lorsqu'elles changent et à ne pas accorder à un serveur distant des capacités que vous n'accorderiez pas à une dépendance de code." } ] }, "de": { "title": "Was ist MCP-Sicherheit?", "summary": "MCP-Sicherheit verhindert, dass ein Model Context Protocol-Server zum einfachsten Einfallstor in ein System wird. Das Protokoll standardisiert, wie Agenten Tools erkennen und aufrufen; es entscheidet nicht, wer sie aufrufen darf, was sie erreichen können oder was passiert, wenn eine Tool-Beschreibung bösartig wird. Diese Entscheidungen liegen beim Server: Authentifizierung, Herkunfts- und Transportvalidierung, eng eingegrenzte Tools, Ratenbegrenzungen (Rate Limits) und ein Audit-Trail.", "definition": "MCP-Sicherheit ist die Gesamtheit der Kontrollmaßnahmen, die auf einen Model Context Protocol-Server und seine Clients angewendet werden – Authentifizierung und Autorisierung, Herkunfts- und Transportvalidierung, Tool-Scoping, Eingabe- und Ausgabeverarbeitung, Ratenbegrenzung und Auditierung –, damit die Bereitstellung von Funktionen für einen KI-Agenten nicht die dahinter liegenden Systeme gefährdet.", "takeaways": [ "MCP standardisiert die Infrastruktur, nicht das Vertrauen: Jeder Server bestimmt seine eigene Sicherheitsstruktur.", "Eine Tool-Beschreibung ist eine nicht vertrauenswürdige Eingabe für das Modell – sie kann Anweisungen enthalten und sich nach der Genehmigung ändern.", "Lokale stdio-Server und Remote-HTTP-Server haben unterschiedliche Bedrohungsmodelle; die gefährlichen Fehler unterscheiden sich.", "Herkunftsprüfungen (Origin Checks) und Ratenbegrenzungen gehören in den Server, da Clients nicht unter Ihrer Kontrolle stehen.", "„Read-only“ ist eine Eigenschaft der Implementierung, niemals des Tool-Namens." ], "context": [ "MCP bietet einem Agenten eine einheitliche Möglichkeit, Funktionen zu erkennen und aufzurufen. Diese Einheitlichkeit ist sowohl der Nutzen als auch das Risiko: Ein Client kann auf viele Server verweisen, und jeder Server erfordert eine neue Vertrauensentscheidung, die in der Praxis von der Person getroffen wird, die eine URL in eine Konfigurationsdatei kopiert hat.", "Zwei Bereitstellungsformen dominieren. Ein lokaler stdio-Server läuft mit den eigenen Rechten des Benutzers auf dessen Rechner: Es gibt keine Netzwerkgrenze, daher stellt sich die Frage, was er lesen kann und ob er Daten nach Hause sendet. Ein Remote-HTTP-Server ist ein öffentlicher Endpunkt: Hier stellt sich die Frage, wer von wo aus wie oft aufruft und ob ein Browser dazu verleitet werden kann, ihn im Namen eines Benutzers aufzurufen.", "Wir betreiben für diese Wissensdatenbank jeweils eine dieser Formen – einen öffentlichen HTTP-Endpunkt und ein veröffentlichtes stdio-Paket –, sodass die folgenden Kontrollmaßnahmen so beschrieben werden, wie sie implementiert sind, und nicht als generische Checkliste." ], "architecture": [ "Entscheiden Sie zuerst über die Freigabe: öffentlich lesbar, authentifiziert oder rein lokal. Alles andere ergibt sich aus dieser Antwort, und die meisten Vorfälle resultieren aus einem Server, der diesen Schritt nie geschafft hat.", "Validieren Sie den Transportweg, bevor Sie irgendwelche Aktionen ausführen. Überprüfen Sie bei HTTP-Servern den Origin-Header gegen eine Allowlist und weisen Sie vom Browser initiierte Cross-Site-Aufrufe ab, bevor ein Handler ausgeführt wird – DNS-Rebinding und CSRF-artiger Missbrauch erfolgen beide auf diesem Weg.", "Halten Sie den Server zustandslos, wo immer das Protokoll es zulässt. Kein Session-Store bedeutet keine Session-Fixation, keine Kontamination zwischen Anfragen und kein Zustand, der zwischen Aufrufern offengelegt werden kann.", "Grenzen Sie Tools eng ein. Ein Tool, eine Funktion, keine Verben, die sich mit einem Argument ändern – ein „query“-Tool, das auch schreiben kann, ist eine Privilege Escalation, die nur auf den richtigen Parameter wartet.", "Implementieren Sie ein Rate Limiting pro Aufrufer und antworten Sie mit einem echten 429 und Retry-After. Ein Agent, der es erneut versucht, ist normaler Traffic; ein Agent, der unbegrenzt fehlschlägt und es erneut versucht, ist ein Denial-of-Service-Tool, das auf Ihr eigenes Backend gerichtet ist.", "Protokollieren Sie jeden Aufruf mit ausreichend Struktur, um Missbrauch zu rekonstruieren – Tool, Ergebnis, Latenz, Identität des Aufrufers – und ohne Daten, die das Log selbst zu einer Sicherheitslücke machen.", "Behandeln Sie jedes Tool-Ergebnis auf dem Rückweg als nicht vertrauenswürdigen Inhalt. Ein Server, der externe Daten weiterleitet, ist konstruktionsbedingt ein Kanal für indirekte Prompt-Injections." ], "components": [ "Authentifizierung: Keine für wirklich öffentlich lesbare Daten, ein Token oder OAuth für alles andere – wobei diese Entscheidung dokumentiert sein muss, da „keine Authentifizierung“ eine bewusste Entscheidung und kein Versehen sein darf.", "Origin- und Host-Validierung für Remote-Server, abgeleitet aus gemessenem Traffic statt angenommen aus einem Web-App-Standardwert.", "Autorisierung pro Tool: Was dieser Aufrufer ausführen darf, nicht nur, ob er sich verbinden darf.", "Eingabevalidierung an der Tool-Grenze mit derselben Strenge wie bei einer öffentlichen API – denn genau das ist es.", "Ausgabe-Shaping: Geben Sie nur das Minimum zurück, das der Aufrufer benötigt; leiten Sie niemals rohe Upstream-Payloads direkt durch.", "Rate Limiting und Quotas, mit ausreichend korrekten Headern, sodass sich gut verhaltende Clients von selbst zurückziehen.", "Audit-Protokollierung und Metriken, die lange genug für Untersuchungen aufbewahrt und ausreichend aggregiert werden, um eine sichere Speicherung zu gewährleisten.", "Supply-Chain-Hygiene für den Server selbst: gepinnte Abhängigkeiten, überprüfte Updates, veröffentlichte Provenienz, damit Clients erkennen können, dass sie mit dem von Ihnen entwickelten Server kommunizieren." ], "pros": [ "Ein gut eingegrenzter MCP-Server bietet eine kleinere Angriffsfläche als die Ad-hoc-Integration, die er ersetzt: ein Protokoll, ein Audit-Punkt, eine Stelle zum Widerrufen.", "Zustandslosigkeit und eng eingegrenzte Tools machen den Server leicht verständlich – die Sicherheitsüberprüfung passt auf eine einzige Seite.", "Standardfehler und Rate-Limit-Header machen das Client-Verhalten vorhersagbar, was an sich schon eine defensive Eigenschaft ist.", "Da alles über eine einzige Grenze läuft, ist die Messung quasi kostenlos: Missbrauch und normale Nutzung erscheinen in denselben Logs und sehen unterschiedlich aus." ], "risks": [ "Tool Rug Pulls: Ein Server, der sich zum Zeitpunkt der Freigabe ordnungsgemäß verhält und seine Tool-Beschreibungen später ändert, sobald der Client nicht mehr nachfragt.", "Zu weit gefasste lokale Server: Ein stdio-Server, der Zugriff auf das Dateisystem und die Anmeldedaten des Benutzers hat, stellt eine vollständige Agenten-Funktion dar, ohne dass eine Netzwerkgrenze dies abfangen könnte.", "Confused Deputy: Der Server besitzt Anmeldedaten, die der Aufrufer nicht hat, sodass jeder, der ihn erreicht, dessen Berechtigungen erbt.", "Stille öffentliche Freigabe: Ein Remote-Server, der ohne Authentifizierung, Origin-Prüfung und Rate Limiting bereitgestellt wird, ist leicht auffindbar und kann ungehindert missbraucht werden.", "Injection-Relay: Tool-Ausgaben, die aus Drittquellen stammen und an das Modell übergeben werden, als handele es sich um vertrauenswürdige Anweisungen." ], "tools": [ "Die MCP-Spezifikation und ihre Richtlinien zur Transportsicherheit – die Baseline, an der sich jeder Server messen lassen sollte.", "Origin-Allowlists und CORS-Konfigurationen, die angewendet werden, bevor der Anwendungscode ausgeführt wird.", "Rate-Limiting-Speicher (Redis oder Äquivalent), die über eine gehashte Identität des Aufrufers statt über eine rohe IP-Adresse indiziert werden.", "Strukturierte Anfrage-Logs und Latenzmetriken, sodass Missbrauch und Kosten in derselben Ansicht sichtbar sind.", "OWASP Top 10 für LLM-Anwendungen, für die Kategorien Injection und Excessive Agency, die durch MCP-Server verstärkt werden.", "Registry-Einträge und signierte Veröffentlichungen, damit Clients überprüfen können, ob der installierte Server dem von Ihnen bereitgestellten entspricht." ], "examples": [ "Diese Knowledge Base stellt einen öffentlichen, schreibgeschützten HTTP-MCP-Endpunkt bereit. Er ist standardmäßig zustandslos, sodass keine Session fixiert oder wiederholt werden kann; die Tools geben nur veröffentlichte Inhalte zurück; und jeder Aufruf ist pro gehashtem Aufrufer mit einem echten 429 und Retry-After ratenbegrenzt.", "Bevor wir eine Origin-Regel für diesen Endpunkt definiert haben, haben wir zuerst dessen Traffic gemessen: Fast jede Anfrage enthielt überhaupt keinen Origin-Header, keine enthielt null, und jede Anfrage, die einen enthielt, stammte von dieser Website. Die implementierte Regel folgt dieser Messung – sie weist Browser-Origin-Aufrufe von überall sonst ab und lässt den headerlosen Agenten-Traffic zu, der die eigentliche Zielgruppe darstellt – anstatt eine Richtlinie aus einem Web-App-Standardwert zu kopieren.", "Das für dieselbe Knowledge Base veröffentlichte stdio-Paket läuft lokal ohne Anmeldedaten und ohne Zugriff auf das Dateisystem, da es lediglich einen ausgehenden Aufruf an den öffentlichen Endpunkt benötigt. Einem lokalen Server, der nichts benötigt, sollte auch nichts gegeben werden." ], "faqs": [ { "q": "Macht MCP Agenten sicherer oder unsicherer?", "a": "Sicherer pro Integration, riskanter in der Gesamtheit. Ein einziges Protokoll bedeutet eine einzige Stelle für Überprüfungen und Widerrufe – aber es senkt auch die Hürde, einen Agenten mit einem anderen System zu verbinden, und jede Verbindung ist eine neue Vertrauensentscheidung, die jemand treffen muss." }, { "q": "Benötige ich eine Authentifizierung für einen schreibgeschützten Server?", "a": "Nicht zwingend, wenn die Daten wirklich öffentlich sind. Sie benötigen dennoch ein Rate Limiting und einen Audit-Trail: Öffentlich bedeutet nicht kostenlos, und ein unbegrenzter öffentlicher Endpunkt ist ein Verstärker, der auf Ihre eigene Infrastruktur gerichtet ist." }, { "q": "Warum sollte man den Origin-Header prüfen, wenn Agenten keinen senden?", "a": "Genau deshalb. Der headerlose Traffic ist die legitime Zielgruppe; eine Anfrage, die einen fremden Origin enthält, ist ein Browser, der im Namen eines Dritten handelt – und genau das ist der Fall, den es abzuweisen gilt." }, { "q": "Was ist ein Tool Rug Pull und wie schütze ich mich davor?", "a": "Ein Server, der harmlose Tool-Beschreibungen anzeigt, wenn der Benutzer ihn freigibt, und diese im Nachhinein ändert. Die Schutzmaßnahmen bestehen darin, die Serverversion zu pinnen, Beschreibungen bei Änderungen neu zu validieren und einem Remote-Server keine Berechtigungen zu erteilen, die Sie nicht auch einer Code-Abhängigkeit gewähren würden." } ] }, "ja": { "title": "MCPセキュリティとは何ですか？", "summary": "MCPセキュリティとは、Model Context Protocolサーバーがシステムへの最も容易な侵入経路になるのを防ぐためのものです。このプロトコルは、エージェントがツールを検出して呼び出す方法を標準化しますが、誰がツールを呼び出せるか、ツールがどこにアクセスできるか、あるいはツールの説明が有害なものに変化した場合に何が起こるかまでは決定しません。これらの決定は、認証、オリジンおよびトランスポートの検証、厳密にスコープ定義されたツール、レート制限、監査トレールなど、サーバー側で行われます。", "definition": "MCPセキュリティとは、AIエージェントに機能を公開してもその背後にあるシステムが公開されないように、Model Context Protocolサーバーとそのクライアントに適用される一連のコントロール（認証と認可、オリジンとトランスポートの検証、ツールのスコープ定義、入力と出力の処理、レート制限、監査など）のことです。", "takeaways": [ "MCPは配管（仕組み）を標準化するのであって、信頼を標準化するわけではありません。各サーバーが独自のセキュリティ姿勢を決定します。", "ツールの説明はモデルに対する信頼できない入力です。指示を含むことがあり、承認後に変更される可能性もあります。", "ローカルのstdioサーバーとリモートのHTTPサーバーでは脅威モデルが異なり、発生しうる危険なミスも異なります。", "クライアントは管理下にはないため、オリジンチェックとレート制限はサーバー側で行う必要があります。", "「読み取り専用」は実装の属性であり、ツールの名前によって保証されるものではありません。" ], "context": [ "MCPは、エージェントに機能を検出して呼び出すための統一された方法を提供します。その統一性は価値であると同時にリスクでもあります。1つのクライアントを多くのサーバーに向けることができ、各サーバーは、実際には設定ファイルにURLを貼り付けた人物によって、その都度新たな信頼の決定が下されることになります。", "主に2つのデプロイ形態があります。ローカルのstdioサーバーは、ユーザー自身のマシン上でそのユーザーの権限で実行されます。ネットワーク境界がないため、問題となるのはそれが何を読み取れるか、そして外部に通信（phone home）するかどうかです。リモートのHTTPサーバーはパブリックなエンドポイントです。問題となるのは、誰が、どこから、どのくらいの頻度で呼び出しているか、そしてブラウザが騙されてユーザーの代わりにそれを呼び出すように仕向けられていないか、ということです。", "このナレッジベースでは、パブリックHTTPエンドポイントと公開されたstdioパッケージという、これら両方の形態を1つずつ運用しています。そのため、以下のコントロールは一般的なチェックリストとしてではなく、実際に実装されている通りに説明されています。" ], "architecture": [ "まず公開範囲を決定します。パブリックな読み取り専用機能、認証が必要な機能、またはローカル専用機能のいずれかです。その他すべての設計はその決定に従うものであり、ほとんどのインシデントは、その決定がなされなかったサーバーから発生しています。", "処理を実行する前にトランスポートを検証します。HTTPサーバーの場合、ハンドラーが実行される前にOriginヘッダーを許可リストと照合し、ブラウザ起点のクロスサイト呼び出しを拒否します。DNSリバインディングやCSRF型の不正利用は、いずれもこの経路から発生するためです。", "プロトコルが許す限り、サーバーをステートレスに保ちます。セッションストアを持たないことは、セッション固定化攻撃、リクエスト間の汚染、および呼び出し元間での状態の漏洩が発生しないことを意味します。", "ツールのスコープを狭く限定します。1つのツールに1つの機能を持たせ、引数によって動作が変わる動詞は避けます。書き込みも実行できる「query」ツールは、適切なパラメータが渡されるのを待っている権限昇格の脆弱性に他なりません。", "呼び出し元ごとにレート制限を適用し、実際の429ステータスコードとRetry-Afterヘッダーで応答します。制限に従って再試行するエージェントは通常のトラフィックですが、制限なしに再試行を繰り返すエージェントは、自社のバックエンドに向けられたサービス拒否（DoS）ツールと化します。", "不正利用を再構成できる十分な情報（ツール、結果、レイテンシ、呼び出し元の識別情報）を含めてすべての呼び出しをログに記録し、ログ自体が情報漏洩の要因にならないようにします。", "返されるすべてのツールの実行結果を、信頼できないコンテンツとして扱います。外部データをプロキシするサーバーは、その構造上、間接的なプロンプトインジェクションの経路となります。" ], "components": [ "認証：完全に公開された読み取りデータには不要、それ以外にはトークンまたはOAuthを使用します。また、その決定を文書化してください。「認証なし」は見落としではなく、意図的な選択である必要があります。", "リモートサーバーに対するOriginおよびホストの検証。Webアプリケーションのデフォルト設定を想定するのではなく、測定された実際のトラフィックに基づいて設定します。", "ツールごとの認可：単に接続可能かだけでなく、この呼び出し元が何を呼び出すことを許可されているかを制御します。", "ツールの境界における入力検証。公開APIと同等の厳格さで実施します。なぜなら、それが実質的に公開APIそのものだからです。", "出力のシェーピング：呼び出し元が必要とする最小限の情報のみを返します。アップストリームからの生のペイロードをそのまま通過させてはなりません。", "レート制限とクォータ。適切なクライアントが自律的にバックオフできるように、正確なヘッダーを返します。", "監査ログとメトリクス。調査に十分な期間保持し、安全に保管できるように適切に集約します。", "サーバー自体のサプライチェーンの健全性：依存関係の固定、更新内容のレビュー、プロベナンス（来歴）の公開により、クライアントが自身で構築したサーバーと通信していることを確認できるようにします。" ], "pros": [ "適切にスコープが定義されたMCPサーバーは、それが置き換えるアドホックな統合よりも攻撃対象領域が小さくなります。1つのプロトコル、1つの監査ポイント、1つの取り消し場所で済みます。", "ステートレス性と限定されたツールにより、サーバーの動作把握が容易になります。セキュリティレビューは1ページに収まる規模になります。", "標準的なエラーとレート制限ヘッダーにより、クライアントの動作が予測可能になります。これはそれ自体が防御的な特性です。", "すべてが単一の境界を通過するため、測定が容易になります。不正利用と通常の利用が同じログに記録され、明確に区別できます。" ], "risks": [ "ツールのラグプル（梯子外し）：承認時には正常に動作し、クライアントが確認を求めてこなくなった後で、ツールの説明を後から変更するサーバー。", "スコープが広すぎるローカルサーバー：ユーザーのファイルシステムや認証情報を保持するstdioサーバーは、それを捕捉するネットワーク境界がないため、エージェントの全権限を持つことになります。", "混乱した代理（Confused Deputy）：サーバーが呼び出し元の持たない認証情報を保持しているため、サーバーにアクセスできるすべてのユーザーがその権限を引き継いでしまいます。", "暗黙的なパブリック公開：認証、Originチェック、レート制限なしでデプロイされたリモートサーバーは、容易に発見され、自由に不正利用されてしまいます。", "インジェクションの中継：サードパーティのソースから取得したツールの出力を、信頼できる指示であるかのようにモデルに渡してしまうこと。" ], "tools": [ "MCP仕様およびそのトランスポートセキュリティガイダンス。すべてのサーバーが準拠すべき基準です。", "アプリケーションコードが実行される前に適用されるOrigin許可リストとCORS設定。", "生のIPアドレスではなく、ハッシュ化された呼び出し元の識別情報をキーとするレート制限ストア（Redisまたは同等品）。", "構造化されたリクエストログとレイテンシメトリクス。不正利用とコストを同じビューで可視化できます。", "OWASP Top 10 for LLM Applications。MCPサーバーが助長するインジェクションや過剰なエージェンシー（Excessive Agency）のカテゴリに対応します。", "レジストリへの登録と署名付き公開。クライアントがインストールするサーバーが、提供されたものであることを検証できるようにします。" ], "examples": [ "このナレッジベースは、パブリックな読み取り専用のHTTP MCPエンドポイントを公開しています。設計上ステートレスであるため、セッションの固定化やリプレイは発生しません。ツールは公開されたコンテンツのみを返し、すべての呼び出しはハッシュ化された呼び出し元ごとに、実際の429ステータスコードとRetry-Afterヘッダーを用いてレート制限されます。", "そのエンドポイントのOriginルールを作成する前に、まず実際のトラフィックを測定しました。ほぼすべてのリクエストにOriginヘッダーが全く含まれておらず、nullを含むものはなく、ヘッダーが含まれていたリクエストはすべてこのサイトからのものでした。適用されたルールはこの測定結果に従っており、Webアプリケーションのデフォルト設定をコピーするのではなく、他の場所からのブラウザ起点の呼び出しを拒否し、実際のターゲットであるヘッダーなしのエージェントトラフィックを許可しています。", "同じナレッジベース向けに公開されているstdioパッケージは、パブリックエンドポイントへのアウトバウンド呼び出しのみを必要とするため、認証情報やファイルシステムへのアクセス権なしでローカルに実行されます。何も必要としないローカルサーバーには、何も与えるべきではありません。" ], "faqs": [ { "q": "MCPはエージェントの安全性を高めますか、それとも低下させますか？", "a": "個々の統合においては安全性が高まりますが、全体としてはリスクが高まります。1つのプロトコルに統合されることで、レビューや取り消しを行う場所が1つにまとまります。しかし、エージェントを別のシステムに接続するコストも下がるため、接続するたびに新たな信頼の決定を迫られることになります。" }, { "q": "読み取り専用サーバーに認証は必要ですか？", "a": "データが完全に公開されているのであれば、必ずしも必要ではありません。ただし、レート制限と監査証跡は依然として必要です。公開されているからといって無料（無制限）で利用できるわけではなく、制限のないパブリックエンドポイントは、自社のインフラに向けられた増幅器となってしまいます。" }, { "q": "エージェントがOriginヘッダーを送信しないのであれば、なぜそれをチェックするのですか？", "a": "まさに送信しないからです。ヘッダーのないトラフィックこそが正当な対象であり、外部のOriginを持つリクエストは、第三者に代わって動作しているブラウザによるものであるため、まさに拒否すべきケースに該当します。" }, { "q": "ツールのラグプル（梯子外し）とは何ですか？また、どのように防御すればよいですか？", "a": "ユーザーが承認した時点では無害なツールの説明を提示し、その後で説明を変更するサーバーのことです。防御策としては、サーバーのバージョンを固定すること、説明が変更されたときに再検証すること、そしてコードの依存関係に付与しないような権限をリモートサーバーに付与しないことが挙げられます。" } ] }, "zh": { "title": "什么是 MCP 安全？", "summary": "MCP 安全是防止 Model Context Protocol（模型上下文协议）服务器成为进入系统最便捷通道的关键。该协议规范了智能体如何发现和调用工具；但它并不决定谁可以调用它们、它们可以访问什么，或者当工具描述变得具有敌意时会发生什么。这些决策存在于服务器中：身份验证、来源和传输验证、严格限制范围的工具、速率限制以及审计追踪。", "definition": "MCP 安全是应用于 Model Context Protocol 服务器及其客户端的一组控制措施——包括身份验证和授权、来源和传输验证、工具范围限定、输入和输出处理、速率限制以及审计——从而确保向 AI 智能体开放能力不会暴露其背后的系统。", "takeaways": [ "MCP 规范的是管道，而不是信任：每个服务器都决定自己的安全态势。", "工具描述对模型而言是不可信的输入——它可以包含指令，并且在批准后可能会发生变化。", "本地 stdio 服务器和远程 HTTP 服务器具有不同的威胁模型；其危险的错误也各不相同。", "来源检查和速率限制属于服务器端职责，因为客户端并不在您的控制之下。", "“只读”是实现的一种属性，绝非工具名称所能决定。" ], "context": [ "MCP 为智能体提供了一种统一的方式来发现和调用能力。这种统一性既是价值所在，也是风险所在：一个客户端可以指向多个服务器，而每个服务器都是一个全新的信任决策——在实践中，这往往是由将 URL 粘贴到配置文件中的人做出的。", "主要存在两种部署形式。本地 stdio 服务器在用户的机器上以用户自身的权限运行：没有网络边界，因此问题在于它可以读取什么以及它是否会向外发送数据。远程 HTTP 服务器是一个公共端点：问题变成了谁在调用、从哪里调用、调用频率如何，以及是否可以诱骗浏览器代表用户调用它。", "我们为此知识库运营着这两种形式的实例——一个公共 HTTP 端点和一个已发布的 stdio 包——因此下面描述的控制措施是基于其实际实现方式，而非通用的检查清单。" ], "architecture": [ "首先确定暴露级别：公开只读能力、经过身份验证的能力，还是仅限本地。其他所有设计都取决于这个决定，而大多数安全事件都源于那些本不该暴露的服务器。", "在执行任何操作之前先验证传输。对于 HTTP 服务器，在处理程序运行之前，根据白名单检查 Origin 标头并拒绝浏览器发起的跨站调用——DNS 重绑定和 CSRF 类型的滥用都是通过这种方式进行的。", "只要协议允许，就保持服务器无状态。没有会话存储意味着没有会话固定、没有跨请求污染，也没有调用者之间泄露状态的风险。", "严格限制工具的作用域。一个工具，一种能力，不要使用会随参数改变而改变的动词——一个同时支持写入的 'query' 工具，随时可能因为一个特定的参数而导致权限提升。", "针对每个调用者进行速率限制，并返回真实的 429 状态码和 Retry-After 标头。会进行重试的智能体（agent）是正常流量；而无限制重试的智能体则是针对您自己后端的拒绝服务（DoS）工具。", "记录每一次调用，并保留足够的信息以重建滥用场景——工具、结果、延迟、调用者身份——且不要记录任何可能使日志本身成为泄露源的信息。", "在返回过程中，将每个工具的结果都视为不可信内容。从设计上讲，代理外部数据的服务器就是一个间接提示词注入（prompt-injection）通道。" ], "components": [ "身份验证：对于真正的公开只读数据，无需验证；对于其他任何数据，使用令牌（token）或 OAuth——并且必须记录这一决定，因为“无验证”必须是一种主动选择，而不是疏忽。", "针对远程服务器的 Origin 和主机验证，应基于实际测量的流量，而不是假定使用 Web 应用的默认设置。", "针对每个工具的授权：明确该调用者可以调用什么，而不仅仅是他们是否可以连接。", "在工具边界进行输入验证，其严格程度应与公开 API 相同——因为它的本质就是公开 API。", "输出整形：仅返回调用者所需的最小内容；绝不直接透传原始的上游负载。", "速率限制和配额，并提供足够准确的标头，以便行为良好的客户端能够自动退避。", "审计日志和指标，保留时间应足够长以便于调查，且聚合度应足够高以确保安全保存。", "服务器自身的供应链卫生：固定依赖项、审查更新、发布来源证明，以便客户端能够确认它们正在与您构建的服务器进行通信。" ], "pros": [ "与它所替代的临时集成相比，一个作用域划分合理的 MCP 服务器具有更小的攻击面：统一的协议、统一的审计点、统一的撤销位置。", "无状态和单一职责的工具使得服务器易于推理——安全审查报告一页纸就能写完。", "标准的错误和速率限制标头使客户端行为变得可预测，这本身就是一种防御性特征。", "因为所有内容都跨越同一个边界，所以测量是顺理成章的：滥用行为和正常使用会出现在相同的日志中，且特征明显不同。" ], "risks": [ "工具“抽毯子”（rug pulls）：服务器在审批时表现正常，但在客户端停止询问后更改其工具描述。", "作用域过宽的本地服务器：持有用户文件系统和凭据的 stdio 服务器具有完整的智能体能力，且没有网络边界来拦截它。", "混淆代理（confused deputy）：服务器持有调用者不具备的凭据，因此任何访问该服务器的人都会继承其访问权限。", "隐蔽的公开暴露：部署时没有身份验证、没有 Origin 检查且没有速率限制的远程服务器很容易被发现并被随意滥用。", "注入中继：从第三方源获取工具输出，并将其作为可信指令传递给模型。" ], "tools": [ "MCP 规范及其传输安全指南——每个服务器都应该能够对照并满足的基线要求。", "在应用代码运行之前应用的 Origin 白名单和 CORS 配置。", "速率限制存储（Redis 或同等工具），以哈希处理后的调用者身份而非原始 IP 作为键。", "结构化请求日志和延迟指标，以便在同一视图中直观查看滥用情况和成本。", "针对 LLM 应用的 OWASP Top 10，用于应对 MCP 服务器会放大的一系列注入和过度授权（excessive agency）问题。", "注册表列表和签名发布，以便客户端可以验证它们安装的服务器就是您发布的那个。" ], "examples": [ "该知识库暴露了一个公开的、只读的 HTTP MCP 端点。它在设计上是无状态的，因此无法固定或重放会话；工具仅返回已发布的内容；并且每次调用都会针对哈希处理后的调用者进行速率限制，并返回真实的 429 和 Retry-After。", "在为该端点编写 Origin 规则之前，我们首先测量了它自身的流量：几乎所有的请求都没有携带 Origin 标头，没有一个携带 null，而每个确实携带该标头的请求都来自本网站。最终发布的规则遵循了这一测量结果——拒绝来自其他任何地方的浏览器源调用，允许作为实际受众的无标头智能体流量——而不是复制 Web 应用的默认策略。", "为该知识库发布的 stdio 包在本地运行，无需凭据，也无需文件系统访问权限，因为它只需要向公开端点发起出站调用。一个什么都不需要的本地服务器，就不应该被赋予任何权限。" ], "faqs": [ { "q": "MCP 是让智能体更安全还是更不安全？", "a": "单次集成更安全，但总体而言风险更高。统一的协议意味着只需在一个地方进行审查和撤销——但它也降低了将智能体连接到另一个系统的成本，而每一次连接都是一个必须由人做出的全新信任决策。" }, { "q": "只读服务器需要身份验证吗？", "a": "如果数据是真正公开的，则不一定需要。但您仍然需要速率限制和审计追踪：公开并不意味着免费，一个无限制的公开端点就是一个指向您自己基础设施的放大器。" }, { "q": "如果智能体不发送 Origin 标头，为什么还要检查它？", "a": "正因为它们不发送。无标头的流量才是合法的受众；而确实携带外部 Origin 的请求则是代表他人操作的浏览器，这恰恰是值得拒绝的情况。" }, { "q": "什么是工具“抽毯子”（rug pull），我该如何防范？", "a": "指服务器在用户批准时提供良性的工具描述，随后又将其更改。防御措施包括固定服务器版本、在描述更改时重新验证，以及不向远程服务器授予您不会授予代码依赖项的权限。" } ] } } }, { "slug": "model-context-protocol", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/model-context-protocol", "api": "https://santismm.com/api/knowledge/model-context-protocol", "canonical_url": "https://santismm.com/en/knowledge/model-context-protocol", "api_url": "https://santismm.com/api/knowledge/model-context-protocol", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation" ] }, "references": [ { "title": "Model Context Protocol — Official site & specification", "url": "https://modelcontextprotocol.io" }, { "title": "Anthropic — Introducing the Model Context Protocol (2024)", "url": "https://www.anthropic.com/news/model-context-protocol" } ], "related": [ "ai-agent", "agentic-ai", "enterprise-rag", "harness-engineering", "mcp-security" ], "locales": { "en": { "title": "What is the Model Context Protocol (MCP)?", "summary": "The Model Context Protocol (MCP) is an open standard for connecting AI models and agents to external tools, data sources and systems through a single, uniform interface. Introduced by Anthropic in late 2024, it standardizes how an application exposes context and capabilities to a model — acting like a universal adapter so any compliant client can talk to any compliant server.", "definition": "MCP is an open protocol that standardizes how AI applications provide tools, resources and context to models through a common client–server interface.", "takeaways": [ "MCP standardizes model-to-tool/data connections, like a universal adapter.", "It uses a client–server model: hosts run clients; integrations are servers.", "Servers expose tools, resources and prompts in a uniform shape.", "It reduces N×M custom integrations to reusable, shareable connectors.", "It is open and vendor-neutral, with growing multi-vendor adoption." ], "context": [ "Before MCP, every agent-to-system integration was bespoke: each tool wired by hand to each application. MCP replaces that with a shared protocol, so a connector written once can be reused across any MCP-aware client.", "This matters for enterprises because integration — not model quality — is often the real bottleneck in shipping agents. A common protocol turns connectors into a reusable ecosystem rather than one-off glue code." ], "architecture": [ "MCP defines three roles: a host application, an MCP client inside it, and one or more MCP servers. The client connects to servers over a transport, and servers expose capabilities the model can use.", "Servers offer three primitives: tools (actions the model can invoke), resources (data the model can read), and prompts (reusable templates). The model, via the host, discovers and uses these in a standard way." ], "components": [ "Host application", "MCP client", "MCP server", "Tools", "Resources", "Prompts", "Transport" ], "pros": [ "Eliminates bespoke N×M integrations.", "Connectors are reusable and shareable across clients.", "Open and vendor-neutral.", "Cleaner separation between agent logic and integrations." ], "risks": [ "Server access expands the attack surface; permissions matter.", "Untrusted servers can attempt prompt injection or data exfiltration.", "A young standard, still evolving.", "Operational overhead of running and securing servers." ], "tools": [ "MCP reference SDKs", "Claude Desktop / Code", "IDE MCP clients", "Community MCP server registries" ], "examples": [ "An MCP server exposing a company knowledge base as readable resources to an agent.", "A filesystem or database MCP server giving an agent scoped, permissioned access.", "A shared connector for a SaaS API reused across several internal agents." ], "faqs": [ { "q": "Who created MCP?", "a": "Anthropic introduced MCP as an open standard in late 2024, and it has since seen adoption across multiple vendors and tools." }, { "q": "Is MCP the same as function calling?", "a": "No. Function calling lets a model invoke tools; MCP standardizes how those tools, data and prompts are exposed and discovered across applications." }, { "q": "Why does MCP matter for the enterprise?", "a": "Integration is usually the bottleneck for agents. MCP turns one-off connectors into a reusable, governable ecosystem." }, { "q": "What are the security considerations?", "a": "Each server is an access point. Apply least-privilege permissions, vet servers, and treat their outputs as untrusted input subject to prompt-injection risk." } ] }, "es": { "title": "¿Qué es el Model Context Protocol (MCP)?", "summary": "El Model Context Protocol (MCP) es un estándar abierto para conectar modelos y agentes de IA con herramientas, fuentes de datos y sistemas externos a través de una interfaz única y uniforme. Presentado por Anthropic a finales de 2024, estandariza cómo una aplicación expone contexto y capacidades a un modelo, actuando como un adaptador universal para que cualquier cliente compatible hable con cualquier servidor compatible.", "definition": "MCP es un protocolo abierto que estandariza cómo las aplicaciones de IA proporcionan herramientas, recursos y contexto a los modelos mediante una interfaz cliente–servidor común.", "takeaways": [ "MCP estandariza la conexión modelo-herramienta/datos, como un adaptador universal.", "Usa un modelo cliente–servidor: los hosts ejecutan clientes; las integraciones son servidores.", "Los servidores exponen herramientas, recursos y prompts con una forma uniforme.", "Reduce las integraciones a medida N×M a conectores reutilizables y compartibles.", "Es abierto y neutral respecto al proveedor, con adopción multifabricante creciente." ], "context": [ "Antes de MCP, cada integración agente-sistema era a medida: cada herramienta cableada a mano a cada aplicación. MCP la sustituye por un protocolo compartido, de modo que un conector escrito una vez se reutiliza en cualquier cliente compatible.", "Importa para las empresas porque el cuello de botella real al desplegar agentes suele ser la integración, no la calidad del modelo. Un protocolo común convierte los conectores en un ecosistema reutilizable en vez de pegamento de un solo uso." ], "architecture": [ "MCP define tres roles: una aplicación host, un cliente MCP dentro de ella y uno o varios servidores MCP. El cliente se conecta a los servidores por un transporte, y los servidores exponen capacidades que el modelo puede usar.", "Los servidores ofrecen tres primitivas: herramientas (acciones que el modelo puede invocar), recursos (datos que el modelo puede leer) y prompts (plantillas reutilizables). El modelo, vía el host, las descubre y usa de forma estándar." ], "components": [ "Aplicación host", "Cliente MCP", "Servidor MCP", "Herramientas", "Recursos", "Prompts", "Transporte" ], "pros": [ "Elimina las integraciones a medida N×M.", "Los conectores son reutilizables y compartibles entre clientes.", "Abierto y neutral respecto al proveedor.", "Separación más limpia entre la lógica del agente y las integraciones." ], "risks": [ "El acceso de los servidores amplía la superficie de ataque; los permisos importan.", "Servidores no confiables pueden intentar inyección de prompts o exfiltración de datos.", "Es un estándar joven, todavía en evolución.", "Coste operativo de ejecutar y asegurar servidores." ], "tools": [ "SDKs de referencia de MCP", "Claude Desktop / Code", "Clientes MCP en IDEs", "Registros comunitarios de servidores MCP" ], "examples": [ "Un servidor MCP que expone la base de conocimiento de la empresa como recursos legibles para un agente.", "Un servidor MCP de sistema de ficheros o base de datos que da a un agente acceso acotado y con permisos.", "Un conector compartido para una API SaaS reutilizado en varios agentes internos." ], "faqs": [ { "q": "¿Quién creó MCP?", "a": "Anthropic presentó MCP como estándar abierto a finales de 2024, y desde entonces ha tenido adopción en varios fabricantes y herramientas." }, { "q": "¿MCP es lo mismo que function calling?", "a": "No. El function calling permite a un modelo invocar herramientas; MCP estandariza cómo se exponen y descubren esas herramientas, datos y prompts entre aplicaciones." }, { "q": "¿Por qué importa MCP en la empresa?", "a": "La integración suele ser el cuello de botella de los agentes. MCP convierte los conectores de un solo uso en un ecosistema reutilizable y gobernable." }, { "q": "¿Qué consideraciones de seguridad tiene?", "a": "Cada servidor es un punto de acceso. Aplica permisos de mínimo privilegio, valida los servidores y trata sus salidas como entrada no confiable sujeta a inyección de prompts." } ] }, "pt": { "title": "O que é o Model Context Protocol (MCP)?", "summary": "O Model Context Protocol (MCP) é um padrão aberto para conectar modelos e agentes de IA a ferramentas, fontes de dados e sistemas externos por meio de uma interface única e uniforme. Apresentado pela Anthropic no fim de 2024, padroniza como uma aplicação expõe contexto e capacidades a um modelo, atuando como um adaptador universal para que qualquer cliente compatível converse com qualquer servidor compatível.", "definition": "MCP é um protocolo aberto que padroniza como as aplicações de IA fornecem ferramentas, recursos e contexto aos modelos por meio de uma interface cliente–servidor comum.", "takeaways": [ "MCP padroniza a conexão modelo-ferramenta/dados, como um adaptador universal.", "Usa um modelo cliente–servidor: os hosts executam clientes; as integrações são servidores.", "Os servidores expõem ferramentas, recursos e prompts numa forma uniforme.", "Reduz as integrações sob medida N×M a conectores reutilizáveis e compartilháveis.", "É aberto e neutro quanto ao fornecedor, com adoção multifabricante crescente." ], "context": [ "Antes do MCP, cada integração agente-sistema era sob medida: cada ferramenta ligada à mão a cada aplicação. O MCP a substitui por um protocolo compartilhado, de modo que um conector escrito uma vez é reutilizado em qualquer cliente compatível.", "Importa para as empresas porque o gargalo real ao implantar agentes costuma ser a integração, não a qualidade do modelo. Um protocolo comum transforma os conectores num ecossistema reutilizável em vez de cola de uso único." ], "architecture": [ "O MCP define três papéis: uma aplicação host, um cliente MCP dentro dela e um ou mais servidores MCP. O cliente se conecta aos servidores por um transporte, e os servidores expõem capacidades que o modelo pode usar.", "Os servidores oferecem três primitivas: ferramentas (ações que o modelo pode invocar), recursos (dados que o modelo pode ler) e prompts (modelos reutilizáveis). O modelo, via host, os descobre e usa de forma padronizada." ], "components": [ "Aplicação host", "Cliente MCP", "Servidor MCP", "Ferramentas", "Recursos", "Prompts", "Transporte" ], "pros": [ "Elimina as integrações sob medida N×M.", "Os conectores são reutilizáveis e compartilháveis entre clientes.", "Aberto e neutro quanto ao fornecedor.", "Separação mais limpa entre a lógica do agente e as integrações." ], "risks": [ "O acesso dos servidores amplia a superfície de ataque; as permissões importam.", "Servidores não confiáveis podem tentar injeção de prompts ou exfiltração de dados.", "É um padrão jovem, ainda em evolução.", "Custo operacional de executar e proteger servidores." ], "tools": [ "SDKs de referência do MCP", "Claude Desktop / Code", "Clientes MCP em IDEs", "Registros comunitários de servidores MCP" ], "examples": [ "Um servidor MCP que expõe a base de conhecimento da empresa como recursos legíveis para um agente.", "Um servidor MCP de sistema de arquivos ou banco de dados que dá a um agente acesso restrito e com permissões.", "Um conector compartilhado para uma API SaaS reutilizado em vários agentes internos." ], "faqs": [ { "q": "Quem criou o MCP?", "a": "A Anthropic apresentou o MCP como padrão aberto no fim de 2024, e desde então teve adoção em vários fabricantes e ferramentas." }, { "q": "MCP é o mesmo que function calling?", "a": "Não. O function calling permite a um modelo invocar ferramentas; o MCP padroniza como essas ferramentas, dados e prompts são expostos e descobertos entre aplicações." }, { "q": "Por que o MCP importa na empresa?", "a": "A integração costuma ser o gargalo dos agentes. O MCP transforma os conectores de uso único num ecossistema reutilizável e governável." }, { "q": "Quais as considerações de segurança?", "a": "Cada servidor é um ponto de acesso. Aplique permissões de privilégio mínimo, valide os servidores e trate suas saídas como entrada não confiável sujeita a injeção de prompts." } ] }, "fr": { "title": "Qu'est-ce que le Model Context Protocol (MCP) ?", "summary": "Le Model Context Protocol (MCP) est un standard ouvert permettant de connecter des modèles et agents d'IA à des outils, sources de données et systèmes externes via une interface unique et uniforme. Introduit par Anthropic fin 2024, il normalise la manière dont une application expose son contexte et ses capacités à un modèle — agissant comme un adaptateur universel pour que tout client conforme puisse communiquer avec tout serveur conforme.", "definition": "Le MCP est un protocole ouvert qui normalise la manière dont les applications d'IA fournissent des outils, des ressources et du contexte aux modèles via une interface client-serveur commune.", "takeaways": [ "Le MCP normalise les connexions entre modèles et outils/données, à l'image d'un adaptateur universel.", "Il utilise un modèle client-serveur : les hôtes exécutent les clients ; les intégrations sont des serveurs.", "Les serveurs exposent des outils, des ressources et des prompts sous une forme uniforme.", "Il réduit les intégrations personnalisées N×M à des connecteurs réutilisables et partageables.", "Il est ouvert et neutre vis-à-vis des fournisseurs, avec une adoption multi-fournisseur croissante." ], "context": [ "Avant le MCP, chaque intégration d'un agent à un système était sur mesure : chaque outil était relié manuellement à chaque application. Le MCP remplace cela par un protocole partagé, de sorte qu'un connecteur écrit une seule fois peut être réutilisé sur n'importe quel client compatible MCP.", "Cela est crucial pour les entreprises car l'intégration — et non la qualité du modèle — est souvent le véritable goulot d'étranglement lors du déploiement d'agents. Un protocole commun transforme les connecteurs en un écosystème réutilisable plutôt qu'en un code de liaison unique." ], "architecture": [ "Le MCP définit trois rôles : une application hôte, un client MCP intégré et un ou plusieurs serveurs MCP. Le client se connecte aux serveurs via un transport, et les serveurs exposent des capacités que le modèle peut utiliser.", "Les serveurs proposent trois primitives : les outils (actions que le modèle peut invoquer), les ressources (données que le modèle peut lire) et les prompts (modèles réutilisables). Le modèle, via l'hôte, les découvre et les utilise de manière standardisée." ], "components": [ "Application hôte", "Client MCP", "Serveur MCP", "Outils", "Ressources", "Prompts", "Transport" ], "pros": [ "Élimine les intégrations sur mesure N×M.", "Les connecteurs sont réutilisables et partageables entre les clients.", "Ouvert et neutre vis-à-vis des fournisseurs.", "Séparation plus nette entre la logique de l'agent et les intégrations." ], "risks": [ "L'accès au serveur élargit la surface d'attaque ; les autorisations sont cruciales.", "Les serveurs non approuvés peuvent tenter des injections de prompt ou des exfiltrations de données.", "Un standard récent, encore en évolution.", "Surcharge opérationnelle liée à l'exécution et à la sécurisation des serveurs." ], "tools": [ "SDK de référence MCP", "Claude Desktop / Code", "Clients MCP pour IDE", "Registres de serveurs MCP de la communauté" ], "examples": [ "Un serveur MCP exposant une base de connaissances d'entreprise sous forme de ressources lisibles pour un agent.", "Un serveur MCP de système de fichiers ou de base de données offrant à un agent un accès restreint et autorisé.", "Un connecteur partagé pour une API SaaS, réutilisé par plusieurs agents internes." ], "faqs": [ { "q": "Qui a créé MCP ?", "a": "Anthropic a introduit MCP en tant que standard ouvert fin 2024, et il a depuis été adopté par de multiples fournisseurs et outils." }, { "q": "MCP est-il identique à l'appel de fonctions (function calling) ?", "a": "Non. L'appel de fonctions permet à un modèle d'invoquer des outils ; MCP standardise la manière dont ces outils, données et prompts sont exposés et découverts à travers les applications." }, { "q": "Pourquoi MCP est-il important pour l'entreprise ?", "a": "L'intégration est généralement le goulot d'étranglement pour les agents. MCP transforme les connecteurs uniques en un écosystème réutilisable et gouvernable." }, { "q": "Quelles sont les considérations de sécurité ?", "a": "Chaque serveur est un point d'accès. Appliquez des autorisations de moindre privilège, évaluez les serveurs et traitez leurs sorties comme des entrées non fiables sujettes aux risques d'injection de prompt." } ] }, "de": { "title": "Was ist das Model Context Protocol (MCP)?", "summary": "Das Model Context Protocol (MCP) ist ein offener Standard zur Verbindung von KI-Modellen und -Agenten mit externen Tools, Datenquellen und Systemen über eine einzige, einheitliche Schnittstelle. Es wurde Ende 2024 von Anthropic eingeführt und standardisiert, wie eine Anwendung Kontext und Funktionen für ein Modell bereitstellt – ähnlich wie ein Universaladapter, sodass jeder konforme Client mit jedem konformen Server kommunizieren kann.", "definition": "MCP ist ein offenes Protokoll, das standardisiert, wie KI-Anwendungen Tools, Ressourcen und Kontext für Modelle über eine gemeinsame Client-Server-Schnittstelle bereitstellen.", "takeaways": [ "MCP standardisiert Verbindungen von Modellen zu Tools/Daten, ähnlich wie ein Universaladapter.", "Es nutzt ein Client-Server-Modell: Hosts führen Clients aus; Integrationen sind Server.", "Server stellen Tools, Ressourcen und Prompts in einer einheitlichen Struktur bereit.", "Es reduziert N×M benutzerdefinierte Integrationen auf wiederverwendbare, teilbare Connectors.", "Es ist offen und herstellerneutral, mit einer wachsenden Akzeptanz durch verschiedene Anbieter." ], "context": [ "Vor MCP war jede Integration von Agenten in Systeme maßgeschneidert: Jedes Tool wurde manuell mit jeder Anwendung verknüpft. MCP ersetzt dies durch ein gemeinsames Protokoll, sodass ein einmal geschriebener Connector in jedem MCP-fähigen Client wiederverwendet werden kann.", "Dies ist für Unternehmen von Bedeutung, da die Integration – und nicht die Modellqualität – oft der eigentliche Flaschenhals bei der Bereitstellung von Agenten ist. Ein gemeinsames Protokoll macht Connectors zu einem wiederverwendbaren Ökosystem statt zu einmaligem Glue-Code." ], "architecture": [ "MCP definiert drei Rollen: eine Host-Anwendung, einen darin befindlichen MCP-Client und einen oder mehrere MCP-Server. Der Client verbindet sich über einen Transportweg mit den Servern, und die Server stellen Funktionen bereit, die das Modell nutzen kann.", "Server bieten drei Primitive: Tools (Aktionen, die das Modell aufrufen kann), Ressourcen (Daten, die das Modell lesen kann) und Prompts (wiederverwendbare Vorlagen). Das Modell erkennt und nutzt diese über den Host auf standardisierte Weise." ], "components": [ "Host-Anwendung", "MCP-Client", "MCP-Server", "Tools", "Ressourcen", "Prompts", "Transport" ], "pros": [ "Eliminiert maßgeschneiderte N×M-Integrationen.", "Connectors sind wiederverwendbar und über verschiedene Clients hinweg teilbar.", "Offen und herstellerneutral.", "Sauberere Trennung zwischen Agenten-Logik und Integrationen." ], "risks": [ "Serverzugriff vergrößert die Angriffsfläche; Berechtigungen sind entscheidend.", "Nicht vertrauenswürdige Server können versuchen, Prompt-Injections oder Datenabfluss durchzuführen.", "Ein junger Standard, der sich noch in der Entwicklung befindet.", "Betrieblicher Aufwand für den Betrieb und die Absicherung von Servern." ], "tools": [ "MCP-Referenz-SDKs", "Claude Desktop / Code", "IDE-MCP-Clients", "Community-MCP-Server-Registries" ], "examples": [ "Ein MCP-Server, der einem Agenten eine Unternehmens-Wissensdatenbank als lesbare Ressourcen bereitstellt.", "Ein Dateisystem- oder Datenbank-MCP-Server, der einem Agenten einen eingegrenzten, autorisierten Zugriff gewährt.", "Ein gemeinsam genutzter Connector für eine SaaS-API, der für mehrere interne Agenten wiederverwendet wird." ], "faqs": [ { "q": "Wer hat MCP entwickelt?", "a": "Anthropic hat MCP Ende 2024 als offenen Standard eingeführt, und er wurde seitdem von zahlreichen Anbietern und Tools übernommen." }, { "q": "Ist MCP dasselbe wie Function Calling?", "a": "Nein. Function Calling ermöglicht es einem Modell, Tools aufzurufen; MCP standardisiert, wie diese Tools, Daten und Prompts anwendungsübergreifend bereitgestellt und erkannt werden." }, { "q": "Warum ist MCP für Unternehmen wichtig?", "a": "Die Integration ist meist der Flaschenhals für Agenten. MCP verwandelt einmalige Connectoren in ein wiederverwendbares, steuerbares Ökosystem." }, { "q": "Welche Sicherheitsaspekte müssen berücksichtigt werden?", "a": "Jeder Server ist ein Zugriffspunkt. Wenden Sie das Prinzip der minimalen Rechtevergabe (Least Privilege) an, überprüfen Sie Server und behandeln Sie deren Ausgaben als nicht vertrauenswürdige Eingaben, bei denen das Risiko von Prompt-Injections besteht." } ] }, "ja": { "title": "Model Context Protocol (MCP) とは何ですか？", "summary": "Model Context Protocol (MCP) は、AIモデルやエージェントを、単一の統一されたインターフェースを介して外部のツール、データソース、システムに接続するためのオープン標準です。2024年後半にAnthropicによって導入され、アプリケーションがコンテキストや機能をモデルに公開する方法を標準化します。ユニバーサルアダプターのように機能し、準拠している任意のクライアントが、準拠している任意のサーバーと通信できるようにします。", "definition": "MCPは、AIアプリケーションが共通のクライアント・サーバーインターフェースを介して、ツール、リソース、コンテキストをモデルに提供する方法を標準化するオープンプロトコルです。", "takeaways": [ "MCPは、ユニバーサルアダプターのように、モデルからツールやデータへの接続を標準化します。", "クライアント・サーバーモデルを使用します。ホストがクライアントを実行し、統合機能がサーバーとなります。", "サーバーは、ツール、リソース、プロンプトを統一された形式で公開します。", "N×M個のカスタム統合を、再利用可能で共有可能なコネクタに削減します。", "オープンかつベンダーニュートラルであり、マルチベンダーによる採用が広がっています。" ], "context": [ "MCPが登場する前は、エージェントとシステムの統合はすべて個別対応（ビスポーク）であり、各ツールが各アプリケーションに手動で接続されていました。MCPはこれを共通プロトコルに置き換えるため、一度作成したコネクタを、MCPに対応した任意のクライアントで再利用できます。", "これは企業にとって重要です。なぜなら、エージェントを本番環境に導入する際の真のボトルネックは、モデルの品質ではなく、統合であることが多いためです。共通プロトコルにより、コネクタは使い捨ての接着コードではなく、再利用可能なエコシステムへと変化します。" ], "architecture": [ "MCPは、ホストアプリケーション、その内部のMCPクライアント、および1つ以上のMCPサーバーという3つの役割を定義します。クライアントはトランスポートを介してサーバーに接続し、サーバーはモデルが使用できる機能を公開します。", "サーバーは、ツール（モデルが呼び出せるアクション）、リソース（モデルが読み取れるデータ）、プロンプト（再利用可能なテンプレート）という3つのプリミティブを提供します。モデルはホストを介して、これらを標準的な方法で検出して使用します。" ], "components": [ "ホストアプリケーション", "MCPクライアント", "MCPサーバー", "ツール", "リソース", "プロンプト", "トランスポート" ], "pros": [ "個別対応のN×M個の統合を排除します。", "コネクタはクライアント間で再利用および共有可能です。", "オープンかつベンダーニュートラルです。", "エージェントロジックと統合機能のより明確な分離を実現します。" ], "risks": [ "サーバーへのアクセスにより攻撃対象領域が拡大するため、権限管理が重要になります。", "信頼できないサーバーが、プロンプトインジェクションやデータの持ち出しを試みる可能性があります。", "まだ発展途上の新しい標準規格です。", "サーバーの実行とセキュリティ確保に伴う運用オーバーヘッド。" ], "tools": [ "MCPリファレンスSDK", "Claude Desktop / Code", "IDE MCPクライアント", "コミュニティMCPサーバーレジストリ" ], "examples": [ "企業のナレッジベースを読み取り可能なリソースとしてエージェントに公開するMCPサーバー。", "エージェントに対してスコープ制限および権限管理されたアクセスを提供する、ファイルシステムまたはデータベースのMCPサーバー。", "複数の社内エージェント間で再利用される、SaaS API用の共有コネクター。" ], "faqs": [ { "q": "MCPは誰が作成したのですか？", "a": "Anthropicが2024年後半にオープン標準としてMCPを導入し、それ以来、複数のベンダーやツールで採用が進んでいます。" }, { "q": "MCPはファンクションコーリング（Function Calling）と同じですか？", "a": "いいえ。ファンクションコーリングはモデルがツールを呼び出せるようにするものです。一方、MCPは、それらのツール、データ、プロンプトをアプリケーション間で公開および検出する方法を標準化します。" }, { "q": "なぜエンタープライズにとってMCPが重要なのですか？", "a": "通常、統合（インテグレーション）がエージェントのボトルネックになります。MCPは、使い捨てのコネクターを、再利用可能でガバナンスの効いたエコシステムへと変換します。" }, { "q": "セキュリティ上の考慮事項は何ですか？", "a": "各サーバーはアクセスポイントとなります。最小権限の原則を適用し、サーバーを審査し、その出力をプロンプトインジェクションのリスクがある信頼できない入力として扱ってください。" } ] }, "zh": { "title": "什么是模型上下文协议（MCP）？", "summary": "模型上下文协议（MCP）是一个开放标准，用于通过单一、统一的接口将 AI 模型和智能体连接到外部工具、数据源和系统。它由 Anthropic 于 2024 年底推出，规范了应用程序向模型暴露上下文和能力的方式——其作用类似于通用适配器，使任何合规的客户端都能与任何合规的服务器进行通信。", "definition": "MCP 是一种开放协议，它规范了 AI 应用程序如何通过通用的客户端-服务器接口向模型提供工具、资源和上下文。", "takeaways": [ "MCP 规范了模型与工具/数据的连接，类似于通用适配器。", "它采用客户端-服务器模型：宿主应用运行客户端；集成充当服务器。", "服务器以统一的形式暴露工具、资源和提示词。", "它将 N×M 个自定义集成减少为可重用、可共享的连接器。", "它是开放且厂商中立的，并获得了越来越多厂商的采用。" ], "context": [ "在 MCP 出现之前，每个智能体到系统的集成都是定制的：每个工具都需要手动连接到每个应用程序。MCP 用共享协议取代了这种方式，因此编写一次连接器就可以在任何支持 MCP 的客户端中重用。", "这对企业至关重要，因为集成（而非模型质量）往往是交付智能体的真正瓶颈。通用协议将连接器转变为可重用的生态系统，而不是一次性的胶水代码。" ], "architecture": [ "MCP 定义了三种角色：宿主应用程序、其内部的 MCP 客户端以及一个或多个 MCP 服务器。客户端通过传输层连接到服务器，服务器则暴露模型可以使用的能力。", "服务器提供三种基元：工具（模型可以调用的操作）、资源（模型可以读取的数据）和提示词（可重用的模板）。模型通过宿主以标准方式发现并使用这些基元。" ], "components": [ "宿主应用程序", "MCP 客户端", "MCP 服务器", "工具", "资源", "提示词", "传输层" ], "pros": [ "消除了定制的 N×M 个集成。", "连接器可在不同客户端之间重用和共享。", "开放且厂商中立。", "智能体逻辑与集成之间更清晰的分离。" ], "risks": [ "服务器访问扩大了攻击面；权限至关重要。", "不可信的服务器可能会尝试提示词注入或数据外泄。", "一个年轻的标准，仍在不断演进。", "运行和保障服务器安全带来的运维开销。" ], "tools": [ "MCP 参考 SDK", "Claude Desktop / Code", "IDE MCP 客户端", "社区 MCP 服务器注册表" ], "examples": [ "将公司知识库作为可读资源暴露给智能体的 MCP 服务器。", "为智能体提供限定范围和权限访问的文件系统或数据库 MCP 服务器。", "在多个内部智能体之间复用的 SaaS API 共享连接器。" ], "faqs": [ { "q": "谁创建了 MCP？", "a": "Anthropic 于 2024 年底将 MCP 作为开放标准推出，此后已被多个厂商和工具采用。" }, { "q": "MCP 与函数调用（function calling）是一回事吗？", "a": "不是。函数调用允许模型调用工具；而 MCP 则规范了这些工具、数据和提示词在不同应用程序之间的暴露和发现方式。" }, { "q": "为什么 MCP 对企业至关重要？", "a": "集成通常是智能体的瓶颈。MCP 将一次性连接器转变为可复用、可治理的生态系统。" }, { "q": "有哪些安全方面的考量？", "a": "每个服务器都是一个访问点。应应用最小权限原则、审查服务器，并将其输出视为存在提示词注入风险的不可信输入。" } ] } } }, { "slug": "multi-agent-architecture", "category": "architecture", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/multi-agent-architecture", "api": "https://santismm.com/api/knowledge/multi-agent-architecture", "canonical_url": "https://santismm.com/en/knowledge/multi-agent-architecture", "api_url": "https://santismm.com/api/knowledge/multi-agent-architecture", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "references": [ { "title": "Anthropic — Building Effective Agents (2024)", "url": "https://www.anthropic.com/research/building-effective-agents" }, { "title": "Yao et al. — ReAct (2022)", "url": "https://arxiv.org/abs/2210.03629" } ], "related": [ "agentic-ai", "ai-agent", "harness-engineering", "model-context-protocol" ], "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." } ] }, "fr": { "title": "Qu'est-ce qu'une architecture multi-agent ?", "summary": "Une architecture multi-agent divise une tâche entre plusieurs agents spécialisés qui collaborent, délèguent ou rivalisent pour atteindre un objectif, plutôt que de s'appuyer sur un seul agent généraliste. Les configurations courantes incluent un orchestrateur qui délègue à des exécutants (workers), des pipelines où chaque agent gère une étape, et des modèles de débat ou de critique. Elle peut améliorer la modularité et la fiabilité pour les tâches complexes, mais ajoute une surcharge de coordination et ne devrait être adoptée que lorsqu'un agent unique s'avère manifestement insuffisant.", "definition": "Une architecture multi-agent est une conception de système dans laquelle plusieurs agents d'IA spécialisés se coordonnent — via un orchestrateur, un pipeline ou une interaction entre pairs — pour accomplir une tâche qui est répartie entre eux.", "takeaways": [ "Plusieurs agents spécialisés surpassent un seul généraliste pour certaines tâches complexes.", "Modèles courants : orchestrateur-exécutants (workers), pipelines, débat/critique.", "La spécialisation améliore la modularité et la concentration par rôle.", "La coordination, la latence et la surcharge de coûts sont les principaux inconvénients.", "Privilégiez par défaut un agent unique ; ne passez au multi-agent que si des mesures le justifient." ], "context": [ "À mesure que les tâches s'intensifient, le contexte et le raisonnement d'un agent unique sont mis à rude épreuve. Diviser le travail en rôles ciblés — chercheur, rédacteur, réviseur ; ou planificateur et exécutants — peut rendre chaque partie plus fiable et plus facile à évaluer.", "Mais le multi-agent n'est pas systématiquement meilleur. Chaque agent supplémentaire ajoute de la communication, des modes de défaillance et des coûts. La rigueur consiste à ne décomposer que là où les rôles sont réellement distincts et où un agent unique est mesurablement moins performant." ], "architecture": [ "Orchestrateur-exécutants (workers) : un agent principal planifie et délègue des sous-tâches à des agents exécutants, puis synthétise les résultats. Pipeline : les agents sont organisés par étapes, chacun transformant la sortie du précédent. Modèles de pairs : les agents débattent, critiquent ou votent pour améliorer la qualité.", "Les aspects transversaux — mémoire partagée, passage de messages, gestion des erreurs, budgets et observabilité — sont les éléments clés de la réussite ou de l'échec de la plupart des systèmes multi-agents. Des contrats clairs entre agents importent plus que des noms de rôles astucieux." ], "components": [ "Orchestrateur / agent principal", "Agents exécutants (workers) / spécialistes", "Mémoire partagée et état", "Passage de messages", "Outils (souvent via MCP)", "Garde-fous et budgets", "Observabilité" ], "pros": [ "Des rôles modulaires et spécialisés, plus faciles à évaluer.", "Parallélisme pour les sous-tâches indépendantes.", "Séparation des préoccupations à travers des flux de travail complexes.", "Les modèles de critique/débat peuvent améliorer la qualité des résultats." ], "risks": [ "Surcharge de coordination et latence accrue.", "Davantage de modes de défaillance et débogage plus difficile.", "Coût en jetons (tokens) plus élevé dû à la communication entre agents.", "Complexité prématurée lorsqu'un seul agent suffirait." ], "tools": [ "LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)" ], "examples": [ "Un orchestrateur déléguant la recherche, la rédaction et la révision à des agents spécialisés.", "Un pipeline qui extrait, transforme et valide les données à travers différentes étapes.", "Un agent critique révisant la sortie d'un autre agent avant sa finalisation." ], "faqs": [ { "q": "Le multi-agent est-il toujours préférable à un agent unique ?", "a": "Non. Cela ajoute de la coordination, des coûts et des modes de défaillance. Privilégiez un agent unique et n'adoptez le multi-agent que lorsqu'une tâche est clairement divisible et qu'un agent unique s'avère insuffisant." }, { "q": "Qu'est-ce que le modèle orchestrateur-exécutants (orchestrator-workers) ?", "a": "Un agent principal planifie une tâche, délègue des sous-tâches à des agents exécutants spécialisés, puis synthétise leurs résultats en une réponse finale." }, { "q": "Comment les systèmes multi-agents échouent-ils ?", "a": "Par des contrats flous entre agents, des pertes de contexte, des boucles infinies et des erreurs cumulatives — c'est pourquoi les budgets et l'observabilité sont essentiels." }, { "q": "Quel est le rapport entre MCP et les systèmes multi-agents ?", "a": "MCP standardise la manière dont chaque agent se connecte aux outils et aux données, rendant les intégrations réutilisables pour l'ensemble des agents du système." } ] }, "de": { "title": "Was ist eine Multi-Agenten-Architektur?", "summary": "Eine Multi-Agenten-Architektur teilt eine Aufgabe auf mehrere spezialisierte Agenten auf, die zusammenarbeiten, delegieren oder konkurrieren, um ein Ziel zu erreichen, anstatt sich auf einen einzigen universellen Agenten zu verlassen. Zu den gängigen Mustern gehören ein Orchestrator, der an Worker delegiert, Pipelines, bei denen jeder Agent eine Phase verantwortet, sowie Debatten- oder Kritiker-Muster. Sie kann die Modularität und Zuverlässigkeit bei komplexen Aufgaben verbessern, verursacht jedoch Koordinationsaufwand und sollte nur dann eingeführt werden, wenn ein einzelner Agent nachweislich unzureichend ist.", "definition": "Eine Multi-Agenten-Architektur ist ein Systemdesign, bei dem sich mehrere spezialisierte KI-Agenten – über einen Orchestrator, eine Pipeline oder Peer-Interaktion – koordinieren, um eine Aufgabe zu bewältigen, die auf sie aufgeteilt ist.", "takeaways": [ "Mehrere spezialisierte Agenten sind bei bestimmten komplexen Aufgaben einem Generalisten überlegen.", "Gängige Muster: Orchestrator-Worker, Pipelines, Debatte/Kritiker.", "Spezialisierung verbessert die Modularität und den Fokus pro Rolle.", "Koordinationsaufwand, Latenz und zusätzliche Kosten sind die Hauptnachteile.", "Nutzen Sie standardmäßig einen einzelnen Agenten; wechseln Sie nur zu Multi-Agenten-Systemen, wenn Messungen dies rechtfertigen." ], "context": [ "Mit wachsenden Aufgaben stoßen der Kontext und die logische Argumentation (Reasoning) eines einzelnen Agenten an ihre Grenzen. Die Aufteilung der Arbeit in fokussierte Rollen – wie Researcher, Writer, Reviewer oder Planer und Executor – kann jeden Teilbereich zuverlässiger und einfacher zu evaluieren machen.", "Multi-Agenten-Systeme sind jedoch nicht automatisch besser. Jeder zusätzliche Agent bringt Kommunikationsaufwand, neue Fehlerquellen und Kosten mit sich. Die Kunst besteht darin, Aufgaben nur dort aufzuteilen, wo Rollen wirklich trennbar sind und ein einzelner Agent messbar unzureichende Ergebnisse liefert." ], "architecture": [ "Orchestrator-Worker: Ein leitender Agent plant und delegiert Teilaufgaben an Worker-Agenten und führt die Ergebnisse anschließend zusammen. Pipeline: Agenten sind in Phasen angeordnet, wobei jeder die Ausgabe des vorherigen transformiert. Peer-Muster: Agenten debattieren, kritisieren oder stimmen ab, um die Qualität zu steigern.", "Übergreifende Aspekte – wie gemeinsamer Speicher (Shared Memory), Message Passing, Fehlerbehandlung, Budgets und Observability – entscheiden meist über Erfolg oder Misserfolg von Multi-Agenten-Systemen. Klare Verträge (Contracts) zwischen den Agenten sind wichtiger als originelle Rollennamen." ], "components": [ "Orchestrator / leitender Agent", "Worker / spezialisierte Agenten", "Gemeinsamer Speicher & Zustand", "Message Passing", "Tools (oft über MCP)", "Guardrails & Budgets", "Observability" ], "pros": [ "Modulare, spezialisierte Rollen, die einfacher zu evaluieren sind.", "Parallelität für unabhängige Teilaufgaben.", "Separation of Concerns über komplexe Workflows hinweg.", "Kritiker-/Debatten-Muster können die Ausgabequalität steigern." ], "risks": [ "Koordinationsaufwand und zusätzliche Latenz.", "Mehr Fehlerquellen und schwierigeres Debugging.", "Höhere Token-Kosten durch die Kommunikation zwischen Agenten.", "Vorzeitige Komplexität, wenn ein einzelner Agent ausreichen würde." ], "tools": [ "LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)" ], "examples": [ "Ein Orchestrator, der Recherche, Entwurf und Review an spezialisierte Agenten delegiert.", "Eine Pipeline, die Daten über verschiedene Phasen hinweg extrahiert, transformiert und validiert.", "Ein Kritiker-Agent, der die Ausgabe eines anderen Agenten überprüft, bevor sie finalisiert wird." ], "faqs": [ { "q": "Ist ein Multi-Agenten-System immer besser als ein einzelner Agent?", "a": "Nein. Es bringt Koordinationsaufwand, Kosten und zusätzliche Fehlerquellen mit sich. Bevorzugen Sie einen einzelnen Agenten und wechseln Sie nur dann zu Multi-Agenten-Systemen, wenn eine Aufgabe klar aufteilbar ist und ein einzelner Agent unzureichende Ergebnisse liefert." }, { "q": "Was ist das Orchestrator-Worker-Muster?", "a": "Ein leitender Agent plant eine Aufgabe, delegiert Teilaufgaben an spezialisierte Worker-Agenten und führt deren Ergebnisse zu einer finalen Antwort zusammen." }, { "q": "Wie schlagen Multi-Agenten-Systeme fehl?", "a": "Durch unklare Verträge (Contracts) zwischen Agenten, Kontextverlust, Endlosschleifen und sich kaskadierende Fehler – weshalb Budgets und Observability unerlässlich sind." }, { "q": "Welche Beziehung besteht zwischen MCP und Multi-Agenten-Systemen?", "a": "MCP standardisiert, wie sich jeder Agent mit Tools und Daten verbindet, wodurch Integrationen für alle Agenten im System wiederverwendbar werden." } ] }, "ja": { "title": "マルチエージェントアーキテクチャとは何ですか？", "summary": "マルチエージェントアーキテクチャとは、1つの汎用エージェントに依存するのではなく、目標を達成するために、連携、委譲、または競合する複数の特化型エージェントにタスクを分割する仕組みです。一般的な形態には、ワーカーに委譲するオーケストレーター、各エージェントがステージを担当するパイプライン、ディベートやクリティック（批評）のパターンなどがあります。複雑なタスクにおけるモジュール性と信頼性を向上させることができますが、調整のオーバーヘッドが加わるため、単一のエージェントでは明らかに不十分な場合にのみ採用すべきです。", "definition": "マルチエージェントアーキテクチャとは、複数の特化型AIエージェントが、オーケストレーター、パイプライン、またはピア間の相互作用を通じて連携し、分解されたタスクを共同で達成するシステム設計です。", "takeaways": [ "一部の複雑なタスクでは、複数の特化型エージェントが1つの汎用エージェントよりも優れた成果を上げます。", "一般的なパターン：オーケストレーター・ワーカー、パイプライン、ディベート／クリティック。", "特化させることで、モジュール性が向上し、役割ごとの集中度が高まります。", "主なコストは、調整、レイテンシー、およびコストのオーバーヘッドです。", "基本は単一のエージェントとし、測定によって妥当性が証明された場合にのみマルチエージェントに移行します。" ], "context": [ "タスクが大きくなると、単一のエージェントのコンテキストと推論能力は限界に達します。作業を、リサーチャー、ライター、レビュアー、あるいはプランナーと実行者のような、焦点を絞った役割に分割することで、各部分の信頼性を高め、評価を容易にすることができます。", "しかし、マルチエージェントが自動的に優れているわけではありません。エージェントを追加するたびに、通信、障害モード、およびコストが増加します。役割が真に分離可能であり、単一のエージェントでは測定可能なレベルでパフォーマンスが低下する場合にのみ分解するという規律が必要です。" ], "architecture": [ "オーケストレーター・ワーカー：リードエージェントが計画を立て、サブタスクをワーカーエージェントに委譲し、その結果を統合します。パイプライン：エージェントがステージごとに配置され、それぞれが前段の出力を変換します。ピアパターン：エージェント同士がディベート、批評、または投票を行い、品質を向上させます。", "共有メモリ、メッセージパッシング、エラーハンドリング、予算、オブザーバビリティなどの横断的関心事は、ほとんどのマルチエージェントシステムの成否を分けるポイントです。巧妙な役割名よりも、エージェント間の明確な契約（インターフェース）の方が重要です。" ], "components": [ "オーケストレーター／リードエージェント", "ワーカー／特化型エージェント", "共有メモリと状態", "メッセージパッシング", "ツール（多くはMCP経由）", "ガードレールと予算", "オブザーバビリティ" ], "pros": [ "評価が容易な、モジュール化された特化型の役割。", "独立したサブタスクの並列処理。", "複雑なワークフローにおける関心の分離。", "クリティック／ディベートパターンによる出力品質の向上。" ], "risks": [ "調整のオーバーヘッドとレイテンシーの増加。", "障害モードの増加とデバッグの難化。", "エージェント間通信によるトークンコストの増加。", "単一のエージェントで十分な場合における、時期尚早な複雑化。" ], "tools": [ "LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)" ], "examples": [ "リサーチ、ドラフト作成、レビューを特化型エージェントに委譲するオーケストレーター。", "各ステージでデータの抽出、変換、検証を行うパイプライン。", "別のエージェントの出力が確定する前に、それをレビューするクリティックエージェント。" ], "faqs": [ { "q": "マルチエージェントは常に単一のエージェントよりも優れていますか？", "a": "いいえ。調整、コスト、障害モードが増加します。基本的には単一のエージェントを優先し、タスクが明確に分離可能で、単一のエージェントではパフォーマンスが低下する場合にのみマルチエージェントを採用してください。" }, { "q": "オーケストレーター・ワーカーパターンとは何ですか？", "a": "リードエージェントがタスクを計画し、特化型のワーカーエージェントにサブタスクを委譲し、それらの結果を統合して最終的な回答を作成するパターンです。" }, { "q": "マルチエージェントシステムはどのように失敗しますか？", "a": "エージェント間の不明確な契約、コンテキストの喪失、無限ループ、エラーの連鎖などによって失敗します。そのため、予算管理とオブザーバビリティが不可欠です。" }, { "q": "MCPはマルチエージェントシステムとどのように関係していますか？", "a": "MCPは、各エージェントがツールやデータに接続する方法を標準化し、システム内のエージェント間で統合を再利用できるようにします。" } ] }, "zh": { "title": "什么是多智能体架构？", "summary": "多智能体架构将任务分配给多个协同、委派或竞争以达成目标的专业化智能体，而不是依赖单个通用智能体。常见形态包括向工作智能体委派任务的编排器、每个智能体负责一个阶段的流水线，以及辩论或批判模式。它可以提高复杂任务的模块化程度和可靠性，但会增加协调开销，只有在单个智能体明显无法胜任时才应采用。", "definition": "多智能体架构是一种系统设计，其中多个专业化 AI 智能体通过编排器、流水线或对等交互进行协同，以完成分解给它们的任务。", "takeaways": [ "对于某些复杂任务，多个专业化智能体的表现优于单个通用智能体。", "常见模式：编排器-工作智能体（orchestrator-workers）、流水线（pipelines）、辩论/批判（debate/critic）。", "专业化提高了模块化程度，使每个角色更加专注。", "协调、延迟和成本开销是主要的代价。", "默认使用单个智能体；只有在评估数据证明有必要时才转向多智能体。" ], "context": [ "随着任务规模的增长，单个智能体的上下文和推理能力会显得捉襟见肘。将工作拆分为专注的角色（如研究员、撰写员、审核员；或规划器和执行器）可以使每个部分更加可靠且更易于评估。", "但多智能体并不自然就更好。每增加一个智能体，就会增加通信开销、故障模式和成本。其原则是仅在角色确实可分离且单个智能体表现明显不佳时才进行拆分。" ], "architecture": [ "编排器-工作智能体：主智能体进行规划并将子任务委派给工作智能体，然后汇总结果。流水线：智能体按阶段排列，每个阶段对前一个阶段的输出进行转换。对等模式：智能体通过辩论、批判或投票来提高质量。", "横切关注点（如共享内存、消息传递、错误处理、预算和可观测性）是大多数多智能体系统成败的关键。智能体之间清晰的契约比巧妙的角色名称更重要。" ], "components": [ "编排器 / 主智能体", "工作智能体 / 专业智能体", "共享内存与状态", "消息传递", "工具（通常通过 MCP）", "护栏与预算", "可观测性" ], "pros": [ "模块化、专业化的角色，更易于评估。", "独立子任务的并行处理。", "复杂工作流中的关注点分离。", "批判/辩论模式可以提高输出质量。" ], "risks": [ "协调开销和增加的延迟。", "更多的故障模式和更难的调试。", "智能体间通信带来的更高 Token 成本。", "在单个智能体即足够时引入过早的复杂性。" ], "tools": [ "LangGraph", "CrewAI", "AutoGen", "OpenAI Agents SDK", "Model Context Protocol (MCP)" ], "examples": [ "将研究、起草和审核委派给专业智能体的编排器。", "跨阶段提取、转换和验证数据的流水线。", "在最终确定之前审查另一个智能体输出的批判智能体。" ], "faqs": [ { "q": "多智能体总是优于单个智能体吗？", "a": "不是。它会增加协调、成本和故障模式。应优先使用单个智能体，只有在任务明显可分离且单个智能体表现不佳时才采用多智能体。" }, { "q": "什么是编排器-工作智能体模式？", "a": "主智能体规划任务，将子任务委派给专业的工作智能体，并将其结果汇总为最终答案。" }, { "q": "多智能体系统是如何失效的？", "a": "通过智能体之间不清晰的契约、丢失的上下文、失控的循环以及复合错误——这就是为什么预算和可观测性至关重要的原因。" }, { "q": "MCP 与多智能体系统有什么关系？", "a": "MCP 规范了每个智能体连接到工具和数据的方式，使集成在系统中的各个智能体之间可复用。" } ] } } }, { "slug": "prompt-engineering", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/prompt-engineering", "api": "https://santismm.com/api/knowledge/prompt-engineering", "canonical_url": "https://santismm.com/en/knowledge/prompt-engineering", "api_url": "https://santismm.com/api/knowledge/prompt-engineering", "evidence": { "evidenceLevel": "benchmark", "confidenceLevel": "high", "sourceType": [ "benchmark", "paper", "industry_observation" ] }, "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" } ], "related": [ "context-engineering", "tool-use", "agentic-ai", "harness-engineering" ], "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." } ] }, "fr": { "title": "Qu'est-ce que le Prompt Engineering ?", "summary": "Le Prompt Engineering est la pratique consistant à concevoir les entrées fournies à un modèle de langage afin qu'il produise le résultat souhaité de manière fiable. Un bon prompt spécifie le rôle, la tâche, les contraintes, le format de sortie et, si nécessaire, des exemples. C'est le levier le plus accessible pour orienter le comportement du modèle — et une couche du harness plus large entourant un modèle — mais à lui seul, il ne rend pas un système fiable à grande échelle.", "definition": "Le Prompt Engineering est la pratique consistant à concevoir et à affiner les instructions, le contexte et les exemples fournis à un modèle de langage pour obtenir de manière fiable le résultat souhaité.", "takeaways": [ "Un prompt efficace précise le rôle, la tâche, les contraintes, le format et des exemples.", "Les exemples (few-shot) surpassent généralement les instructions seules pour les tâches structurées.", "Le prompt par chaîne de pensée (chain-of-thought) améliore le raisonnement en plusieurs étapes.", "Les prompts doivent être testés et versionnés, et non ajustés manuellement au ressenti.", "Il s'agit d'une couche du harness, et non d'un substitut aux outils, à la mémoire et à l'évaluation." ], "context": [ "Puisque les modèles suivent des instructions en langage naturel, la formulation d'une tâche modifie sensiblement le résultat. Le Prompt Engineering est la discipline qui consiste à bien la formuler : en étant explicite sur l'objectif, le public cible, les contraintes et le format attendu.", "C'est le moyen le plus rapide et le moins coûteux d'améliorer la qualité des résultats, c'est pourquoi la plupart des équipes commencent par là. Mais à mesure que les systèmes évoluent vers des agents, le prompt devient un composant parmi d'autres — outils, mémoire, récupération (retrieval) et évaluation — constituant le harness complet." ], "architecture": [ "Techniques courantes : zero-shot (instruction seule), few-shot (instruction et exemples), chain-of-thought (demande de raisonnement étape par étape), spécification de rôle et de format, et décomposition (division d'une tâche en prompts plus simples).", "Une pratique mature traite les prompts comme du code : stockés, versionnés, testés par rapport à des évaluations (evals) et modifiés de manière délibérée. Les modèles de prompts réutilisables et les schémas de sortie structurés réduisent la variance." ], "components": [ "Rôle / persona", "Instruction de tâche", "Contraintes", "Format de sortie", "Exemples (few-shot)", "Indices de raisonnement" ], "pros": [ "Le moyen le plus rapide et le moins coûteux de modifier le comportement d'un modèle.", "Aucun entraînement ni infrastructure requis.", "Fonctionne sur différents modèles et tâches.", "Facile à itérer et à combiner avec d'autres techniques." ], "risks": [ "Fragile : de légères modifications de formulation peuvent modifier le comportement.", "Injection de prompt lorsque les prompts incluent des entrées non fiables.", "Difficile de mettre à l'échelle la fiabilité uniquement par le prompting.", "Couplage masqué avec les particularités d'un modèle spécifique." ], "tools": [ "Modèles de prompts", "Sortie structurée / schéma JSON", "LangSmith / Langfuse (test de prompts)", "Suites d'évaluation" ], "examples": [ "Ajouter quelques exemples concrets pour que le modèle produise un JSON cohérent.", "Demander un raisonnement étape par étape pour améliorer une réponse mathématique ou logique.", "Spécifier un format strict pour que le code en aval puisse analyser la réponse." ], "faqs": [ { "q": "Le prompt engineering est-il toujours pertinent à mesure que les modèles s'améliorent ?", "a": "Oui, mais son rôle se restreint. Les meilleurs modèles ont besoin de moins d'incitations, mais des instructions claires, des exemples et des spécifications de format améliorent encore de manière mesurable la fiabilité — en particulier au sein des agents." }, { "q": "Quelle est la différence avec le context engineering ?", "a": "Le prompt engineering se concentre sur l'instruction. Le context engineering est la tâche plus large consistant à décider quelles informations entrent dans la fenêtre de contexte limitée du modèle à chaque étape." }, { "q": "La chaîne de pensée (chain-of-thought) aide-t-elle toujours ?", "a": "Elle est surtout utile pour les tâches de raisonnement en plusieurs étapes, au prix d'un plus grand nombre de tokens. Pour les recherches simples, elle ajoute de la latence sans aucun avantage." }, { "q": "Comment maintenir la fiabilité des prompts ?", "a": "Traitez-les comme du code : versionnez-les, testez-les par rapport à des évaluations et modifiez-les de manière délibérée plutôt que par tâtonnements." } ] }, "de": { "title": "Was ist Prompt Engineering?", "summary": "Prompt Engineering ist die Praxis des Entwerfens von Eingaben für ein Sprachmodell, damit dieses zuverlässig die gewünschte Ausgabe erzeugt. Ein guter Prompt spezifiziert die Rolle, die Aufgabe, die Einschränkungen, das Ausgabeformat und, falls nützlich, Beispiele. Es ist der am leichtesten zugängliche Hebel zur Steuerung des Modellverhaltens – und eine Ebene des umfassenderen Harness um ein Modell –, aber für sich genommen macht es ein System im großen Maßstab noch nicht zuverlässig.", "definition": "Prompt Engineering ist die Praxis des Entwerfens und Verfeinerns von Anweisungen, Kontexten und Beispielen für ein Sprachmodell, um zuverlässig eine gewünschte Ausgabe hervorzurufen.", "takeaways": [ "Ein starker Prompt definiert Rolle, Aufgabe, Einschränkungen, Format und Beispiele.", "Beispiele (Few-Shot) sind bei strukturierten Aufgaben reinen Anweisungen meist überlegen.", "Chain-of-Thought-Prompting verbessert mehrstufiges logisches Denken (Reasoning).", "Prompts sollten getestet und versioniert werden, anstatt sie nach Gefühl manuell anzupassen.", "Es ist eine Ebene des Harness, kein Ersatz für Tools, Speicher und Evaluierung." ], "context": [ "Da Modelle Anweisungen in natürlicher Sprache befolgen, verändert die Art und Weise, wie eine Aufgabe formuliert ist, das Ergebnis erheblich. Prompt Engineering ist die Disziplin, diese gut zu formulieren: explizit in Bezug auf das Ziel, die Zielgruppe, die Einschränkungen und das gewünschte Rückgabeformat zu sein.", "Es ist der schnellste und kostengünstigste Weg, die Ausgabequalität zu verbessern, weshalb die meisten Teams hier anfangen. Doch wenn Systeme zu Agenten heranwachsen, wird Prompting zu einer Komponente unter vielen neben Tools, Speicher, Retrieval und Evaluierung – dem vollständigen Harness." ], "architecture": [ "Gängige Techniken: Zero-Shot (nur Anweisung), Few-Shot (Anweisung plus Beispiele), Chain-of-Thought (Aufforderung zu schrittweisem Denken), Rollen- und Formatspezifikation sowie Dekomposition (Aufteilung einer Aufgabe in kleinere Prompts).", "Eine ausgereifte Praxis behandelt Prompts wie Code: gespeichert, versioniert, gegen Evals getestet und gezielt geändert. Wiederverwendbare Prompt-Templates und strukturierte Ausgabeschemata reduzieren die Varianz." ], "components": [ "Rolle / Persona", "Aufgabenanweisung", "Einschränkungen", "Ausgabeformat", "Beispiele (Few-Shot)", "Reasoning-Hinweise" ], "pros": [ "Der schnellste und kostengünstigste Weg, das Modellverhalten zu ändern.", "Kein Training oder Infrastruktur erforderlich.", "Funktioniert modell- und aufgabenübergreifend.", "Einfach zu iterieren und mit anderen Techniken zu kombinieren." ], "risks": [ "Fragil: Geringfügige Änderungen im Wortlaut können das Verhalten verändern.", "Prompt Injection, wenn Prompts nicht vertrauenswürdige Eingaben enthalten.", "Schwer, die Zuverlässigkeit allein durch Prompting zu skalieren.", "Verdeckte Kopplung an die Eigenheiten eines bestimmten Modells." ], "tools": [ "Prompt-Templates", "Strukturierte Ausgabe / JSON-Schema", "LangSmith / Langfuse (Prompt-Testing)", "Evaluations-Suites" ], "examples": [ "Hinzufügen einiger ausgearbeiteter Beispiele, damit das Modell konsistentes JSON ausgibt.", "Aufforderung zu einer schrittweisen Argumentation, um mathematische oder logische Antworten zu verbessern.", "Spezifizieren eines strikten Formats, damit nachgelagerter Code die Antwort parsen kann." ], "faqs": [ { "q": "Ist Prompt Engineering angesichts besserer Modelle immer noch relevant?", "a": "Ja, aber seine Rolle schrumpft. Bessere Modelle benötigen weniger Überredung, doch klare Anweisungen, Beispiele und Formatspezifikationen verbessern die Zuverlässigkeit immer noch messbar – insbesondere innerhalb von Agenten." }, { "q": "Was ist der Unterschied zu Context Engineering?", "a": "Prompt Engineering konzentriert sich auf die Anweisung. Context Engineering ist die umfassendere Aufgabe zu entscheiden, welche Informationen in jedem Schritt in das begrenzte Kontextfenster des Modells einfließen." }, { "q": "Hilft Chain-of-Thought immer?", "a": "Es hilft am meisten bei mehrstufigen logischen Aufgaben, auf Kosten von mehr Token. Bei einfachen Abfragen erhöht es die Latenz ohne Nutzen." }, { "q": "Wie hält man Prompts zuverlässig?", "a": "Behandeln Sie sie wie Code: Versionieren Sie sie, testen Sie sie gegen Evaluationen und ändern Sie sie gezielt statt durch Ausprobieren." } ] }, "ja": { "title": "プロンプトエンジニアリングとは何ですか？", "summary": "プロンプトエンジニアリングとは、言語モデルが望ましい出力を確実に生成するように、モデルに与える入力を設計する手法です。優れたプロンプトは、役割、タスク、制約、出力形式、および必要に応じて例を指定します。これはモデルの挙動を制御するための最も手軽な手段であり、モデルを取り囲む広範なハーネスの1つのレイヤーですが、これ単体でシステムの大規模な信頼性を担保できるわけではありません。", "definition": "プロンプトエンジニアリングとは、望ましい出力を確実に引き出すために、言語モデルに与える指示、コンテキスト、および例を設計・洗練させる手法です。", "takeaways": [ "強力なプロンプトは、役割、タスク、制約、形式、および例を明示します。", "構造化されたタスクでは、通常、指示のみよりも例（フューショット）を提示する方が優れた結果をもたらします。", "Chain-of-Thought（思考の連鎖）プロンプトは、複数ステップの推論を向上させます。", "プロンプトは感覚で手動調整するのではなく、テストおよびバージョン管理を行うべきです。", "それはハーネスの1つのレイヤーであり、ツール、メモリ、評価の代わりになるものではありません。" ], "context": [ "モデルは自然言語の指示に従うため、タスクの表現方法によって結果が大きく変わります。プロンプトエンジニアリングとは、表現を洗練させる技術であり、目標、対象読者、制約、および期待する出力形式を明示することです。", "これは出力品質を向上させる最も迅速かつ安価な方法であり、多くのチームがここから開始する理由でもあります。しかし、システムがエージェントへと進化するにつれて、プロンプト作成は、ツール、メモリ、検索、評価といったコンポーネント（完全なハーネス）の一部にすぎなくなります。" ], "architecture": [ "一般的な手法：ゼロショット（指示のみ）、フューショット（指示と例）、Chain-of-Thought（段階的な推論を求める）、役割と形式の指定、および分解（タスクをより小さなプロンプトに分割する）。", "成熟したプラクティスでは、プロンプトをコードとして扱います。保存、バージョン管理、評価（evals）に対するテストを行い、計画的に変更します。再利用可能なプロンプトテンプレートや構造化された出力スキーマにより、ばらつきを抑えることができます。" ], "components": [ "役割／ペルソナ", "タスクの指示", "制約", "出力形式", "例（フューショット）", "推論の手がかり" ], "pros": [ "モデルの挙動を変更するための、最も迅速かつ安価な方法。", "トレーニングやインフラストラクチャは不要。", "さまざまなモデルやタスクに対応可能。", "反復（イテレーション）が容易で、他の手法と組み合わせやすい。" ], "risks": [ "脆弱性：わずかな表現の違いで挙動が変化する可能性がある。", "プロンプトに信頼できない入力が含まれる場合のプロンプトインジェクション。", "プロンプティング単体では信頼性のスケールが困難。", "特定のモデルの癖に対する隠れた結合。" ], "tools": [ "プロンプトテンプレート", "構造化出力 / JSONスキーマ", "LangSmith / Langfuse（プロンプトテスト）", "評価スイート" ], "examples": [ "モデルが一貫したJSONを出力するように、いくつかの具体的な実行例（Few-shot）を追加する。", "数学や論理の回答を改善するために、段階的な思考（推論）を求める。", "後続のコードがレスポンスをパースできるように、厳格なフォーマットを指定する。" ], "faqs": [ { "q": "モデルが向上しても、プロンプトエンジニアリングは依然として重要ですか？", "a": "はい、ただしその役割は狭まります。優れたモデルほど誘導を必要としなくなりますが、明確な指示、例、フォーマット指定は、特にエージェントの内部において、信頼性を測定可能な形で向上させます。" }, { "q": "コンテキストエンジニアリングとの違いは何ですか？", "a": "プロンプトエンジニアリングは指示に焦点を当てます。コンテキストエンジニアリングは、各ステップでモデルの限られたコンテキストウィンドウにどの情報を入力するかを決定する、より広範なタスクです。" }, { "q": "Chain-of-Thought（思考の連鎖）は常に効果的ですか？", "a": "トークン消費量が増える代わりに、複数ステップの推論タスクで最も効果を発揮します。単純な検索タスクでは、メリットなしにレイテンシーが増加するだけです。" }, { "q": "プロンプトの信頼性を維持するにはどうすればよいですか？", "a": "コードとして扱うことです。バージョン管理を行い、評価（evals）に対してテストし、試行錯誤ではなく意図的に変更を加えます。" } ] }, "zh": { "title": "什么是提示词工程？", "summary": "提示词工程是设计提供给语言模型的输入以使其可靠地产生所需输出的实践。一个好的提示词会指定角色、任务、约束、输出格式以及（在有用时）示例。它是引导模型行为最易用的手段——也是围绕模型的更广泛支撑系统（harness）中的一层——但仅凭其自身并不能使系统在大规模下保持可靠。", "definition": "提示词工程是设计和改进提供给语言模型的指令、上下文和示例，以可靠地引导出所需输出的实践。", "takeaways": [ "一个强大的提示词应说明角色、任务、约束、格式和示例。", "对于结构化任务，示例（少样本/few-shot）的效果通常优于仅有指令。", "思维链（chain-of-thought）提示词可以提高多步推理能力。", "提示词应该经过测试和版本控制，而不是凭感觉手动调整。", "它是支撑系统（harness）的一层，不能替代工具、内存和评估。" ], "context": [ "因为模型遵循自然语言指令，所以任务的表述方式会实质性地改变结果。提示词工程就是将其表述得当的学科：明确目标、受众、约束以及你希望返回的格式。", "这是提高输出质量最快、最便宜的方法，也是大多数团队的起点。但随着系统演变为智能体，提示词编写变成了工具、内存、检索和评估（即完整的支撑系统/harness）中的一个组件。" ], "architecture": [ "常用技术：零样本/zero-shot（仅指令）、少样本/few-shot（指令加示例）、思维链/chain-of-thought（要求逐步推理）、角色和格式规范，以及分解（将任务拆分为更小的提示词）。", "成熟的实践将提示词视为代码：进行存储、版本控制、针对评估（evals）进行测试，并谨慎地进行更改。可复用的提示词模板和结构化输出模式（schemas）可以减少偏差。" ], "components": [ "角色 / 人设（persona）", "任务指令", "约束条件", "输出格式", "示例（少样本/few-shot）", "推理线索" ], "pros": [ "改变模型行为最快、最便宜的方法。", "无需训练或基础设施。", "适用于各种模型和任务。", "易于迭代并与其他技术结合。" ], "risks": [ "脆弱性：微小的措辞变化就可能改变模型行为。", "当提示词包含不可信输入时，存在提示词注入风险。", "仅靠提示词很难规模化地提升可靠性。", "隐性耦合于特定模型的独特怪癖。" ], "tools": [ "提示词模板", "结构化输出 / JSON Schema", "LangSmith / Langfuse（提示词测试）", "评估套件" ], "examples": [ "添加几个完整示例，使模型输出一致的 JSON。", "要求进行分步推理，以提高数学或逻辑回答的准确性。", "指定严格的格式，以便下游代码能够解析响应。" ], "faqs": [ { "q": "随着模型能力的提升，提示词工程依然重要吗？", "a": "是的，但其作用范围在缩小。更好的模型需要更少的引导，但清晰的指令、示例和格式规范仍然能显著提高可靠性——特别是在智能体内部。" }, { "q": "它与上下文工程有什么区别？", "a": "提示词工程侧重于指令本身。而上下文工程是一项更广泛的任务，旨在决定在每一步中哪些信息进入模型有限的上下文窗口。" }, { "q": "思维链（Chain-of-Thought）总是有效吗？", "a": "它在多步推理任务中帮助最大，代价是消耗更多 Token。对于简单的查询，它只会增加延迟而无任何益处。" }, { "q": "如何保持提示词的可靠性？", "a": "将它们视为代码：进行版本控制，对照评估集进行测试，并有目的地进行修改，而不是盲目试错。" } ] } } }, { "slug": "prompt-injection", "category": "governance", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/prompt-injection", "api": "https://santismm.com/api/knowledge/prompt-injection", "canonical_url": "https://santismm.com/en/knowledge/prompt-injection", "api_url": "https://santismm.com/api/knowledge/prompt-injection", "evidence": { "evidenceLevel": "industry_observation", "confidenceLevel": "high", "sourceType": [ "industry_observation", "paper" ] }, "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" } ], "related": [ "guardrails", "tool-use", "ai-governance", "model-context-protocol", "ai-cyberdefense", "agentic-threat-model" ], "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." } ] }, "fr": { "title": "Qu'est-ce que l'injection de prompt ?", "summary": "L'injection de prompt est une attaque dans laquelle des instructions malveillantes masquées dans l'entrée d'un modèle de langage détournent son comportement — l'amenant à ignorer ses règles, à divulguer des données ou à faire un mauvais usage des outils. Elle figure en tête du Top 10 de l'OWASP pour les applications LLM. La cause profonde est que les modèles ne peuvent pas séparer de manière fiable les instructions de confiance du contenu non fiable, de sorte que tout texte lu par un agent — une page web, un document, un résultat d'outil — peut véhiculer une attaque.", "definition": "L'injection de prompt est une attaque de sécurité dans laquelle des instructions contradictoires intégrées dans une entrée non fiable amènent un modèle de langage à s'écarter de son comportement prévu, à contourner les garde-fous ou à effectuer des actions involontaires.", "takeaways": [ "Le texte non fiable lu par un modèle peut contenir des instructions masquées.", "C'est le risque numéro 1 du Top 10 de l'OWASP pour les applications LLM.", "L'injection indirecte masque les charges utiles (payloads) dans des documents, des pages ou des sorties d'outils.", "Le risque augmente avec l'accès aux outils — l'injection peut déclencher des actions réelles.", "Il n'existe pas de solution unique ; la défense est multicouche (moindre privilège, isolation, approbation humaine)." ], "context": [ "Les modèles suivent des instructions en langage naturel et ne peuvent pas distinguer de manière fiable les instructions système de confiance du contenu non fiable de l'utilisateur ou d'un document. Un attaquant exploite cela en plaçant des instructions telles que 'ignorez les instructions précédentes et...' là où le modèle les lira.", "L'injection directe provient de l'utilisateur ; l'injection indirecte (et plus dangereuse) se cache dans le contenu récupéré par l'agent — une page web, un e-mail, un fichier, un résultat d'outil MCP. À mesure que les agents accèdent aux outils, une injection réussie peut exfiltrer des données ou entreprendre des actions préjudiciables." ], "architecture": [ "La défense est multicouche et ne repose pas sur un contrôle unique : autorisations d'outils selon le principe du moindre privilège, isolation et délimitation claire du contenu non fiable, validation des sorties et des actions, listes d'autorisation pour les opérations sensibles et approbation humaine (human-in-the-loop) pour les actions à fort impact.", "Traitez toutes les sorties d'outils et de récupération comme des entrées non fiables. Surveillez et journalisez les actions de l'agent (observabilité) afin que les tentatives d'injection soient détectables, et effectuez régulièrement des simulations d'attaque (red-teaming) sur le système." ], "components": [ "Limite des entrées non fiables", "Autorisations de moindre privilège", "Isolation / délimitation du contenu", "Validation des sorties et des actions", "Approbation humaine pour les actions à fort impact", "Surveillance et red-teaming" ], "pros": [], "risks": [ "Exfiltration de données de contextes sensibles ou d'identifiants.", "Actions d'outils non autorisées dans les systèmes connectés.", "Contournement des politiques de sécurité et des garde-fous.", "Attaques indirectes via des documents, des pages web ou des résultats d'outils." ], "tools": [ "Bibliothèques de garde-fous d'entrée/sortie", "Couches d'autorisation et de sandboxing", "Listes d'autorisation pour les actions d'outils", "Surveillance / observabilité", "Frameworks de red-teaming" ], "examples": [ "Une page web lue par l'agent contient du texte masqué lui demandant d'envoyer des données privées par e-mail.", "Un document ordonne à un outil de synthèse d'ignorer ses règles et de générer un lien malveillant.", "Le résultat d'un outil tente de forcer un agent à appeler un autre outil qu'il ne devrait pas." ], "faqs": [ { "q": "Pourquoi les modèles ne peuvent-ils pas simplement ignorer les instructions injectées ?", "a": "Parce qu'ils ne peuvent pas distinguer de manière fiable les instructions de confiance du contenu non fiable — les deux se présentant sous forme de texte. Cette ambiguïté constitue la vulnérabilité principale." }, { "q": "Qu'est-ce que l'injection de prompt indirecte ?", "a": "C'est lorsque les instructions malveillantes sont masquées dans un contenu externe récupéré par le modèle — une page, un fichier, un e-mail ou une sortie d'outil — plutôt que saisies par l'utilisateur. Elle est souvent plus dangereuse." }, { "q": "L'injection de prompt peut-elle être totalement évitée ?", "a": "Pas par une mesure unique aujourd'hui. Vous réduisez les risques grâce à des défenses multicouches : moindre privilège, isolation du contenu, validation, surveillance et approbation humaine pour les actions sensibles." }, { "q": "En quoi l'utilisation d'outils augmente-t-elle les enjeux ?", "a": "Sans outils, l'injection produit principalement du texte erroné. Avec des outils, une instruction injectée peut entreprendre des actions réelles — envoyer des données, effectuer des modifications — de sorte que les autorisations et l'approbation revêtent une importance accrue." } ] }, "de": { "title": "Was ist Prompt Injection?", "summary": "Prompt Injection ist ein Angriff, bei dem bösartige Anweisungen, die in der Eingabe eines Sprachmodells verborgen sind, dessen Verhalten kapern – was dazu führt, dass es seine Regeln ignoriert, Daten preisgibt oder Tools missbraucht. Es steht an der Spitze der OWASP Top 10 für LLM-Anwendungen. Die Ursache liegt darin, dass Modelle vertrauenswürdige Anweisungen nicht zuverlässig von nicht vertrauenswürdigen Inhalten trennen können. Jeder Text, den ein Agent liest – eine Webseite, ein Dokument, ein Tool-Ergebnis –, kann daher einen Angriff enthalten.", "definition": "Prompt Injection ist ein Sicherheitsangriff, bei dem gegnerische Anweisungen, die in nicht vertrauenswürdige Eingaben eingebettet sind, ein Sprachmodell dazu bringen, von seinem beabsichtigten Verhalten abzuweichen, Sicherheitsvorkehrungen zu umgehen oder unbeabsichtigte Aktionen auszuführen.", "takeaways": [ "Nicht vertrauenswürdiger Text, den ein Modell liest, kann versteckte Anweisungen enthalten.", "Es ist das Risiko Nummer 1 in den OWASP Top 10 für LLM-Anwendungen.", "Indirekte Injection verbirgt Payloads in Dokumenten, Seiten oder Tool-Ausgaben.", "Das Risiko wächst mit dem Tool-Zugriff – eine Injection kann echte Aktionen auslösen.", "Es gibt keine Universallösung; die Verteidigung ist mehrschichtig (Least Privilege, Isolation, menschliche Freigabe)." ], "context": [ "Modelle folgen Anweisungen in natürlicher Sprache und können vertrauenswürdige Systemanweisungen nicht zuverlässig von nicht vertrauenswürdigen Benutzer- oder Dokumenteninhalten unterscheiden. Ein Angreifer nutzt dies aus, indem er Anweisungen wie „Ignoriere vorherige Anweisungen und...“ dort platziert, wo das Modell sie liest.", "Direkte Injection geht vom Benutzer aus; indirekte (und gefährlichere) Injection verbirgt sich in Inhalten, die der Agent abruft – einer Webseite, einer E-Mail, einer Datei oder einem MCP-Tool-Ergebnis. Da Agenten Zugriff auf Tools erhalten, kann eine erfolgreiche Injection Daten exfiltrieren oder schädliche Aktionen ausführen." ], "architecture": [ "Die Verteidigung ist mehrschichtig und besteht nicht aus einer einzelnen Kontrollmaßnahme: Tool-Berechtigungen nach dem Prinzip der minimalen Rechtevergabe (Least Privilege), Isolierung und klare Abgrenzung von nicht vertrauenswürdigen Inhalten, Validierung von Ausgaben und Aktionen, Allow-Lists für sensible Operationen und Human-in-the-Loop-Freigaben für folgenschwere Aktionen.", "Behandeln Sie alle Tool- und Retrieval-Ausgaben als nicht vertrauenswürdige Eingaben. Überwachen und protokollieren Sie die Aktionen des Agenten (Observability), damit Injection-Versuche erkennbar sind, und führen Sie regelmäßig Red-Teaming für das System durch." ], "components": [ "Grenze für nicht vertrauenswürdige Eingaben", "Berechtigungen nach dem Prinzip der minimalen Rechtevergabe (Least Privilege)", "Inhaltsisolierung / -abgrenzung", "Validierung von Ausgaben und Aktionen", "Menschliche Freigabe für folgenschwere Aktionen", "Monitoring & Red-Teaming" ], "pros": [], "risks": [ "Datenexfiltration von sensiblem Kontext oder Anmeldedaten.", "Unbefugte Tool-Aktionen in verbundenen Systemen.", "Umgehung von Sicherheitsrichtlinien und Guardrails.", "Indirekte Angriffe über Dokumente, Webseiten oder Tool-Ergebnisse." ], "tools": [ "Bibliotheken für Input/Output-Guardrails", "Berechtigungs- und Sandboxing-Ebenen", "Allow-Lists für Tool-Aktionen", "Monitoring / Observability", "Red-Teaming-Frameworks" ], "examples": [ "Eine Webseite, die der Agent liest, enthält versteckten Text, der ihn anweist, private Daten per E-Mail zu senden.", "Ein Dokument weist ein Zusammenfassungstool an, seine Regeln zu ignorieren und einen schädlichen Link auszugeben.", "Ein Tool-Ergebnis versucht, einen Agenten dazu zu bringen, ein anderes Tool aufzurufen, das er nicht aufrufen sollte." ], "faqs": [ { "q": "Warum können Modelle injizierte Anweisungen nicht einfach ignorieren?", "a": "Weil sie vertrauenswürdige Anweisungen nicht zuverlässig von nicht vertrauenswürdigen Inhalten unterscheiden können – beides kommt als Text an. Diese Mehrdeutigkeit ist die Kernschwachstelle." }, { "q": "Was ist indirekte Prompt Injection?", "a": "Wenn die bösartigen Anweisungen in externen Inhalten verborgen sind, die das Modell abruft – einer Seite, Datei, E-Mail oder Tool-Ausgabe –, anstatt vom Benutzer eingegeben zu werden. Dies ist oft gefährlicher." }, { "q": "Kann Prompt Injection vollständig verhindert werden?", "a": "Heutzutage nicht durch eine einzelne Maßnahme. Sie reduzieren das Risiko durch mehrschichtige Verteidigung: Least Privilege, Inhaltsisolierung, Validierung, Monitoring und menschliche Freigabe für sensible Aktionen." }, { "q": "Wie erhöht die Nutzung von Tools das Risiko?", "a": "Ohne Tools führt eine Injection meist nur zu schlechtem Text. Mit Tools kann eine injizierte Anweisung echte Aktionen ausführen – Daten senden, Änderungen vornehmen –, weshalb Berechtigungen und Freigaben umso wichtiger sind." } ] }, "ja": { "title": "プロンプトインジェクションとは？", "summary": "プロンプトインジェクションとは、言語モデルへの入力に隠された悪意のある指示によってモデルの挙動が乗っ取られ、ルールを無視させられたり、データを漏洩させられたり、ツールを悪用させられたりする攻撃です。これはLLMアプリケーションにおけるOWASP Top 10の第1位に挙げられています。根本的な原因は、モデルが信頼できる指示と信頼できないコンテンツを確実に分離できないことにあります。そのため、エージェントが読み取るあらゆるテキスト（Webページ、ドキュメント、ツールの実行結果など）が攻撃を媒介する可能性があります。", "definition": "プロンプトインジェクションとは、信頼できない入力に埋め込まれた敵対的な指示によって、言語モデルが意図された挙動から逸脱したり、安全対策をバイパスしたり、意図しないアクションを実行したりするセキュリティ攻撃です。", "takeaways": [ "モデルが読み取る信頼できないテキストには、隠された指示が含まれている可能性があります。", "LLMアプリケーションにおけるOWASP Top 10の第1位のリスクです。", "間接的インジェクションは、ドキュメント、Webページ、またはツールの出力にペイロードを隠します。", "ツールへのアクセス権限が増えるほどリスクが高まります。インジェクションによって実際のアクションが引き起こされる可能性があります。", "単一の解決策はありません。防御は多層的（最小権限、隔離、人間による承認）に行う必要があります。" ], "context": [ "モデルは自然言語の指示に従うため、信頼できるシステム指示と、信頼できないユーザーやドキュメントのコンテンツを確実に区別することができません。攻撃者はこの弱点を突き、モデルが読み取る場所に「これまでの指示を無視して…」といった指示を仕込みます。", "直接的インジェクションはユーザーから行われます。間接的（かつより危険な）インジェクションは、エージェントが取得するコンテンツ（Webページ、メール、ファイル、MCPツールの実行結果など）に隠されています。エージェントがツールへのアクセス権限を持つようになると、インジェクションの成功によってデータが外部に送信されたり、有害なアクションが実行されたりする可能性があります。" ], "architecture": [ "防御は単一の制御ではなく、多層的に行います。ツールの最小権限、信頼できないコンテンツの隔離と明確な境界設定、出力とアクションの検証、機密性の高い操作の許可リスト（アローリスト）、影響の大きいアクションに対する人間による承認（Human-in-the-loop）などです。", "すべてのツールおよび検索の出力を、信頼できない入力として扱います。インジェクションの試みを検出できるようにエージェントのアクションを監視およびログ記録（オブザーバビリティ）し、定期的にシステムのレッドチーム演習を実施します。" ], "components": [ "信頼できない入力の境界", "最小権限", "コンテンツの隔離 / 境界設定", "出力とアクションの検証", "影響の大きいアクションに対する人間による承認", "監視とレッドチーム演習" ], "pros": [], "risks": [ "機密性の高いコンテキストや資格情報のデータ漏洩。", "接続されたシステムにおける不正なツールアクション。", "安全ポリシーやガードレールのバイパス。", "ドキュメント、Webページ、またはツールの実行結果を介した間接的な攻撃。" ], "tools": [ "入出力ガードレールライブラリ", "権限およびサンドボックスレイヤー", "ツールアクションの許可リスト", "監視 / オブザーバビリティ", "レッドチーム演習フレームワーク" ], "examples": [ "エージェントが読み取るWebページに、個人データをメールで送信するよう指示する隠しテキストが含まれている。", "要約ツールに対し、ルールを無視して悪意のあるリンクを出力するよう指示するドキュメント。", "ツールの実行結果が、エージェントに呼び出すべきではない別のツールを呼び出させようとする。" ], "faqs": [ { "q": "なぜモデルはインジェクションされた指示を単に無視できないのですか？", "a": "信頼できる指示と信頼できないコンテンツを確実に区別できないためです。どちらも同じテキストとして入力されます。この曖昧さが根本的な脆弱性です。" }, { "q": "間接的プロンプトインジェクションとは何ですか？", "a": "ユーザーが直接入力するのではなく、モデルが取得する外部コンテンツ（Webページ、ファイル、メール、ツールの出力など）に悪意のある指示が隠されている場合を指します。多くの場合、こちらの方がより危険です。" }, { "q": "プロンプトインジェクションは完全に防ぐことができますか？", "a": "現在のところ、単一の対策で完全に防ぐことはできません。最小権限、コンテンツの隔離、検証、監視、機密性の高いアクションに対する人間による承認など、多層的な防御によってリスクを軽減します。" }, { "q": "ツールの使用によって、なぜリスク（影響）が高まるのですか？", "a": "ツールがない場合、インジェクションの影響は主に不適切なテキストの生成にとどまります。ツールを使用する場合、インジェクションされた指示によって、データの送信や変更といった実際のアクションが実行される可能性があるため、権限管理と承認がより重要になります。" } ] }, "zh": { "title": "什么是提示词注入？", "summary": "提示词注入是一种攻击方式，隐藏在语言模型输入中的恶意指令会劫持其行为——使其忽略自身规则、泄露数据或滥用工具。它位列 OWASP LLM 应用十大安全风险之首。其根本原因在于模型无法可靠地将可信指令与不可信内容区分开来，因此智能体读取的任何文本（网页、文档、工具结果）都可能携带攻击载荷。", "definition": "提示词注入是一种安全攻击，嵌入在不可信输入中的对抗性指令会导致语言模型偏离其预期行为、绕过安全防护或执行非预期的操作。", "takeaways": [ "模型读取的不可信文本可能包含隐藏指令。", "它是 OWASP LLM 应用十大安全风险中排名第一的风险。", "间接注入将攻击载荷隐藏在文档、网页或工具输出中。", "风险随着工具访问权限的增加而增长——注入可能会触发真实的物理操作。", "没有单一的解决方案；防御需要分层进行（最小权限、隔离、人工审批）。" ], "context": [ "模型遵循自然语言指令，无法可靠地将可信的系统指令与不可信的用户或文档内容区分开来。攻击者利用这一点，在模型会读取的地方植入诸如“忽略之前的指令并……”之类的指令。", "直接注入来自用户；间接注入（且更具危险性）隐藏在智能体检索的内容中——如网页、电子邮件、文件或 MCP 工具结果。随着智能体获得工具访问权限，成功的注入可能会导致数据外泄或执行有害操作。" ], "architecture": [ "防御是分层的，而不是单一的控制措施：最小权限的工具权限、隔离并清晰界定不可信内容、输出与操作验证、敏感操作的白名单，以及高影响操作的人工介入审批。", "将所有工具和检索输出视为不可信输入。监控并记录智能体操作（可观测性）以便检测注入尝试，并定期对系统进行红队测试。" ], "components": [ "不可信输入边界", "最小权限许可", "内容隔离 / 界定", "输出与操作验证", "高影响操作的人工审批", "监控与红队测试" ], "pros": [], "risks": [ "敏感上下文或凭据的数据外泄。", "在连接的系统中执行未授权的工具操作。", "绕过安全策略和护栏。", "通过文档、网页或工具结果进行的间接攻击。" ], "tools": [ "输入/输出护栏库", "权限与沙箱层", "工具操作白名单", "监控 / 可观测性", "红队测试框架" ], "examples": [ "智能体读取的网页包含隐藏文本，指示其通过电子邮件发送私密数据。", "一份文档指示摘要生成器忽略其规则并输出恶意链接。", "工具结果试图让智能体调用另一个它不应该调用的工具。" ], "faqs": [ { "q": "为什么模型不能直接忽略注入的指令？", "a": "因为它们无法可靠地将可信指令与不可信内容区分开来——两者都以文本形式呈现。这种模糊性是核心漏洞所在。" }, { "q": "什么是间接提示词注入？", "a": "指恶意指令隐藏在模型检索的外部内容（如网页、文件、电子邮件或工具输出）中，而不是由用户直接输入。这通常更具危险性。" }, { "q": "提示词注入可以被完全防止吗？", "a": "目前无法通过单一措施完全防止。您可以通过分层防御来降低风险：最小权限、内容隔离、验证、监控以及对敏感操作的人工审批。" }, { "q": "工具的使用如何提高了风险？", "a": "在没有工具的情况下，注入大多只会产生不良文本。而有了工具，注入的指令可以执行真实的物理操作——发送数据、进行修改——因此权限和审批变得更加重要。" } ] } } }, { "slug": "reasoning-models", "category": "concept", "updated": "2026-06-21", "version": "1.0", "url": "https://santismm.com/en/knowledge/reasoning-models", "api": "https://santismm.com/api/knowledge/reasoning-models", "canonical_url": "https://santismm.com/en/knowledge/reasoning-models", "api_url": "https://santismm.com/api/knowledge/reasoning-models", "evidence": { "evidenceLevel": "benchmark", "confidenceLevel": "high", "sourceType": [ "benchmark", "paper" ] }, "references": [ { "title": "Wei et al. — Chain-of-Thought Prompting Elicits Reasoning in LLMs (2022)", "url": "https://arxiv.org/abs/2201.11903" }, { "title": "DeepSeek-AI — DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via RL (2025)", "url": "https://arxiv.org/abs/2501.12948" } ], "related": [ "foundation-models", "agentic-ai", "prompt-engineering", "agentic-evaluation" ], "locales": { "en": { "title": "What are Reasoning Models?", "summary": "Reasoning models are language models trained to spend extra computation 'thinking' before they answer — generating internal reasoning steps to solve harder problems in math, code and logic. They trade latency and cost for accuracy on complex, multi-step tasks. The key idea is test-time compute: letting a model reason longer at inference, rather than only making the model bigger, can substantially improve results.", "definition": "Reasoning models are language models optimized to perform extended step-by-step reasoning at inference time — using additional test-time compute — to improve accuracy on complex, multi-step problems.", "takeaways": [ "They 'think' before answering, using extra inference compute.", "Test-time compute is a new scaling axis beyond model size.", "Best for math, code, logic and multi-step planning.", "They trade latency and token cost for accuracy.", "Overkill for simple tasks — match the model to the problem." ], "context": [ "Standard models answer in roughly constant time regardless of difficulty. Reasoning models break that: they generate a chain of internal reasoning, effectively spending more compute on harder questions, which lifts performance on tasks that need multi-step deduction.", "This introduced a second scaling axis. Beyond making models larger (train-time compute), you can let them reason longer at inference (test-time compute) — a major driver of recent progress on hard benchmarks." ], "architecture": [ "Reasoning models are typically trained to produce long internal reasoning before a final answer, often reinforced with reinforcement learning that rewards correct outcomes. At inference, more 'thinking' tokens generally mean better answers on hard problems.", "In agentic systems, reasoning models serve as strong planners and decision-makers, while cheaper, faster models can handle routine steps. Routing between them by task difficulty is a common cost-control pattern." ], "components": [ "Extended reasoning (thinking tokens)", "Test-time compute budget", "RL-based training for reasoning", "Final-answer extraction" ], "pros": [ "Higher accuracy on complex, multi-step problems.", "Strong at math, coding and planning.", "Reasoning effort can be scaled per query.", "Good planners at the core of capable agents." ], "risks": [ "Higher latency and token cost.", "Overkill — and wasteful — for simple tasks.", "Longer reasoning is not always more correct.", "Internal reasoning can be hard to audit or trust verbatim." ], "tools": [ "Reasoning model tiers from major providers", "Adjustable reasoning-effort settings", "Model routing by task difficulty", "Evaluation suites" ], "examples": [ "Solving a multi-step math or logic problem that trips up a standard model.", "Planning a complex agent task before execution.", "Routing only hard tickets to a reasoning model to control cost." ], "faqs": [ { "q": "How are reasoning models different from standard LLMs?", "a": "They are trained and configured to reason at length before answering, spending more inference compute on hard problems instead of replying in near-constant time." }, { "q": "What is test-time compute?", "a": "Computation spent at inference (the model 'thinking' longer), as opposed to train-time compute spent making the model. It is a distinct way to improve results." }, { "q": "Should I always use a reasoning model?", "a": "No. They cost more and add latency. Use them for hard, multi-step problems and route simpler tasks to faster, cheaper models." }, { "q": "Do they eliminate hallucination?", "a": "No. Reasoning improves accuracy on many tasks but does not guarantee correctness; grounding, tools and evaluation remain necessary." } ] }, "es": { "title": "¿Qué son los Modelos de Razonamiento (Reasoning Models)?", "summary": "Los modelos de razonamiento son modelos de lenguaje entrenados para gastar cómputo extra 'pensando' antes de responder, generando pasos de razonamiento internos para resolver problemas más difíciles de matemáticas, código y lógica. Cambian latencia y coste por precisión en tareas complejas de varios pasos. La idea clave es el cómputo en inferencia (test-time compute): dejar que un modelo razone más en la inferencia, en vez de solo hacerlo más grande, puede mejorar mucho los resultados.", "definition": "Los modelos de razonamiento son modelos de lenguaje optimizados para realizar razonamiento extendido paso a paso en el momento de la inferencia —usando cómputo adicional en inferencia— para mejorar la precisión en problemas complejos de varios pasos.", "takeaways": [ "'Piensan' antes de responder, usando cómputo extra en inferencia.", "El cómputo en inferencia es un nuevo eje de escalado más allá del tamaño.", "Mejores para matemáticas, código, lógica y planificación de varios pasos.", "Cambian latencia y coste de tokens por precisión.", "Excesivos para tareas simples: ajusta el modelo al problema." ], "context": [ "Los modelos estándar responden en un tiempo casi constante sin importar la dificultad. Los modelos de razonamiento rompen eso: generan una cadena de razonamiento interno, gastando de hecho más cómputo en preguntas más difíciles, lo que mejora tareas que necesitan deducción de varios pasos.", "Esto introdujo un segundo eje de escalado. Más allá de hacer modelos más grandes (cómputo en entrenamiento), puedes dejarlos razonar más en inferencia (cómputo en inferencia): un motor importante del progreso reciente en benchmarks difíciles." ], "architecture": [ "Los modelos de razonamiento suelen entrenarse para producir un razonamiento interno largo antes de la respuesta final, a menudo reforzado con aprendizaje por refuerzo que premia resultados correctos. En inferencia, más tokens de 'pensamiento' suelen significar mejores respuestas en problemas difíciles.", "En sistemas agénticos, los modelos de razonamiento sirven como planificadores y decisores fuertes, mientras que modelos más baratos y rápidos manejan pasos rutinarios. Enrutar entre ellos según la dificultad es un patrón común de control de coste." ], "components": [ "Razonamiento extendido (tokens de pensamiento)", "Presupuesto de cómputo en inferencia", "Entrenamiento por RL para razonar", "Extracción de la respuesta final" ], "pros": [ "Mayor precisión en problemas complejos de varios pasos.", "Fuertes en matemáticas, programación y planificación.", "El esfuerzo de razonamiento puede escalarse por consulta.", "Buenos planificadores en el núcleo de agentes capaces." ], "risks": [ "Mayor latencia y coste de tokens.", "Excesivos —y derrochadores— para tareas simples.", "Razonar más no siempre es más correcto.", "El razonamiento interno puede ser difícil de auditar o de creer al pie de la letra." ], "tools": [ "Niveles de modelos de razonamiento de los grandes proveedores", "Ajustes de esfuerzo de razonamiento", "Enrutamiento de modelos por dificultad", "Suites de evaluación" ], "examples": [ "Resolver un problema de matemáticas o lógica de varios pasos que confunde a un modelo estándar.", "Planificar una tarea de agente compleja antes de ejecutarla.", "Enrutar solo los tickets difíciles a un modelo de razonamiento para controlar el coste." ], "faqs": [ { "q": "¿En qué se diferencian de los LLM estándar?", "a": "Están entrenados y configurados para razonar extensamente antes de responder, gastando más cómputo en inferencia en problemas difíciles en vez de responder en tiempo casi constante." }, { "q": "¿Qué es el cómputo en inferencia?", "a": "El cómputo gastado en la inferencia (el modelo 'pensando' más tiempo), frente al cómputo en entrenamiento gastado en construir el modelo. Es una forma distinta de mejorar resultados." }, { "q": "¿Debería usar siempre un modelo de razonamiento?", "a": "No. Cuestan más y añaden latencia. Úsalos para problemas difíciles de varios pasos y enruta las tareas simples a modelos más rápidos y baratos." }, { "q": "¿Eliminan la alucinación?", "a": "No. El razonamiento mejora la precisión en muchas tareas pero no garantiza la corrección; siguen siendo necesarios la fundamentación, las herramientas y la evaluación." } ] }, "pt": { "title": "O que são Modelos de Raciocínio (Reasoning Models)?", "summary": "Os modelos de raciocínio são modelos de linguagem treinados para gastar computação extra 'pensando' antes de responder, gerando passos de raciocínio internos para resolver problemas mais difíceis de matemática, código e lógica. Trocam latência e custo por precisão em tarefas complexas de vários passos. A ideia central é a computação em inferência (test-time compute): deixar um modelo raciocinar mais na inferência, em vez de só torná-lo maior, pode melhorar muito os resultados.", "definition": "Os modelos de raciocínio são modelos de linguagem otimizados para realizar raciocínio estendido passo a passo no momento da inferência — usando computação adicional em inferência — para melhorar a precisão em problemas complexos de vários passos.", "takeaways": [ "'Pensam' antes de responder, usando computação extra em inferência.", "A computação em inferência é um novo eixo de escala além do tamanho.", "Melhores para matemática, código, lógica e planejamento de vários passos.", "Trocam latência e custo de tokens por precisão.", "Exagero para tarefas simples: ajuste o modelo ao problema." ], "context": [ "Os modelos padrão respondem em tempo quase constante independentemente da dificuldade. Os modelos de raciocínio quebram isso: geram uma cadeia de raciocínio interno, gastando de fato mais computação em perguntas mais difíceis, o que melhora tarefas que precisam de dedução de vários passos.", "Isso introduziu um segundo eixo de escala. Além de tornar os modelos maiores (computação em treinamento), você pode deixá-los raciocinar mais na inferência (computação em inferência): um motor importante do progresso recente em benchmarks difíceis." ], "architecture": [ "Os modelos de raciocínio costumam ser treinados para produzir um raciocínio interno longo antes da resposta final, muitas vezes reforçado com aprendizado por reforço que premia resultados corretos. Na inferência, mais tokens de 'pensamento' costumam significar melhores respostas em problemas difíceis.", "Em sistemas agênticos, os modelos de raciocínio servem como planejadores e decisores fortes, enquanto modelos mais baratos e rápidos lidam com passos rotineiros. Rotear entre eles conforme a dificuldade é um padrão comum de controle de custo." ], "components": [ "Raciocínio estendido (tokens de pensamento)", "Orçamento de computação em inferência", "Treinamento por RL para raciocinar", "Extração da resposta final" ], "pros": [ "Maior precisão em problemas complexos de vários passos.", "Fortes em matemática, programação e planejamento.", "O esforço de raciocínio pode ser escalado por consulta.", "Bons planejadores no núcleo de agentes capazes." ], "risks": [ "Maior latência e custo de tokens.", "Exagero — e desperdício — para tarefas simples.", "Raciocinar mais nem sempre é mais correto.", "O raciocínio interno pode ser difícil de auditar ou de crer ao pé da letra." ], "tools": [ "Níveis de modelos de raciocínio dos grandes provedores", "Ajustes de esforço de raciocínio", "Roteamento de modelos por dificuldade", "Suítes de avaliação" ], "examples": [ "Resolver um problema de matemática ou lógica de vários passos que confunde um modelo padrão.", "Planejar uma tarefa de agente complexa antes de executá-la.", "Rotear só os chamados difíceis a um modelo de raciocínio para controlar o custo." ], "faqs": [ { "q": "Como diferem dos LLMs padrão?", "a": "São treinados e configurados para raciocinar longamente antes de responder, gastando mais computação em inferência em problemas difíceis em vez de responder em tempo quase constante." }, { "q": "O que é computação em inferência?", "a": "A computação gasta na inferência (o modelo 'pensando' mais tempo), frente à computação em treinamento gasta em construir o modelo. É uma forma distinta de melhorar resultados." }, { "q": "Devo usar sempre um modelo de raciocínio?", "a": "Não. Custam mais e adicionam latência. Use-os para problemas difíceis de vários passos e roteie as tarefas simples a modelos mais rápidos e baratos." }, { "q": "Eles eliminam a alucinação?", "a": "Não. O raciocínio melhora a precisão em muitas tarefas mas não garante a correção; fundamentação, ferramentas e avaliação seguem necessárias." } ] }, "fr": { "title": "Que sont les modèles de raisonnement ?", "summary": "Les modèles de raisonnement sont des modèles de langage entraînés à consacrer de la puissance de calcul supplémentaire à « réfléchir » avant de répondre — en générant des étapes de raisonnement internes pour résoudre des problèmes plus difficiles en mathématiques, en code et en logique. Ils échangent de la latence et du coût contre de la précision sur des tâches complexes en plusieurs étapes. L'idée clé est le calcul au moment du test (test-time compute) : permettre à un modèle de raisonner plus longtemps lors de l'inférence, plutôt que de simplement l'agrandir, peut améliorer considérablement les résultats.", "definition": "Les modèles de raisonnement sont des modèles de langage optimisés pour effectuer un raisonnement étape par étape étendu au moment de l'inférence — en utilisant du calcul supplémentaire au moment du test (test-time compute) — afin d'améliorer la précision sur des problèmes complexes en plusieurs étapes.", "takeaways": [ "Ils « réfléchissent » avant de répondre, en utilisant du calcul d'inférence supplémentaire.", "Le calcul au moment du test (test-time compute) est un nouvel axe de mise à l'échelle au-delà de la taille du modèle.", "Idéal pour les mathématiques, le code, la logique et la planification en plusieurs étapes.", "Ils échangent de la latence et du coût en tokens contre de la précision.", "Surdimensionné pour les tâches simples — adaptez le modèle au problème." ], "context": [ "Les modèles standards répondent dans un temps à peu près constant, quelle que soit la difficulté. Les modèles de raisonnement rompent avec cela : ils génèrent une chaîne de raisonnement interne, consacrant ainsi plus de calcul aux questions difficiles, ce qui améliore les performances sur les tâches nécessitant une déduction en plusieurs étapes.", "Cela a introduit un second axe de mise à l'échelle. Au-delà de l'agrandissement des modèles (calcul au moment de l'entraînement), vous pouvez les laisser raisonner plus longtemps lors de l'inférence (calcul au moment du test) — un moteur majeur des progrès récents sur les benchmarks difficiles." ], "architecture": [ "Les modèles de raisonnement sont généralement entraînés à produire un long raisonnement interne avant d'apporter une réponse finale, souvent renforcé par un apprentissage par renforcement qui récompense les résultats corrects. Lors de l'inférence, un plus grand nombre de tokens de « réflexion » se traduit généralement par de meilleures réponses sur les problèmes difficiles.", "Dans les systèmes agentiques, les modèles de raisonnement font office de planificateurs et de décideurs performants, tandis que des modèles plus rapides et moins coûteux peuvent gérer les étapes de routine. L'aiguillage entre eux en fonction de la difficulté de la tâche est un modèle courant de contrôle des coûts." ], "components": [ "Raisonnement étendu (tokens de réflexion)", "Budget de calcul au moment du test (test-time compute)", "Entraînement basé sur l'apprentissage par renforcement (RL) pour le raisonnement", "Extraction de la réponse finale" ], "pros": [ "Précision accrue sur les problèmes complexes en plusieurs étapes.", "Performant en mathématiques, en codage et en planification.", "L'effort de raisonnement peut être adapté par requête.", "Bons planificateurs au cœur d'agents performants." ], "risks": [ "Latence et coût en tokens plus élevés.", "Surdimensionné — et inutilement coûteux — pour les tâches simples.", "Un raisonnement plus long n'est pas toujours plus correct.", "Le raisonnement interne peut être difficile à auditer ou à croire sur parole." ], "tools": [ "Niveaux de modèles de raisonnement des principaux fournisseurs", "Paramètres d'effort de raisonnement ajustables", "Routage des modèles selon la difficulté de la tâche", "Suites d'évaluation" ], "examples": [ "Résoudre un problème mathématique ou logique à plusieurs étapes sur lequel bute un modèle standard.", "Planifier une tâche d'agent complexe avant son exécution.", "Router uniquement les tickets difficiles vers un modèle de raisonnement pour contrôler les coûts." ], "faqs": [ { "q": "En quoi les modèles de raisonnement diffèrent-ils des LLM standards ?", "a": "Ils sont entraînés et configurés pour raisonner longuement avant de répondre, consacrant plus de calcul d'inférence aux problèmes difficiles au lieu de répondre dans un temps quasi constant." }, { "q": "Qu'est-ce que le calcul au moment du test (test-time compute) ?", "a": "Le calcul effectué lors de l'inférence (le modèle « réfléchissant » plus longtemps), par opposition au calcul lors de l'entraînement (train-time compute) consacré à la création du modèle. C'est une méthode distincte pour améliorer les résultats." }, { "q": "Dois-je toujours utiliser un modèle de raisonnement ?", "a": "Non. Ils coûtent plus cher et ajoutent de la latence. Utilisez-les pour les problèmes complexes à plusieurs étapes et routez les tâches plus simples vers des modèles plus rapides et moins coûteux." }, { "q": "Éliminent-ils les hallucinations ?", "a": "Non. Le raisonnement améliore la précision sur de nombreuses tâches mais ne garantit pas l'exactitude ; l'ancrage (grounding), les outils et l'évaluation restent nécessaires." } ] }, "de": { "title": "Was sind Reasoning-Modelle?", "summary": "Reasoning-Modelle sind Sprachmodelle, die darauf trainiert sind, vor der Antwort zusätzliche Rechenleistung für das „Nachdenken“ aufzuwenden. Sie generieren interne Argumentationsschritte, um schwierigere Probleme in Mathematik, Code und Logik zu lösen. Sie tauschen Latenz und Kosten gegen Genauigkeit bei komplexen, mehrstufigen Aufgaben ein. Die Kernidee ist Test-Time Compute: Wenn man ein Modell bei der Inferenz länger nachdenken lässt, anstatt nur das Modell zu vergrößern, können die Ergebnisse erheblich verbessert werden.", "definition": "Reasoning-Modelle sind Sprachmodelle, die darauf optimiert sind, zum Inferenzzeitpunkt eine erweiterte, schrittweise Argumentation durchzuführen – unter Nutzung von zusätzlichem Test-Time Compute – um die Genauigkeit bei komplexen, mehrstufigen Problemen zu verbessern.", "takeaways": [ "Sie „denken“ vor der Antwort nach und nutzen dafür zusätzliche Inferenz-Rechenleistung.", "Test-Time Compute ist eine neue Skalierungsachse jenseits der Modellgröße.", "Am besten geeignet für Mathematik, Code, Logik und mehrstufige Planung.", "Sie tauschen Latenz und Token-Kosten gegen Genauigkeit ein.", "Überdimensioniert für einfache Aufgaben – passen Sie das Modell an das Problem an." ], "context": [ "Standardmodelle antworten unabhängig von der Schwierigkeit in einer annähernd konstanten Zeit. Reasoning-Modelle brechen damit: Sie generieren eine Kette interner Argumentation und wenden so effektiv mehr Rechenleistung für schwierigere Fragen auf, was die Leistung bei Aufgaben steigert, die eine mehrstufige Deduktion erfordern.", "Dies führte eine zweite Skalierungsachse ein. Neben der Vergrößerung von Modellen (Train-Time Compute) kann man sie bei der Inferenz länger nachdenken lassen (Test-Time Compute) – ein wesentlicher Treiber für die jüngsten Fortschritte bei anspruchsvollen Benchmarks." ], "architecture": [ "Reasoning-Modelle sind in der Regel darauf trainiert, vor einer endgültigen Antwort eine lange interne Argumentation zu führen, was oft durch Reinforcement Learning verstärkt wird, das korrekte Ergebnisse belohnt. Bei der Inferenz bedeuten mehr „Thinking“-Token im Allgemeinen bessere Antworten auf schwierige Probleme.", "In agentischen Systemen dienen Reasoning-Modelle als starke Planer und Entscheidungsträger, während günstigere, schnellere Modelle Routineaufgaben übernehmen können. Das Routing zwischen ihnen je nach Aufgabenschwierigkeit ist ein gängiges Muster zur Kostenkontrolle." ], "components": [ "Erweiterte Argumentation (Thinking-Token)", "Test-Time-Compute-Budget", "RL-basiertes Training für Reasoning", "Extraktion der endgültigen Antwort" ], "pros": [ "Höhere Genauigkeit bei komplexen, mehrstufigen Problemen.", "Stark in Mathematik, Coding und Planung.", "Der Reasoning-Aufwand kann pro Abfrage skaliert werden.", "Gute Planer als Kern leistungsfähiger Agenten." ], "risks": [ "Höhere Latenz und Token-Kosten.", "Überdimensioniert – und verschwenderisch – für einfache Aufgaben.", "Längeres Reasoning führt nicht immer zu korrekteren Ergebnissen.", "Internes Reasoning lässt sich oft nur schwer auditieren oder wortwörtlich vertrauen." ], "tools": [ "Reasoning-Modellstufen führender Anbieter", "Einstellbare Einstellungen für den Reasoning-Aufwand", "Modell-Routing nach Aufgabenschwierigkeit", "Evaluations-Suites" ], "examples": [ "Lösen eines mehrstufigen mathematischen oder logischen Problems, an dem ein Standardmodell scheitert.", "Planen einer komplexen Agenten-Aufgabe vor der Ausführung.", "Routing nur schwieriger Tickets an ein Reasoning-Modell zur Kostenkontrolle." ], "faqs": [ { "q": "Wie unterscheiden sich Reasoning-Modelle von Standard-LLMs?", "a": "Sie sind darauf trainiert und konfiguriert, vor der Antwort ausführlich nachzudenken (Reasoning), wodurch sie bei schwierigen Problemen mehr Inferenz-Rechenleistung aufwenden, anstatt in nahezu konstanter Zeit zu antworten." }, { "q": "Was ist Test-Time Compute?", "a": "Rechenleistung, die während der Inferenz aufgewendet wird (das Modell „denkt“ länger nach), im Gegensatz zur Train-Time Compute, die für die Erstellung des Modells aufgewendet wird. Dies ist ein eigenständiger Weg zur Verbesserung der Ergebnisse." }, { "q": "Sollte ich immer ein Reasoning-Modell verwenden?", "a": "Nein. Sie kosten mehr und verursachen zusätzliche Latenz. Verwenden Sie sie für schwierige, mehrstufige Probleme und leiten Sie einfachere Aufgaben an schnellere, günstigere Modelle weiter." }, { "q": "Verhindern sie Halluzinationen vollständig?", "a": "Nein. Reasoning verbessert die Genauigkeit bei vielen Aufgaben, garantiert jedoch keine Korrektheit; Grounding, Tools und Evaluierung bleiben weiterhin erforderlich." } ] }, "ja": { "title": "推論モデルとは？", "summary": "推論モデルとは、回答する前に「思考」するために追加の計算処理を行うようトレーニングされた言語モデルです。数学、コーディング、論理におけるより困難な問題を解決するために、内部的な推論ステップを生成します。複雑で複数ステップに及ぶタスクにおいて、レイテンシーとコストを引き換えに精度を向上させます。重要なアイデアは「テスト時計算（test-time compute）」です。モデルのサイズを大きくするだけでなく、推論時により長く推論を行わせることで、結果を大幅に改善できます。", "definition": "推論モデルとは、複雑で複数ステップに及ぶ問題の精度を向上させるために、追加のテスト時計算（test-time compute）を使用して、推論時（インファレンス時）に拡張された段階的な推論を実行するように最適化された言語モデルです。", "takeaways": [ "回答する前に、追加の推論計算を使用して「思考」します。", "テスト時計算は、モデルサイズを超えた新しいスケーリング軸です。", "数学、コーディング、論理、および複数ステップの計画に最適です。", "レイテンシーとトークンコストを引き換えに、精度を向上させます。", "単純なタスクには過剰（オーバースペック）です。問題に適したモデルを選択してください。" ], "context": [ "標準的なモデルは、難易度に関係なくほぼ一定の時間で回答します。推論モデルはこれを打破します。内部的な推論の連鎖を生成し、難しい問題に対して効果的により多くの計算処理を費やすことで、複数ステップの演繹が必要なタスクのパフォーマンスを向上させます。", "これにより、第2のスケーリング軸が導入されました。モデルを大きくする（トレーニング時計算）だけでなく、推論時（テスト時計算）により長く推論を行わせることが可能になり、これが困難なベンチマークにおける最近の進歩の大きな原動力となっています。" ], "architecture": [ "推論モデルは通常、最終的な回答の前に長い内部推論を生成するようにトレーニングされ、多くの場合、正しい結果に対して報酬を与える強化学習（RL）によって強化されます。推論時において、一般的に「思考」トークンが多いほど、困難な問題に対してより優れた回答が得られます。", "エージェントシステムにおいて、推論モデルは強力なプランナーおよび意思決定者として機能し、より安価で高速なモデルが日常的なステップを処理します。タスクの難易度に応じてこれらをルーティングすることは、一般的なコスト管理パターンです。" ], "components": [ "拡張された推論（思考トークン）", "テスト時計算バジェット", "強化学習（RL）に基づく推論トレーニング", "最終回答の抽出" ], "pros": [ "複雑で複数ステップに及ぶ問題における高い精度。", "数学、コーディング、計画に強い。", "クエリごとに推論の労力をスケール可能。", "有能なエージェントの核となる優れたプランナー。" ], "risks": [ "高いレイテンシーとトークンコスト。", "単純なタスクには過剰（オーバースペック）であり、無駄が多い。", "推論が長いほど、より正確であるとは限りません。", "内部の推論プロセスは、監査することや、そのまま信頼することが難しい場合があります。" ], "tools": [ "主要プロバイダーが提供する推論モデルのティア", "調整可能な推論エフォート（reasoning-effort）設定", "タスクの難易度に応じたモデルルーティング", "評価スイート" ], "examples": [ "標準的なモデルが躓くような、複数ステップの数学や論理の問題を解決する。", "実行前に複雑なエージェントタスクを計画する。", "コストを抑制するため、難解なチケットのみを推論モデルにルーティングする。" ], "faqs": [ { "q": "推論モデルは標準的なLLMとどう違うのですか？", "a": "ほぼ一定の時間で回答するのではなく、回答する前に時間をかけて推論するようにトレーニングおよび構成されており、難しい問題に対してより多くの推論計算リソースを費やします。" }, { "q": "テスト時計算（test-time compute）とは何ですか？", "a": "モデルの作成に費やされるトレーニング時計算とは異なり、推論時に費やされる計算（モデルがより長く「考える」こと）です。これは、結果を向上させるための明確なアプローチです。" }, { "q": "常に推論モデルを使用すべきですか？", "a": "いいえ。コストが高くなり、レイテンシーも増加します。複数ステップの難しい問題にのみ使用し、よりシンプルなタスクは高速で安価なモデルにルーティングしてください。" }, { "q": "ハルシネーション（幻覚）は解消されますか？", "a": "いいえ。推論によって多くのタスクで正確性は向上しますが、正しさが保証されるわけではありません。グラウンディング、ツール、および評価が引き続き必要です。" } ] }, "zh": { "title": "什么是推理模型？", "summary": "推理模型是经过训练的语言模型，在回答前会消耗额外的计算资源进行“思考”——生成内部推理步骤以解决数学、代码和逻辑方面的更难问题。它们在复杂的多步任务中以延迟和成本换取准确性。其核心思想是测试时计算（test-time compute）：让模型在推理时进行更长时间 of 推理，而不仅仅是把模型做大，这可以显著改善结果。", "definition": "推理模型是经过优化的语言模型，旨在推理阶段执行扩展的分步推理——利用额外的测试时计算（test-time compute）——以提高解决复杂、多步问题的准确性。", "takeaways": [ "它们在回答前进行“思考”，使用额外的推理计算资源。", "测试时计算（test-time compute）是超越模型尺寸的新扩展维度。", "最适合数学、代码、逻辑和多步规划。", "它们以延迟 and Token 成本换取准确性。", "对于简单任务来说是大材小用——应使模型与问题相匹配。" ], "context": [ "标准模型无论问题难易，回答时间大致恒定。推理模型打破了这一常规：它们生成内部推理链，实际上在更难的问题上投入更多计算资源，从而提升了在需要多步推导的任务上的表现。", "这引入了第二个扩展维度。除了将模型做大（训练时计算）之外，您还可以让它们在推理时进行更长时间的推理（测试时计算）——这是近期在困难基准测试上取得进展的主要驱动力。" ], "architecture": [ "推理模型通常经过训练，在给出最终答案之前产生冗长的内部推理，这通常通过奖励正确结果的强化学习（RL）进行巩固。在推理时，更多的“思考”Token 通常意味着在困难问题上能获得更好的答案。", "在智能体系统中，推理模型充当强大的规划者和决策者，而更便宜、更快速的模型则可以处理常规步骤。根据任务难度在它们之间进行路由是一种常见的成本控制模式。" ], "components": [ "扩展推理（思考 Token）", "测试时计算预算", "基于强化学习（RL）的推理训练", "最终答案提取" ], "pros": [ "在复杂、多步问题上具有更高的准确性。", "擅长数学、编程和规划。", "推理工作量可以根据每个查询进行扩展。", "作为高能力智能体核心的优秀规划者。" ], "risks": [ "更高的延迟和 Token 成本。", "对于简单任务来说是大材小用，且造成浪费。", "较长的推理并不总是更正确。", "内部推理可能难以审计，也难以逐字信任。" ], "tools": [ "来自主要供应商的推理模型层级", "可调节的推理力度设置", "按任务难度进行模型路由", "评估套件" ], "examples": [ "解决让标准模型感到棘手的多步骤数学或逻辑问题。", "在执行前规划复杂的智能体任务。", "仅将困难的工单路由到推理模型以控制成本。" ], "faqs": [ { "q": "推理模型与标准 LLM 有何不同？", "a": "它们经过训练和配置，可以在回答前进行长时间的推理，在困难问题上消耗更多的推理算力，而不是在几乎恒定的时间内做出回复。" }, { "q": "什么是测试时算力？", "a": "在推理阶段消耗的计算资源（模型“思考”更长时间），与用于构建模型的训练时算力相对。这是提升效果的一种独特方式。" }, { "q": "我应该一直使用推理模型吗？", "a": "不应该。它们的成本更高且会增加延迟。请将它们用于复杂的、多步骤的问题，并将更简单的任务路由到更快、更便宜的模型。" }, { "q": "它们能消除幻觉吗？", "a": "不能。推理提高了许多任务的准确性，但并不能保证正确性；事实依据（grounding）、工具和评估仍然是必不可少的。" } ] } } }, { "slug": "tool-use", "category": "concept", "updated": "2026-06-24", "version": "1.1", "url": "https://santismm.com/en/knowledge/tool-use", "api": "https://santismm.com/api/knowledge/tool-use", "canonical_url": "https://santismm.com/en/knowledge/tool-use", "api_url": "https://santismm.com/api/knowledge/tool-use", "evidence": { "evidenceLevel": "production", "confidenceLevel": "medium", "sourceType": [ "production_system", "personal_experience", "industry_observation", "paper" ] }, "references": [ { "title": "Schick et al. — Toolformer: Language Models Can Teach Themselves to Use Tools (2023)", "url": "https://arxiv.org/abs/2302.04761" }, { "title": "Anthropic — Tool use (function calling)", "url": "https://docs.anthropic.com/en/docs/build-with-claude/tool-use" } ], "related": [ "ai-agent", "model-context-protocol", "agentic-ai", "harness-engineering" ], "locales": { "en": { "title": "What is Tool Use (Function Calling)?", "summary": "Tool use, also called function calling, lets a language model invoke external functions, APIs or code to fetch information or take actions in the real world. The model decides which tool to call and with what arguments; the application runs the tool and returns the result, which the model uses to continue. Tool use is the bridge that turns a text generator into an agent that can actually do things.", "definition": "Tool use (function calling) is the capability that lets a language model call predefined external functions or APIs, with arguments it generates, and incorporate the results into its response or next step.", "takeaways": [ "Tool use connects a model to live data and real actions.", "The model picks the tool and arguments; the app executes it.", "Clear, well-described tools dramatically improve reliability.", "It is the core mechanism behind agents and MCP.", "Tool access expands capability and the security surface alike." ], "context": [ "On its own a model only produces text. Tool use breaks that boundary: given a set of declared tools, the model can choose to call one — for example a search, a database query or a payment API — and then reason over the result.", "How tools are described matters as much as the model. Tools written for a model to use — clear names, precise parameters, helpful descriptions and error messages — are a central concern of harness engineering." ], "architecture": [ "The loop: the application declares tools (name, description, parameter schema); the model emits a structured tool call; the application validates and executes it; the result returns to the model as an observation; the model continues or answers.", "MCP standardizes how tools are exposed and discovered across applications, so a tool written once can be reused by any compliant client. Guardrails and permissions wrap execution to keep it safe." ], "components": [ "Tool declaration (schema)", "Tool selection (model)", "Argument generation", "Execution layer", "Result / observation", "Guardrails & permissions" ], "pros": [ "Grounds answers in live, real data.", "Lets models take real actions, not just describe them.", "Extends a model without retraining.", "Composes into full agentic workflows." ], "risks": [ "Prompt injection can trigger unintended tool calls.", "Wrong arguments or tool misuse cause real-world errors.", "Over-broad tool access widens the attack surface.", "Latency and cost grow with each tool round-trip." ], "tools": [ "Function calling APIs", "Model Context Protocol (MCP)", "LangGraph / Agents SDKs", "Schema validation (e.g. JSON Schema, Zod)" ], "examples": [ "A model calling a weather API to answer a forecast question.", "An agent querying a database to look up an order before acting.", "A coding agent invoking a test runner and reading the results.", "In practice: an autonomous OpenClaw agent issued 800 tool calls across 10 distinct tools over 57 days — exec (481), web_search (190), write (48), web_fetch (22), read (21) and others — averaging 5.97 tool calls per session. A single-operator local-first deployment, measured from the agent's own traces." ], "faqs": [ { "q": "Is tool use the same as MCP?", "a": "No. Tool use is the model capability to call functions. MCP is a standard for how those tools and data are exposed and discovered across applications." }, { "q": "How do you make tool use reliable?", "a": "Write tools for the model: clear names, precise parameter schemas, useful descriptions and informative errors. Validate arguments and constrain permissions." }, { "q": "What are the security risks?", "a": "Tools are real access. Prompt injection can attempt to trigger harmful calls, so apply least-privilege permissions, validate inputs, and treat tool outputs as untrusted." }, { "q": "Does tool use make a model an agent?", "a": "It is the key enabler. An agent combines tool use with a control loop, memory and a goal so it can act over multiple steps." } ] }, "es": { "title": "¿Qué es el Uso de Herramientas (Function Calling)?", "summary": "El uso de herramientas, también llamado function calling, permite a un modelo de lenguaje invocar funciones, APIs o código externos para obtener información o tomar acciones en el mundo real. El modelo decide qué herramienta llamar y con qué argumentos; la aplicación ejecuta la herramienta y devuelve el resultado, que el modelo usa para continuar. El uso de herramientas es el puente que convierte a un generador de texto en un agente que de verdad hace cosas.", "definition": "El uso de herramientas (function calling) es la capacidad que permite a un modelo de lenguaje llamar a funciones o APIs externas predefinidas, con argumentos que genera, e incorporar los resultados a su respuesta o siguiente paso.", "takeaways": [ "El uso de herramientas conecta un modelo con datos en vivo y acciones reales.", "El modelo elige la herramienta y los argumentos; la aplicación la ejecuta.", "Herramientas claras y bien descritas mejoran mucho la fiabilidad.", "Es el mecanismo central detrás de los agentes y de MCP.", "El acceso a herramientas amplía la capacidad y la superficie de seguridad por igual." ], "context": [ "Por sí solo un modelo solo produce texto. El uso de herramientas rompe esa frontera: dado un conjunto de herramientas declaradas, el modelo puede elegir llamar a una —por ejemplo una búsqueda, una consulta a base de datos o una API de pago— y luego razonar sobre el resultado.", "Cómo se describen las herramientas importa tanto como el modelo. Las herramientas escritas para que las use un modelo —nombres claros, parámetros precisos, descripciones útiles y mensajes de error— son una preocupación central de la ingeniería de harness." ], "architecture": [ "El bucle: la aplicación declara herramientas (nombre, descripción, esquema de parámetros); el modelo emite una llamada estructurada; la aplicación la valida y ejecuta; el resultado vuelve al modelo como observación; el modelo continúa o responde.", "MCP estandariza cómo se exponen y descubren las herramientas entre aplicaciones, de modo que una herramienta escrita una vez se reutiliza en cualquier cliente compatible. Los guardarraíles y permisos envuelven la ejecución para mantenerla segura." ], "components": [ "Declaración de herramienta (esquema)", "Selección de herramienta (modelo)", "Generación de argumentos", "Capa de ejecución", "Resultado / observación", "Guardarraíles y permisos" ], "pros": [ "Fundamenta las respuestas en datos reales y en vivo.", "Permite a los modelos tomar acciones reales, no solo describirlas.", "Extiende un modelo sin reentrenarlo.", "Se compone en flujos agénticos completos." ], "risks": [ "La inyección de prompts puede disparar llamadas no deseadas.", "Argumentos erróneos o mal uso de herramientas causan errores reales.", "Un acceso demasiado amplio a herramientas amplía la superficie de ataque.", "La latencia y el coste crecen con cada ida y vuelta a una herramienta." ], "tools": [ "APIs de function calling", "Model Context Protocol (MCP)", "LangGraph / SDKs de agentes", "Validación de esquemas (p. ej. JSON Schema, Zod)" ], "examples": [ "Un modelo que llama a una API del tiempo para responder sobre el pronóstico.", "Un agente que consulta una base de datos para buscar un pedido antes de actuar.", "Un agente de programación que invoca un runner de tests y lee los resultados.", "En la práctica: un agente autónomo OpenClaw realizó 800 llamadas a herramientas entre 10 herramientas distintas en 57 días — exec (481), web_search (190), write (48), web_fetch (22), read (21) y otras — con una media de 5,97 llamadas por sesión. Despliegue local-first mono-operador, medido desde las propias trazas del agente." ], "faqs": [ { "q": "¿El uso de herramientas es lo mismo que MCP?", "a": "No. El uso de herramientas es la capacidad del modelo de llamar a funciones. MCP es un estándar de cómo se exponen y descubren esas herramientas y datos entre aplicaciones." }, { "q": "¿Cómo se hace fiable el uso de herramientas?", "a": "Escribiendo las herramientas para el modelo: nombres claros, esquemas de parámetros precisos, descripciones útiles y errores informativos. Validar argumentos y limitar permisos." }, { "q": "¿Cuáles son los riesgos de seguridad?", "a": "Las herramientas son acceso real. La inyección de prompts puede intentar disparar llamadas dañinas, así que aplica permisos de mínimo privilegio, valida entradas y trata las salidas como no confiables." }, { "q": "¿El uso de herramientas convierte a un modelo en agente?", "a": "Es el habilitador clave. Un agente combina el uso de herramientas con un bucle de control, memoria y un objetivo para actuar en varios pasos." } ] }, "pt": { "title": "O que é Uso de Ferramentas (Function Calling)?", "summary": "O uso de ferramentas, também chamado function calling, permite a um modelo de linguagem invocar funções, APIs ou código externos para obter informação ou tomar ações no mundo real. O modelo decide qual ferramenta chamar e com quais argumentos; a aplicação executa a ferramenta e devolve o resultado, que o modelo usa para continuar. O uso de ferramentas é a ponte que transforma um gerador de texto num agente que de fato faz coisas.", "definition": "O uso de ferramentas (function calling) é a capacidade que permite a um modelo de linguagem chamar funções ou APIs externas predefinidas, com argumentos que gera, e incorporar os resultados à sua resposta ou próximo passo.", "takeaways": [ "O uso de ferramentas conecta um modelo a dados ao vivo e ações reais.", "O modelo escolhe a ferramenta e os argumentos; a aplicação a executa.", "Ferramentas claras e bem descritas melhoram muito a confiabilidade.", "É o mecanismo central por trás dos agentes e do MCP.", "O acesso a ferramentas amplia a capacidade e a superfície de segurança igualmente." ], "context": [ "Sozinho, um modelo só produz texto. O uso de ferramentas quebra essa fronteira: dado um conjunto de ferramentas declaradas, o modelo pode escolher chamar uma — por exemplo uma busca, uma consulta a banco de dados ou uma API de pagamento — e então raciocinar sobre o resultado.", "Como as ferramentas são descritas importa tanto quanto o modelo. Ferramentas escritas para um modelo usar — nomes claros, parâmetros precisos, descrições úteis e mensagens de erro — são uma preocupação central da engenharia de harness." ], "architecture": [ "O laço: a aplicação declara ferramentas (nome, descrição, esquema de parâmetros); o modelo emite uma chamada estruturada; a aplicação a valida e executa; o resultado retorna ao modelo como observação; o modelo continua ou responde.", "O MCP padroniza como as ferramentas são expostas e descobertas entre aplicações, de modo que uma ferramenta escrita uma vez é reutilizada por qualquer cliente compatível. Guard-rails e permissões envolvem a execução para mantê-la segura." ], "components": [ "Declaração de ferramenta (esquema)", "Seleção de ferramenta (modelo)", "Geração de argumentos", "Camada de execução", "Resultado / observação", "Guard-rails e permissões" ], "pros": [ "Fundamenta as respostas em dados reais e ao vivo.", "Permite aos modelos tomar ações reais, não só descrevê-las.", "Estende um modelo sem retreiná-lo.", "Compõe-se em fluxos agênticos completos." ], "risks": [ "A injeção de prompts pode disparar chamadas indesejadas.", "Argumentos errados ou mau uso de ferramentas causam erros reais.", "Um acesso amplo demais a ferramentas amplia a superfície de ataque.", "A latência e o custo crescem a cada ida e volta a uma ferramenta." ], "tools": [ "APIs de function calling", "Model Context Protocol (MCP)", "LangGraph / SDKs de agentes", "Validação de esquemas (ex.: JSON Schema, Zod)" ], "examples": [ "Um modelo que chama uma API de clima para responder sobre a previsão.", "Um agente que consulta um banco de dados para buscar um pedido antes de agir.", "Um agente de programação que invoca um runner de testes e lê os resultados.", "Na prática: um agente autônomo OpenClaw fez 800 chamadas de ferramentas entre 10 ferramentas distintas em 57 dias — exec (481), web_search (190), write (48), web_fetch (22), read (21) e outras — com média de 5,97 chamadas por sessão. Implantação local-first de operador único, medida a partir dos próprios rastros do agente." ], "faqs": [ { "q": "O uso de ferramentas é o mesmo que MCP?", "a": "Não. O uso de ferramentas é a capacidade do modelo de chamar funções. O MCP é um padrão de como essas ferramentas e dados são expostos e descobertos entre aplicações." }, { "q": "Como tornar o uso de ferramentas confiável?", "a": "Escrevendo as ferramentas para o modelo: nomes claros, esquemas de parâmetros precisos, descrições úteis e erros informativos. Validar argumentos e limitar permissões." }, { "q": "Quais são os riscos de segurança?", "a": "Ferramentas são acesso real. A injeção de prompts pode tentar disparar chamadas nocivas, então aplique permissões de privilégio mínimo, valide entradas e trate as saídas como não confiáveis." }, { "q": "O uso de ferramentas torna um modelo um agente?", "a": "É o habilitador-chave. Um agente combina o uso de ferramentas com um laço de controle, memória e um objetivo para agir em vários passos." } ] }, "fr": { "title": "Qu'est-ce que l'utilisation d'outils (Function Calling) ?", "summary": "L'utilisation d'outils, également appelée appel de fonction (function calling), permet à un modèle de langage d'invoquer des fonctions externes, des API ou du code pour récupérer des informations ou entreprendre des actions dans le monde réel. Le modèle décide quel outil appeler et avec quels arguments ; l'application exécute l'outil et renvoie le résultat, que le modèle utilise pour continuer. L'utilisation d'outils est la passerelle qui transforme un générateur de texte en un agent capable d'agir concrètement.", "definition": "L'utilisation d'outils (function calling) est la capacité qui permet à un modèle de langage d'appeler des fonctions ou des API externes prédéfinies, avec des arguments qu'il génère, et d'intégrer les résultats dans sa réponse ou son étape suivante.", "takeaways": [ "L'utilisation d'outils connecte un modèle à des données en direct et à des actions réelles.", "Le modèle choisit l'outil et les arguments ; l'application l'exécute.", "Des outils clairs et bien décrits améliorent considérablement la fiabilité.", "C'est le mécanisme central derrière les agents et le protocole MCP.", "L'accès aux outils élargit à la fois les capacités et la surface de sécurité." ], "context": [ "Seul, un modèle ne produit que du texte. L'utilisation d'outils brise cette frontière : face à un ensemble d'outils déclarés, le modèle peut choisir d'en appeler un — par exemple une recherche, une requête de base de données ou une API de paiement — puis de raisonner sur le résultat.", "La manière dont les outils sont décrits importe tout autant que le modèle. Les outils écrits pour être utilisés par un modèle — noms clairs, paramètres précis, descriptions utiles et messages d'erreur — sont au cœur des préoccupations de Harness Engineering." ], "architecture": [ "La boucle : l'application déclare les outils (nom, description, schéma des paramètres) ; le modèle émet un appel d'outil structuré ; l'application le valide et l'exécute ; le résultat est renvoyé au modèle sous forme d'observation ; le modèle continue ou répond.", "Le protocole MCP standardise la manière dont les outils sont exposés et découverts à travers les applications, de sorte qu'un outil écrit une fois puisse être réutilisé par n'importe quel client conforme. Des garde-fous (guardrails) et des permissions encadrent l'exécution pour garantir sa sécurité." ], "components": [ "Déclaration de l'outil (schéma)", "Sélection de l'outil (modèle)", "Génération d'arguments", "Couche d'exécution", "Résultat / observation", "Garde-fous et permissions" ], "pros": [ "Ancre les réponses dans des données réelles et en direct.", "Permet aux modèles d'entreprendre des actions réelles, et pas seulement de les décrire.", "Étend un modèle sans réentraînement.", "S'intègre dans des flux de travail (workflows) agentiques complets." ], "risks": [ "L'injection de requêtes (prompt injection) peut déclencher des appels d'outils involontaires.", "Des arguments erronés ou une mauvaise utilisation des outils provoquent des erreurs dans le monde réel.", "Un accès trop large aux outils élargit la surface d'attaque.", "La latence et le coût augmentent à chaque aller-retour d'outil." ], "tools": [ "API d'appel de fonction (function calling)", "Model Context Protocol (MCP)", "SDK LangGraph / Agents", "Validation de schéma (ex. JSON Schema, Zod)" ], "examples": [ "Un modèle appelant une API météo pour répondre à une question sur les prévisions.", "Un agent interrogeant une base de données pour rechercher une commande avant d'agir.", "Un agent de codage invoquant un exécuteur de tests et lisant les résultats.", "En pratique : un agent autonome OpenClaw a émis 800 appels d'outils sur 10 outils distincts en 57 jours — exec (481), web_search (190), write (48), web_fetch (22), read (21) et autres — avec une moyenne de 5,97 appels d'outils par session. Un déploiement local-first à opérateur unique, mesuré à partir des propres traces de l'agent." ], "faqs": [ { "q": "L'utilisation d'outils est-elle identique au protocole MCP ?", "a": "Non. L'utilisation d'outils est la capacité du modèle à appeler des fonctions. Le protocole MCP est un standard définissant la manière dont ces outils et données sont exposés et découverts à travers les applications." }, { "q": "Comment fiabiliser l'utilisation d'outils ?", "a": "Écrivez des outils adaptés au modèle : des noms clairs, des schémas de paramètres précis, des descriptions utiles et des erreurs informatives. Validez les arguments et limitez les permissions." }, { "q": "Quels sont les risques de sécurité ?", "a": "Les outils constituent des accès réels. L'injection de requêtes (prompt injection) peut tenter de déclencher des appels malveillants ; appliquez donc le principe du moindre privilège, validez les entrées et traitez les sorties des outils comme non fiables." }, { "q": "L'utilisation d'outils fait-elle d'un modèle un agent ?", "a": "C'est le catalyseur clé. Un agent combine l'utilisation d'outils avec une boucle de contrôle, une mémoire et un objectif afin de pouvoir agir sur plusieurs étapes." } ] }, "de": { "title": "Was ist Tool Use (Function Calling)?", "summary": "Tool Use, auch Function Calling genannt, ermöglicht es einem Sprachmodell, externe Funktionen, APIs oder Code aufzurufen, um Informationen abzurufen oder Aktionen in der realen Welt auszuführen. Das Modell entscheidet, welches Tool mit welchen Argumenten aufgerufen wird; die Anwendung führt das Tool aus und gibt das Ergebnis zurück, das das Modell zur Fortsetzung verwendet. Tool Use ist die Brücke, die einen Textgenerator in einen Agenten verwandelt, der tatsächlich handeln kann.", "definition": "Tool Use (Function Calling) ist die Fähigkeit, die es einem Sprachmodell ermöglicht, vordefinierte externe Funktionen oder APIs mit selbst generierten Argumenten aufzurufen und die Ergebnisse in seine Antwort oder den nächsten Schritt einzubinden.", "takeaways": [ "Tool Use verbindet ein Modell mit Live-Daten und realen Aktionen.", "Das Modell wählt das Tool und die Argumente aus; die App führt es aus.", "Klare, gut beschriebene Tools verbessern die Zuverlässigkeit drastisch.", "Es ist der Kernmechanismus hinter Agenten und MCP.", "Der Zugriff auf Tools erweitert sowohl die Fähigkeiten als auch die Sicherheitsangriffsfläche." ], "context": [ "Für sich genommen erzeugt ein Modell nur Text. Tool Use durchbricht diese Grenze: Ausgestattet mit einer Reihe deklarierter Tools kann das Modell entscheiden, eines davon aufzurufen – beispielsweise eine Suche, eine Datenbankabfrage oder eine Zahlungs-API – und anschließend über das Ergebnis nachdenken.", "Wie Tools beschrieben werden, ist ebenso wichtig wie das Modell selbst. Tools, die für die Nutzung durch ein Modell entwickelt wurden – mit klaren Namen, präzisen Parametern, hilfreichen Beschreibungen und Fehlermeldungen –, sind ein zentrales Anliegen von Harness Engineering." ], "architecture": [ "Der Kreislauf: Die Anwendung deklariert Tools (Name, Beschreibung, Parameterschema); das Modell gibt einen strukturierten Tool-Aufruf aus; die Anwendung validiert und führt ihn aus; das Ergebnis wird als Beobachtung an das Modell zurückgegeben; das Modell fährt fort oder antwortet.", "MCP standardisiert, wie Tools anwendungsübergreifend bereitgestellt und erkannt werden, sodass ein einmal geschriebenes Tool von jedem kompatiblen Client wiederverwendet werden kann. Guardrails und Berechtigungen sichern die Ausführung ab." ], "components": [ "Tool-Deklaration (Schema)", "Tool-Auswahl (Modell)", "Argumentgenerierung", "Ausführungsschicht", "Ergebnis / Beobachtung", "Guardrails & Berechtigungen" ], "pros": [ "Fundiert Antworten in echten Live-Daten.", "Ermöglicht es Modellen, reale Aktionen auszuführen, statt sie nur zu beschreiben.", "Erweitert ein Modell ohne erneutes Training.", "Lässt sich zu vollständigen agentischen Workflows zusammensetzen." ], "risks": [ "Prompt-Injection kann unbeabsichtigte Tool-Aufrufe auslösen.", "Falsche Argumente oder Tool-Missbrauch verursachen Fehler in der realen Welt.", "Zu weitreichender Tool-Zugriff vergrößert die Angriffsfläche.", "Latenz und Kosten steigen mit jedem Tool-Roundtrip." ], "tools": [ "Function-Calling-APIs", "Model Context Protocol (MCP)", "LangGraph / Agents SDKs", "Schema-Validierung (z. B. JSON Schema, Zod)" ], "examples": [ "Ein Modell, das eine Wetter-API aufruft, um eine Frage zur Vorhersage zu beantworten.", "Ein Agent, der eine Datenbank abfragt, um eine Bestellung nachzuschlagen, bevor er handelt.", "Ein Coding-Agent, der einen Test-Runner aufruft und die Ergebnisse liest.", "In der Praxis: Ein autonomer OpenClaw-Agent führte über 57 Tage hinweg 800 Tool-Aufrufe über 10 verschiedene Tools aus – exec (481), web_search (190), write (48), web_fetch (22), read (21) und andere – mit durchschnittlich 5,97 Tool-Aufrufen pro Sitzung. Ein Local-First-Deployment mit nur einem Operator, gemessen anhand der eigenen Traces des Agenten." ], "faqs": [ { "q": "Ist Tool Use dasselbe wie MCP?", "a": "Nein. Tool Use ist die Fähigkeit des Modells, Funktionen aufzurufen. MCP ist ein Standard dafür, wie diese Tools und Daten anwendungsübergreifend bereitgestellt und erkannt werden." }, { "q": "Wie macht man Tool Use zuverlässig?", "a": "Entwickeln Sie Tools speziell für das Modell: klare Namen, präzise Parameterschemata, nützliche Beschreibungen und informative Fehlermeldungen. Validieren Sie Argumente und schränken Sie Berechtigungen ein." }, { "q": "Welche Sicherheitsrisiken gibt es?", "a": "Tools bedeuten echten Zugriff. Prompt-Injection kann versuchen, schädliche Aufrufe auszulösen. Wenden Sie daher das Prinzip der minimalen Rechtevergabe an, validieren Sie Eingaben und behandeln Sie Tool-Ausgaben als nicht vertrauenswürdig." }, { "q": "Macht Tool Use ein Modell zu einem Agenten?", "a": "Es ist der entscheidende Wegbereiter. Ein Agent kombiniert Tool Use mit einer Kontrollschleife, einem Gedächtnis und einem Ziel, um über mehrere Schritte hinweg agieren zu können." } ] }, "ja": { "title": "ツール利用（Function Calling）とは何ですか？", "summary": "ファンクションコーリング（function calling）とも呼ばれるツール利用（tool use）は、言語モデルが外部の関数、API、またはコードを呼び出して、情報を取得したり現実世界でアクションを実行したりできるようにする機能です。モデルはどのツールをどのような引数で呼び出すかを決定し、アプリケーションがそのツールを実行して結果を返します。モデルはその結果を使用して処理を継続します。ツール利用は、テキスト生成AIを、実際にアクションを実行できるエージェントへと変える架け橋となります。", "definition": "ツール利用（ファンクションコーリング）とは、言語モデルが事前に定義された外部の関数やAPIを、自身が生成した引数を用いて呼び出し、その結果を自身の回答や次のステップに組み込むことができる機能です。", "takeaways": [ "ツール利用は、モデルをライブデータや実際のアクションに接続します。", "モデルがツールと引数を選択し、アプリケーションがそれを実行します。", "明確で十分に説明されたツールは、信頼性を劇的に向上させます。", "これは、エージェントやMCP（Model Context Protocol）の背後にある中核的なメカニズムです。", "ツールへのアクセスは、機能を拡張すると同時に、セキュリティの攻撃対象領域（アタックサーフェス）も広げます。" ], "context": [ "モデル単体ではテキストを生成することしかできません。ツール利用はその境界を打ち破ります。宣言されたツール群が与えられると、モデルは検索、データベースクエリ、決済APIなどのいずれかを呼び出すことを選択し、その結果に基づいて推論を行うことができます。", "ツールがどのように記述されているかは、モデルそのものと同じくらい重要です。モデルが使用するために作成されたツール（明確な名前、正確なパラメータ、役立つ説明、エラーメッセージなど）は、ハーネスエンジニアリング (Harness Engineering) の中心的な関心事です。" ], "architecture": [ "ループ：アプリケーションがツール（名前、説明、パラメータスキーマ）を宣言し、モデルが構造化されたツール呼び出しを出力します。アプリケーションはそれを検証して実行し、結果がオブザベーション（観測結果）としてモデルに返され、モデルは処理を継続するか回答を出力します。", "MCPは、アプリケーション間でツールを公開および検出する方法を標準化するため、一度作成したツールを準拠する任意のクライアントで再利用できます。ガードレールと権限が実行を包み込み、安全性を維持します。" ], "components": [ "ツールの宣言（スキーマ）", "ツールの選択（モデル）", "引数の生成", "実行レイヤー", "結果 / オブザベーション（観測結果）", "ガードレールと権限" ], "pros": [ "回答をライブのリアルなデータにグラウンディング（根拠付け）します。", "モデルにアクションを説明させるだけでなく、実際のアクションを実行させることができます。", "再トレーニングなしでモデルを拡張します。", "完全なエージェント型ワークフローへと構成できます。" ], "risks": [ "プロンプトインジェクションにより、意図しないツール呼び出しがトリガーされる可能性があります。", "誤った引数やツールの誤用は、現実世界でのエラーを引き起こします。", "広すぎるツールアクセス権限は、攻撃対象領域（アタックサーフェス）を広げます。", "ツールのラウンドトリップごとに、レイテンシーとコストが増加します。" ], "tools": [ "ファンクションコーリングAPI", "Model Context Protocol (MCP)", "LangGraph / Agents SDK", "スキーマ検証（例：JSON Schema、Zod）" ], "examples": [ "モデルが天気APIを呼び出して、予報に関する質問に回答する。", "エージェントがアクションを実行する前に、データベースにクエリを実行して注文を検索する。", "コーディングエージェントがテストランナーを起動し、その結果を読み取る。", "実践例：自律型のOpenClawエージェントは、57日間にわたり10個の異なるツールに対して800回のツール呼び出しを実行しました。内訳は、exec（481回）、web_search（190回）、write（48回）、web_fetch（22回）、read（21回）などであり、1セッションあたり平均5.97回のツール呼び出しでした。これは、エージェント自身のトレースから測定された、シングルオペレーターによるローカルファーストのデプロイメントにおける数値です。" ], "faqs": [ { "q": "ツール利用はMCPと同じですか？", "a": "いいえ。ツール利用は、関数を呼び出すためのモデルの機能です。MCPは、それらのツールやデータがアプリケーション間でどのように公開され、検出されるかを定義する標準規格です。" }, { "q": "ツール利用の信頼性を高めるにはどうすればよいですか？", "a": "モデル向けにツールを作成します。明確な名前、正確なパラメータスキーマ、役立つ説明、有益なエラーメッセージを用意します。また、引数を検証し、権限を制限します。" }, { "q": "セキュリティ上のリスクは何ですか？", "a": "ツールは実際のアクセス権限を持ちます。プロンプトインジェクションによって有害な呼び出しが試みられる可能性があるため、最小特権の原則を適用し、入力を検証し、ツールの出力を信頼できないものとして扱ってください。" }, { "q": "ツールを利用すれば、モデルはエージェントになりますか？", "a": "ツール利用は重要なイネーブラー（実現要素）です。エージェントは、ツール利用に制御ループ、メモリ、および目標を組み合わせることで、複数のステップにわたって行動できるようになります。" } ] }, "zh": { "title": "什么是工具使用（函数调用）？", "summary": "工具使用（也称为函数调用）允许语言模型调用外部函数、API 或代码，以获取信息或在现实世界中执行操作。模型决定调用哪个工具以及使用什么参数；应用程序运行该工具并返回结果，模型利用该结果继续执行。工具使用是将文本生成器转变为能够实际执行任务的智能体的桥梁。", "definition": "工具使用（函数调用）是指允许语言模型调用预定义的外部函数或 API（使用其生成的参数），并将结果整合到其响应或下一步骤中的能力。", "takeaways": [ "工具使用将模型与实时数据 and 实际操作连接起来。", "模型选择工具和参数；应用程序执行该工具。", "清晰、描述详尽的工具可以显著提高可靠性。", "它是智能体和 MCP 背后的核心机制。", "工具访问在扩展能力的同时，也扩大了安全攻击面。" ], "context": [ "模型本身只能生成文本。工具使用打破了这一界限：在给定一组声明的工具后，模型可以选择调用其中一个（例如搜索、数据库查询或支付 API），然后对结果进行推理。", "工具的描述方式与模型本身同样重要。为模型使用而编写的工具——清晰的名称、精确的参数、有用的描述和错误信息——是 Harness Engineering（智能体支撑系统工程）的核心关注点。" ], "architecture": [ "循环过程：应用程序声明工具（名称、描述、参数 Schema）；模型发出结构化的工具调用；应用程序对其进行验证和执行；结果作为观测值（observation）返回给模型；模型继续执行或做出回答。", "MCP 标准化了跨应用程序公开和发现工具的方式，因此编写一次的工具可以被任何兼容的客户端复用。护栏（Guardrails）和权限封装了执行过程以确保其安全。" ], "components": [ "工具声明（Schema）", "工具选择（模型）", "参数生成", "执行层", "结果 / 观测值", "护栏与权限" ], "pros": [ "使回答基于实时的真实数据。", "允许模型采取实际行动，而不仅仅是描述它们。", "无需重新训练即可扩展模型能力。", "组合成完整的智能体工作流。" ], "risks": [ "提示词注入可能会触发非预期的工具调用。", "错误的参数或工具误用会导致现实世界中的错误。", "过宽的工具访问权限会扩大攻击面。", "延迟和成本随着每次工具往返而增加。" ], "tools": [ "函数调用 API", "Model Context Protocol (MCP)", "LangGraph / 智能体 SDK", "Schema 验证（例如 JSON Schema、Zod）" ], "examples": [ "模型调用天气 API 来回答天气预报问题。", "智能体在采取行动前查询数据库以查找订单。", "编码智能体调用测试运行器并读取结果。", "实践案例：一个自主的 OpenClaw 智能体在 57 天内通过 10 个不同的工具发起了 800 次工具调用——包括 exec (481)、web_search (190)、write (48)、web_fetch (22)、read (21) 等——平均每个会话进行 5.97 次工具调用。这是一个单操作员、本地优先的部署，数据源自该智能体自身的追踪记录。" ], "faqs": [ { "q": "工具使用和 MCP 是一回事吗？", "a": "不是。工具使用是模型调用函数的能力。而 MCP 是一种标准，用于规范如何在跨应用程序中公开和发现这些工具和数据。" }, { "q": "如何让工具使用更可靠？", "a": "为模型编写工具：清晰的名称、精确的参数 Schema、有用的描述和信息丰富的错误提示。验证参数并限制权限。" }, { "q": "安全风险有哪些？", "a": "工具代表着真实的访问权限。提示词注入可能会尝试触发有害的调用，因此请应用最小特权原则、验证输入，并将工具输出视为不可信内容。" }, { "q": "工具使用能让模型成为智能体吗？", "a": "它是关键的赋能因素。智能体将工具使用与控制循环、记忆和目标相结合，从而能够跨多个步骤采取行动。" } ] } } } ] }