دليل OpenAI Agents SDK في Python: ابْنِ وكلاء AI Agents أذكى وبشكل أسرع

دروس AI agents موجودة في كل مكان، لكن معظمها يتجاوز الجزء الأهم في بيئة الإنتاج: كيفية هيكلة الأدوات (tools)، وكيفية توجيه العمل بين الوكلاء المتخصّصين، وكيفية فحص ما حدث فعليًا أثناء التشغيل. لهذا السبب يُعدّ OpenAI Agents SDK Python موضوعًا قويًا في الوقت الراهن. نيّة البحث واضحة، والكلمة المفتاحية ترتبط بمشكلة تنفيذ حقيقية، والوثائق الرسمية تقدّم للمطوّرين بالفعل مسارًا يمتدّ من الـ prompts البسيطة إلى سير عمل موجَّه مع tracing.

إذا أردت تجاوز نصوص chatbot المنفردة، فإن هذا الدليل يوضّح ما يجيده الـ SDK، وكيف تبدأ، وأين يندرج ضمن حزمة Python عملية. وللاطّلاع على نظرة أوسع لمعماريات الوكلاء، راجع دليلنا حول Building AI Agents with Python.

لماذا يهمّ هذا الموضوع الآن

تحوّل النقاش الحالي حول الوكلاء من «هل أستطيع استدعاء نموذج؟» إلى «هل أستطيع بناء سير عمل موثوق حوله؟». هذا التحوّل مهمّ لكلٍّ من تحسين محرّكات البحث (SEO) وهندسة المنتج.

يركّز دليل البدء السريع (quickstart) الرسمي للـ SDK من OpenAI على الأجزاء التي يهتمّ بها المطوّرون أولًا:

• إنشاء وكيل (agent)
• تشغيله عبر runner
• ربط الأدوات (tools)
• إضافة وكلاء آخرين
• تعريف عمليات التسليم (handoffs)
• عرض عمليات التتبّع (traces)

يهمّ هذا التسلسل لأنه يحاكي النموّ الفعلي للمنتج. عادةً ما تبدأ بوكيل واحد، ثم تضيف الأدوات، ثم تقسّم المسؤوليات، ثم تصحّح السلوك. وفي أكتوبر 2025، وصفت OpenAI أيضًا AgentKit بأنه تطوير للحزمة السابقة المكوّنة من Responses API وAgents SDK، وهي إشارة جيدة إلى أن سير عمل الوكلاء يظلّ مجالًا استراتيجيًا لا تجربة عابرة.

بالنسبة إلى موقع يركّز على Python، يُعدّ هذا هدفًا أفضل لتحسين محرّكات البحث من مقال غامض من نوع «AI agents explained». فالشخص الذي يبحث عن OpenAI Agents SDK Python يريد على الأرجح شيفرة وخطوات إعداد وإرشادات معمارية، لا نظرية عامة.

ماذا يقدّم لك OpenAI Agents SDK فعليًا

الـ SDK مفيد لأنه يوفّر تجريدًا أنظف للأنماط الشائعة للوكلاء.

1. الوكلاء (Agents)

يجمع الوكيل بين تعليمات واسم وإعداد اختياري. يبدو ذلك بسيطًا، لكنه يُنشئ وحدة قابلة لإعادة الاستخدام يمكنك التفكير فيها بوضوح، بدلًا من تشتيت الـ prompts عبر شيفرة التطبيق بأكملها.

2. الأدوات (Tools)

تتيح الأدوات لوكيلك القيام بشيء ملموس، مثل استدعاء دالة Python، أو البحث عن بيانات، أو تشغيل إجراء تجاري. هنا يبدأ الوكلاء بالتحوّل من مجرد عروض توضيحية إلى منتجات.

3. عمليات التسليم (Handoffs)

تتيح عمليات التسليم لوكيل أن يوجّه العمل إلى وكيل متخصّص آخر. وهذا مفيد عندما تريد طبقة فرز (triage)، مثل:

1. موجِّه للدعم
2. متخصّص في الفوترة
3. متخصّص في الوثائق

