BroadRouter

تشغيل OpenAI Agents SDK على BroadNet Inference

آخر تحديث

أنشئ عميل AsyncOpenAI مع ضبط base_url على https://inference.broadnet.ai/v1 ووضع مفتاح BroadNet، ثم غلّفه في OpenAIChatCompletionsModel مع معرّف نموذج مثل broadnet/glm-5.3، ومرّر هذا النموذج إلى Agent. استدعِ set_tracing_disabled(True) ما لم يكن لديك مفتاح OpenAI منفصل للتتبّع.

OpenAI Agents SDK إطار عمل بلغة Python لبناء وكلاء يستخدمون الأدوات وعمليات التسليم (handoffs) وضوابط الحماية (guardrails). وتشرح وثائقه كيفية ربط مزوّدين من غير OpenAI. ومع واجهة API متوافقة مع OpenAI مثل BroadNet Inference، تعطي SDK عميل AsyncOpenAI خاصًا بك وتستخدم صنف نموذج Chat Completions. فالحزمة تستخدم Responses API افتراضيًا، وهي واجهة لا يقدّمها كثير من المزوّدين.

الإعداد

  1. ثبّت الحزمة. تحتاج إلى Python 3.10 أو أحدث.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
  1. أنشئ العميل والنموذج والوكيل.
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())
  1. شغّله. يُفترض أن يستدعي الوكيل 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 يحتاج كل منهم إلى جلسة، وإلا اصطفّوا في طابور. راجع تشغيل وكلاء متوازين بسعر ثابت.

أسئلة شائعة

لماذا تظهر أخطاء 404 من Agents SDK عند استخدام base URL مخصّص؟

تستخدم حزمة SDK الواجهة Responses API افتراضيًا، بينما يقدّم BroadNet إكمال المحادثات (chat completions). استخدم OpenAIChatCompletionsModel، أو استدعِ set_default_openai_api("chat_completions") إذا كنت تضبط العميل عبر متغيرات البيئة.

لماذا تشتكي Agents SDK من التتبّع (tracing)؟

يرفع التتبّع البيانات إلى OpenAI ويحتاج إلى مفتاح من platform.openai.com. وتوصي وثائق SDK باستدعاء set_tracing_disabled() إن لم يكن لديك مفتاح، أو باستخدام معالج تتبّع آخر.

هل يمكنني إعداد Agents SDK بمتغيرات البيئة فقط؟

نعم. اضبط OPENAI_BASE_URL على https://inference.broadnet.ai/v1 وOPENAI_API_KEY على مفتاح BroadNet، ثم استدعِ set_default_openai_api("chat_completions") وset_tracing_disabled(True). ويحدّد OPENAI_DEFAULT_MODEL النموذج للوكلاء الذين لا يسمّون نموذجًا.

كم جلسة من جلسات الخطة يحتاج تشغيل متعدد الوكلاء؟

جلسة واحدة لكل طلب يعمل في الوقت نفسه. عمليات التسليم (handoffs) تشغّل وكيلًا بعد آخر، فتكفي جلسة واحدة. أما الوكلاء الذين يعملون بالتوازي عبر asyncio.gather فيحتاج كل منهم إلى جلسة.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity