Yükseltme Kılavuzu: Generikler ile TypedDict Olarak Sohbet Seçenekleri

Bu kılavuz, Python kodunuzu Microsoft Agent Framework'ün Options sürümünde kullanıma sunulan yeni TypedDict tabanlı sisteme yükseltmenize yardımcı olur. Bu, gelişmiş tür güvenliği, IDE otomatik tamamlama ve çalışma zamanı genişletilebilirliği sağlayan kritik bir değişikliktir.

Değişikliklere Genel Bakış

Bu sürüm, sohbet istemcilerine ve sohbet aracılarına seçeneklerin nasıl geçirildiğinin önemli bir yeniden düzenlemesini sunar.

Daha Önce Nasıl Çalışıyordu?

Daha önce, seçenekler , , get_response()ve aracı oluşturucuları gibi get_streaming_response()yöntemlerde run() olarak geçirildi:

# Options were individual keyword arguments
response = await client.get_response(
    "Hello!",
    model_id="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_id="gpt-4",
    additional_properties={"reasoning_effort": "medium"},
)

Şimdi Nasıl Çalışır?

Çoğu seçenek artık tek options bir parametreden yazılan sözlük olarak geçirilir:

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

Not:Ajanlar için instructions ve tools parametreleri, Agent.__init__() ve client.as_agent() üzerinde doğrudan anahtar kelime bağımsız değişkenleri olarak kullanılabilir durumda kalır. agent.run() için yalnızca tools anahtar sözcük bağımsız değişkeni olarak kullanılabilir:

# Agent creation accepts both tools and instructions as keyword arguments
agent = Agent(
    chat_client=client,
    tools=[my_function],
    instructions="You are a helpful assistant.",
    default_options={"model_id": "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
)

Önemli Değişiklikler

1. Birleştirilmiş Seçenekler Parametresi: Çoğu anahtar sözcük bağımsız değişkenleri (model_id, temperature ve diğerleri) artık tek bir options sözlük yoluyla geçiriliyor.
2. Aracı Oluşturma İstisnası: instructions ve tools, Agent.__init__() ve as_agent() üzerinde doğrudan anahtar sözcük bağımsız değişkenleri olarak kullanılabilir durumda kalır.
3. Aracı Çalıştırması için özel durum: tools üzerinde doğrudan anahtar sözcük bağımsız değişkeni olarak kullanılabilir durumda kalır agent.run()
4. TypedDict Tabanlı Seçenekler: Seçenekler, tür güvenliği için sınıflar olarak TypedDict tanımlanır
5. Genel Tür Desteği: Sohbet istemcileri ve temsilciler, çalışma zamanında aşırı yüklemeleri etkinleştirmek amacıyla sağlayıcıya özgü opsiyonlar için genel türleri destekler
6. Sağlayıcıya Özgü Seçenekler: Her sağlayıcının kendi varsayılan TypedDict'i vardır (örneğin, OpenAIChatOptions, OllamaChatOptions)
7. Daha Fazla additional_properties Yok: Sağlayıcıya özgü parametreler artık birinci sınıf türemiş alanlardır

Fayda -ları

• Tür Güvenliği: IDE otomatik tamamlama ve tüm seçenekler için tür denetimi
• Sağlayıcı Esnekliği: Birinci günde sağlayıcıya özgü parametreler için destek
• Temiz Kod: Tutarlı sözlük tabanlı parametre aktarımı
• Daha Kolay Uzantı: Özel kullanım örnekleri için özel seçenekler oluşturma (örneğin, akıl yürütme modelleri veya diğer API arka uçları)

Geçiş Kılavuzu

1. Anahtar Kelime Argümanlarını Seçenekler Dict'e Dönüştürme

En yaygın değişiklik, tek tek anahtar kelime argümanlarını options sözlüğe dönüştürmektir.

Anahtar parametrelerden önce:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# Options passed as individual keyword arguments
response = await client.get_response(
    "Hello!",
    model_id="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_id="gpt-4",
    temperature=0.9,
):
    print(chunk.text, end="")

Sonra (seçenekler sözlüğü):

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_id": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
    },
)

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

Bu istemci için uygun olmayan seçenekler sağlarsanız, IDE'nizde bir tip hatası alırsınız.

2. Sağlayıcıya Özgü Seçenekleri Kullanma ("additional_properties" Artık Yok)

Daha önce anahtar sözcük bağımsız değişkenlerinin temel kümesinin parçası olmayan sağlayıcıya özgü parametreleri geçirmek için parametresini additional_properties kullanmanız gerekiyordu:

Önce (additional_properties kullanarak):

from agent_framework.openai import OpenAIChatClient

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

After (TypedDict ile doğrudan seçenekler):

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_id": "gpt-4",
        "temperature": 0.7,
        "reasoning_effort": "medium",  # Type checking or autocomplete
    },
)

Sonra (yeni parametreler için özel alt sınıflama):

Veya henüz Agent Framework'ün parçası olmayan bir parametreyse (yeni olduğundan veya OpenAI uyumlu bir arka uç için özel olduğundan), artık seçenekleri alt sınıfa alabilir ve genel desteği kullanabilirsiniz:

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_id": "gpt-4",
        "temperature": 0.7,
        "custom_param": "my_value",  # IDE autocomplete works!
    },
)

Başlıca avantajı, sağlayıcıya özgü parametrelerin çoğunun artık türü belirtilmiş seçenekler sözlüğünün bir parçası haline gelmesidir.

• Tüm kullanılabilir seçenekler için IDE otomatik tamamlama
• Geçersiz anahtarları veya değerleri yakalamak için tür denetimi
• Bilinen sağlayıcı parametreler için additional_properties gerek yoktur
• Özel veya yeni parametreler için kolay uzantı

3. Aracı Yapılandırmasını Güncelleştirme

Aracı başlatma ve çalıştırma yöntemleri aynı deseni izler:

Önce (oluşturucu ve çalıştırmada anahtar sözcük bağımsız değişkenleri):

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

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

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

After:

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

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

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

4. Sağlayıcıya Özgü Seçenekler

Artık her sağlayıcının seçenekler için kendi TypedDict'i vardır ve bunlar varsayılan olarak etkindir. Bu, sağlayıcıya özgü parametreleri tam tür güvenliğiyle kullanmanıza olanak tanır:

OpenAI Örneği:

from agent_framework.openai import OpenAIChatClient

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

Ancak bunu açık hale de getirebilirsiniz:

from agent_framework_anthropic import AnthropicClient, AnthropicChatOptions

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

5. Özel Modeller için Özel Seçenekler Oluşturma

Yeni sistemin güçlü özelliklerinden biri, özel modeller için özel TypedDict seçenekleri oluşturabilmektir. Bu özellikle OpenAI ile modellerin akıl yürütmesi gibi benzersiz parametreleri olan modeller için kullanışlıdır:

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_id": "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. Seçeneklerle Sohbet Aracıları

Genel kurulum, Sohbet Aracıları'na da genişletildi:

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

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

Hem istemcide hem de aracıda geneli belirtebilirsiniz, bu nedenle bu da geçerlidir:

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

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

6. Özel Sohbet İstemcisi Uygulamalarını Güncelleştirme

BaseChatClient genişleterek özel bir sohbet istemcisi uyguladıysanız, iç yöntemleri güncelleyin.

Before:

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_id
        temp = chat_options.temperature
        # ...

After:

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],
        options: dict[str, Any],  # Note: parameter renamed and just a dict
        **kwargs: Any,
    ) -> ChatResponse:
        # Access options via dict access
        model = options.get("model_id")
        temp = options.get("temperature")
        # ...

Yaygın Geçiş Kalıpları

Desen 1: Basit Parametre Güncelleştirmesi

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

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

Desen 2: Birden Çok Parametre

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

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

Desen 3: Araçlarla Sohbet İstemcisi

Sohbet istemcileri için, tools artık seçenekler sözlüğüne ekleniyor.

# Before - tools as keyword argument on chat client
await client.get_response(
    "What's the weather?",
    model_id="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_id": "gpt-4",
        "tools": [my_function],
        "tool_choice": "auto",
    },
)

Model 4: Araçlar ve Talimatlar ile Temsilci

Aracı oluşturmak için, tools ve instructions anahtar sözcük bağımsız değişkenleri olarak kalabilir. run() için yalnızca tools kullanılabilir.

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

