ورقة غش OpenAI Agents SDK

ورقة غش OpenAI Agents SDK

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

التثبيت

الخطوة	الأمر
التثبيت	pip install openai-agents
مع uv	uv add openai-agents
اضبط المفتاح	export OPENAI_API_KEY="sk-..."
extras الصوت	pip install "openai-agents[voice]"
التحقق	python -c "import agents; print(agents.__version__)"

وكيل بسيط

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a concise, helpful assistant.",
)

result = Runner.run_sync(agent, "Summarize the Unix philosophy in one line.")
print(result.final_output)

الاستدعاء	الوصف
Runner.run_sync(agent, input)	تشغيل متزامن
await Runner.run(agent, input)	تشغيل غير متزامن
Runner.run_streamed(agent, input)	بث الأحداث وهي تحدث
result.final_output	إجابة الوكيل النهائية
result.new_items	عناصر التشغيل المنظمة (الرسائل واستدعاءات الأدوات والتسليمات)

الأدوات

from agents import Agent, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Return the weather for a city."""
    return f"Sunny in {city}"

agent = Agent(name="Weather", tools=[get_weather])

المفهوم	الوصف
@function_tool	تحويل وظيفة Python المكتوبة إلى أداة (يتم إنشاء Schema تلقائياً من التوقيع والتوثيق)
الأدوات المستضافة	المدمجات مثل البحث على الويب والبحث عن الملفات
tool_use_behavior	التحكم في ما إذا كان مخرجات الأداة تنهي الدور
الوكلاء كأدوات	يكشف agent.as_tool(...) عن وكيل واحد كأداة قابلة للاستدعاء لوكيل آخر

التسليمات

from agents import Agent, handoff

billing = Agent(name="Billing", instructions="Handle billing questions.")
triage = Agent(
    name="Triage",
    instructions="Route the user to the right specialist.",
    handoffs=[billing],          # or handoff(billing, ...)
)

تنقل التسليمات المحادثة الكاملة إلى الوكيل المستقبل داخل التشغيل الواحد؛ تنطبق حراس المدخلات على الوكيل الأول وحراس المخرجات على الوكيل الذي ينتج المخرجات النهائية.

الحراس

from agents import Agent, input_guardrail, GuardrailFunctionOutput

@input_guardrail
async def no_secrets(ctx, agent, user_input):
    tripped = "password" in user_input.lower()
    return GuardrailFunctionOutput(output_info={}, tripwire_triggered=tripped)

agent = Agent(name="Safe", input_guardrails=[no_secrets])

النوع	التشغيلات	الغرض
@input_guardrail	قبل الوكيل	التحقق من صحة/فحص مدخلات المستخدم
@output_guardrail	بعد المخرجات النهائية	التحقق من صحة استجابة الوكيل
حراس الأدوات	حول كل استدعاء أداة	تحقق من مدخلات/مخرجات الأدوات الفردية
Tripwire	عند التنشيط	يرفع استثناء لإيقاف التشغيل

الجلسات (الذاكرة)

from agents import Agent, Runner, SQLiteSession

session = SQLiteSession("user-123", "conversations.db")
Runner.run_sync(agent, "My name is Nick.", session=session)
Runner.run_sync(agent, "What's my name?", session=session)  # remembers

الجلسة	الاستخدام
SQLiteSession	ذاكرة محادثة محلية وثابتة
الجلسة في الذاكرة	السياق الفناء داخل عملية
جلسة مخصصة	تنفيذ بروتوكول الجلسة للمتجر الخاص بك

التتبع

الميزة	الوصف
التتبعات التلقائية	كل Runner.run يسجل استدعاءات النموذج واستدعاءات الأدوات والتسليمات ونتائج الحراس والتوقيت
لوحة التحكم	تظهر التتبعات تحت مشروعك على منصة OpenAI
trace(...)	دمج عمليات متعددة في تتبع سير عمل واحد
المعالجات الخارجية	تصدير الحوافز إلى أدوات المراقبة الجهات الخارجية

سير العمل الشائع

# بث الرموز إلى واجهة مستخدم
import asyncio
from agents import Agent, Runner

async def main():
    agent = Agent(name="Writer", instructions="Write vividly.")
    streamed = Runner.run_streamed(agent, "Describe a thunderstorm.")
    async for event in streamed.stream_events():
        print(event)

asyncio.run(main())

الموارد

• التوثيق الرسمي
• مستودع GitHub
• دليل التسليمات
• دليل الحراس