Agent Harnesses: Ein Ordnerstandard für Fähigkeiten und Referenzen

Ein Agent-Harness ist eine Methode, um Strukturen um das Verhalten und Denken eines KI-Systems zu legen, sodass ein zugrundeliegendes Modell für viele verschiedene Aufgaben eingesetzt werden kann. Die Idee baut auf einigen früheren Grundlagen auf, daher werden diese zuerst erläutert: Was ein LLM ist, was ein Agent ist, wie Schlussfolgerung und Werkzeugnutzung zusammenhängen sowie welche Fähigkeiten hinzukommen. Wenn das verstanden ist, stellt der Harness selbst nur einen kleinen Schritt dar – bereits eine einfache Ordnerstruktur reicht aus, um ihn zu beschreiben.

Die Grundlagen

Sprachmodelle als Funktionen

Zu diesem Zweck kann ein LLM als Funktion betrachtet werden: Eingabe ist Text, Ausgabe ist ebenfalls Text. Es beschränkt sich darauf, auf Text mit Text zu antworten, doch der Großteil der jüngsten Welle an KI-Produkten basiert auf diesem einzigen Verhalten.

Was als Agent gilt

„Agent“ ist ein weit gefasster Begriff. Wissenschaftliche Arbeiten beschreiben verschiedene Arten von Agenten, die auf grundlegend unterschiedliche Weise funktionieren. Im alltäglichen Gespräch meint jedoch fast jeder dasselbe: ein Chat-System, das eine Nachricht entgegennimmt, etwas verarbeitet und antwortet. Dieses Muster wird üblicherweise als ReAct bezeichnet – eine schmale Schicht Code, die ein Modell mit Funktionalitäten verbindet, damit es reasoningen, handeln und beobachten kann. ReAct ermöglicht es dem Modell, darüber nachzudenken, was es tun wird, eine Aktion auszuwählen, die auf die Umgebung einwirkt, und anschließend eine Beobachtung über das Ergebnis zu erhalten. Alles im Folgenden verwendet den Begriff „Agent“ in diesem reAct-ähnlichen Sinne.

Reasoning und Handeln

Zwei Konzepte stehen hinter dieser Vorgehensweise. Das Schlussfolgern wird in der Regel mithilfe einer Gedankenkette bewältigt, was bedeutet, dass das Modell dazu angeleitet wird, seine Lösung Schritt für Schritt zu entwickeln, bevor es sich auf eine Antwort festlegt. Die Veröffentlichung, die dieses Konzept einführte, tat dies, indem sie ein gelöstes Beispiel in die Anfrage aufnahm – eine Frage, die bei herkömmlicher Ansprache fehlschlug, funktionierte mit derselben Modellversion bereits nach Hinzufügen des Beispiels.

Diese Technik ist mittlerweile so zentral geworden, dass viele Modelle nun darauf trainiert werden, selbstständig eine Gedankenkette zu erstellen. Herkömmliche Modelle neigen dazu, ein Problem gründlich durchzudenken, bevor sie antworten, während die von DeepSeek populär gemachten Schlussfolgerrmodelle eine spezielle Phase haben, in der das Modell ein Problem mit einer sehr langen Gedankenkette bearbeitet.

Der Einsatz von Tools hat eine ähnliche Geschichte: Er existiert bereits seit längerer Zeit, erweist sich stets als nützlich und entwickelt sich zu einem Standard. In seiner einfachsten Form teilt er dem Modell mit, dass, wenn es einen bestimmten Textausschnitt ausgibt, ein bestimmter Code ausgeführt wird und das Ergebnis zurückkommt. Das Modell entscheidet anschließend, wann es im Internet suchen, Dateien durchlesen oder im schlimmsten Fall Geld an einen Ort überweisen soll, an den es nicht sollte. Komplexe Fragen erfordern oft eine Kombination aus Logik und Handlung, und Vergleiche verschiedener Prompting-Strategien zeigen, dass diese Kombination besser ist als jede einzelne Strategie für sich allein.

Fähigkeiten

Im Laufe der Zeit entstehen aus den Praktiken Agenten, während der Einsatz von Tools und das Prompting weiter reifen. Angenommen, ein Agent soll Zeilen in eine Datenbank hinzufügen. Dafür benötigt er Tools, die es dem Modell ermöglichen, die Datenbank zu sehen und darauf zuzugreifen, sowie Prompts, die die Struktur der Datenbank und die verfügbaren Tools beschreiben.

Eine Fähigkeit ist eine standardmäßige Methode, um dieses Bündel zu strukturieren. Informationen und Funktionalitäten werden in eine Einheit zusammengefasst, sodass der Agent sie als vollständiges Paket erhält. Eine Fähigkeit ist ein Ordner:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Die meisten Fähigkeiten sind im Grunde nur Textdateien. Dennoch ermöglichen sie es einem Agenten, komplexe Systeme zu verstehen und zu bedienen, und bieten den Entwicklern von Agenten eine wiederverwendbare, portable Schicht für Pläne und Verfahren.

