Agent-Tool-Builder

Was macht Agent-Tool-Builder?

Werkzeuge sind die Art und Weise, wie KI-Agenten mit der Welt interagieren. Ein gut gestaltetes Werkzeug ist der Unterschied zwischen einem funktionierenden Agenten und einem, der halluziniert, stillschweigend scheitert oder zehnmal mehr Tokens als nötig verbraucht.

Diese Fähigkeit behandelt das Design von Werkzeugen vom Schema bis zur Fehlerbehandlung. Best Practices für JSON-Schema, Beschreibungen, die dem LLM tatsächlich helfen, Validierung und der aufkommende MCP-Standard, der zur Lingua Franca für KI-Werkzeuge wird.

Wichtige Erkenntnis: Tool-Beschreibungen sind wichtiger als Tool-Implementierungen. Das LLM sieht nie Ihren Code – es sieht nur das Schema und die Beschreibung.

Prinzipien

• Beschreibungsqualität > Implementierungsqualität für die LLM-Genauigkeit
• Streben Sie nach weniger als 20 Tools – mehr verursacht Verwirrung
• Jedes Tool benötigt explizite Fehlerbehandlung – stille Fehler vergiften Agenten
• Geben Sie Strings zurück, keine Objekte – LLMs verarbeiten Text
• Validierung vor der Ausführung – ablehnen, korrigieren oder eskalieren, niemals stillschweigend scheitern
• Testen Sie Tools mit dem LLM, nicht nur mit Unit-Tests

Fähigkeiten

• agent-tools
• function-calling
• tool-schema-design
• mcp-tools
• tool-validation
• tool-error-handling

Anwendungsbereich

• multi-agent-coordination → multi-agent-orchestration
• agent-memory → agent-memory-systems
• api-design → api-designer
• llm-prompting → prompt-engineering

Werkzeuge

Standards

• JSON Schema - Wann: Alle Tool-Definitionen Hinweis: Das universelle Format für Tool-Schemata
• MCP (Model Context Protocol) - Wann: Erstellung wiederverwendbarer, plattformübergreifender Tools Hinweis: Offener Standard von Anthropic, weit verbreitet

Frameworks

• Anthropic SDK - Wann: Claude-basierte Agenten Hinweis: Beta-Tool-Runner übernimmt die meiste Komplexität
• OpenAI Functions - Wann: OpenAI-basierte Agenten Hinweis: Strict-Modus für garantierte Schema-Konformität verwenden
• Vercel AI SDK - Wann: Multi-Provider-Tool-Handling Hinweis: Abstrahiert Unterschiede zwischen Anbietern
• LangChain Tools - Wann: LangChain-basierte Agenten Hinweis: Konvertiert MCP-Tools in LangChain-Format

Muster

Tool-Schema-Design

Erstellen klarer, eindeutiger JSON-Schemata für Tools

Wann verwenden: Beim Definieren eines neuen Tools für einen Agenten

BEST PRACTICES FÜR TOOL-SCHEMATA:

1. Detaillierte Beschreibungen (Am Wichtigsten)

SCHLECHT - Zu vage:
{
  "name": "get_stock_price",
  "description": "Ruft Aktienkurs ab",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {"type": "string"}
    }
  }
}

