كيفية منح وكلاء الذكاء الاصطناعي أدوات واقعية باستخدام واجهة برمجة تطبيقات واحدة

أنت تقوم ببناء وكيل الذكاء الاصطناعي الذي يساعد المستخدمين في المهام الفنية. يحتاج الوكيل إلى البحث عن سجلات DNS، والتحقق من صحة رسائل البريد الإلكتروني، وإنشاء رموز QR، والتحقق من شهادات SSL. يمكن لطلاب LLM التفكير في هذه المهام، لكنهم لا يستطيعون إجراء مكالمات عبر الشبكة أو إنشاء صور. وكيلك يحتاج إلى أدوات.

المسار النموذجي مؤلم. تقوم بتوصيل مكتبة واحدة لـ DNS، وأخرى للتحقق من صحة البريد الإلكتروني، وثالثة لرموز QR. ولكل منها مصادقة خاصة بها، وتنسيق استجابة خاص بها، ومعالجة الأخطاء الخاصة بها. تصبح طبقة تنفيذ الأدوات الخاصة بوكيلك خليطًا من عملاء واجهة برمجة التطبيقات (API).

النهج الأفضل: منح الوكيل إمكانية الوصول إلى واجهة برمجة تطبيقات واحدة تغطي كل هذه الإمكانات. رمز مصادقة واحد. صيغة الرد واحدة. حد معدل واحد للتتبع. توضح هذه المشاركة كيفية توصيل الأسلاك واجهة برمجة تطبيقات بوتوي (أكثر من 150 نقطة نهاية لأداة المطور) في ثلاث بنيات وكيل: استخدام أداة 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 الأداة نفسها أبدًا. وينتج مخرجات منظمة (اسم الأداة + الوسائط)، ويقوم الكود الخاص بك بالتنفيذ. وهذا يعني أن الأدوات يمكن أن تكون أي شيء: أمر Shell، أو استعلام قاعدة بيانات، أو استدعاء API.

لماذا تتوافق واجهة برمجة تطبيقات botoi جيدًا مع نمط استخدام الأداة

كل نقطة نهاية 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"]
  }
}

هناك ثلاثة أشياء تجعل هذا الأمر ناجحًا بالنسبة للوكلاء:

• مسح مخططات الإدخال. تقبل كل نقطة نهاية نص JSON صغيرًا ومحددًا جيدًا. تعتبر LLMs جيدة في إنتاج JSON منظم عندما يكون المخطط ضيقًا.
• تنسيق الإخراج متسقة. تعود كافة نقاط النهاية {"{ success: true, data: { ... } }"} أو {"{ success: false, message: '...' }"}. يتعامل محلل نتائج الأداة الخاص بوكيلك مع كل نقطة نهاية بنفس الطريقة.
• مواصفات OpenAPI للاكتشاف التلقائي. المواصفات في api.botoi.com/openapi.json يحتوي على مخططات كاملة لجميع نقاط النهاية التي يزيد عددها عن 150 نقطة. يمكنك إنشاء تعريفات للأداة منه برمجيًا بدلاً من كتابتها يدويًا.

البنية 1: استخدام أداة Claude مع Anthropic SDK

تتيح لك واجهة برمجة تطبيقات استخدام الأدوات الخاصة بـ Claude تمرير تعريفات الأداة إلى جانب رسائلك. عندما يقرر كلود استدعاء أداة، فإنها تقوم بإرجاع ملف tool_use كتلة المحتوى مع اسم الأداة والإدخال. يمكنك تنفيذ المكالمة وإرسال النتيجة مرة أخرى كملف tool_result.

إليك وكيل عامل يمكنه البحث عن سجلات DNS والتحقق من شهادات SSL والتحقق من صحة رسائل البريد الإلكتروني باستخدام 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);

اطلب من هذا الوكيل "التحقق من سجلات DNS وشهادة SSL لموقع stripe.com" وسيقوم كلود بإجراء استدعاءين للأداة بالتسلسل، ثم يقوم بتجميع النتائج في ملخص قابل للقراءة. يتعامل الوكيل مع التفكير متعدد الخطوات تلقائيًا؛ يختار كلود الأدوات التي سيتم الاتصال بها وبأي ترتيب بناءً على سؤال المستخدم.