Was ein Harness ist

Einen Harness kann man am besten als Erweiterung von Fähigkeiten betrachten. Eine Fähigkeit umfasst eine breite Funktionalität wie das Bearbeiten einer Website, die Verwaltung einer Datenbank oder das Verstehen von Kundenfeedback. Ernsthaftere Aufgaben, wie beispielsweise die Unterstützung der Entwickler eines Produkts, können viele Fähigkeiten erfordern, die gemeinsam eingesetzt werden. Ein Harness bündelt mehrere Fähigkeiten zusammen mit den Referenzmaterialien, die der Agent benötigt, um seine Rolle sowie die Umgebung, in der er arbeitet, zu verstehen.

Das Agent Harnesses-Format

Nach diesem vorgeschlagenen Standard besteht ein Harness aus drei Teilen: einer Markdown-Datei, die ihn beschreibt, einer Reihe von Fähigkeiten zur Interaktion mit der Umgebung sowie einer Reihe von Referenzen, die dem Agenten dabei helfen, zu verstehen, wo er arbeitet. Der Standard ist ein öffentlich gepflegtes Open-Source-Projekt.

my-harness/
├── HARNESS.md        # Required: metadata + instructions
├── skills/           # Optional: a set of skills
└── references/       # Optional: a set of reference documents

Die oberste Datei, HARNESS.md, soll kurz sein. Sie gibt dem Agenten ein schnelles Überblicksbild über das Problem und weist darauf hin, wo man detaillierte Informationen in den Fähigkeiten sowie Referenzen findet.

Das Design folgt dem Prinzip der schrittweisen Offenlegung, einem Muster, das kürzlich durch den Agent Skills Standard populär geworden ist. Es erfolgt in drei Phasen:

1. Entdeckung. Beim Start lädt der Agent nur HARNESS.md, das die Struktur des „Harness“ darstellt. Wenn eine Anfrage eintrifft, vergleicht der Agent sie mit diesen Beschreibungen und durchläuft schrittweise die Namen sowie Beschreibungen der Fähigkeiten und Referenzen, bis er das Gewünschte findet.
2. Aktivierung. Sobald relevante Materialien gefunden wurden, wird die vollständige Dokumentation zu diesen Fähigkeiten und Referenzen geladen und gelesen.
3. Ausführung. Der Agent befolgt die Anweisungen des „Harness“ und kann Fähigkeiten ausführen.

Die HARNESS.md-Datei

Ebenso wie bei Fähigkeiten verwendet das Harness Frontmatter – wichtige Informationen, die an den Anfang einer Markdown-Datei gesetzt werden, damit der Agent Ressourcen effizient durchsuchen kann.

---
name: <name of the harness>
description: <description of what the harness is for>
---

<body>

Ein Name und eine Beschreibung sind erforderlich, damit der Agent sofort erkennen kann, um welches Gurtsystem es sich handelt. Der Körperabschnitt enthält eine kurze Erklärung der wichtigsten Elemente und weist den Agenten auf die erforderlichen Fähigkeiten sowie Referenzen hin.

Das Fähigkeitsverzeichnis

In diesem Verzeichnis sind Fähigkeiten enthalten, die dem Agent Skills-Standard entsprechen, der eine solche Fähigkeit wie folgt definiert:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Ein Harness baut darauf auf, sodass der Fähigkeitsverzeichnis wie folgt aussieht:

my-harness/
├── HARNESS.md
├── skills/
|  ├── my-skill-1/
|  |  ├── SKILL.md
|  |  ├── scripts/
|  |  ├── references/
|  |  ├── assets/
|  |  └── ...
|  └── my-skill-2/
|     ├── SKILL.md
|     ├── scripts/
|     ├── references/
|     ├── assets/
|     └── ...
└── references/

Der Referenzordner

Der Referenzordner enthält beliebige Dokumente, die dem Agenten dabei helfen, seine Umgebung, seine Rolle oder andere übergeordnete Kontexte zu verstehen.

Auch Fähigkeiten enthalten Referenzen, und die beiden Ebenen unterscheiden sich in ihrem Umfang. Referenzen innerhalb einer Fähigkeit erklären, wie diese spezifische Fähigkeit verwendet werden soll. Referenzen auf der Ebene des Harness sollten das enthalten, was mehrere Fähigkeiten gemeinsam benötigen, auf einer höheren Abstraktionsstufe.

Nehmen wir einen Agenten, der dazu dient, Marketinginhalte zu erstellen. Er könnte eine Fähigkeit zum Schreiben von Blogartikeln, eine zur Erstellung von Bildern und eine zum Scannen sozialer Medien haben:

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/

Jede Fähigkeit kann ihre eigenen Referenzen haben. Die Fähigkeit zum sozialen Scannen könnte die Konten des Unternehmens auflisten, die Bildverarbeitungsfähigkeit könnte angeben, wo fertige Bilder gespeichert sind, und die Blog-Fähigkeit könnte den Veröffentlichungsprozess beschreiben. Die auf der Harness-Ebene liegenden Referenzen bilden den natürlichen Ort für Elemente, die in allen drei Bereichen verwendet werden, wie beispielsweise Stilrichtlinien und Markenprioritäten:

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/
   ├── style-guide.md
   └── brand-priorities.md

Jeder Inhalt kann im Verzeichnis für Harness-Ebene-Referenzen abgelegt werden, doch es wird dringend empfohlen, Markdown zu verwenden und oben in jeder Datei eine kurze Beschreibung anzufügen, damit ein Agent die Relevanz schnell beurteilen kann. Ein Stilleitfaden in diesem Beispiel könnte wie folgt beginnen:

---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---

<body>

Organisieren eines umfangreichen Harnesses

Ein Harness kann viele Fähigkeiten und Referenzen enthalten. Wenn die Mengen groß genug werden, wird die Wartung verwirrend und das Bereitstellen von Informationen an den Agenten uneffizient.

my-harness/
├── HARNESS.md
├── skills/
|  ├── skill1/
|  ├── skill2/
|  ├── skill3/
|  └── ...
└── references/
   ├── reference1
   ├── reference2
   ├── reference3
   └── ...

Die Antwort sind Unterordner. Sowohl in „Skills“ als auch in „References“ können Ordner Elemente in Untergruppen zusammenfassen:

my-harness/
├── HARNESS.md
├── skills/
│   ├── software-development/
│   │   ├── SKILLS.md
│   │   ├── skill1/
│   │   │   └── SKILL.md
│   │   └── skill2/
│   │       └── SKILL.md
│   ├── market-analysis/
│   │   ├── SKILLS.md
│   │   └── skill3/
│   │       └── SKILL.md
│   └── social-media/
│       ├── SKILLS.md
│       ├── skill4/
│       │   └── SKILL.md
│       └── skill5/
│           └── SKILL.md
└── references/
    ├── brand-assets/
    │   ├── REFERENCES.md
    │   ├── reference1.md
    │   └── reference2.md
    ├── software-infrastructure/
    │   ├── REFERENCES.md
    │   ├── reference3.md
    │   └── reference4.md
    └── product-information/
        ├── REFERENCES.md
        └── reference5.md

Damit der Agent diese Struktur vollständig, aber effizient verstehen kann, sollte HARNESS.md sie beschreiben. Jeder Unterordner enthält außerdem eine beschreibende Datei: SKILLS.md behandelt die Fähigkeiten in einem Unterordner und REFERENCES.md seine Referenzen.

Hier zeigt sich der Vorteil der schrittweisen Offenlegung. Der Agent liest die Datei auf höchster Ebene, um das Gesamtbild zu erfassen, und öffnet anschließend nur dann spezifische SKILLS.md- sowie REFERENCES.md-Dateien, wenn sie benötigt werden – das ist der effizienteste Weg zu den relevanten Inhalten.

Die Verzweigung kann so tief gehen, wie es der Inhalt erfordert, sodass eine umfangreiche Sammlung auf höherer Ebene organisiert werden kann. Jeder Unterordner sollte seine eigene SKILLS.md- oder REFERENCES.md-Datei enthalten, damit der Agent jede Ebene beim Herunterschreiten versteht:

...
└── references/
  └── data-sources/
      ├── REFERENCES.md
      ├── relational/
      │   ├── REFERENCES.md
      │   └── schema-overview.md
      └── warehouse/
          ├── REFERENCES.md
          └── dataset-catalog.md

Warum die Struktur funktioniert

Das Format verlangt vom Autor nur sehr wenig. Alles befindet sich in einer Datei innerhalb eines Verzeichnisses, was bedeutet, dass ein „Harness“ wie jedes andere Projekt versioniert, überprüft und geteilt werden kann. Der Agent muss niemals die gesamte Sammlung laden, denn jede beschreibende Datei dient als kleiner Leitfaden, der entscheidet, ob weitergegangen werden soll. Ein „Harness“ für ein Marketingteam und einer für einen Datenbankadministrator unterscheiden sich nur in ihrem Inhalt, während der Ablauf der Erkennung, Aktivierung und Ausführung identisch bleibt.

Zwei Gewohnheiten sorgen dafür, dass ein „Harness“ funktionsfähig bleibt. Erstens sollte jede Beschreibung so formuliert sein, dass klar ist, wann das Material relevant ist – und nicht nur, was es enthält –, denn allein aus diesem Satz wählt der Agent aus, was geöffnet werden soll. Zweitens sollten die auf „Harness“-Ebene gesetzten Verweise tatsächlich geteilt werden. Wenn ein Dokument sich auf eine einzige Fähigkeit bezieht, gehört es in diese Fähigkeit; seine Aufstufung nach oben fügt lediglich Unordnung in alle anderen Abfragen ein.