دليل الترقية: خيارات الدردشة ك TypedDict مع الأنواع المعممة

يساعدك هذا الدليل على ترقية التعليمات البرمجية Python إلى النظام الجديد المستند إلى Options TypedDict المقدم في الإصدار 1.0.0b260114 من إطار عمل عامل Microsoft. هذا تغيير فاصل يوفر أمانا محسنا للنوع والإكمال التلقائي ل IDE وقابلية التوسع في وقت التشغيل.

نظرة عامة على التغييرات

يقدم هذا الإصدار إعادة بناء التعليمات البرمجية الرئيسية لكيفية تمرير الخيارات إلى عملاء الدردشة ووكلاء الدردشة.

كيفية عملها من قبل

في السابق، تم تمرير الخيارات كوسيطات كلمات أساسية مباشرة على أساليب مثل get_response()منشئات get_streaming_response()run()الوكيل و:

# Options were individual keyword arguments
response = await client.get_response(
    "Hello!",
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

# For provider-specific options not in the base set, you used additional_properties
response = await client.get_response(
    "Hello!",
    model="gpt-4",
    additional_properties={"reasoning_effort": "medium"},
)

كيف يعمل الآن

يتم الآن تمرير معظم الخيارات من خلال معلمة واحدة options كقاموس مكتوب:

# Most options go in a single typed dict
response = await client.get_response(
    "Hello!",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
        "reasoning_effort": "medium",  # Provider-specific options included directly
    },
)

ملاحظة: بالنسبة إلى العوامل، instructions تظل المعلمات و tools متوفرة كوسيطات مباشرة للكلمات الأساسية على Agent.__init__() و client.as_agent(). بالنسبة إلى agent.run()، يتوفر فقط tools كوسيطة للكلمة الأساسية:
# Agent creation accepts both tools and instructions as keyword arguments
agent = Agent(
    client=client,
    tools=[my_function],
    instructions="You are a helpful assistant.",
    default_options={"model": "gpt-4", "temperature": 0.7},
)

# agent.run() only accepts tools as a keyword argument
response = await agent.run(
    "Hello!",
    tools=[another_function],  # Can override tools per-run
)

التغييرات الرئيسية

معلمة الخيارات الموحدة: يتم الآن تمرير معظم وسيطات الكلمة الأساسية (model، temperatureوما إلى ذلك) عبر إملاء واحد options
استثناء لإنشاء عامل: instructions والبقاء tools متاحة كوسيطات الكلمات الأساسية المباشرة على Agent.__init__() و as_agent()
استثناء تشغيل العامل: tools يظل متوفرا كوسيطة كلمة أساسية مباشرة على agent.run()
الخيارات المستندة إلى TypedDict: يتم تعريف الخيارات كفئات TypedDict لسلامة النوع
دعم النوع العام: يدعم عملاء الدردشة والوكلاء الأنواع المعممة للخيارات الخاصة بموفر الخدمة، للسماح بالتحميل الإضافي لوقت التشغيل
خيارات خاصة بموفر الخدمة: لكل موفر TypedDict الافتراضي الخاص به (على سبيل المثال، OpenAIChatOptions، ) OllamaChatOptions
لا مزيد من additional_properties: المعلمات الخاصة بموفر الخدمة هي الآن حقول مكتوبة من الدرجة الأولى

الفوائد

أمان النوع: الإكمال التلقائي ل IDE والتحقق من النوع لكافة الخيارات
مرونة الموفر: دعم المعلمات الخاصة بموفر الخدمة في اليوم الأول
التعليمات البرمجية الأنظف: تمرير معلمة متسقة تستند إلى الإملاء
الامتداد الأسهل: إنشاء خيارات مخصصة لحالات الاستخدام المتخصصة (على سبيل المثال، نماذج المنطق أو الخلفيات الأخرى لواجهة برمجة التطبيقات)

دليل الهجرة

1. تحويل وسيطات الكلمة الأساسية إلى خيارات الإملاء

التغيير الأكثر شيوعا هو تحويل وسيطات الكلمات الأساسية الفردية إلى options القاموس.

قبل (وسيطات الكلمة الأساسية):

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# Options passed as individual keyword arguments
response = await client.get_response(
    "Hello!",
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

# Streaming also used keyword arguments
async for chunk in client.get_streaming_response(
    "Tell me a story",
    model="gpt-4",
    temperature=0.9,
):
    print(chunk.text, end="")

بعد (خيارات الإملاء):

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# All options now go in a single 'options' parameter
response = await client.get_response(
    "Hello!",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
    },
)

# Same pattern for streaming
async for chunk in client.get_response(
    "Tell me a story",
    options={
        "model": "gpt-4",
        "temperature": 0.9,
    },
    stream=True,
):
    print(chunk.text, end="")

إذا قمت بتمرير الخيارات غير المناسبة لهذا العميل، فستحصل على خطأ نوع في IDE الخاص بك.

2. استخدام خيارات Provider-Specific (لا مزيد من additional_properties)

في السابق، لتمرير المعلمات الخاصة بالموفر التي لم تكن جزءا من المجموعة الأساسية من وسيطات الكلمة الأساسية، كان عليك استخدام المعلمة additional_properties :

قبل (باستخدام additional_properties):

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()
response = await client.get_response(
    "What is 2 + 2?",
    model="gpt-4",
    temperature=0.7,
    additional_properties={
        "reasoning_effort": "medium",  # No type checking or autocomplete
    },
)

بعد (خيارات مباشرة مع TypedDict):

from agent_framework.openai import OpenAIChatClient

# Provider-specific options are now first-class citizens with full type support
client = OpenAIChatClient()
response = await client.get_response(
    "What is 2 + 2?",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "reasoning_effort": "medium",  # Type checking or autocomplete
    },
)

بعد (التصنيف الفرعي المخصص للمعلمات الجديدة):

أو إذا كانت معلمة ليست جزءا من إطار عمل العامل (لأنها جديدة، أو لأنها مخصصة لخلفية متوافقة مع OpenAI)، يمكنك الآن تصنيف الخيارات الفرعية واستخدام الدعم العام:

from typing import Literal
from agent_framework.openai import OpenAIChatOptions, OpenAIChatClient

class MyCustomOpenAIChatOptions(OpenAIChatOptions, total=False):
    """Custom OpenAI chat options with additional parameters."""

    # New or custom parameters
    custom_param: str

# Use with the client
client = OpenAIChatClient[MyCustomOpenAIChatOptions]()
response = await client.get_response(
    "Hello!",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "custom_param": "my_value",  # IDE autocomplete works!
    },
)

الفائدة الرئيسية هي أن معظم المعلمات الخاصة بالموفر أصبحت الآن جزءا من قاموس الخيارات التي تم كتابتها، مما يمنحك:

الإكمال التلقائي ل IDE لجميع الخيارات المتاحة
التحقق من الكتابة لالتقاط مفاتيح أو قيم غير صالحة
لا حاجة additional_properties لمعلمات الموفر المعروفة
ملحق سهل للمعلمات المخصصة أو الجديدة

3. تحديث تكوين العامل

تتبع أساليب تهيئة العامل وتشغيله نفس النمط:

قبل (وسيطات الكلمة الأساسية على الدالة الإنشائية وتشغيلها):

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# Default options as keyword arguments on constructor
agent = Agent(
    client=client,
    name="assistant",
    model="gpt-4",
    temperature=0.7,
)

# Run also took keyword arguments
response = await agent.run(
    "Hello!",
    max_tokens=1000,
)

بعد:

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions

client = OpenAIChatClient()
agent = Agent(
    client=client,
    name="assistant",
    default_options={ # <- type checkers will verify this dict
        "model": "gpt-4",
        "temperature": 0.7,
    },
)

response = await agent.run("Hello!", options={ # <- and this dict too
    "max_tokens": 1000,
})

4. خيارات Provider-Specific

كل موفر لديه الآن TypedDict الخاص به للخيارات، يتم تمكينها بشكل افتراضي. يسمح لك هذا باستخدام معلمات خاصة بالموفر مع أمان النوع الكامل:

مثال OpenAI:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()
response = await client.get_response(
    "Hello!",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "reasoning_effort": "medium",
    },
)

ولكن يمكنك أيضا جعله صريحا:

from agent_framework_anthropic import AnthropicClient, AnthropicChatOptions

client = AnthropicClient[AnthropicChatOptions]()
response = await client.get_response(
    "Hello!",
    options={
        "model": "claude-3-opus-20240229",
        "max_tokens": 1000,
    },
)

5. إنشاء خيارات مخصصة للنماذج المتخصصة

إحدى الميزات القوية للنظام الجديد هي القدرة على إنشاء خيارات TypedDict مخصصة للنماذج المتخصصة. هذا مفيد بشكل خاص للنماذج التي تحتوي على معلمات فريدة، مثل نماذج المنطق مع OpenAI:

from typing import Literal
from agent_framework.openai import OpenAIChatOptions, OpenAIChatClient

class OpenAIReasoningChatOptions(OpenAIChatOptions, total=False):
    """Chat options for OpenAI reasoning models (o1, o3, o4-mini, etc.)."""

    # Reasoning-specific parameters
    reasoning_effort: Literal["none", "minimal", "low", "medium", "high", "xhigh"]

    # Unsupported parameters for reasoning models (override with None)
    temperature: None
    top_p: None
    frequency_penalty: None
    presence_penalty: None
    logit_bias: None
    logprobs: None
    top_logprobs: None
    stop: None


