単一の API で AI エージェントに現実世界のツールを提供する方法

あなたは、ユーザーの技術的なタスクを支援する AI エージェントを構築しています。 エージェントは、DNS レコードを検索し、電子メールを検証し、QR コードを生成し、SSL 証明書を確認する必要があります。 LLM はこれらのタスクについて推論できますが、ネットワーク呼び出しを行ったり、イメージを生成したりすることはできません。 エージェントにはツールが必要です。

典型的な道は苦痛です。 1 つのライブラリを DNS 用に、もう 1 つを電子メール検証用に、3 つ目のライブラリを QR コード用に接続します。 それぞれに独自の認証、独自の応答形式、独自のエラー処理があります。 エージェントのツール実行層は、API クライアントのパッチワークになります。

より良いアプローチは、エージェントにこれらの機能をすべてカバーする単一の API へのアクセスを提供することです。 認証トークン 1 つ。 応答形式は 1 つです。 追跡する 1 つのレート制限。 この投稿では、配線方法を示します ボトイAPI (150 以上の開発者ツール エンドポイント) を 3 つのエージェント アーキテクチャに分割: Claude ツールの使用、OpenAI 関数の呼び出し、MCP。

30 秒のツール使用パターン

主要な LLM プロバイダーはすべて、ツールの使用 (関数呼び出しとも呼ばれます) をサポートするようになりました。 パターンはすべて同じです。

1. 名前、説明、入力スキーマを使用してツールのセットを定義します。
2. ユーザーメッセージをツール定義とともに LLM に送信します。
3. LLM は、どのツールをどの引数で呼び出すかを決定します。
4. コードはツール呼び出し (HTTP リクエスト、データベース クエリ、ファイル読み取り) を実行します。
5. ツールの結果を LLM に送り返します。
6. LLM は、その結果を使用して最終的な答えを定式化します。

ループは擬似コードでは次のようになります。

// 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
  }
}

LLM がツール自体を実行することはありません。 構造化された出力 (ツール名 + 引数) が生成され、コードが実行されます。 これは、シェル コマンド、データベース クエリ、API 呼び出しなど、ツールは何でもよいことを意味します。

botoi の API がツールの使用パターンにうまく対応する理由

各 Botoi エンドポイントは、すでにツール定義のように形作られています。 すべてのエンドポイントは JSON 入力を受け取り、一貫した構造を持つ JSON 出力を返します。 DNS ルックアップ ツールの定義は次のようになります。

// 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"]
  }
}

これがエージェントにとってうまく機能する理由は 3 つあります。

• 入力スキーマをクリアします。 すべてのエンドポイントは、小さく明確に定義された JSON 本文を受け入れます。 LLM は、スキーマが緊密な場合に構造化された JSON を生成するのに適しています。
• 一貫した出力形式。 すべてのエンドポイントが戻ります {"{ success: true, data: { ... } }"} または {"{ success: false, message: '...' }"}。 エージェントのツール結果パーサーは、すべてのエンドポイントを同じ方法で処理します。
• 自動検出のための OpenAPI 仕様。 での仕様 api.botoi.com/openapi.json 150 以上のエンドポイントすべての完全なスキーマが含まれています。 ツール定義を手動で作成する代わりに、そこからプログラムで生成できます。

アーキテクチャ 1: Anthropic SDK での Claude ツールの使用

Claude のツール使用 API を使用すると、メッセージと一緒にツール定義を渡すことができます。 クロードがツールを呼び出すことを決定すると、ツールは tool_use ツール名と入力を含むコンテンツ ブロック。 呼び出しを実行し、結果を tool_result。

これは、botoi を使用して DNS レコードを検索し、SSL 証明書を確認し、電子メールを検証できる機能するエージェントです。

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);

このエージェントに「stripe.com の DNS レコードと SSL 証明書を確認してください」と依頼すると、Claude は 2 つのツール呼び出しを順番に実行し、結果を読みやすい概要に合成します。 エージェントは複数ステップの推論を自動的に処理します。 クロードは、ユーザーの質問に基づいて、どのツールをどの順序で呼び出すかを選択します。

アーキテクチャ 2: OpenAI 関数呼び出し

OpenAI の関数呼び出しは、フィールド名が異なる同じパターンに従います。 ツールは tools 配列 type: "function"。 モデルが帰ってくる tool_calls 関数を実行したいとき。

1 つの違い: GPT は 1 つの応答で複数のツール呼び出しを要求できます。 以下のコードはツールの並列実行を処理します。

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 は両方を呼び出すことができます dns_lookup そして qr_generate タスクが独立している場合は並行して実行します。 ループは、結果をモデルに返す前に、すべてのツール呼び出しを処理します。

