بناء وكلاء ذكاء اصطناعي يستخدمون أكثر من 300 تطبيق باستخدام Composio و TypeScript

أصعب جزء في إطلاق وكيل ذكاء اصطناعي مفيد في عام 2026 ليس النموذج — بل كل ما يحيط به. تدفقات OAuth، رموز التحديث، حدود المعدّل، توقيعات الـ webhook، واختلاف المخططات عبر مئات واجهات SaaS البرمجية. Composio يستوعب كل ذلك ويمنح وكيلك سطحاً واحداً ومحدد الأنواع: أكثر من 300 أداة جاهزة عبر Gmail و Slack و GitHub و Notion و Linear و Google Calendar و Stripe و HubSpot و Salesforce وغيرها.

في هذا الدرس، ستربط Composio بوكيل TypeScript مبني على Vercel AI SDK، وستوثّق مستخدماً حقيقياً مع Gmail و GitHub، وستترك النموذج يختار الأداة المناسبة، وستنشره خلف مسار في Next.js.

ما ستتعلمه

بنهاية هذا الدرس، ستكون قادراً على:

• تثبيت وتكوين Composio TypeScript SDK
• إنشاء إعدادات مصادقة وتشغيل تدفق ربط OAuth للمستخدم
• سرد الأدوات وفلترتها حسب مجموعة الأدوات أو الإجراء أو حالة الاستخدام
• تمرير أدوات Composio إلى Vercel AI SDK و OpenAI Agents SDK
• الاستماع إلى محفّزات الوقت الفعلي (بريد جديد، إصدار GitHub جديد، رسالة Slack)
• تغليف كل ذلك خلف نقطة نهاية في Next.js App Router
• تطبيق أنماط الإنتاج: أدوات مُقيَّدة، حسابات لكل مستخدم، قابلية الملاحظة

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

• Node.js 20+ مُثبّت (node --version)
• معرفة عملية بـ TypeScript و async/await
• حساب Composio على app.composio.dev (المستوى المجاني كافٍ)
• مفتاح OpenAI API (أو أي نموذج يدعمه Vercel AI SDK)
• حساب Gmail للاختبار وحساب GitHub تتحكم به
• محرر كود — يُنصح بـ VS Code أو Cursor

كيف يتموضع Composio في حِزمة الوكلاء

حلقة الوكيل النموذجية تبدو هكذا:

طلب المستخدم → LLM → استدعاء أداة → تنفيذ → نتيجة → LLM → إجابة

بدون Composio، تعني كلمة "تنفيذ" أنك كتبت التكامل بنفسك: رقصة OAuth، تحديث الرمز، تشكيل الطلب، تعيين الأخطاء. مع Composio، "التنفيذ" هو استدعاء واحد للـ SDK. يختار النموذج GMAIL_SEND_EMAIL، يُمرّر وقت تشغيل وكيلك الاستدعاء، يُشغّله Composio تحت حساب المستخدم المرتبط، وتستعيد نتيجة منظمة.

الهندسة المعمارية

┌──────────────────────────────────────────────┐
│   خدمة Next.js / Node لديك                   │
│  ┌────────────────────────────────────────┐  │
│  │ Vercel AI SDK / OpenAI Agents SDK      │  │
│  │   ↑   يوفّر الأدوات                   │  │
│  │   │                                    │  │
│  │   Composio SDK                         │  │
│  └─────────────┬──────────────────────────┘  │
└────────────────┼─────────────────────────────┘
                 │ HTTPS
        ┌────────▼─────────┐
        │   Composio API   │
        │ - إعدادات مصادقة │
        │ - الاتصالات      │
        │ - تنفيذ الأدوات  │
        │ - المحفّزات      │
        └────────┬─────────┘
                 │
   ┌─────────────┼──────────────────┐
   ▼             ▼                  ▼
 Gmail        GitHub             Notion  ... +300

وحدة الهوية في Composio هي الحساب المرتبط — سجل واحد لكل مستخدم لكل مجموعة أدوات. يُمرّر وكيلك دائماً userId ليعرف Composio أي حساب يستخدم.

الخطوة 1: إعداد المشروع

أنشئ مشروعاً جديداً وثبّت الـ SDK.

mkdir composio-agent && cd composio-agent
npm init -y
npm install composio @ai-sdk/openai ai zod dotenv
npm install -D typescript tsx @types/node
npx tsc --init --target es2022 --module nodenext --moduleResolution nodenext --esModuleInterop true --strict true

أضف ملف .env:

COMPOSIO_API_KEY=ak_xxx_from_app_composio_dev
OPENAI_API_KEY=sk-xxx

احصل على مفتاح Composio من app.composio.dev/developers.

أنشئ src/composio.ts:

