Frissítési útmutató: Csevegési lehetőségek TypedDict és Generics használatával

Ez az útmutató segít frissíteni a Python-kódot a Microsoft Agent Framework Options verziójában bevezetett új TypedDict-alapú rendszerre. Ez egy kompatibilitástörő változás , amely továbbfejlesztett típusbiztonságot, IDE automatikus kiegészítést és futásidejű bővíthetőséget biztosít.

A módosítások áttekintése

Ez a kiadás jelentős átalakítást vezet be abban, hogy hogyan adják át a beállításokat a csevegőklienseknek és csevegőügynököknek.

Hogyan működött korábban?

Korábban a beállítások közvetlen kulcsszóargumentumként lettek átadva az olyan metódusokon, mint a get_response(), get_streaming_response(), run()és az ügynökkonstruktorok:

# 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"},
)

Hogyan működik most?

A legtöbb lehetőség mostantól egyetlen options paraméteren keresztül van átadva gépelt szótárként:

# 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
    },
)

Megjegyzés: Ügynökök esetében a és a instructions paraméterek közvetlen kulcsszó argumentumként érhetők el a tools és a Agent.__init__() számára. agent.run() esetén csak tools érhető el kulcsszóargumentumként.

# 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
)

Kulcsmódosítások

1. Konszolidált beállítások paramétere: A kulcsszóargumentumok többsége (model_idtemperaturestb.) mostantól egyetlen options diktáláson keresztül van átadva
2. Az ügynöklétrehozás kivétele: instructions és tools továbbra is elérhető közvetlen kulcsszóargumentumként a Agent.__init__()as_agent()
3. Kivétel az ügynök futtatásánál: mint közvetlen kulcsszóargumentum továbbra is elérhető toolsagent.run()
4. TypedDict-alapú beállítások: A beállítások típusbiztonsági osztályokként TypedDict vannak definiálva
5. Általános típustámogatás: A csevegési ügyfelek és ügynökök támogatják a szolgáltatóspecifikus beállítások általános beállításait, hogy lehetővé tegyék a futtatókörnyezet túlterhelését
6. Szolgáltatóspecifikus beállítások: Minden szolgáltatónak megvan a saját alapértelmezett TypedDict-je (pl. OpenAIChatOptions, OllamaChatOptions)
7. Nincs több "additional_properties": A szolgáltatóspecifikus paraméterek most már teljes értékű típusmezők.

Előnyök

• Típusbiztonság: IDE automatikus kiegészítés és típusellenőrzés az összes beállításhoz
• Szolgáltatói rugalmasság: A szolgáltatóspecifikus paraméterek támogatása az első napon
• Tisztább kód: Konzisztens diktálási alapú paraméterátadás
• Egyszerűbb bővítmény: Egyéni beállítások létrehozása speciális használati esetekhez (például érvelési modellekhez vagy más API-háttérrendszerekhez)

Migrálási útmutató

1. Kulcsszóargumentumok konvertálása opciós szótárrá

A leggyakoribb változás az, hogy az egyes kulcsszóargumentumokat a options szótárba konvertálja.

Előtte (kulcsszóargumentumok):

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="")

(Opciók szótár után):

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="")

Ha olyan beállításokat ad át, amelyek nem megfelelőek az adott ügyfélhez, típushiba jelenik meg az IDE-ben.

2. A Provider-Specific beállításainak használata (nincs több additional_properties)

Korábban a kulcsszóargumentumok alaphalmazának nem részét képező szolgáltatóspecifikus paraméterek átadásához a additional_properties következő paramétert kellett használnia:

Előtte (additional_properties használata):

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 (közvetlen beállítások a TypedDict használatával):

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
    },
)

After (egyéni alosztályozás új paraméterek esetén):

Vagy ha olyan paraméterről van szó, amely még nem része az Ügynök-keretrendszernek (mert új, vagy mert egy OpenAI-kompatibilis háttérrendszer esetében egyéni), a beállításokat átsorolhatja, és használhatja az általános támogatást:

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!
    },
)

A fő előnye az, hogy a legtöbb szolgáltatóspecifikus paraméter már része a gépelt beállítási szótárnak, így:

• IDE automatikus kiegészítés az összes elérhető beállításhoz
• Típusellenőrzés érvénytelen kulcsok vagy értékek elfogásához
• Nincs szükség további_tulajdonságokra az ismert szolgáltatói paraméterekhez
• Egyszerű bővítmény egyéni vagy új paraméterekhez

3. Az ügynök konfigurációjának frissítése

Az ügynökinicializálási és -futtatási módszerek ugyanazt a mintát követik:

Előtte (kulcsszóargumentumok konstruktoron és futtatáskor):

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. Szolgáltatóspecifikus beállítások

Mostantól minden szolgáltató saját TypedDict típusú beállításokkal rendelkezik, ezek alapértelmezés szerint engedélyezve vannak. Ez lehetővé teszi, hogy szolgáltatóspecifikus paramétereket használjon teljes típusú biztonsággal:

OpenAI-példa:

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",
    },
)

De explicit módon is megadható:

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. Egyéni beállítások létrehozása speciális modellekhez

