OpenAI Agents SDK إطار عمل بلغة Python لبناء وكلاء يستخدمون الأدوات وعمليات التسليم (handoffs) وضوابط الحماية (guardrails). وتشرح وثائقه كيفية ربط مزوّدين من غير OpenAI. ومع واجهة API متوافقة مع OpenAI مثل BroadNet Inference، تعطي SDK عميل AsyncOpenAI خاصًا بك وتستخدم صنف نموذج Chat Completions. فالحزمة تستخدم Responses API افتراضيًا، وهي واجهة لا يقدّمها كثير من المزوّدين.
الإعداد
- ثبّت الحزمة. تحتاج إلى Python 3.10 أو أحدث.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
- أنشئ العميل والنموذج والوكيل.
import asyncio
import os
from agents import (
Agent,
AsyncOpenAI,
OpenAIChatCompletionsModel,
Runner,
function_tool,
set_tracing_disabled,
)
set_tracing_disabled(disabled=True) # tracing needs a platform.openai.com key
client = AsyncOpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
)
model = OpenAIChatCompletionsModel(model="broadnet/glm-5.3", openai_client=client)
@function_tool
def get_order_status(order_id: str) -> str:
"""Look up an order."""
return f"Order {order_id}: shipped"
agent = Agent(
name="Support agent",
instructions="Answer briefly. Use tools when you need order data.",
model=model,
tools=[get_order_status],
)
async def main():
result = await Runner.run(agent, "Where is order 4471?")
print(result.final_output)
asyncio.run(main())
- شغّله. يُفترض أن يستدعي الوكيل
get_order_statusثم يجيب بناءً على نتيجتها.
ثلاث طرق لربط المزوّد
تذكر وثائق SDK هذه الخيارات المدمجة:
- لكل وكيل: مرّر
OpenAIChatCompletionsModelفيAgent.modelكما في المثال أعلاه. استخدم هذه الطريقة عندما يستخدم كل وكيل مزوّدًا مختلفًا. - افتراضي عام: تجعل
set_default_openai_client(client)عميلك هو العميل الافتراضي. استخدمها معset_default_openai_api("chat_completions"). - لكل تشغيل: مرّر
ModelProviderمخصّصًا فيRunConfig(model_provider=...).
وهكذا يبدو الإعداد الافتراضي العام:
import os
from agents import (
Agent,
AsyncOpenAI,
set_default_openai_api,
set_default_openai_client,
set_tracing_disabled,
)
client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")
set_tracing_disabled(True)
agent = Agent(name="Assistant", instructions="Be brief.", model="broadnet/glm-5.3")
وإذا كنت تكتفي بمتغيرات البيئة، فاضبط OPENAI_BASE_URL=https://inference.broadnet.ai/v1 واضبط OPENAI_API_KEY على مفتاح BroadNet، ثم نفّذ استدعاءَي set_default_openai_api وset_tracing_disabled نفسيهما.
عند التوجيه عبر Chat Completions، تقول وثائق SDK إنها تُسقط بصمت الحقول الخاصة بـ Responses فقط، مثل previous_response_id وconversation_id وprompt. وللحصول على خطأ بدلًا من ذلك، اضبط strict_feature_validation=True على OpenAIProvider. احتفظ بحالة المحادثة في شيفرتك، كأن تمرّر قائمة المدخلات من النتيجة السابقة إلى التشغيل التالي. أما أدوات OpenAI المستضافة، مثل البحث في الويب والبحث في الملفات، فلا وجود لها لدى المزوّدين الآخرين. استخدم function_tool لكل ما يجب أن يستدعيه الوكيل.
التتبّع
التتبّع (tracing) مفعّل افتراضيًا ويرسل البيانات إلى OpenAI. وتقول وثائق SDK إنه إن لم يكن لديك مفتاح API من platform.openai.com فعليك تعطيله بـ set_tracing_disabled() أو إعداد معالج تتبّع آخر. وإذا كان لديك مفتاح OpenAI، فيمكنك إبقاء التتبّع مفعّلًا وتمرير ذلك المفتاح عبر set_tracing_export_api_key(...). لا تستخدمه SDK إلا لرفع بيانات التتبّع، ولن يعمل مفتاح BroadNet لهذا الغرض.
أي نموذج تختار
| نوع الوكيل | النموذج | ملاحظات |
|---|---|---|
| وكلاء يستخدمون الأدوات | GLM 5.3 | الأدوات والمخرجات المنظَّمة مدرجة؛ سياق 1M |
| إدخال الصور مع الأدوات | Qwen3.8 27B | سياق 262K؛ مُختبَر بالعربية |
| وكلاء طويلو التشغيل بسعر ثابت | DeepSeek V4.1 Flash | خطط غير محدودة؛ لا يدرج BroadNet الأدوات له |
تحذّر وثائق SDK من أن بعض المزوّدين لا يدعمون المخرجات المنظَّمة وفق JSON schema. فإذا ضبطت output_type على وكيل، فاستخدم GLM 5.3 أو Qwen3.8 27B. قارن الأسعار في صفحة الأسعار.
حل المشكلات
- 401. مفتاح BroadNet خاطئ أو منتهي الصلاحية، أو استُنفدت حصة الدفع حسب الاستخدام. أما أخطاء التتبّع في السجلات فأمر منفصل: تعني أن التتبّع ما زال مفعّلًا دون مفتاح OpenAI.
- 404 أو “not found”. الأرجح أنك تستخدم Responses API. استخدم
OpenAIChatCompletionsModelأوset_default_openai_api("chat_completions"). وإذا كان ذلك مضبوطًا، فتأكّد من تطابق معرّف النموذج مع معرّف BroadNet تمامًا. تحتاج النماذج المدفوعة إلى شحن الرصيد؛ فرصيد $5 لا يغطي إلا Gemma 4 VL 26B ونموذجَي Transcribe. final_outputفارغ. يُحتسب الاستدلال المنطقي ضمنmax_tokens. إذا ضبطتModelSettings(max_tokens=...)، فارفع القيمة. لماذا تصل الإجابات فارغة.- 429. يسمح مفتاح الدفع حسب الاستخدام بـ 30 من الطلبات في الدقيقة و4 في آنٍ واحد. وكل جولة استدعاء أداة طلب جديد. راجع الأخطاء وإعادة المحاولة.
- وكلاء متوازون على خطة. تشغّل جلسة الخطة غير المحدودة طلبًا واحدًا في كل مرة. فالوكلاء الذين يُطلَقون معًا عبر
asyncio.gatherيحتاج كل منهم إلى جلسة، وإلا اصطفّوا في طابور. راجع تشغيل وكلاء متوازين بسعر ثابت.