import "dotenv/config";
import { Composio } from "composio";
import { VercelProvider } from "composio/providers/vercel";
 
export const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new VercelProvider(),
});

يُخبر المزوّد Composio كيف يُنسّق مخططات الأدوات لوقت تشغيل وكيلك. يُقدّم Composio مزوّدين لـ Vercel AI SDK و OpenAI Agents SDK و LangChain و LlamaIndex و CrewAI وغيرها.

الخطوة 2: إنشاء إعداد مصادقة

إعداد المصادقة هو هوية تطبيقك مع خدمة طرف ثالث (معرّف OAuth client، النطاقات، عنوان إعادة التوجيه). تنشئه عادة مرة واحدة لكل مجموعة أدوات في لوحة تحكم Composio، لكن يمكنك أيضاً برمجته.

افتح app.composio.dev، اختر مجموعة أدوات Gmail، انقر Setup، ثم اختر Use Composio's OAuth app للتطوير. يُنشئ Composio معرّف إعداد مصادقة مثل ac_xxx. احفظه.

كرر العملية مع GitHub. الآن لديك:

GMAIL_AUTH_CONFIG_ID=ac_gmail_xxx
GITHUB_AUTH_CONFIG_ID=ac_github_xxx

الخطوة 3: ربط حساب مستخدم

ربط حساب يعني توجيه المستخدم خلال OAuth. يُعطيك Composio عنوان إعادة توجيه.

أنشئ src/connect.ts:

import { composio } from "./composio.js";
 
const USER_ID = "user_demo_123"; // معرف المستخدم الداخلي لديك
 
async function connectGmail() {
  const connection = await composio.connectedAccounts.initiate(
    USER_ID,
    process.env.GMAIL_AUTH_CONFIG_ID!,
  );
 
  console.log("افتح هذا الرابط في المتصفح:");
  console.log(connection.redirectUrl);
 
  const account = await connection.waitForConnection(120_000);
  console.log("تم الربط:", account.id, account.status);
}
 
connectGmail().catch(console.error);

شغّله:

npx tsx src/connect.ts

افتح الرابط المطبوع، امنح الإذن، ثم سيُحلّ السكربت باتصال بحالة status: "ACTIVE". يحتفظ Composio الآن برمز التحديث لـ user_demo_123 ضد مجموعة أدوات Gmail.

كرر العملية مع GitHub بتبديل معرّف إعداد المصادقة.

الخطوة 4: اكتشاف الأدوات المناسبة

يكشف Composio عن أكثر من 9,000 إجراء. تمريرها كلها لنموذج سيُمزّق نافذة سياقك. فلتر بقوة.

import { composio } from "./composio.js";
 
const tools = await composio.tools.get("user_demo_123", {
  toolkits: ["gmail", "github"],
  limit: 20,
});
 
for (const tool of Object.values(tools)) {
  console.log(tool.name);
}

يمكنك أيضاً الفلترة بحسب حالة استخدام بلغة طبيعية، مما يستخدم بحث Composio لإظهار أكثر الإجراءات صلة:

const tools = await composio.tools.get("user_demo_123", {
  useCase: "الرد على آخر بريد غير مقروء وفتح إصدار متابعة في GitHub",
  limit: 8,
});

أو بأسماء الإجراءات بدقّة حين تعرف ما تريد:

const tools = await composio.tools.get("user_demo_123", {
  tools: [
    "GMAIL_FETCH_EMAILS",
    "GMAIL_SEND_EMAIL",
    "GITHUB_CREATE_AN_ISSUE",
  ],
});

قاعدة عامة: ابقَ تحت 20 أداة لكل استدعاء وكيل. أكثر من ذلك تنخفض الدقة وتزداد الزمن.

الخطوة 5: تشغيل وكيل مع Vercel AI SDK

الآن ادمج كل ذلك في وكيل حقيقي. أنشئ src/agent.ts:

import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { composio } from "./composio.js";
 
const USER_ID = "user_demo_123";
 
async function run(prompt: string) {
  const tools = await composio.tools.get(USER_ID, {
    toolkits: ["gmail", "github"],
    limit: 12,
  });
 
  const result = await generateText({
    model: openai("gpt-4.1"),
    tools,
    stopWhen: stepCountIs(8),
    system: [
      "أنت مساعد يُعين المستخدم على إدارة البريد و GitHub.",
      "أكّد دائماً الإجراءات المُدمّرة بلغة واضحة قبل تنفيذها.",
      "عند إرسال بريد، استخدم نبرة مهنية قصيرة.",
    ].join("\n"),
    prompt,
  });
 
  console.log("\n--- المساعد ---\n");
  console.log(result.text);
  console.log("\n--- الخطوات ---\n");
  for (const step of result.steps) {
    for (const call of step.toolCalls ?? []) {
      console.log(`  ↳ ${call.toolName}`);
    }
  }
}
 