GUT - Umfassend:
{
  "name": "get_stock_price",
  "description": "Ruft den aktuellen Aktienkurs für ein bestimmtes Ticker-Symbol ab. Das Ticker-Symbol muss ein gültiges Symbol für ein börsennotiertes Unternehmen an einer großen US-Börse wie NYSE oder NASDAQ sein. Gibt den letzten Handelskurs in USD zurück. Verwenden, wenn der Benutzer nach aktuellen oder kürzlichen Aktienkursen fragt. Stellt KEINE historischen Daten, Unternehmensinformationen oder Vorhersagen bereit.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Das Aktien-Ticker-Symbol, z.B. AAPL für Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

2. Parameterbeschreibungen

Jeder Parameter benötigt:
- Was es ist
- Erwartetes Format
- Beispielwert
- Randfälle/Einschränkungen

{
  "location": {
    "type": "string",
    "description": "Stadt und Bundesland/Land. Format: 'Stadt, Bundesland' für US (z.B. 'San Francisco, CA') oder 'Stadt, Land' für international (z.B. 'Tokyo, Japan'). Keine PLZ oder Koordinaten verwenden."
  },
  "unit": {
    "type": "string",
    "enum": ["celsius", "fahrenheit"],
    "description": "Temperatureinheit. Standardmäßig auf die Region des Benutzers, falls nicht angegeben. 'fahrenheit' für US-Benutzer, 'celsius' für andere."
  }
}

3. Enums nach Möglichkeit verwenden

Enums schränken das LLM auf gültige Werte ein:

"priority": {
  "type": "string",
  "enum": ["niedrig", "mittel", "hoch", "kritisch"],
  "description": "Aufgabenprioritätsstufe"
}

"action": {
  "type": "string",
  "enum": ["create", "read", "update", "delete"],
  "description": "Die auszuführende CRUD-Operation"
}

4. Erforderlich vs. Optional

Seien Sie explizit darüber, was erforderlich ist:

{
  "type": "object",
  "properties": {
    "query": {...},      // Erforderlich
    "limit": {...},      // Optional mit Standardwert
    "offset": {...}      // Optional
  },
  "required": ["query"],
  "additionalProperties": false  // Strict-Modus
}

Tool mit Eingabebeispielen

Verwendung von Beispielen zur Steuerung der LLM-Tool-Nutzung

Wann verwenden: Komplexe Tools mit verschachtelten Objekten oder formatempfindlichen Eingaben

BEISPIELE FÜR DIE TOOL-NUTZUNG (Anthropic Beta-Funktion):

Beispiele zeigen Claude konkrete Muster, die Schemata nicht ausdrücken können.
Verbessert die Genauigkeit von 72 % auf 90 % bei komplexen Operationen.

{ "name": "create_calendar_event", "description": "Erstellt ein Kalenderereignis mit optionalen Teilnehmern und Erinnerungen", "input_schema": { "type": "object", "properties": { "title": {"type": "string", "description": "Ereignistitel"}, "start_time": { "type": "string", "description": "ISO 8601 Datum/Uhrzeit, z.B. 2024-03-15T14:00:00Z" }, "duration_minutes": {"type": "integer", "description": "Ereignisdauer"}, "attendees": { "type": "array", "items": {"type": "string"}, "description": "E-Mail-Adressen der Teilnehmer" } }, "required": ["title", "start_time", "duration_minutes"] }, "input_examples": [ { "title": "Team Standup", "start_time": "2024-03-15T09:00:00Z", "duration_minutes": 30, "attendees": ["[email protected]", "[email protected]"] }, { "title": "Kurzer Chat", "start_time": "2024-03-15T14:00:00Z", "duration_minutes": 15 }, { "title": "Projektüberprüfung", "start_time": "2024-03-15T16:00:00-05:00", "duration_minutes": 60, "attendees": ["[email protected]"] } ] }

PRINZIPIEN FÜR DAS BEISPIELDESIGN:

- Verwenden Sie realistische Daten, keine Platzhalter

- Zeigen Sie minimale, partielle und vollständige Spezifikationsmuster

- Halten Sie es prägnant: 1-5 Beispiele pro Tool

- Konzentrieren Sie sich auf mehrdeutige Fälle

Tool-Fehlerbehandlung

Rückgabe von Fehlern, die dem LLM helfen, sich zu erholen

Wann verwenden: Jedes Tool, das fehlschlagen kann

BEST PRACTICES FÜR DIE FEHLERBEHANDLUNG:

Informative Fehler zurückgeben

SCHLECHT:
{"error": "Fehlgeschlagen"}
{"error": true}

GUT:
{
  "error": true,
  "error_type": "not_found",
  "message": "Standort 'Atlantis' nicht in der Wetterdatenbank gefunden. Bitte geben Sie einen echten Stadtnamen wie 'San Francisco, CA' an.",
  "suggestions": ["San Francisco, CA", "Los Angeles, CA"]
}

Anthropic Tool-Ergebnis mit Fehler

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "content": "Fehler: Standort 'Atlantis' nicht in der Wetterdatenbank gefunden. Bitte geben Sie einen echten Stadtnamen wie 'San Francisco, CA' an.",
  "is_error": true
}

