Blog

كيف تستخدم مجموعة تطوير البرمجيات لوكلاء OpenAI؟

@apidog

@apidog

21 أكتوبر 2025

كيف تستخدم مجموعة تطوير البرمجيات لوكلاء OpenAI؟

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

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

💡
قبل البدء، إليك نصيحة سريعة: نظرًا لأننا سنعمل مع واجهات برمجة التطبيقات كثيرًا في هذا الدليل، قد ترغب في الحصول على Apidog. إنه أداة مجانية تجعل اختبار وتصحيح واجهات برمجة التطبيقات سهل للغاية، وهو مثالي للتجريب مع OpenAI Agents SDK. يمكنك تنزيل Apidog مجانًا هنا. ثق بي، سيوفر عليك بعض المتاعب في المستقبل!
button

مقدمة

توفر OpenAI Agents SDK إطار عمل منظم لبناء أنظمة متعددة الوكلاء حيث يتم تخصيص كل وكيل لأداء مهام محددة. يمكن أن تتفاعل هذه الوكلاء مع المستخدمين، وتنفيذ الإجراءات من خلال الأدوات المدمجة، والتعاون من خلال تمرير المهام إلى وكلاء آخرين. تشمل المكونات الأساسية لـ SDK:

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

التثبيت والتكوين

تعد الإعدادات الصحيحة أمرًا حيويًا لاستخدام OpenAI Agents SDK بفعالية. تغطي هذه القسم المتطلبات الأساسية، وإعداد البيئة، والتثبيت، والتحقق.

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

قبل المتابعة، تأكد مما يلي:

الموقع الرسمي لبايثون
منصة OpenAI

الخطوة 1: إعداد بيئة افتراضية

تعمل البيئة الافتراضية على عزل تبعيات المشروع، مما يمنع التعارضات مع مشاريع بايثون الأخرى. لإنشاء وتفعيل واحدة:

python -m venv agents_env
source agents_env/bin/activate

python -m venv agents_env
agents_env\Scripts\activate

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

الخطوة 2: تثبيت SDK

مع تفعيل البيئة الافتراضية، قم بتثبيت SDK باستخدام pip:

pip install openai-agents

تستخرج هذه الأوامر أحدث إصدار من SDK وتبعياته من PyPI. لتأكيد التثبيت، قم بتشغيل:

pip show openai-agents-python

يعرض هذا البيانات الوصفية، بما في ذلك رقم الإصدار، مؤكدًا أن الحزمة مثبتة.

الخطوة 3: تكوين مفتاح واجهة برمجة التطبيقات

تتطلب SDK مفتاح واجهة برمجة تطبيقات OpenAI لتعمل. قم بتعيينه كمتغير بيئي لتجنب تضمينه في الشيفرة الخاصة بك، مما يعزز الأمان:

export OPENAI_API_KEY='your-api-key'

set OPENAI_API_KEY='your-api-key'

لجعل هذا دائمًا عبر الجلسات، أضف الأمر إلى ملف تكوين الصدفة الخاص بك (مثل .bashrc أو .zshrc على أنظمة يونكس). بدلاً من ذلك، يمكنك تعيينه برمجيًا في بايثون، على الرغم من أن ذلك أقل أمانًا:

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

الخطوة 4: تحقق من التثبيت

اختبر الإعداد باستخدام وكيل بسيط للتأكد من أن كل شيء يعمل:

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # النص المتوقع: "Setup successful"

إذا تمت طباعة "Setup successful"، فإن التثبيت يعمل. تشمل المشكلات الشائعة:

إنشاء وكلاء

الوكلاء هم اللبنات الأساسية لـ SDK، يتم تعريف كل منها من خلال دور وسلوك فريدين.

تهيئة الوكيل

يتم استخدام فئة Agent لإنشاء الوكلاء. تشمل المعلمات الرئيسية ما يلي:

مثال: وكيل أساسي

إليك وكيل بسيط لحساب الرياضيات:

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # الناتج: "20"

تقوم طريقة Runner.run_sync بتنفيذ الوكيل بشكل متزامن، مما يعيد كائن النتيجة مع خاصية final_output.

تكوين متقدم

خصص الوكلاء لاحتياجات معينة عن طريق تعديل المعلمات:

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # الناتج: قصة إبداعية

مثال على عدة وكلاء

قم بإنشاء وكلاء متميزين لمهام مختلفة:

support_agent = Agent(
    name="SupportBot",
    instructions="Answer technical support questions."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Generate Python code snippets."
)

support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output)  # الناتج: تعليمات التثبيت
print(code_result.final_output)     # الناتج: "def add(a, b): return a + b"

هذا يوضح مرونة SDK في التعامل مع أدوار متنوعة.