run("اعثر على آخر ثلاث رسائل بريد غير مقروءة في صندوقي ولخّصها.").catch(
  console.error,
);

شغّله:

npx tsx src/agent.ts

ما يجب أن تراه: يستدعي النموذج GMAIL_FETCH_EMAILS، يستقبل نتيجة منظمة، ويُنتج ملخصاً بلغة طبيعية. لاحظ أنك لم تكتب أي كود Gmail — لا عميل API، ولا معالجة مصادقة، ولا منطق ترقيم.

مثال متعدد الخطوات

استبدل الطلب:

run(
  "اعثر على آخر بريد من عميل يتحدث عن خطأ، ثم افتح إصداراً في GitHub " +
  "في المستودع 'noqta/example-app' باستخدام عنوان البريد كعنوان للإصدار " +
  "ومحتوى البريد مُقتبساً في الوصف.",
).catch(console.error);

سيُسلسل الوكيل GMAIL_FETCH_EMAILS ← GITHUB_CREATE_AN_ISSUE في خطوتين ويُعيد رابط الإصدار المُنشأ.

الخطوة 6: الأدوات نفسها، مع OpenAI Agents SDK

إذا كنت تُفضّل OpenAI Agents SDK، فبدّل المزوّد فقط — منطق عملك يبقى مطابقاً.

npm install @openai/agents

import { Agent, run } from "@openai/agents";
import { Composio } from "composio";
import { OpenAIAgentsProvider } from "composio/providers/openai-agents";
 
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new OpenAIAgentsProvider(),
});
 
const tools = await composio.tools.get("user_demo_123", {
  toolkits: ["linear", "slack"],
  limit: 10,
});
 
const agent = new Agent({
  name: "ops-assistant",
  instructions: "فرز رسائل Slack الواردة وفتح تذاكر Linear حين يكون ذلك مناسباً.",
  tools,
});
 
const result = await run(agent, "افحص آخر 10 رسائل في قناة #support وافتح تذاكر Linear لكل ما يبدو خطأً.");
console.log(result.finalOutput);

يُعيد مزوّد Composio الأدوات بالشكل الذي يتوقعه وقت التشغيل. لن تُعيد تنفيذ المخططات أبداً.

الخطوة 7: محفّزات الوقت الفعلي

استطلاع البريد جيد. التفاعل معه في الوقت الفعلي أفضل. تُحوّل محفّزات Composio أحداث الطرف الثالث إلى webhooks يستطيع وكيلك الاشتراك فيها.

فعّل محفّزاً لمستخدم:

const trigger = await composio.triggers.enable("user_demo_123", {
  triggerName: "GMAIL_NEW_GMAIL_MESSAGE",
  config: { labelIds: ["INBOX"], userId: "me" },
});
 
console.log("المحفّز فعّال:", trigger.id);

الآن وجّه مشروع Composio إلى عنوان webhook (الإعدادات ← Webhooks). كل بريد جديد يُرسل JSON إلى هذا العنوان. معالج بسيط في Next.js Route Handler:

// app/api/composio/webhook/route.ts
import { NextResponse } from "next/server";
import { composio } from "@/lib/composio";
 
export async function POST(req: Request) {
  const event = await req.json();
 
  if (event.triggerName !== "GMAIL_NEW_GMAIL_MESSAGE") {
    return NextResponse.json({ ok: true });
  }
 
  const userId = event.connectedAccount.userId;
  const tools = await composio.tools.get(userId, {
    toolkits: ["gmail", "linear"],
    limit: 6,
  });
 
  // ... استدعِ وكيلك هنا مرّراً حمولة الحدث كمدخل ...
 
  return NextResponse.json({ ok: true });
}

اقرن ذلك مع Vercel AI SDK وستحصل على وكيل فرز بريد وارد مدفوع بالأحداث، يستيقظ فقط حين يكون هناك عمل.

الخطوة 8: نشره خلف مسار Next.js

اربط القطع في نقطة نهاية واحدة في App Router.

// app/api/agent/route.ts
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { Composio } from "composio";
import { VercelProvider } from "composio/providers/vercel";
import { NextResponse } from "next/server";
 
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new VercelProvider(),
});
 
export async function POST(req: Request) {
  const { prompt, userId } = await req.json();
 
  const tools = await composio.tools.get(userId, {
    toolkits: ["gmail", "github", "linear"],
    limit: 15,
  });
 
  const result = await generateText({
    model: openai("gpt-4.1-mini"),
    tools,
    stopWhen: stepCountIs(6),
    system: "أنت مساعد عمليات للمستخدم. كن موجزاً. لا ترسل بريداً أبداً دون تأكيد صريح.",
    prompt,
  });
 
  return NextResponse.json({
    text: result.text,
    steps: result.steps.length,
    usage: result.usage,
  });
}

