Open Agent SDK: So funktionieren die 34 integrierten Tools im Detail

Das Open Agent SDK setzt auf eine ausgeklügelte Architektur, um große Sprachmodelle (LLMs) mit präzisen Funktionen zu verbinden. Im Mittelpunkt steht ein System aus 34 vordefinierten Tools, die je nach Bedarf aufgerufen werden können. Doch wie sind diese Tools organisiert? Welche Sicherheitsmechanismen steuern ihre Ausführung? Und wie kommunizieren sie mit der Laufzeitumgebung des SDKs?

Dieser zweite Teil der Deep-Dive-Serie beleuchtet die technische Grundlage des Tool-Systems – von der Protokolldefinition bis zur dynamischen Integration in den Agent-Loop.

ToolProtocol: Die Blaupause für jedes Tool

Jedes Tool im Open Agent SDK folgt dem ToolProtocol-Protokoll, das sechs zentrale Komponenten definiert. Dieses Protokoll dient als Schnittstelle zwischen den Tools und dem Agent-Loop, der die Ausführung steuert.

public protocol ToolProtocol: Sendable {
    var name: String { get }
    var description: String { get }
    var inputSchema: ToolInputSchema { get }
    var isReadOnly: Bool { get }
    var annotations: ToolAnnotations? { get }
    func call(input: Any, context: ToolContext) async -> ToolResult
}

Die fünf Eigenschaften und die Methode call bestimmen, wie ein Tool mit der Umgebung interagiert:

• `name` ist der eindeutige Bezeichner des Tools, den das LLM in tool_use-Blöcken referenziert. Alle eingebauten Tools nutzen die PascalCase-Konvention, etwa Read, Bash oder Glob.
• `description` liefert eine textuelle Erklärung des Tools, die an das LLM übermittelt wird. Diese Beschreibung beeinflusst maßgeblich, ob und wann das LLM ein Tool auswählt.
• `inputSchema` definiert die erwartete Eingabestruktur im JSON-Format. Das Schema wird direkt an die API übergeben und validiert die Eingabedaten.
• `isReadOnly` markiert, ob ein Tool Seiteneffekte hat. Der Agent-Loop nutzt diese Information, um parallele oder serielle Ausführungen zu steuern.
• `annotations` sind optionale Metadaten, die dem LLM Hinweise zur sicheren Nutzung geben. Dazu gehören:
• readOnlyHint – Tool hat keine Seiteneffekte.
• destructiveHint – Tool könnte irreversible Änderungen vornehmen (Standard: true).
• idempotentHint – Mehrfache Aufrufe führen zum gleichen Ergebnis.
• openWorldHint – Tool interagiert mit externen Systemen.

Die Methode call führt die eigentliche Aktion aus und gibt ein ToolResult zurück, das an das LLM weitergeleitet wird. Dieses Ergebnis enthält:

• toolUseId – Korreliert mit der Anfrage des LLMs.
• content – Textausgabe oder Fehlermeldung.
• typedContent – Unterstützt multimodale Inhalte wie Bilder oder Ressourcenverweise.
• isError – Kennzeichnet, ob die Ausführung fehlgeschlagen ist.

Die Kompatibilität zwischen content und typedContent stellt sicher, dass bestehende Implementierungen weiterhin funktionieren, während neue Tools erweiterte Inhalte nutzen können.

ToolContext: Die Laufzeitumgebung eines Tools

Jedes Tool erhält bei der Ausführung einen ToolContext, der Zugriff auf relevante Laufzeitdaten und Speicherorte bietet. Statt alle Felder zu füllen, injiziert das SDK nur die benötigten Informationen – ein Prinzip, das die Effizienz und Sicherheit erhöht.

Zu den wichtigsten Feldern gehören:

• cwd – Aktuelles Arbeitsverzeichnis.
• toolUseId – Eindeutige Kennung der Tool-Ausführung.
• sandbox – Sandbox-Einstellungen für isolierte Ausführung.
• fileCache – Zwischenspeicher für Dateizugriffe.
• env – Benutzerdefinierte Umgebungsvariablen.

Spezialisierte Tools greifen auf spezifische Stores zu, etwa cronStore für geplante Aufgaben oder worktreeStore für Arbeitsbereiche. Diese Trennung stellt sicher, dass Tools nur auf die Daten zugreifen, die sie benötigen.

Zusätzlich bietet ToolContext Methoden wie withToolUseId zur Aktualisierung der Ausführungskennung und withSkillContext für verschachtelte Skill-Aufrufe.

Die drei Ebenen der Tool-Architektur

Die 34 eingebauten Tools sind in drei Kategorien unterteilt, die ihre Komplexität und ihren Anwendungsbereich widerspiegeln:

Kern-Tools (10 Tools)

Diese Tools decken grundlegende Funktionen ab, die für die meisten Agenten unverzichtbar sind:

• Read – Liest Dateiinhalte.
• Write – Schreibt in Dateien.
• Edit – Bearbeitet Dateien.
• Glob – Durchsucht Dateien nach Mustern.
• Config – Verwaltet Konfigurationen.
• AskUser – Fordert Benutzereingaben an.
• ToolSearch – Sucht nach Tools.
• EnterPlanMode / ExitPlanMode – Aktiviert oder deaktiviert den Planungsmodus.
• EnterWorktree / ExitWorktree – Wechselt zwischen Arbeitsbereichen.

Fortgeschrittene Tools (11 Tools)

Diese Tools erweitern die Funktionalität für komplexere Szenarien:

• Agent – Erstellt und steuert Sub-Agenten.
• Skill – Fügt dem Agenten neue Fähigkeiten hinzu.
• Bash – Führt Shell-Befehle aus.
• TaskCreate / TaskGet / TaskList / TaskOutput / TaskUpdate / TaskStop – Verwaltet Aufgaben.
• WebFetch / WebSearch – Führt Webanfragen durch.
• SendMessage – Sendet Nachrichten.
• TeamCreate / TeamDelete – Verwaltet Teams.
• ListMcpRes / ReadMcpRes – Listet oder liest MCP-Ressourcen.

Spezialisierte Tools (13 Tools)

Diese Tools adressieren spezifische Anwendungsfälle:

• CronCreate / CronDelete / CronList – Verwaltet cron-Jobs.
• LSP – Integriert Language Server Protocol.
• Grep – Sucht nach Textmustern in Dateien.
• NotebookEdit – Bearbeitet Notizbücher.
• RemoteTrigger – Löst Remote-Aktionen aus.
• TodoWrite – Erstellt Todo-Einträge.

Die Einteilung in Ebenen ermöglicht eine klare Trennung der Verantwortlichkeiten und erleichtert die Wartung des SDKs.

Fazit: Ein modulares System für zuverlässige Tool-Integration

Das Tool-System des Open Agent SDK verbindet Flexibilität mit Sicherheit. Durch die klare Protokolldefinition, die granulare Laufzeitumgebung und die strukturierte Tool-Einteilung können Entwickler zuverlässige und erweiterbare Agenten erstellen. Die nächste Herausforderung wird sein, die Integration mit externen APIs und die Skalierung für große Workloads weiter zu optimieren.