البنية 2: استدعاء وظيفة OpenAI

يتبع استدعاء وظائف OpenAI نفس النمط مع أسماء حقول مختلفة. يتم تعريف الأدوات تحت أ tools مصفوفة مع type: "function". يعود النموذج tool_calls عندما يريد تنفيذ وظيفة.

اختلاف واحد: يمكن لـ GPT طلب استدعاءات أدوات متعددة في استجابة واحدة. يتعامل الكود أدناه مع تنفيذ الأداة المتوازية:

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

بعد إضافة هذا التكوين، يمكن لمساعد الذكاء الاصطناعي الخاص بك الاتصال بأي من الأدوات الـ 44 بالاسم. اطلب "البحث عن سجلات MX لموقع github.com" وسيتصل المساعد بـ lookup_dns أداة، وتمرير المجال ونوع السجل، وإرجاع JSON منظم.

يعد MCP هو الخيار الصحيح عند استخدام مساعد الذكاء الاصطناعي بشكل تفاعلي (في IDE أو عميل الدردشة). يعد استدعاء الوظائف هو الاختيار الصحيح عند إنشاء وكيل برمجي يعمل بشكل مستقل.

لماذا تعتبر واجهة برمجة التطبيقات (API) واحدة مهمة للوكلاء

عندما تقوم بتوصيل الأدوات لأحد الوكلاء، فإن طبقة تنفيذ الأداة هي الجزء الذي ينكسر في الإنتاج. تقدم كل واجهة برمجة تطبيقات خارجية تضيفها وضع الفشل الخاص بها. ضع في اعتبارك ما يحدث عندما يستخدم وكيلك خمس واجهات برمجة تطبيقات مختلفة:

• خمسة مفاتيح API للتدوير والتخزين بشكل آمن.
• خمسة حدود للمعدلات للتتبع بشكل مستقل.
• خمسة تنسيقات استجابة للتطبيع قبل إرسال النتائج مرة أخرى إلى LLM.
• خمسة مسارات لمعالجة الأخطاء برموز حالة وأشكال أخطاء مختلفة.
• خمس لوحات تحكم للفواتير للمراقبة.

باستخدام واجهة برمجة تطبيقات واحدة، يتم تقليل وظيفة تنفيذ الأداة إلى نمط واحد:

// 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، اختبار regex، عدد الرموز المميزة

ابدأ بالضيق. أضف أدوات عندما يطلب مستخدمو وكيلك إمكانيات لا يمكنهم التعامل معها. راقب الأدوات التي يتم استدعاؤها وقم بإزالة الأدوات التي لا يتم إطلاقها مطلقًا.

النقاط الرئيسية

• سبب LLMs؛ أدوات الفعل. يفصل نمط استخدام الأداة بين تخطيط LLM وتنفيذ إجراءات العالم الحقيقي. يحتاج وكيلك إلى أدوات موثوقة لسد هذه الفجوة.
• واجهة برمجة تطبيقات واحدة ومسار تنفيذ واحد. تعمل واجهة برمجة التطبيقات الواحدة ذات المصادقة المتسقة وتنسيق الاستجابة ومعالجة الأخطاء على تبسيط طبقة تنفيذ الأداة التي يحتاجها كل وكيل.
• ثلاث أبنية، نفس API. يعمل كل من استخدام أداة Claude واستدعاء وظائف OpenAI وMCP مع نقاط نهاية botoi. اختر النموذج الذي يتوافق مع نموذج النشر الخاص بك.
• اجعل قائمة الأدوات صغيرة. قم بتسجيل 5-15 أداة لكل وكيل. تؤدي الخيارات الكثيرة إلى انخفاض دقة اختيار الأدوات في LLM.
• MCP للاستخدام التفاعلي، واستدعاء الوظائف للوكلاء المستقلين. يتولى MCP اكتشاف الأداة وتنفيذها نيابةً عنك. يمنحك استدعاء الوظيفة التحكم الكامل في الحلقة.

ال مستندات API قم بإدراج كل نقطة نهاية بمخططات الطلب/الاستجابة. ال مواصفات OpenAPI يتيح لك إنشاء تعريفات الأداة برمجياً. ال بيان أداة MCP يعرض 44 أداة منسقة متاحة عبر MCP.