يقبل المسار userId بحيث يعمل كل طلب ضد حساب Composio المرتبط الصحيح — قصة تعدد المستأجرين مدمجة منذ البداية.

أنماط الإنتاج

دليل ميداني قصير للذهاب أبعد من العرض التوضيحي.

قيّد الأدوات حسب النية، لا حسب مجموعة الأدوات

تحميل كل إجراءات Gmail لوكيل "لخّص صندوقي" يهدر الرموز. ابنِ سجلّاً صغيراً لنية ← أدوات:

const INTENT_TOOLS: Record<string, string[]> = {
  triage: ["GMAIL_FETCH_EMAILS", "GMAIL_REPLY_TO_THREAD", "LINEAR_CREATE_ISSUE"],
  release: ["GITHUB_LIST_PULL_REQUESTS", "SLACK_SEND_MESSAGE", "NOTION_CREATE_PAGE"],
};

أكّد الإجراءات المُدمّرة

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

خزّن قوائم الأدوات في الذاكرة

composio.tools.get يضرب Composio API. خزّن النتيجة لكل مستخدم/مجموعة أدوات لبضع دقائق — القائمة نادراً ما تتغير، وتنخفض زمن التوجيه بشكل ملحوظ.

قابلية الملاحظة

سجّل كل إدخال toolCalls يُعيده generateText. اقرنه مع Langfuse أو PostHog لتجيب "أي أداة فشلت أكثر الأسبوع الماضي؟" دون تخمين.

الميزانيات

يحتسب Composio فاتورة لكل تنفيذ. حُد وكيلك بـ stepCountIs(n) وارفض الطلبات التي تُطالب بمسوحات غير محدودة ("اقرأ كل بريدي منذ 2019").

اختبار التنفيذ

1. شغّل npx tsx src/connect.ts وتأكد أن Gmail يُعيد status: "ACTIVE".
2. شغّل npx tsx src/agent.ts مع طلب ملخص صندوق الوارد. يجب أن ترى استدعاء GMAIL_FETCH_EMAILS واحداً على الأقل في الخطوات.
3. بدّل الطلب إلى مثال Gmail-إلى-GitHub متعدد الخطوات وتأكد من إنشاء الإصدار.
4. شغّل خادم تطوير Next.js، أرسل POST إلى /api/agent بجسم JSON، وتأكد من الاستجابة.
5. فعّل محفّزاً، أرسل لنفسك بريداً تجريبياً، وتأكد من إطلاق webhook.

استكشاف الأخطاء وإصلاحها

Connection not found عند استدعاء الأدوات. لم يُكمل المستخدم تدفق OAuth، أو تُمرّر userId مختلفاً عن المستخدم في initiate. Composio صارم بشأن الهوية — احتفظ بمعرف قانوني واحد لكل مستخدم.

النموذج يختار الأداة الخطأ. ضيّق فلترك (أدوات أقل لكل استدعاء) أو أحدّ موجّه النظام. مع أكثر من 20 أداة، تنخفض الدقة بشدة.

حدود معدّل من واجهة برمجة التطبيقات الأساسية. يُظهر Composio خطأ الطرف الثالث حرفياً. التقطه في وقت تشغيل وكيلك وإما تراجَع أو أَظهره للمستخدم.

فشل توقيع webhook. تأكد أن السر في إعدادات Composio يطابق ما يفحصه معالجك، وأن نقطة النهاية قابلة للوصول من الإنترنت العام (استخدم ngrok في التطوير).

الخطوات التالية

• أضف HubSpot أو Salesforce ليمتلك وكيلك قدرات CRM
• اجمع Composio مع درس Claude Agent SDK لإعداد هجين
• اربط محفّزات Composio بـ دوال Inngest الدائمة لسير عمل قابل لإعادة المحاولة
• شغّل Langfuse لتتبّع كل استدعاء أداة من البداية إلى النهاية
• استبدل تطبيقات OAuth المشتركة بعملاء بعلامتك الخاصة قبل النشر للمستخدمين الفعليين

الخاتمة

يُقلّص Composio أشهر العمل اللاصق التي تفصل بين وكيل تجريبي ووكيل مفيد. ربطت المصادقة، اخترت الأدوات بذكاء، شغّلتها عبر Vercel AI SDK و OpenAI Agents SDK، تفاعلت مع أحداث في الوقت الفعلي، ونشرت كل شيء خلف مسار Next.js — دون كتابة تكامل واحد يدوياً.

وكيلك الآن يتحدث إلى التطبيقات التي يعيش فيها مستخدموك فعلاً. تلك هي الانطلاقة.