Fehlerkategorien, die behandelt werden müssen

1. Eingabevalidierungsfehler
   - Fehlende erforderliche Parameter
   - Ungültiges Format
   - Werte außerhalb des Bereichs

2. Externe Dienstfehler
   - API nicht verfügbar
   - Ratenbegrenzung erreicht
   - Zeitüberschreitung

3. Geschäftslogikfehler
   - Ressource nicht gefunden
   - Zugriff verweigert
   - Konflikt/Duplikat

4. Interne Fehler
   - Unerwartete Ausnahmen
   - Datenbeschädigung

Implementierungsmuster

from dataclasses import dataclass
from typing import Union

@dataclass
class ToolResult:
    success: bool
    content: str
    error_type: str = None
    suggestions: list[str] = None

    def to_response(self) -> dict:
        if self.success:
            return {"content": self.content}
        return {
            "content": f"Fehler ({self.error_type}): {self.content}",
            "is_error": True
        }

def get_weather(location: str) -> ToolResult:
    # Eingabe validieren
    if not location or len(location) < 2:
        return ToolResult(
            success=False,
            content="Der Standort muss mindestens 2 Zeichen lang sein",
            error_type="validation_error"
        )

    try:
        data = weather_api.fetch(location)
        return ToolResult(
            success=True,
            content=f"Temperatur: {data.temp}°F, Bedingungen: {data.conditions}"
        )
    except LocationNotFound:
        return ToolResult(
            success=False,
            content=f"Standort '{location}' nicht gefunden",
            error_type="not_found",
            suggestions=weather_api.suggest_locations(location)
        )
    except RateLimitError:
        return ToolResult(
            success=False,
            content="Ratenbegrenzung des Wetterdienstes überschritten. Versuchen Sie es in 60 Sekunden erneut.",
            error_type="rate_limit"
        )
    except Exception as e:
        return ToolResult(
            success=False,
            content=f"Unerwarteter Fehler: {str(e)}",
            error_type="internal_error"
        )

MCP-Tool-Muster

Erstellung von Tools mit dem Model Context Protocol

Wann verwenden: Erstellung wiederverwendbarer, plattformübergreifender Tools

MCP-TOOL-IMPLEMENTIERUNG:

MCP (Model Context Protocol) ist ein offener Standard von Anthropic zum
Verbinden von KI-Agenten mit externen Systemen. Einmal erstellen, überall verwenden.

Grundlegender MCP-Server (TypeScript)

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";

const server = new Server({
  name: "weather-server",
  version: "1.0.0"
});

// Tools definieren
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_weather",
      description: "Ruft das aktuelle Wetter für einen Standort ab. Gibt Temperatur, Bedingungen und Luftfeuchtigkeit zurück. Für Wetteranfragen zu bestimmten Städten verwenden.",
      inputSchema: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "Stadt und Bundesland, z.B. 'San Francisco, CA'"
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            default: "fahrenheit"
          }
        },
        required: ["location"]
      }
    }
  ]
}));

// Tool-Aufrufe behandeln
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_weather") {
    try {
      const weather = await fetchWeather(args.location, args.unit);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(weather)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Fehler: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }

  throw new Error(`Unbekanntes Tool: ${name}`);
});

// Server starten
const transport = new StdioServerTransport();
await server.connect(transport);