Az új rendszer egyik hatékony funkciója, hogy egyéni TypedDict-beállításokat hozhat létre speciális modellekhez. Ez különösen hasznos az olyan modellek esetében, amelyek egyedi paraméterekkel rendelkeznek, például az OpenAI-val rendelkező érvelési modellek esetében:

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. Opciókkal rendelkező csevegőügynökök

Az általános beállítás a csevegőügynökökre is ki lett terjesztve:

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",
    },
)

és megadhatja a generikus típusokat mind az ügyféloldalon, mind az ügynökoldalon, így ez is érvényes:

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. Egyéni csevegési ügyfélalkalmazások frissítése

Ha egyéni csevegési ügyfelet implementált a kiterjesztéssel BaseChatClient, frissítse a belső metódusokat:

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")
        # ...

Gyakori áttelepítési minták

1. minta: Egyszerű paraméterfrissítés

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

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

2. minta: Több paraméter

# 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,
    },
)

3. minta: Csevegőügyfél eszközökkel

Csevegési ügyfelek esetén a tools most az opciók könyvtárába kerül.

# 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",
    },
)

4. minta: Ügynök eszközökkel és utasításokkal

Ügynöklétrehozás esetén, tools és instructions kulcsszóargumentumként is megmaradhat. Csak run() érhető el a tools számára:

# 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",
    },
)

5. minta: Szolgáltatóspecifikus paraméterek

# 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}

A kompatibilitástörő változások összefoglalása

Jellemző	Előtte	Utána
Csevegési ügyfél beállításai	Egyéni kulcsszóargumentumok (temperature=0.7)	Egyetlen options szótár (options={"temperature": 0.7})
Csevegési ügyféleszközök	tools=[...] kulcsszóargumentum	options={"tools": [...]}
Ügynök létrehozása tools és instructions	Kulcsszóargumentumok	Még mindig kulcsszóargumentumok (változatlan)
Ügynök run()tools	Kulcsszóargumentum	Még mindig kulcsszóargumentum (változatlan)
Ügynök run()instructions	Kulcsszóargumentum	Áthelyezés ide: options={"instructions": ...}
Szolgáltatóspecifikus beállítások	additional_properties={...}	Közvetlenül a options szótárban
Az ügynök alapértelmezett beállításai	Kulcsszóargumentumok a konstruktoron	default_options={...}
Ügynök futtatási beállítások	Kulcsszóargumentumok a run()	options={...} paraméter
Ügyfél gépelése	OpenAIChatClient()	OpenAIChatClient[CustomOptions]() (nem kötelező)
Ügynök gépelése	Agent(...)	Agent[CustomOptions](...) (nem kötelező)

A migrálás tesztelése

ChatClient-frissítések

1. Keresse meg az get_response()get_streaming_response() összes olyan hívást, amely olyan kulcsszóargumentumokat használ, mint a model_id=, temperature=, tools=stb.
2. Az összes kulcsszóargumentum áthelyezése egy options={...} szótárba
3. Bármely additional_properties érték közvetlen áthelyezése a options szótárba

Ügynökfrissítések

1. A kulcsszóargumentumokat használó összes Agent konstruktor és run() hívás megkeresése
2. Kulcsszóargumentumok áthelyezése konstruktorokon a default_options={...}
3. Kulcsszóargumentumok áthelyezése a run()-ről a options={...}-re
4. Kivétel: tools és instructions maradhat kulcsszóargumentumként a Agent.__init__()as_agent()
5. Kivétel: a(z) toolsrun() kulcsszóargumentumként maradhat.

Egyéni csevegési ügyfélfrissítések

1. A _inner_get_response() és _inner_get_streaming_response() metódus-aláírások frissítése: a chat_options: ChatOptions paraméter módosítása options: dict[str, Any]
2. Attribútumhozzáférés frissítése (pl. chat_options.model_id) szótár-hozzáférésre (pl. options.get("model_id"))
3. (Nem kötelező) Nem szabványos paraméterek használata esetén: Egyéni TypedDict definiálása
4. Általános típusparaméterek hozzáadása az ügyfélosztályhoz

Mindenkinek

1. Típustesztelő futtatása: Típushibák elkapásához használja a mypy vagy pyright opciót
2. Végpontok közötti tesztelés: Az alkalmazás futtatása a funkciók ellenőrzéséhez

IDE-támogatás

Az új TypedDict-alapú rendszer kiváló IDE-támogatást nyújt:

• Automatikus kiegészítés: Javaslatok lekérése az összes elérhető beállításhoz
• Típusellenőrzés: Érvénytelen beállításkulcsok elfogása a fejlesztéskor
• Dokumentáció: Mutasson a kulcsokra a leírások megtekintéséhez
• Szolgáltatóspecifikus: Minden szolgáltató beállításai csak a releváns paramétereket jelenítik meg

Következő lépések

Ha meg szeretné tekinteni az OpenAI-érvelési modellek csevegés-befejezési API-val való használatakor működés közbeni beírt diktálásokat, tekintse meg ezt a mintát

A migrálás befejezése után:

1. A szolgáltatóspecifikus lehetőségek megismerése az API dokumentációjában
2. Frissített minták áttekintése
3. Tudnivalók az egyéni csevegési ügyfelek létrehozásáról

További segítségért tekintse meg az Agent Framework dokumentációját , vagy forduljon a közösséghez.