Cara memberikan alat dunia nyata kepada agen AI dengan satu API

Anda sedang membangun agen AI yang membantu pengguna dalam tugas teknis. Agen perlu mencari data DNS, memvalidasi email, membuat kode QR, dan memeriksa sertifikat SSL. LLM dapat mempertimbangkan tugas-tugas ini, tetapi mereka tidak dapat membuat panggilan jaringan atau menghasilkan gambar. Agen Anda membutuhkan alat.

Jalan yang khas itu menyakitkan. Anda menghubungkan satu perpustakaan untuk DNS, perpustakaan lainnya untuk validasi email, dan perpustakaan ketiga untuk kode QR. Masing-masing memiliki autentikasinya sendiri, format responsnya sendiri, penanganan kesalahannya sendiri. Lapisan eksekusi alat agen Anda menjadi gabungan klien API.

Pendekatan yang lebih baik: berikan agen akses ke satu API yang mencakup semua kemampuan ini. Satu token autentikasi. Satu format respons. Satu batas tarif untuk dilacak. Posting ini menunjukkan cara menyambungkan botoi API (150+ titik akhir alat pengembang) menjadi tiga arsitektur agen: penggunaan alat Claude, pemanggilan fungsi OpenAI, dan MCP.

Pola penggunaan alat dalam 30 detik

Setiap penyedia LLM besar sekarang mendukung penggunaan alat (juga disebut pemanggilan fungsi). Polanya sama pada semuanya:

1. Anda menentukan seperangkat alat dengan nama, deskripsi, dan skema masukan.
2. Anda mengirim pesan pengguna ke LLM bersama dengan definisi alat.
3. LLM memutuskan alat mana yang akan digunakan dan dengan argumen apa.
4. Kode Anda menjalankan panggilan alat (permintaan HTTP, kueri basis data, pembacaan file).
5. Anda mengirimkan hasil alat kembali ke LLM.
6. LLM menggunakan hasilnya untuk merumuskan jawaban akhirnya.

Loopnya terlihat seperti ini dalam pseudocode:

// 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 tidak pernah menjalankan alat itu sendiri. Ini menghasilkan output terstruktur (nama alat + argumen), dan kode Anda melakukan eksekusi. Artinya, alatnya bisa apa saja: perintah shell, kueri database, atau panggilan API.

Mengapa API botoi memetakan dengan baik pola penggunaan alat

Setiap titik akhir botoi sudah berbentuk seperti definisi alat. Setiap titik akhir mengambil masukan JSON dan mengembalikan keluaran JSON dengan struktur yang konsisten. Berikut definisi alat pencarian 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"]
  }
}

Tiga hal yang membuat ini berhasil bagi agen:

• Hapus skema masukan. Setiap titik akhir menerima isi JSON yang kecil dan terdefinisi dengan baik. LLM pandai menghasilkan JSON terstruktur ketika skemanya ketat.
• Format keluaran yang konsisten. Semua titik akhir kembali {"{ success: true, data: { ... } }"} atau {"{ success: false, message: '...' }"}. Pengurai hasil alat agen Anda menangani setiap titik akhir dengan cara yang sama.
• Spesifikasi OpenAPI untuk penemuan otomatis. Spesifikasi di api.botoi.com/openapi.json berisi skema lengkap untuk 150+ titik akhir. Anda dapat membuat definisi alat secara terprogram daripada menulisnya dengan tangan.

Arsitektur 1: Alat Claude digunakan dengan Anthropic SDK

API penggunaan alat Claude memungkinkan Anda meneruskan definisi alat bersama pesan Anda. Ketika Claude memutuskan untuk memanggil suatu alat, ia mengembalikan a tool_use blok konten dengan nama alat dan masukan. Anda menjalankan panggilan dan mengirimkan hasilnya kembali sebagai tool_result.

Berikut adalah agen yang dapat mencari data DNS, memeriksa sertifikat SSL, dan memvalidasi email menggunakan botoi:

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

Tanyakan kepada agen ini "Periksa catatan DNS dan sertifikat SSL untuk stripe.com" dan Claude akan membuat dua panggilan alat secara berurutan, lalu menyatukan hasilnya menjadi ringkasan yang dapat dibaca. Agen menangani penalaran multi-langkah secara otomatis; Claude memilih alat mana yang akan dipanggil, dalam urutan apa, berdasarkan pertanyaan pengguna.

Arsitektur 2: Panggilan fungsi OpenAI

Pemanggilan fungsi OpenAI mengikuti pola yang sama dengan nama bidang yang berbeda. Alat didefinisikan dalam a tools susunan dengan type: "function". Modelnya kembali tool_calls ketika ingin menjalankan suatu fungsi.

Satu perbedaannya: GPT dapat meminta beberapa panggilan alat dalam satu respons. Kode di bawah ini menangani eksekusi alat paralel:

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 dapat memanggil keduanya dns_lookup Dan qr_generate secara paralel ketika tugasnya independen. Perulangan memproses semua panggilan alat sebelum mengirimkan hasilnya kembali ke model.