غالبًا ما يكون هذا النمط أسهل في الصيانة من وكيل واحد ضخم محمّل بتعليمات أكثر من اللازم.

من واقع خبرتي في بناء أطر عمل AI agents في Codiste، فإن نمط الـ handoff هو ما يفصل وكلاء العرض التوضيحي عن الوكلاء الجاهزين للإنتاج. عندما بنيت نظام chatbot توليديًا باستخدام LSTM وBART، حاولت في البداية حشر جميع القدرات في وكيل واحد، فاصطدمت سريعًا بجدار من تعارض الـ prompts والتوجيه غير المتوقّع. وأدّى التقسيم إلى وكلاء متخصّصين بقواعد تسليم واضحة إلى جعل النظام أكثر موثوقية بشكل كبير.

4. تتبّع التنفيذ (Tracing)

يُعدّ الـ tracing من أكبر المكاسب العملية. فعندما يختار الوكيل الأداة الخطأ أو يوجّه طلبًا توجيهًا سيئًا، تحتاج إلى رؤية واضحة. وتوجّه وثائق الـ SDK المطوّرين صراحةً إلى Trace viewer ليتمّ فحص عمليات التشغيل بدلًا من تخمينها.

إعداد سريع لمشروعك الأول

يستخدم دليل البدء السريع الرسمي إعدادًا قياسيًا لمشروع Python. ويبدو التثبيت الأدنى كما يلي:

python -m venv .venv
.venv\Scripts\activate
pip install openai-agents

ستحتاج أيضًا إلى OPENAI_API_KEY في بيئتك قبل تشغيل الأمثلة.

ومن هناك، يكون أصغر مثال عملي مباشرًا:

import asyncio
from agents import Agent, Runner

agent = Agent(
    name="Python Helper",
    instructions="Answer Python questions clearly and concisely.",
)

