Wie man KI-Agenten mit einer einzigen API reale Tools zur Verfügung stellt

Sie erstellen einen KI-Agenten, der Benutzer bei technischen Aufgaben unterstützt. Der Agent muss DNS-Einträge nachschlagen, E-Mails validieren, QR-Codes generieren und SSL-Zertifikate prüfen. LLMs können über diese Aufgaben nachdenken, aber sie können keine Netzwerkanrufe tätigen oder Bilder generieren. Ihr Agent benötigt Tools.

Der typische Weg ist schmerzhaft. Sie verkabeln eine Bibliothek für DNS, eine andere für die E-Mail-Validierung und eine dritte für QR-Codes. Jeder hat seine eigene Authentifizierung, sein eigenes Antwortformat und seine eigene Fehlerbehandlung. Die Tool-Ausführungsschicht Ihres Agenten wird zu einem Flickenteppich aus API-Clients.

Ein besserer Ansatz: Geben Sie dem Agenten Zugriff auf eine einzige API, die alle diese Funktionen abdeckt. Ein Authentifizierungstoken. Ein Antwortformat. Ein Ratenlimit zum Nachverfolgen. Dieser Beitrag zeigt, wie man das verkabelt Botoi-API (Über 150 Entwickler-Tool-Endpunkte) in drei Agentenarchitekturen: Claude-Tool-Nutzung, OpenAI-Funktionsaufruf und MCP.

Das Werkzeugnutzungsmuster in 30 Sekunden

Jeder große LLM-Anbieter unterstützt mittlerweile die Verwendung von Tools (auch Funktionsaufruf genannt). Das Muster ist bei allen gleich:

1. Sie definieren eine Reihe von Tools mit Namen, Beschreibungen und Eingabeschemata.
2. Sie senden zusammen mit den Werkzeugdefinitionen eine Benutzernachricht an das LLM.
3. Der LLM entscheidet, welches Tool mit welchen Argumenten aufgerufen wird.
4. Ihr Code führt den Tool-Aufruf aus (eine HTTP-Anfrage, eine Datenbankabfrage, ein Dateilesen).
5. Sie senden das Werkzeugergebnis zurück an das LLM.
6. Das LLM verwendet das Ergebnis, um seine endgültige Antwort zu formulieren.

Im Pseudocode sieht die Schleife so aus:

// The tool-use loop: LLM reasons, picks a tool, you execute it
while (true) {
  const response = await llm.chat(messages);

  if (response.stop_reason === "tool_use") {
    const toolCall = response.tool_calls[0];
    const result = await executeToolCall(toolCall);
    messages.push({ role: "tool", content: result });
  } else {
    return response.content;  // Final answer
  }
}

Das LLM führt das Tool niemals selbst aus. Es erzeugt eine strukturierte Ausgabe (Toolname + Argumente) und Ihr Code übernimmt die Ausführung. Das bedeutet, dass die Tools alles Mögliche sein können: ein Shell-Befehl, eine Datenbankabfrage oder ein API-Aufruf.

Warum die API von Botois gut zum Tool-Nutzungsmuster passt

Jeder Botoi-Endpunkt hat bereits die Form einer Werkzeugdefinition. Jeder Endpunkt nimmt eine JSON-Eingabe entgegen und gibt eine JSON-Ausgabe mit einer konsistenten Struktur zurück. So sieht eine DNS-Lookup-Tool-Definition aus:

// Each botoi endpoint maps to a tool definition
// The OpenAPI spec at /openapi.json provides this automatically
{
  "name": "dns_lookup",
  "description": "Look up DNS records for a domain",
  "parameters": {
    "type": "object",
    "properties": {
      "domain": { "type": "string", "description": "Domain to query" },
      "type": { "type": "string", "enum": ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] }
    },
    "required": ["domain"]
  }
}

Drei Dinge sorgen dafür, dass dies für Agenten gut funktioniert:

• Klare Eingabeschemata. Jeder Endpunkt akzeptiert einen kleinen, klar definierten JSON-Body. LLMs sind gut darin, strukturiertes JSON zu erstellen, wenn das Schema eng ist.
• Konsistentes Ausgabeformat. Alle Endpunkte kehren zurück {"{ success: true, data: { ... } }"} oder {"{ success: false, message: '...' }"}. Der Tool-Ergebnisparser Ihres Agents behandelt jeden Endpunkt auf die gleiche Weise.
• OpenAPI-Spezifikation für die automatische Erkennung. Die Spezifikation bei api.botoi.com/openapi.json enthält vollständige Schemata für alle über 150 Endpunkte. Sie können daraus Werkzeugdefinitionen programmgesteuert generieren, anstatt sie manuell zu schreiben.