دمج الأدوات

تعزز الأدوات الوكلاء من خلال تمكينهم من تنفيذ إجراءات خارجية. يدعم SDK أدوات مستضافة، وأدوات وظيفية مخصصة، وأدوات قائمة على الوكلاء.

استخدام الأدوات المستضافة

الأدوات المستضافة، مثل web_search، هي أدوات مسبقة البناء وجاهزة للاستخدام:

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using web search.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # الناتج: "عاصمة فرنسا هي باريس."

يستدعي الوكيل تلقائيًا web_search لجلب البيانات في الوقت الحقيقي.

إنشاء أدوات الوظائف المخصصة

حدد أدواة مخصصة باستخدام الزخرفة @function_tool. يجب أن تقبل الأدوات وتعيد نصوص.

مثال: أداة جلب البيانات

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """إرجاع البيانات للمعرف المحدد."""
    # محاكاة البحث في قاعدة البيانات
    return f"Data for ID {id}: active"

agent = Agent(
    name="DataAgent",
    instructions="Retrieve data using the tool.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output)  # الناتج: "Data for ID 123: active"

دمج واجهات برمجة التطبيقات الخارجية

يمكن أن تتصل الأدوات بالخدمات الخارجية. إليك مثال على أداة الطقس:

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """الحصول على الطقس الحالي لمدينة."""
    api_key = "your-weather-api-key"  # استبداله بمفتاح حقيقي
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"الطقس في {city} هو {data['current']['condition']['text']}."
    return "بيانات الطقس غير متاحة."

agent = Agent(
    name="WeatherAgent",
    instructions="Provide weather updates using the tool.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)  # الناتج: "الطقس في طوكيو مشمس." (مثال)

قم بالتسجيل للحصول على مفتاح API مجاني في weatherapi.com لاختبار ذلك.

الموقع الرسمي weatherapi

دمج عدة أدوات

يمكن للوكلاء استخدام عدة أدوات في نفس الوقت:

@function_tool
def log_entry(text: str) -> str:
    """تسجيل الرسالة."""
    return f"Logged: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use tools to search and log.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output)  # الناتج يتضمن نتائج البحث وتأكيد السجل

تفويض الوكلاء

تسمح التفويضات للوكلاء بتفويض المهام، مما يتيح سير العمل المعقد.

إعداد التفويضات

حدد وكيلًا رئيسيًا يمكنه الوصول إلى وكلاء ثانويين عبر معلمة handoffs:

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Respond in English only."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Respond in Spanish only."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detect the language and hand off to the appropriate agent.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # الناتج: "¡Bien, gracias!" (أو مشابه)

يحلل triage_agent المدخلات ويفوض إلى الوكيل المناسب بناءً على اللغة.

منطق التفويض

يعتمد قرار التفويض على تعليمات الوكيل الرئيسي. على سبيل المثال:

اختبر مع إدخال باللغة الإنجليزية:

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # الناتج: "I'm good, thanks!"

تفويضات متداخلة

للحصول على سير عمل أعمق، يمكن للوكلاء تفويض مهام إلى وكلاء آخرين باستخدام التفويضات:

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Generate a report from analysis."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Start with analysis.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output)  # الناتج: تقرير تم إنشاؤه

تطبيق حواجز الأمان

تفرض حواجز الأمان قيودًا على المدخلات والمخرجات باستخدام نماذج Pydantic.

تحديد حاجز أمان

قم بإنشاء نموذج للتحقق من بنية المخرجات:

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine if the input is a question.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output)  # الناتج: {"is_question": true, "reason": "Ends with a question mark"}

دمج سير العمل

استخدم حواجز الأمان لتصفية المدخلات:

task_agent = Agent(
    name="TaskProcessor",
    instructions="Process questions only.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output)  # الناتج يشير إلى أنه ليس سؤالًا

التتبع وتصحيح الأخطاء

تقوم عملية التتبع بتسجيل تفاصيل تنفيذ الوكلاء، ويمكن الوصول إليها عبر لوحة تحكم OpenAI.

تمكين التتبع

التتبع تلقائي. كل تشغيل يولد تتبعًا يتضمن:

مثال على تصحيح الأخطاء

إذا فشل وكيل، راجع التتبع لتحديد:

أفضل الممارسات

تحسين الأداء

معالجة الأخطاء

تصميم سير العمل

الخاتمة

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

إذًا، ماذا بعد؟ ابدأ في التجريب! جرب تعليمات وأدوات وسير عمل مختلفة. وإذا واجهت صعوبات، يمكن أن تساعدك أدوات مثل Apidog في اختبار API، احصل عليها مجانًا.

button

ممارسة تصميم API في Apidog

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

التسجيل مجانًاتحميل