Arsitektur 3: Agen berbasis MCP

Model Context Protocol (MCP) adalah pendekatan yang berbeda. Daripada mendefinisikan alat dalam kode Anda, agen menemukan alat dari server MCP saat runtime. Botoi menjalankan server MCP di api.botoi.com/mcp dengan 44 alat yang dikurasi.

Ini adalah opsi tanpa kode. Tidak ada definisi alat untuk ditulis. Tidak ada lapisan eksekusi yang perlu dibangun. Klien MCP (Claude Desktop, Cursor, Claude Code, VS Code) terhubung ke server, menemukan alat, dan menangani eksekusi.

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

Setelah menambahkan konfigurasi ini, asisten AI Anda dapat memanggil salah satu dari 44 alat berdasarkan namanya. Tanyakan "cari data MX untuk github.com" dan asisten akan memanggil lookup_dns alat, meneruskan domain dan jenis rekaman, dan mengembalikan JSON terstruktur.

MCP adalah pilihan tepat saat Anda menggunakan asisten AI secara interaktif (dalam IDE atau klien obrolan). Pemanggilan fungsi adalah pilihan yang tepat saat Anda membuat agen terprogram yang berjalan secara mandiri.

Mengapa satu API penting bagi agen

Saat Anda memasang alat untuk agen, lapisan eksekusi alat adalah bagian yang rusak dalam produksi. Setiap API eksternal yang Anda tambahkan memperkenalkan mode kegagalannya sendiri. Pertimbangkan apa yang terjadi jika agen Anda menggunakan lima API berbeda:

• Lima kunci API untuk diputar dan disimpan dengan aman.
• Lima batas kecepatan untuk dilacak secara mandiri.
• Lima format respons untuk dinormalisasi sebelum mengembalikan hasil ke LLM.
• Lima jalur penanganan kesalahan dengan kode status dan bentuk kesalahan berbeda.
• Lima dasbor penagihan untuk dipantau.

Dengan satu API, fungsi eksekusi alat Anda dikurangi menjadi satu pola:

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

Setiap pemanggilan alat melewati header autentikasi yang sama, bentuk kesalahan yang sama, batas kecepatan yang sama. Menambahkan alat baru berarti menambahkan satu baris ke ENDPOINTS peta. Tidak ada ketergantungan baru, tidak ada kredensial baru.

Memilih alat yang tepat untuk agen Anda

Jangan daftarkan 150+ titik akhir sebagai alat. LLM berkinerja lebih buruk ketika daftar alatnya panjang karena mereka harus mempertimbangkan lebih banyak pilihan. Pilih 5-15 alat yang dibutuhkan agen Anda untuk kasus penggunaan spesifiknya.

Beberapa arketipe agen dan alat yang sesuai:

• Agen pemantauan infrastruktur: Pencarian DNS, pemeriksaan SSL, header HTTP, pemeriksaan kinerja situs, pemeriksaan uptime, pencarian IP
• Auditor keamanan email: Pemeriksaan SPF, pemeriksaan DMARC, pemeriksaan DKIM, pemeriksaan data MX, validasi email, pemeriksaan email sekali pakai
• Agen pemrosesan data: Format JSON, CSV ke JSON, XML ke JSON, encode/decode Base64, HTML ke Markdown, deteksi PII
• Asisten pengembang: Dekode JWT, pembuatan hash, pembuatan UUID, penguraian cron, pengujian regex, jumlah token

Mulai sempit. Tambahkan alat ketika pengguna agen Anda meminta kemampuan yang tidak dapat ditangani. Pantau alat mana yang dipanggil dan hapus alat yang tidak pernah menyala.

Poin-poin penting

• alasan LLM; alat bertindak. Pola penggunaan alat memisahkan perencanaan LLM dari pelaksanaan tindakan dunia nyata. Agen Anda memerlukan alat yang andal untuk menjembatani kesenjangan tersebut.
• Satu API, satu jalur eksekusi. API tunggal dengan autentikasi yang konsisten, format respons, dan penanganan kesalahan menyederhanakan lapisan eksekusi alat yang dibutuhkan setiap agen.
• Tiga arsitektur, API yang sama. Penggunaan alat Claude, pemanggilan fungsi OpenAI, dan MCP semuanya berfungsi dengan titik akhir botoi. Pilih salah satu yang cocok dengan model penerapan Anda.
• Jaga agar daftar alat tetap kecil. Daftarkan 5-15 alat per agen. Terlalu banyak pilihan menurunkan akurasi pemilihan alat LLM.
• MCP untuk penggunaan interaktif, fungsi memanggil agen otonom. MCP menangani penemuan dan eksekusi alat untuk Anda. Pemanggilan fungsi memberi Anda kendali penuh atas loop.

Itu dokumen API daftar setiap titik akhir dengan skema permintaan/respons. Itu spesifikasi OpenAPI memungkinkan Anda menghasilkan definisi alat secara terprogram. Itu Manifes alat MCP menunjukkan 44 alat kurasi yang tersedia melalui MCP.