Architektur 1: Verwendung des Claude-Tools mit dem Anthropic SDK

Mit der Tool-Use-API von Claude können Sie Tooldefinitionen zusammen mit Ihren Nachrichten übergeben. Wenn Claude beschließt, ein Tool aufzurufen, wird ein zurückgegeben tool_use Inhaltsblock mit dem Werkzeugnamen und der Eingabe. Sie führen den Aufruf aus und senden das Ergebnis als zurück tool_result.

Hier ist ein funktionierender Agent, der mit botoi nach DNS-Einträgen suchen, SSL-Zertifikate überprüfen und E-Mails validieren kann:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const BOTOI_KEY = process.env.BOTOI_API_KEY;

// Define botoi endpoints as Claude tools
const tools = [
  {
    name: "dns_lookup",
    description: "Look up DNS records (A, MX, TXT, etc.) for a domain",
    input_schema: {
      type: "object",
      properties: {
        domain: { type: "string", description: "Domain to query" },
        type: { type: "string", enum: ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] },
      },
      required: ["domain"],
    },
  },
  {
    name: "ssl_check",
    description: "Check SSL certificate and security headers for a domain",
    input_schema: {
      type: "object",
      properties: {
        url: { type: "string", description: "Domain or URL to check" },
      },
      required: ["url"],
    },
  },
  {
    name: "email_validate",
    description: "Validate an email address (syntax, MX, disposable check)",
    input_schema: {
      type: "object",
      properties: {
        email: { type: "string", description: "Email address to validate" },
      },
      required: ["email"],
    },
  },
];

// Map tool names to botoi API endpoints
const toolEndpoints = {
  dns_lookup: "/v1/dns/lookup",
  ssl_check: "/v1/ssl",
  email_validate: "/v1/email/validate",
};