# Use with the client
client = OpenAIChatClient[OpenAIReasoningChatOptions]()
response = await client.get_response(
    "What is 2 + 2?",
    options={
        "model": "o3",
        "max_tokens": 100,
        "allow_multiple_tool_calls": True,
        "reasoning_effort": "medium",  # IDE autocomplete works!
        # "temperature": 0.7,  # Would raise a type error, because the value is not None
    },
)

6. وكلاء الدردشة مع خيارات

تم توسيع الإعداد العام أيضا إلى وكلاء الدردشة:

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

agent = Agent(
    client=OpenAIChatClient[OpenAIReasoningChatOptions](),
    default_options={
        "model": "o3",
        "max_tokens": 100,
        "allow_multiple_tool_calls": True,
        "reasoning_effort": "medium",
    },
)

ويمكنك تحديد النوع العام على كل من العميل والعامل، لذلك هذا صالح أيضا:

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

agent = Agent[OpenAIReasoningChatOptions](
    client=OpenAIChatClient(),
    default_options={
        "model": "o3",
        "max_tokens": 100,
        "allow_multiple_tool_calls": True,
        "reasoning_effort": "medium",
    },
)

6. تحديث تطبيقات عميل الدردشة المخصصة

إذا قمت بتطبيق عميل دردشة مخصص عن طريق توسيع BaseChatClient، فقم بتحديث الأساليب الداخلية:

قبل:

from agent_framework import BaseChatClient, Message, ChatOptions, ChatResponse

