OpenAI Agents SDK مع TypeScript: بناء وكلاء ذكاء اصطناعي جاهزين للإنتاج في 2026

أصدرت OpenAI رسمياً Agents SDK لتمنح مطوري TypeScript أداة احترافية وجاهزة للإنتاج لبناء أنظمة الذكاء الاصطناعي المستقلة. لا حاجة بعد اليوم لكتابة حلقات استدعاء الأدوات يدوياً، ولا لإعادة اختراع منطق التسليم بين الوكلاء المتخصصين، ولا للتساؤل عما إذا كانت حواجز الأمان قد عملت فعلاً أم لا.

في هذا الدرس التطبيقي، ستبني منصة دعم عملاء كاملة متعددة الوكلاء باستخدام OpenAI Agents SDK في TypeScript — تغطي الأدوات وعمليات التسليم والحواجز والبث المباشر والتتبع — وتنتهي بأنماط جاهزة للنقل المباشر إلى الإنتاج.

ما الذي ستتعلمه

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

• إعداد مشروع TypeScript مع @openai/agents
• تعريف وكلاء بتعليمات ونماذج وأدوات
• إضافة أدوات آمنة الأنواع مدعومة بمخططات Zod
• تنسيق تدفقات عمل متعددة الوكلاء عبر Handoffs
• التحقق من المدخلات والمخرجات بواسطة Guardrails
• بث مخرجات الوكيل إلى المستخدم في الوقت الفعلي
• فحص كل خطوة عبر لوحة Tracing المدمجة
• نشر الوكلاء مع إعادة المحاولة وضوابط التكلفة والمراقبة

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

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

• Node.js 20+ مثبت (node --version)
• مفتاح API لـ OpenAI مع وصول إلى Responses API
• معرفة عملية بـ TypeScript و async/await
• محرر كود (يُنصح بـ VS Code)
• حوالي 30 دقيقة من الوقت المركّز

ما الذي ستبنيه

منصة دعم ذكاء اصطناعي معيارية بثلاثة وكلاء متخصصين:

1. وكيل الفرز الذي يوجه الاستفسارات
2. وكيل الفوترة الذي يجيب على أسئلة الفواتير باستخدام أداة
3. وكيل الاسترداد الذي يعالج طلبات الاسترداد مع حواجز الأمان

يبث النظام الردود إلى المستخدم، وينقل الزمام بين الوكلاء حسب النية، ويسجل كل قرار عبر لوحة تتبع OpenAI.

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

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

mkdir openai-agents-tutorial && cd openai-agents-tutorial
npm init -y
npm install @openai/agents zod
npm install -D typescript tsx @types/node
npx tsc --init

حدّث tsconfig.json لاستخدام إعدادات Node الحديثة:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

أضف "type": "module" في package.json، ثم أنشئ ملف .env وأضف مفتاح API:

OPENAI_API_KEY=sk-proj-...

أضف سكريبت dev:

{
  "scripts": {
    "dev": "tsx --env-file=.env src/index.ts"
  }
}

الخطوة 2: أول وكيل لك

أنشئ src/index.ts وعرّف وكيلاً بسيطاً.

import { Agent, run } from "@openai/agents";
 
const helpAgent = new Agent({
  name: "Help Assistant",
  instructions:
    "أنت مساعد دعم ودود لـ Noqta. أجب باختصار في جملتين أو أقل.",
  model: "gpt-5",
});
 
async function main() {
  const result = await run(helpAgent, "كيف يمكنني إعادة تعيين كلمة المرور؟");
  console.log(result.finalOutput);
}
 
main();

شغّله:

npm run dev

يجب أن ترى إجابة مختصرة وفي صلب الموضوع. تنفذ الدالة run حلقة الوكيل حتى تنتج مخرجاً نهائياً أو تصل إلى حد الجولات.

الخطوة 3: أداة آمنة الأنواع مع Zod

تحتاج الوكلاء الحقيقية إلى استدعاء واجهات APIs الخاصة بك. تُعرَّف الأدوات في OpenAI Agents SDK بمخططات Zod، مما يمنحك الأمان عند الترجمة والتحقق وقت التشغيل.

أنشئ src/tools.ts:

import { tool } from "@openai/agents";
import { z } from "zod";
 