MCP-Vorteile

- Universelle Kompatibilität über LLM-Anbieter hinweg
- Wiederverwendbare Tool-Bibliotheken
- Unterstützung für Streaming- und SSE-Transport
- Integrierte Beobachtbarkeit
- Tool-Zugriffskontrollen

Tool-Runner-Muster

Verwendung von SDK-Tool-Runnern für die automatische Handhabung

Wann verwenden: Erstellung von Tool-Schleifen ohne manuelle Verwaltung

TOOL-RUNNER (Anthropic SDK Beta):

Der Tool-Runner handhabt die Tool-Aufruf-Schleife automatisch:
- Führt Tools aus, wenn Claude sie aufruft
- Verwaltet den Gesprächsstatus
- Behandelt Fehlerwiederholungen
- Bietet Streaming-Unterstützung

Python-Beispiel

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    '''Ruft das aktuelle Wetter an einem bestimmten Standort ab.

    Args:
        location: Die Stadt und das Bundesland, z.B. San Francisco, CA
        unit: Temperatureinheit, entweder 'celsius' oder 'fahrenheit'
    '''
    # Implementierung
    return json.dumps({"temperature": "72°F", "conditions": "Sonnig"})

@beta_tool
def search_web(query: str) -> str:
    '''Durchsucht das Web nach Informationen.

    Args:
        query: Die Suchanfrage
    '''
    # Implementierung
    return json.dumps({"results": [...]})

# Tool-Runner handhabt die Schleife
runner = client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, search_web],
    messages=[
        {"role": "user", "content": "Wie ist das Wetter in Paris?"}
    ]
)

# Jede Nachricht verarbeiten
for message in runner:
    print(message.content[0].text)

# Oder nur das Endergebnis abrufen
final = runner.until_done()

TypeScript mit Zod

import { Anthropic } from '@anthropic-ai/sdk';
import { betaZodTool } from '@anthropic-ai/sdk/helpers/beta/zod';
import { z } from 'zod';

const anthropic = new Anthropic();

const getWeatherTool = betaZodTool({
  name: 'get_weather',
  description: 'Ruft das aktuelle Wetter an einem bestimmten Standort ab',
  inputSchema: z.object({
    location: z.string().describe('Stadt und Bundesland, z.B. San Francisco, CA'),
    unit: z.enum(['celsius', 'fahrenheit']).default('fahrenheit')
  }),
  run: async (input) => {
    // Typsichere Eingabe!
    return JSON.stringify({temperature: '72°F'});
  }
});

const runner = anthropic.beta.messages.toolRunner({
  model: 'claude-sonnet-4-5',
  max_tokens: 1024,
  tools: [getWeatherTool],
  messages: [{ role: 'user', content: "Wie ist das Wetter in Paris?" }]
});

for await (const message of runner) {
  console.log(message.content[0].text);
}

Parallele Tool-Ausführung

Gleichzeitige Ausführung mehrerer Tools

Wann verwenden: Unabhängige Tool-Aufrufe, die parallel ausgeführt werden können

PARALLELE TOOL-AUSFÜHRUNG:

Standardmäßig kann Claude mehrere Tools in einer Antwort aufrufen.
Dies reduziert die Latenz für unabhängige Operationen drastisch.

Handhabung paralleler Ergebnisse

# Claude gibt mehrere tool_use-Blöcke zurück:
response.content = [
    {"type": "text", "text": "Ich überprüfe beide Standorte..."},
    {"type": "tool_use", "id": "toolu_01", "name": "get_weather",
     "input": {"location": "San Francisco, CA"}},
    {"type": "tool_use", "id": "toolu_02", "name": "get_weather",
     "input": {"location": "New York, NY"}},
    {"type": "tool_use", "id": "toolu_03", "name": "get_time",
     "input": {"timezone": "America/Los_Angeles"}},
    {"type": "tool_use", ...}
]