async function callBotoiTool(name, input) {
  const endpoint = toolEndpoints[name];
  const res = await fetch(\`https://api.botoi.com\${endpoint}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${BOTOI_KEY}\`,
    },
    body: JSON.stringify(input),
  });
  return await res.json();
}

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      tools,
      messages,
    });

    // If Claude wants to use a tool, execute it and feed the result back
    if (response.stop_reason === "tool_use") {
      const toolBlock = response.content.find((b) => b.type === "tool_use");
      const result = await callBotoiTool(toolBlock.name, toolBlock.input);

      messages.push({ role: "assistant", content: response.content });
      messages.push({
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolBlock.id,
            content: JSON.stringify(result),
          },
        ],
      });
    } else {
      // Claude is done; return the final text
      return response.content[0].text;
    }
  }
}

// Usage
const answer = await runAgent(
  "Check the DNS records and SSL certificate for stripe.com"
);
console.log(answer);

Bitten Sie diesen Agenten „Überprüfen Sie die DNS-Einträge und das SSL-Zertifikat für Stripe.com“, und Claude führt nacheinander zwei Tool-Aufrufe durch und fasst die Ergebnisse dann in einer lesbaren Zusammenfassung zusammen. Der Agent verarbeitet die mehrstufige Argumentation automatisch; Claude wählt basierend auf der Frage des Benutzers aus, welche Tools in welcher Reihenfolge aufgerufen werden sollen.

Architektur 2: OpenAI-Funktionsaufruf

Der Funktionsaufruf von OpenAI folgt demselben Muster mit unterschiedlichen Feldnamen. Werkzeuge werden unter a definiert tools Array mit type: "function". Das Modell kehrt zurück tool_calls wenn es eine Funktion ausführen möchte.

Ein Unterschied: GPT kann mehrere Toolaufrufe in einer einzigen Antwort anfordern. Der folgende Code übernimmt die parallele Toolausführung:

import OpenAI from "openai";

const openai = new OpenAI();
const BOTOI_KEY = process.env.BOTOI_API_KEY;

const tools = [
  {
    type: "function",
    function: {
      name: "dns_lookup",
      description: "Look up DNS records for a domain",
      parameters: {
        type: "object",
        properties: {
          domain: { type: "string" },
          type: { type: "string", enum: ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] },
        },
        required: ["domain"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "qr_generate",
      description: "Generate a QR code SVG from text or a URL",
      parameters: {
        type: "object",
        properties: {
          text: { type: "string", description: "Content to encode" },
          size: { type: "number", description: "Size in pixels (100-1000)" },
        },
        required: ["text"],
      },
    },
  },
];

const toolEndpoints = {
  dns_lookup: "/v1/dns/lookup",
  qr_generate: "/v1/qr/generate",
};

async function callBotoiTool(name, args) {
  const endpoint = toolEndpoints[name];
  const res = await fetch(\`https://api.botoi.com\${endpoint}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${BOTOI_KEY}\`,
    },
    body: JSON.stringify(args),
  });
  return await res.json();
}

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await openai.chat.completions.create({
      model: "gpt-4o",
      tools,
      messages,
    });

    const choice = response.choices[0];

    if (choice.finish_reason === "tool_calls") {
      messages.push(choice.message);

      for (const call of choice.message.tool_calls) {
        const args = JSON.parse(call.function.arguments);
        const result = await callBotoiTool(call.function.name, args);

        messages.push({
          role: "tool",
          tool_call_id: call.id,
          content: JSON.stringify(result),
        });
      }
    } else {
      return choice.message.content;
    }
  }
}

const answer = await runAgent(
  "Generate a QR code for https://botoi.com and look up the MX records"
);
console.log(answer);

GPT-4o kann beides aufrufen dns_lookup Und qr_generate parallel, wenn die Aufgaben unabhängig sind. Die Schleife verarbeitet alle Werkzeugaufrufe, bevor die Ergebnisse an das Modell zurückgesendet werden.

Architektur 3: MCP-basierte Agenten

Das Model Context Protocol (MCP) ist ein anderer Ansatz. Anstatt Tools in Ihrem Code zu definieren, erkennt der Agent zur Laufzeit Tools von einem MCP-Server. Botoi betreibt einen MCP-Server unter api.botoi.com/mcp mit 44 kuratierten Tools.

Dies ist die Null-Code-Option. Es müssen keine Werkzeugdefinitionen geschrieben werden. Es muss keine Ausführungsschicht erstellt werden. Der MCP-Client (Claude Desktop, Cursor, Claude Code, VS Code) stellt eine Verbindung zum Server her, erkennt die Tools und übernimmt die Ausführung.

// Claude Desktop, Cursor, or VS Code: add to your MCP config
{
  "mcpServers": {
    "botoi": {
      "type": "streamable-http",
      "url": "https://api.botoi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

// Claude Code: one command
// claude mcp add botoi --transport streamable-http https://api.botoi.com/mcp

Nachdem Sie diese Konfiguration hinzugefügt haben, kann Ihr KI-Assistent jedes der 44 Tools namentlich aufrufen. Fragen Sie „Schauen Sie nach den MX-Einträgen für github.com“ und der Assistent ruft auf lookup_dns Tool, übergibt die Domäne und den Datensatztyp und gibt strukturiertes JSON zurück.

MCP ist die richtige Wahl, wenn Sie einen KI-Assistenten interaktiv verwenden (in einer IDE oder einem Chat-Client). Funktionsaufrufe sind die richtige Wahl, wenn Sie einen programmatischen Agenten erstellen, der autonom ausgeführt wird.

Warum eine einzige API für Agenten wichtig ist

Wenn Sie Tools für einen Agenten vernetzen, ist die Tool-Ausführungsschicht der Teil, der die Produktion unterbricht. Jede externe API, die Sie hinzufügen, führt ihren eigenen Fehlermodus ein. Überlegen Sie, was passiert, wenn Ihr Agent fünf verschiedene APIs verwendet:

• Fünf API-Schlüssel zum Rotieren und sicheren Speichern.
• Fünf Ratengrenzen zur unabhängigen Verfolgung.
• Fünf Antwortformate zur Normalisierung, bevor die Ergebnisse an das LLM zurückgegeben werden.
• Fünf Fehlerbehandlungspfade mit unterschiedlichen Statuscodes und Fehlerformen.
• Fünf Abrechnungs-Dashboards zur Überwachung.

Mit einer einzigen API reduziert sich Ihre Tool-Ausführungsfunktion auf ein Muster:

// Shared helper: route any tool call to the right botoi endpoint
async function executeBotoiTool(name, input) {
  const ENDPOINTS = {
    dns_lookup:      "/v1/dns/lookup",
    ssl_check:       "/v1/ssl",
    email_validate:  "/v1/email/validate",
    qr_generate:     "/v1/qr/generate",
    ip_lookup:       "/v1/ip/lookup",
    hash_generate:   "/v1/hash",
    jwt_decode:      "/v1/jwt/decode",
    pii_detect:      "/v1/pii/detect",
    whois_lookup:    "/v1/whois",
    token_count:     "/v1/token/count",
  };

  const path = ENDPOINTS[name];
  if (!path) throw new Error("Unknown tool: " + name);

  const res = await fetch(\`https://api.botoi.com\${path}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${process.env.BOTOI_API_KEY}\`,
    },
    body: JSON.stringify(input),
  });

  if (!res.ok) {
    const err = await res.json();
    return { error: err.message || "API call failed" };
  }

  return await res.json();
}

Jeder Tool-Aufruf durchläuft denselben Authentifizierungsheader, dieselbe Fehlerform und dasselbe Ratenlimit. Das Hinzufügen eines neuen Tools bedeutet das Hinzufügen einer Zeile zum ENDPOINTS Karte. Keine neuen Abhängigkeiten, keine neuen Anmeldeinformationen.

Auswahl der richtigen Tools für Ihren Agenten

Registrieren Sie nicht alle über 150 Endpunkte als Tools. LLMs schneiden schlechter ab, wenn die Werkzeugliste lang ist, weil sie über mehr Optionen nachdenken müssen. Wählen Sie die 5–15 Tools aus, die Ihr Agent für seinen spezifischen Anwendungsfall benötigt.

Einige Agenten-Archetypen und die dazu passenden Tools:

• Infrastrukturüberwachungsagent: DNS-Suche, SSL-Prüfung, HTTP-Header, Site-Leistungsprüfung, Verfügbarkeitsprüfung, IP-Suche
• E-Mail-Sicherheitsprüfer: SPF-Prüfung, DMARC-Prüfung, DKIM-Prüfung, MX-Eintragsprüfung, E-Mail-Validierung, Einweg-E-Mail-Prüfung
• Verantwortlicher für die Datenverarbeitung: JSON-Format, CSV zu JSON, XML zu JSON, Base64-Kodierung/Dekodierung, HTML zu Markdown, PII-Erkennung
• Entwicklerassistent: JWT-Dekodierung, Hash-Generierung, UUID-Generierung, Cron-Analyse, Regex-Test, Token-Anzahl

Fangen Sie eng an. Fügen Sie Tools hinzu, wenn die Benutzer Ihres Agenten Funktionen anfordern, die er nicht verarbeiten kann. Überwachen Sie, welche Tools aufgerufen werden, und entfernen Sie diejenigen, die nie ausgelöst werden.

Wichtige Punkte

• Grund des LLM; Werkzeuge handeln. Das Werkzeugnutzungsmuster trennt die LLM-Planung von der Ausführung realer Aktionen. Ihr Agent benötigt zuverlässige Tools, um diese Lücke zu schließen.
• Eine API, ein Ausführungspfad. Eine einzige API mit konsistenter Authentifizierung, Antwortformat und Fehlerbehandlung vereinfacht die Tool-Ausführungsebene, die jeder Agent benötigt.
• Drei Architekturen, gleiche API. Die Verwendung des Claude-Tools, der OpenAI-Funktionsaufruf und MCP funktionieren alle mit Botoi-Endpunkten. Wählen Sie diejenige aus, die Ihrem Bereitstellungsmodell entspricht.
• Halten Sie die Werkzeugliste klein. Registrieren Sie 5–15 Werkzeuge pro Agent. Zu viele Optionen beeinträchtigen die Genauigkeit der Werkzeugauswahl des LLM.
• MCP für interaktive Nutzung, Funktionsaufruf für autonome Agenten. MCP übernimmt die Tool-Erkennung und -Ausführung für Sie. Durch Funktionsaufrufe haben Sie die volle Kontrolle über die Schleife.

Der API-Dokumente Listen Sie jeden Endpunkt mit Anforderungs-/Antwortschemata auf. Der OpenAPI-Spezifikation ermöglicht die programmgesteuerte Generierung von Werkzeugdefinitionen. Der Manifest des MCP-Tools zeigt die 44 kuratierten Tools, die über MCP verfügbar sind.