async def main():
    result = await Runner.run(
        agent,
        "Explain list comprehensions with one short example."
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

هذا المثال صغير عن قصد، لكنه يوضّح العقد الأساسي: عرّف وكيلًا، ومرّر المُدخل إلى الـ runner، واقرأ المُخرج النهائي.

إضافة الأدوات تجعل الـ SDK أكثر فائدة بكثير

يصبح OpenAI Agents SDK Python مثيرًا للاهتمام عند استخدام الأدوات. تعرض الوثائق الرسمية نمط function_tool، وهو طريقة نظيفة لكشف منطق Python أمام الوكيل.

إليك مثالًا بسيطًا:

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def get_python_tip() -> str:
    return "Use enumerate() when you need both index and value."

agent = Agent(
    name="Python Coach",
    instructions="Help users learn Python. Use get_python_tip when useful.",
    tools=[get_python_tip],
)

async def main():
    result = await Runner.run(agent, "Give me one practical Python habit.")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

يتوسّع هذا النمط بشكل أفضل من حشر كل إجابة داخل prompt. فبدلًا من أن تأمل أن يتذكّر النموذج قواعد عملك، يمكنك نقل المنطق المستقرّ إلى دوال Python وترك الوكيل يستدعيها عند الحاجة.

بالنسبة لقرّاء المدوّنة الذين يبنون تطبيقات حقيقية، هذه هي الزاوية الفريدة الجديرة بالتأكيد: الـ SDK ليس مجرد غلاف (wrapper) حول استدعاء نموذج، بل هو طبقة سير عمل لفِرَق Python التي تريد حدودًا أوضح بين الاستدلال والتوجيه والتنفيذ. وللاطّلاع على طريقة موحّدة لكشف الأدوات والسياق أمام الوكلاء، انظر كيف يكمّل Model Context Protocol هذا النهج.

توجيه متعدد الوكلاء دون فوضى

يصطدم كثير من المطوّرين بالتعقيد بمجرّد أن يضطر وكيل واحد إلى فعل الكثير. ويعالج دليل البدء السريع ذلك مباشرةً بعرض عدة وكلاء وعمليات handoff.

على سبيل المثال، يمكنك إنشاء:

• وكيل فرز (triage agent) للطلبات الواردة
• وكيل برمجة (coding agent) للأسئلة التقنية
• وكيل محتوى (content agent) لإعادة صياغة النصوص أو تلخيصها

لهذا التصميم ميزتان. الأولى أن الـ prompts تبقى أصغر وأسهل في الصيانة. والثانية أن التقييم يصبح أكثر دلالة لأن لكل وكيل مهمّة أضيق.

إذا كنت تكتب أدوات داخلية أو أنظمة دعم أو مساعدين بحثيين، فإن OpenAI Agents SDK Python يمنحك بنية افتراضية معقولة قبل أن تبتكر طبقة التنسيق (orchestration) الخاصة بك. وهذا يمكن أن يوفّر الوقت ويقلّل الدَّيْن التقني مبكرًا.

أفضل الممارسات قبل الإطلاق

إذا كنت تنتقل من العرض التوضيحي إلى الإنتاج، فضع هذه القواعد في الحسبان:

• اجعل أوصاف الأدوات صريحة كي يعرف النموذج متى يستدعيها
• افصل سلوك التوجيه عن خبرة المجال
• افحص عمليات الـ traces قبل تغيير الـ prompts بشكل أعمى
• ابدأ بوكيل واحد وأداة واحدة، ثم أضِف عمليات handoff عند الحاجة فقط
• انقل منطق العمل الحتمي إلى Python، لا إلى تعليمات طويلة

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

نقطة عملية أخرى: ليست كل سير عمل بحاجة إلى عدة وكلاء. أحيانًا يكون وكيل واحد بأداتين مصمَّمتين جيدًا هو الحل الأنظف. ويدعم الـ SDK كلا النمطين، وتميّز الوثائق صراحةً بين عمليات الـ handoff وإعداد على نمط المنسِّق (orchestrator) يمكن فيه استخدام الوكلاء كأدوات.

تلك المرونة جزء من سبب جدارة هذه الكلمة المفتاحية بالاستهداف. فالباحثون عن OpenAI Agents SDK Python عادةً ما يكونون قريبين من مرحلة التنفيذ. إنهم يريدون أمثلة ومفاضلات ومسارًا لا ينهار حين يكبر مشروعهم.

الخلاصة

إذا كان موقعك يغطّي Python أو الـ AI أو أدوات المطوّرين، فهذا نوع الموضوعات القادرة على جذب زيارات بحث مؤهَّلة: راهنة وعملية ومرتبطة بمنظومة رسمية لا تزال في توسّع.

الخطوة التالية الصحيحة ليست المبالغة في البناء. ابدأ بوكيل واحد، وأضِف أداة function tool واحدة، وشغّل بضعة prompts حقيقية، وراجع عمليات الـ traces. وحين ينجح ذلك، قسّم المسؤوليات فقط حيث يساعد التوجيه فعليًا.

إذا أردت بناء أول سير عمل للوكلاء مناسب للإنتاج هذا الأسبوع، فإن OpenAI Agents SDK Python من أوضح نقاط البداية. جرّب دليل البدء السريع، وكيّف الأمثلة مع مجالك، وحوّل سير عمل مفيدًا واحدًا إلى خدمة وكيل قابلة لإعادة الاستخدام. وإذا احتاج وكلاؤك إلى استدلال خاصّ بالمجال، يمكنك ضبط نموذج LLM (fine-tune) لتشغيلهم.

---

مقالات ذات صلة

• Building AI Agents with Python: A Complete Guide - تعلّم أساسيات معمارية AI agents واستخدام الأدوات والذاكرة من الصفر
• Model Context Protocol Python Tutorial - وحِّد طريقة اتصال وكلائك بالأدوات والبيانات الخارجية عبر MCP
• Fine-Tuning Large Language Models with Python - درّب نماذج خاصّة بالمجال لتشغيل سير عمل وكلائك

المصادر

• OpenAI Agents SDK Quickstart

• [Introducing AgentKit

  OpenAI](https://openai.com/index/introducing-agentkit/)