const fakeInvoices = new Map([
  ["INV-001", { amount: 89.0, status: "paid", date: "2026-04-12" }],
  ["INV-002", { amount: 240.5, status: "pending", date: "2026-05-03" }],
]);
 
export const getInvoice = tool({
  name: "get_invoice",
  description: "جلب تفاصيل الفاتورة بمعرف الفاتورة.",
  parameters: z.object({
    invoiceId: z.string().describe("معرف فاتورة مثل INV-001"),
  }),
  async execute({ invoiceId }) {
    const invoice = fakeInvoices.get(invoiceId);
    if (!invoice) return { error: `الفاتورة ${invoiceId} غير موجودة.` };
    return invoice;
  },
});

الآن، اربطها بوكيل فوترة:

import { Agent } from "@openai/agents";
import { getInvoice } from "./tools.js";
 
export const billingAgent = new Agent({
  name: "Billing Agent",
  instructions: [
    "أنت تجيب على أسئلة الفوترة لعملاء Noqta.",
    "استدعِ دائماً get_invoice قبل ذكر أي مبلغ.",
    "إذا أعادت الأداة خطأً، اعتذر واقترح التواصل مع الدعم.",
  ].join(" "),
  model: "gpt-5",
  tools: [getInvoice],
});

استبدل استدعاء main() للاختبار:

const result = await run(
  billingAgent,
  "ما حالة الفاتورة INV-002؟"
);
console.log(result.finalOutput);

سيستدعي الوكيل تلقائياً get_invoice، ويحلل النتيجة، ويرد بالحالة والمبلغ الصحيحين.

الخطوة 4: عمليات التسليم متعددة الوكلاء (Handoffs)

عمليات التسليم هي الأساس المميز للـ SDK. بدلاً من موجّه واحد ضخم، تركب وكلاء متخصصين وتدعهم ينقلون الزمام حسب نية المستخدم.

أنشئ src/refunds.ts:

import { Agent, tool } from "@openai/agents";
import { z } from "zod";
 
const issueRefund = tool({
  name: "issue_refund",
  description: "إصدار استرداد لفاتورة محددة.",
  parameters: z.object({
    invoiceId: z.string(),
    reason: z.string().describe("السبب الموجّه للعميل بشأن الاسترداد"),
  }),
  async execute({ invoiceId, reason }) {
    return {
      ok: true,
      refundId: `RF-${Date.now()}`,
      invoiceId,
      reason,
    };
  },
});
 
export const refundsAgent = new Agent({
  name: "Refunds Agent",
  instructions:
    "أنت تعالج طلبات الاسترداد. أكّد دائماً معرف الفاتورة والسبب قبل الإصدار.",
  model: "gpt-5",
  tools: [issueRefund],
});

الآن ابنِ وكيل الفرز الذي يسلم إلى الفوترة أو الاسترداد:

import { Agent, run } from "@openai/agents";
import { billingAgent } from "./billing.js";
import { refundsAgent } from "./refunds.js";
 
const triageAgent = new Agent({
  name: "Triage Agent",
  instructions: [
    "أنت مكتب الاستقبال لدعم Noqta.",
    "سلّم إلى Billing Agent لأسئلة الفواتير والدفع.",
    "سلّم إلى Refunds Agent إذا أراد المستخدم استرداد المال.",
    "وإلا، أجب مباشرة بجملة واحدة مهذبة.",
  ].join(" "),
  model: "gpt-5-mini",
  handoffs: [billingAgent, refundsAgent],
});
 
const result = await run(
  triageAgent,
  "أريد استرداد قيمة الفاتورة INV-002، فالخدمة لم تعمل."
);
console.log(result.finalOutput);

يكتشف وكيل الفرز نية الاسترداد، ويسلّم إلى وكيل الاسترداد، الذي يستدعي بدوره issue_refund ويعيد التأكيد — كل هذا دون أن تنسق آلة حالات واحدة.

الخطوة 5: الحواجز (Guardrails)

تعمل الحواجز بالتوازي مع الوكيل الرئيسي ويمكنها قطع الطلبات الخطرة أو الخارجة عن السياسة. استخدمها لفرض الأمان أو النطاق أو الامتثال.

أنشئ حاجز إدخال يمنع الطلبات خارج نطاق الدعم:

import { Agent, InputGuardrail, run } from "@openai/agents";
import { z } from "zod";
 
const scopeCheckAgent = new Agent({
  name: "Scope Check",
  instructions:
    "قرر ما إذا كان إدخال المستخدم سؤال دعم عملاء. أعد JSON.",
  model: "gpt-5-mini",
  outputType: z.object({
    isSupport: z.boolean(),
    reason: z.string(),
  }),
});
 
const supportScopeGuardrail: InputGuardrail = {
  name: "support_scope_guardrail",
  async execute({ input }) {
    const result = await run(scopeCheckAgent, input);
    return {
      outputInfo: result.finalOutput,
      tripwireTriggered: !result.finalOutput?.isSupport,
    };
  },
};

اربط الحاجز بوكيل الفرز:

const triageAgent = new Agent({
  name: "Triage Agent",
  instructions: "...",
  model: "gpt-5-mini",
  handoffs: [billingAgent, refundsAgent],
  inputGuardrails: [supportScopeGuardrail],
});

عندما يطرح المستخدم سؤالاً خارج الموضوع، يتحول tripwireTriggered إلى true ويرمي الـ SDK خطأ InputGuardrailTripwireTriggered يمكنك التقاطه ومعالجته بأناقة.

الخطوة 6: ردود البث المباشر

لواجهات الدردشة، تريد بث الـ tokens فور وصولها. يكشف الـ SDK عن API لأحداث البث:

import { run } from "@openai/agents";
 
const stream = await run(triageAgent, "أخبرني عن الفاتورة INV-001.", {
  stream: true,
});
 
for await (const event of stream) {
  if (event.type === "raw_model_stream_event") {
    if (event.data.type === "output_text_delta") {
      process.stdout.write(event.data.delta);
    }
  }
  if (event.type === "agent_updated_stream_event") {
    console.error(`\n[تسليم إلى: ${event.agent.name}]`);
  }
}
 
await stream.completed;
console.log("\n\nالنهائي:", stream.finalOutput);

تحصل على أحداث دقيقة لـ deltas الـ tokens، واستدعاءات الأدوات، وعمليات التسليم، والمخرج النهائي. مرّر output_text_delta إلى واجهة المستخدم عبر Server-Sent Events أو WebSockets.

الخطوة 7: التتبع والمراقبة

يتم تتبع كل تشغيل للوكيل تلقائياً إلى لوحة OpenAI على platform.openai.com/traces. ترى شجرة كاملة من استدعاءات LLM، استدعاءات الأدوات، عمليات التسليم، وتقييمات الحواجز — ملوّنة ومحاذاة على خط زمني.

لإضافة بيانات وصفية مخصصة للتصفية لاحقاً:

import { withTrace, run } from "@openai/agents";
 
await withTrace(
  "support_session",
  async () => {
    await run(triageAgent, userMessage);
  },
  {
    metadata: {
      userId: "user_42",
      tier: "pro",
      sessionId: "sess_abc123",
    },
  }
);

في الإنتاج، يمكنك أيضاً إعادة توجيه التتبعات إلى Logfire أو Langfuse أو Braintrust أو AgentOps بتثبيت حزم المعالجات الخاصة بها. خط أنابيب التتبع قابل للتوسعة.

الخطوة 8: أنماط الإنتاج

إليك الأنماط التي نستخدمها في Noqta عند نشر الوكلاء في حركة حقيقية.

تحديد الجولات والتكلفة

ضع سقف maxTurns كي لا يستهلك وكيل خارج عن السيطرة ميزانيتك في حلقة:

await run(triageAgent, userMessage, { maxTurns: 8 });

اجمع ذلك مع ميزانيات الـ tokens على مستوى منظمة OpenAI للحصول على حدود صارمة.

حفظ تاريخ المحادثة

يقبل الـ SDK مصفوفة history من الرسائل السابقة ليتمكن المستخدمون من إجراء محادثات متعددة الجولات:

const result = await run(triageAgent, userMessage, {
  history: previousMessages,
});
 
const updatedHistory = result.history;

احفظ updatedHistory في قاعدة بياناتك (Postgres، Redis، Convex) مفهرساً بمعرف الجلسة.

إعادة المحاولة عند الأخطاء العابرة