アーキテクチャ 3: MCP ベースのエージェント

モデル コンテキスト プロトコル (MCP) は、別のアプローチです。 コード内でツールを定義する代わりに、エージェントは実行時に MCP サーバーからツールを検出します。 Botoi は MCP サーバーを次の場所で実行します。 api.botoi.com/mcp 44 の厳選されたツールを備えています。

これはゼロコード オプションです。 記述するツール定義はありません。 構築する実行層はありません。 MCP クライアント (Claude Desktop、Cursor、Claude Code、VS Code) はサーバーに接続し、ツールを検出し、実行を処理します。

// 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

この構成を追加すると、AI アシスタントは 44 のツールのいずれかを名前で呼び出すことができます。 「github.com の MX レコードを調べて」と尋ねると、アシスタントが lookup_dns ツールを使用して、ドメインとレコード タイプを渡し、構造化された JSON を返します。

MCP は、AI アシスタントを対話的に (IDE またはチャット クライアントで) 使用する場合に最適です。 自律的に実行されるプログラム エージェントを構築する場合、関数呼び出しは正しい選択です。

単一の API がエージェントにとって重要な理由

エージェントにツールを接続する場合、実稼働環境で機能しなくなる部分はツール実行層です。 追加する各外部 API には、独自の障害モードが導入されます。 エージェントが 5 つの異なる API を使用するとどうなるかを考えてみましょう。

• 5 つの API キーをローテーションして安全に保存します。
• 独立して追跡できる 5 つのレート制限。
• 結果を LLM にフィードバックする前に正規化する 5 つの応答形式。
• ステータス コードとエラーの形状が異なる 5 つのエラー処理パス。
• 監視する 5 つの請求ダッシュボード。

単一の API を使用すると、ツール実行機能は 1 つのパターンに減ります。

// 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();
}

すべてのツール呼び出しは、同じ認証ヘッダー、同じエラー形状、同じレート制限を通過します。 新しいツールを追加するということは、 ENDPOINTS 地図。 新しい依存関係や新しい認証情報はありません。

エージェントに適切なツールを選択する

150 以上のエンドポイントをすべてツールとして登録しないでください。 LLM は、ツールのリストが長い場合、より多くのオプションを検討する必要があるため、パフォーマンスが低下します。 エージェントが特定のユースケースに必要とするツールを 5 ～ 15 個選択します。

いくつかのエージェントの原型とそれに適合するツール:

• インフラストラクチャ監視エージェント: DNS ルックアップ、SSL チェック、HTTP ヘッダー、サイト パフォーマンス チェック、稼働時間チェック、IP ルックアップ
• 電子メールセキュリティ監査人: SPFチェック、DMARCチェック、DKIMチェック、MXレコードチェック、メール検証、使い捨てメールチェック
• データ処理エージェント: JSON 形式、CSV から JSON、XML から JSON、Base64 エンコード/デコード、HTML から Markdown、PII 検出
• 開発者アシスタント: JWT デコード、ハッシュ生成、UUID 生成、cron 解析、正規表現テスト、トークン カウント

狭く始めてください。 エージェントのユーザーがエージェントで処理できない機能を要求した場合は、ツールを追加します。 どのツールが呼び出されるかを監視し、起動しないツールを削除します。

重要なポイント

• LLM の理由。 ツールが機能します。 ツールの使用パターンにより、LLM の計画と実際のアクションの実行が分離されます。 エージェントには、そのギャップを埋めるための信頼できるツールが必要です。
• 1 つの API、1 つの実行パス。 一貫した認証、応答形式、エラー処理を備えた単一の API により、すべてのエージェントが必要とするツール実行レイヤーが簡素化されます。
• 3 つのアーキテクチャ、同じ API。 Claude ツールの使用、OpenAI 関数呼び出し、MCP はすべて botoi エンドポイントで動作します。 導入モデルに一致するものを選択してください。
• ツールのリストは小さくしてください。 エージェントごとに 5 ～ 15 個のツールを登録します。 オプションが多すぎると、LLM のツール選択の精度が低下します。
• インタラクティブな使用のための MCP、自律エージェントの関数呼び出し。 MCP はツールの検出と実行を処理します。 関数呼び出しにより、ループを完全に制御できます。

の APIドキュメント すべてのエンドポイントをリクエスト/レスポンス スキーマとともにリストします。 の OpenAPI仕様 ツール定義をプログラムで生成できます。 の MCP ツール マニフェスト に、MCP 経由で利用できる 44 の厳選されたツールを示します。