# After - tools and instructions stay as keyword args on creation
agent = Agent(
    chat_client=client,
    name="assistant",
    tools=[my_function],  # Still a keyword argument!
    instructions="You are helpful.",  # Still a keyword argument!
    default_options={"model_id": "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_id="o3",
    additional_properties={"reasoning_effort": "high"},
)

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

Kalıp 5: Sağlayıcıya Özgü Parametreler

# Define reusable options
my_options: OpenAIChatOptions = {
    "model_id": "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}

Yazılımda Uyum Bozan Değişikliklerin Özeti

Görünüş	Önce	Sonra
Sohbet istemcisi seçenekleri	Tek tek anahtar sözcük bağımsız değişkenleri (temperature=0.7)	Tek options dikte (options={"temperature": 0.7})
Sohbet istemcisi araçları	tools=[...] anahtar sözcük argümanı	options={"tools": [...]}
Aracı oluşturma tools ve instructions	Anahtar sözcük bağımsız değişkenleri	Still anahtar kelime argümanları (değişmemiş)
Aracısı run()tools	Anahtar sözcük argümanı	Still anahtar bağımsız değişkeni (değişmemiş)
Aracısı run()instructions	Anahtar sözcük argümanı	Taşınan yer options={"instructions": ...}
Sağlayıcıya özgü seçenekler	additional_properties={...}	Doğrudan options sözcüğe dahil edilmiştir
Aracın varsayılan seçenekleri	Oluşturucuda anahtar parametreler	default_options={...}
Aracı çalıştırma seçenekleri	Anahtar sözcük bağımsız değişkenleri etkin run()	options={...} parametresi
İstemci yazma	OpenAIChatClient()	OpenAIChatClient[CustomOptions]() (isteğe bağlı)
Temsilci yazıyor	Agent(...)	Agent[CustomOptions](...) (isteğe bağlı)

Geçişinizi Test Etme

ChatClient Güncelleştirmeleri

1. Anahtar sözcük bağımsız değişkenleri olarak get_response(), get_streaming_response(), model_id= gibi ifadeleri kullanan temperature= ve tools= çağrılarını bulun.
2. Tüm anahtar sözcük argümanlarını bir options={...} sözlüğe taşıyın
3. additional_properties değerlerini doğrudan options sözlüğe taşıyın

Temsilci Güncellemeleri

1. Anahtar sözcük bağımsız değişkenlerini kullanan tüm Agent oluşturucuları ve run() çağrılarını bulun
2. Oluşturuculardaki anahtar sözcük bağımsız değişkenlerini şuraya taşı: default_options={...}
3. Anahtar kelime argümanlarını run()'den options={...}'e taşıyın.
4. Özel durum: tools ve instructions, Agent.__init__() ve as_agent() üzerinde anahtar sözcük bağımsız değişkenleri olarak kalabilir
5. İstisna: tools bir anahtar kelime argümanı olarak run() üzerinde kalabilir

Özel Sohbet İstemcisi Güncelleştirmeleri

1. _inner_get_response() ve _inner_get_streaming_response() yöntem imzalarını güncelleyin: chat_options: ChatOptions parametresini options: dict[str, Any] olarak değiştirin.
2. Öznitelik erişimini (örneğin, chat_options.model_id) dikte erişimine güncelleştirin (örn. options.get("model_id"))
3. (İsteğe bağlı) Standart olmayan parametreler kullanıyorsanız: Özel bir TypedDict tanımlayın
4. İstemci sınıfınıza genel tür parametreleri ekleme

Tümü İçin

1. Tür Denetleyicisini Çalıştır: Tür hatalarını yakalamak için mypy veya pyright kullanın
2. Test Et Uçtan Uca: İşlevselliği doğrulamak için uygulamanızı başlatın

IDE Desteği

Yeni TypedDict tabanlı sistem mükemmel IDE desteği sağlar:

• Otomatik tamamlama: Kullanılabilir tüm seçenekler için öneriler alma
• Tür Denetimi: Geliştirme zamanında geçersiz seçenek anahtarlarını yakalama
• Belgeler: Açıklamaları görmek için tuşların üzerine gelin
• Sağlayıcıya özgü: Her sağlayıcının seçenekleri yalnızca ilgili parametreleri gösterir

Sonraki Adımlar

Sohbet Tamamlama API'siyle OpenAI Akıl Yürütme Modellerini kullanma durumunda yazılan dikteleri iş başında görmek için bu örneği inceleyin

Geçişi tamamladıktan sonra:

1. API belgelerinde sağlayıcıya özgü seçenekleri keşfetme
2. Güncelleştirilmiş örnekleri gözden geçirme
3. Özel sohbet istemcileri oluşturma hakkında bilgi edinin

Ek yardım için Agent Framework belgelerine bakın veya topluluğa ulaşın.