لُف run() بمساعد إعادة محاولة للأخطاء المتعلقة بحدود المعدل والشبكة:

import { run } from "@openai/agents";
 
async function runWithRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  let lastError: unknown;
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      lastError = err;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
    }
  }
  throw lastError;
}
 
await runWithRetry(() => run(triageAgent, userMessage));

استخدام نماذج أرخص للفرز

مرّر الطلبات عبر وكيل فرز سريع على gpt-5-mini، ولا تتصاعد إلى gpt-5 إلا عند حدوث عمليات التسليم. يخفض هذا متوسط التكلفة بنسبة 60 إلى 80 بالمئة في أحمال العمل الحقيقية.

عزل الآثار الجانبية للأدوات

إذا كانت الأداة تكتب في قاعدة بيانات أو تشحن بطاقة، ضعها خلف وضع dry-run أثناء التطوير واشترط علم بيئة لتمكين الكتابات الحقيقية في الإنتاج.

اختبار التطبيق

فحوصات سريعة:

# فرز إلى الفوترة
npm run dev -- "ما حالة INV-001؟"
 
# فرز إلى الاسترداد
npm run dev -- "أعد لي قيمة الفاتورة INV-002 من فضلك."
 
# تفعيل الحاجز
npm run dev -- "اكتب لي قصيدة عن الكرواسون."

افتح لوحة تتبع OpenAI وتأكد أن شجرة التتبع تطابق توقعاتك: وكيل الفرز في الجذر، تشغيلات فرعية لكل تسليم، استدعاءات الأدوات تحت الوكيل المسؤول.

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

الوكيل لا يستدعي الأداة أبداً. تأكد أن وصف أداتك يبدأ بفعل ("جلب"، "إصدار"، "إنشاء") وأن مخطط Zod يطابق المعاملات التي ينتجها LLM. افحص التتبع لرؤية معاملات الأداة الخام.

يتم تجاهل عمليات التسليم. يحتاج وكيل الفرز إلى تعليمات صريحة تخبره متى يسلّم وإلى أي وكيل. التعليمات الغامضة مثل "فوّض حسب الحاجة" نادراً ما تنجح — كن محدداً.

الحاجز يرمي خطأً ولا تستطيع التقاطه. لُف استدعاء run() في try/catch وافحص InputGuardrailTripwireTriggered من @openai/agents. يصدّر الـ SDK فئات الأخطاء هذه صراحة.

استخدام الـ tokens يتضخم. أنزل maxTurns، انقل طبقة الفرز إلى gpt-5-mini، وراجع التتبع بحثاً عن استدعاءات أدوات متكررة. خطأ شائع هو أن يستدعي الوكيل الأداة نفسها مراراً لأن مخرجها غير واضح.

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

الآن وقد عمل القلب، إليك ما يأتي بعد:

• أضف الدعم الصوتي عبر OpenAI Realtime API — يمكن تغليف الوكلاء في حلقة صوتية
• اربط خوادم MCP كمصادر أدوات باستخدام دعم MCP المدمج في الـ SDK
• ضع تقييمات Langfuse أو Braintrust فوق تتبعاتك
• انقل حالة المحادثة إلى Convex أو Postgres للاستمرارية متعددة الجلسات
• انشر بيئة تشغيل الوكيل على Vercel أو Cloudflare Workers أو AWS Lambda

إذا لم تطلع عليه بعد، يغطي دليلنا المرافق حول Claude Agent SDK في TypeScript أساسيات Anthropic المكافئة، وهو مفيد لمقارنة المقايضات بين المزودين.

الخلاصة

لقد بنيت منصة دعم عملاء متعددة الوكلاء مع OpenAI Agents SDK — أدوات آمنة الأنواع، عمليات تسليم ذكية، حواجز إدخال، بث، وتتبع كامل — في أقل من 300 سطر من TypeScript. يزيل الـ SDK الكود التكراري لتتمكن من التركيز على ما ينبغي أن يفعله الوكيل بدلاً من كيفية تنفيذه.

انشره، راقبه، وكرّر بناءً على بيانات التتبع. هذه هي الحلقة التي تحول نموذجاً أولياً ذكياً إلى وكيل يعتمد عليه عملاؤك فعلاً.