class MyCustomClient(BaseChatClient):
    async def _inner_get_response(
        self,
        *,
        messages: MutableSequence[Message],
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> ChatResponse:
        # Access options via class attributes
        model = chat_options.model
        temp = chat_options.temperature
        # ...

بعد:

from typing import Generic
from agent_framework import BaseChatClient, Message, ChatOptions, ChatResponse

# Define your provider's options TypedDict
class MyCustomChatOptions(ChatOptions, total=False):
    my_custom_param: str

# This requires the TypeVar from Python 3.13+ or from typing_extensions, so for Python 3.13+:
from typing import TypeVar

TOptions = TypeVar("TOptions", bound=TypedDict, default=MyCustomChatOptions, covariant=True)

class MyCustomClient(BaseChatClient[TOptions], Generic[TOptions]):
    async def _inner_get_response(
        self,
        *,
        messages: MutableSequence[Message],
        stream: bool,
        options: dict[str, Any],  # Note: parameter renamed and just a dict
        **kwargs: Any,
    ) -> ChatResponse:
        # Access options via dict access
        model = options.get("model")
        temp = options.get("temperature")
        # ...

أنماط الترحيل الشائعة

النمط 1: تحديث المعلمة البسيط

# Before - keyword arguments
await client.get_response("Hello", temperature=0.7)

# After - options dict
await client.get_response("Hello", options={"temperature": 0.7})

النمط 2: معلمات متعددة

# Before - multiple keyword arguments
await client.get_response(
    "Hello",
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

# After - all in options dict
await client.get_response(
    "Hello",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
    },
)

النمط 3: عميل الدردشة مع الأدوات

بالنسبة لعملاء الدردشة، tools انتقل الآن إلى إملاء الخيارات:

# Before - tools as keyword argument on chat client
await client.get_response(
    "What's the weather?",
    model="gpt-4",
    tools=[my_function],
    tool_choice="auto",
)

# After - tools in options dict for chat clients
await client.get_response(
    "What's the weather?",
    options={
        "model": "gpt-4",
        "tools": [my_function],
        "tool_choice": "auto",
    },
)

النمط 4: عامل مع الأدوات والتعليمات

لإنشاء عامل، toolsinstructions ويمكن أن يبقى كوسيطات الكلمات الأساسية. بالنسبة إلى run()، يتوفر فقط tools :

# Before
agent = Agent(
    client=client,
    name="assistant",
    tools=[my_function],
    instructions="You are helpful.",
    model="gpt-4",
)

# After - tools and instructions stay as keyword args on creation
agent = Agent(
    client=client,
    name="assistant",
    tools=[my_function],  # Still a keyword argument!
    instructions="You are helpful.",  # Still a keyword argument!
    default_options={"model": "gpt-4"},
)

# For run(), only tools is available as keyword argument
response = await agent.run(
    "Hello!",
    tools=[another_function],  # Can override tools
    options={"max_tokens": 100},
)

# Before - using additional_properties
await client.get_response(
    "Solve this problem",
    model="o3",
    additional_properties={"reasoning_effort": "high"},
)

# After - directly in options
await client.get_response(
    "Solve this problem",
    options={
        "model": "o3",
        "reasoning_effort": "high",
    },
)

النمط 5: معلمات Provider-Specific

# Define reusable options
my_options: OpenAIChatOptions = {
    "model": "gpt-4",
    "temperature": 0.7,
}

# Use with different messages
await client.get_response("Hello", options=my_options)
await client.get_response("Goodbye", options=my_options)

# Extend options using dict merge
extended_options = {**my_options, "max_tokens": 500}

ملخص التغييرات العاجلة

الجانب	قبل	بعد
خيارات عميل الدردشة	وسيطات الكلمة الأساسية الفردية (`temperature=0.7`)	إملاء واحد `options` (`options={"temperature": 0.7}`)
أدوات عميل الدردشة	`tools=[...]` وسيطة الكلمة الأساسية	`options={"tools": [...]}`
إنشاء `tools` عامل و `instructions`	وسيطات الكلمة الأساسية	وسيطات الكلمة الأساسية لا تزال (دون تغيير)
عامل `run()tools`	حجة الكلمات المفتاحية	وسيطة الكلمة الأساسية الثابتة (دون تغيير)
عامل `run()instructions`	حجة الكلمات المفتاحية	تم نقله إلى `options={"instructions": ...}`
خيارات خاصة بموفر الخدمة	`additional_properties={...}`	مضمن مباشرة في `options` الإملاء
الخيارات الافتراضية للعامل	وسيطات الكلمة الأساسية على الدالة الإنشائية	`default_options={...}`
خيارات تشغيل العامل	تشغيل وسيطات الكلمة الأساسية `run()`	`options={...}` المعامل
كتابة العميل	`OpenAIChatClient()`	`OpenAIChatClient[CustomOptions]()` (اختياري)
كتابة العامل	`Agent(...)`	`Agent[CustomOptions](...)` (اختياري)

اختبار الترحيل الخاص بك

تحديثات ChatClient

ابحث عن جميع الاستدعاءات التي get_response() تستخدم وسيطات الكلمات الأساسية مثل model=و temperature=tools=و وما إلى ذلك.
نقل كافة وسيطات الكلمة الأساسية إلى options={...} قاموس
نقل أي additional_properties قيم مباشرة إلى الإملاء options

تحديثات العامل

البحث عن كافة Agent الدالات الإنشائية والمكالمات run() التي تستخدم وسيطات الكلمة الأساسية
نقل وسيطات الكلمة الأساسية على الدالات الإنشائية إلى default_options={...}
نقل وسيطات run() الكلمة الأساسية إلى options={...}
الاستثناء: toolsinstructions ويمكن أن يبقى كوسيطات للكلمات الأساسية في Agent.__init__() و as_agent()
الاستثناء: tools يمكن أن يبقى كوسيطة كلمة أساسية على run()

تحديثات عميل الدردشة المخصصة

_inner_get_response() تحديث توقيع الأسلوب: إضافة stream: bool المعلمة القديمة chat_options: ChatOptions وتغييرها إلىoptions: dict[str, Any]
تحديث الوصول إلى السمة (على سبيل المثال، chat_options.model) للوصول إلى الإملاء (على سبيل المثال، options.get("model"))
(اختياري) إذا كنت تستخدم معلمات غير قياسية: حدد TypedDict مخصصا
إضافة معلمات نوع عام إلى فئة العميل

للكل

تشغيل مدقق النوع: استخدام mypy أخطاء النوع أو pyright التقاطها
اختبار من طرف إلى طرف: قم بتشغيل التطبيق الخاص بك للتحقق من الوظائف

دعم IDE

يوفر النظام الجديد المستند إلى TypedDict دعما ممتازا ل IDE:

الإكمال التلقائي: الحصول على اقتراحات لجميع الخيارات المتوفرة
التحقق من النوع: التقاط مفاتيح خيارات غير صالحة في وقت التطوير
الوثائق: مرر مؤشر الماوس فوق المفاتيح للاطلاع على الأوصاف
خاص بموفر الخدمة: تعرض خيارات كل موفر المعلمات ذات الصلة فقط

الخطوات التالية

لمشاهدة الإملاءات التي تم كتابتها أثناء العمل لحالة استخدام نماذج المنطق OpenAI مع واجهة برمجة تطبيقات إكمال الدردشة، استكشف هذه العينة

بعد إكمال الترحيل:

استكشاف الخيارات الخاصة بالموفر في وثائق واجهة برمجة التطبيقات
مراجعة العينات المحدثة
تعرف على إنشاء عملاء دردشة مخصصين

للحصول على مساعدة إضافية، راجع وثائق إطار عمل العامل أو تواصل مع المجتمع.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-08-25