Průvodce upgradem: Možnosti chatu ve formátu TypedDict s obecnými typy

Tato příručka vám pomůže upgradovat kód Pythonu na nový systém založený na Options TypedDict představený ve verzi 1.0.0b260114 rozhraní Microsoft Agent Framework. Jedná se o zásadní změnu , která poskytuje vylepšenou bezpečnost typů, automatické dokončování IDE a rozšiřitelnost modulu runtime.

Přehled změn

Tato verze představuje hlavní refaktoring toho, jak se možnosti předávají chatovacím klientům a chatovacím agentům.

Jak to fungovalo dříve

Dříve byly možnosti předány jako argumenty přímého klíčového slova pro metody, jako jsou get_response(), get_streaming_response(), run()a konstruktory agenta:

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

Jak to teď funguje

Většina možností je nyní předávána jedním options parametrem jako typový slovník.

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

Poznámka: U agentů zůstávají parametry instructionstools dostupné jako přímé argumenty klíčového slova na ChatAgent.__init__() a client.as_agent(). Pro agent.run(), je k dispozici pouze tools jako argument klíčového slova:

# Agent creation accepts both tools and instructions as keyword arguments
agent = ChatAgent(
    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
)

Klíčové změny

1. Konsolidovaný parametr možností: Většina argumentů klíčových slov (model_idtemperature atd.) se teď předává prostřednictvím jednoho options slovníku.
2. Výjimka pro vytvoření agenta: instructions a tools zůstávají k dispozici jako přímé klíčové argumenty na ChatAgent.__init__() a create_agent()
3. Výjimka pro spuštění agenta: tools zůstává k dispozici jako argument přímého klíčového slova na agent.run()
4. Možnosti založené na TypedDict: Možnosti jsou definovány jako TypedDict třídy pro zabezpečení typů
5. Podpora obecného typu: Klienti chatu a agenti podporují obecné typy možností specifických pro poskytovatele, aby bylo možné přetížení modulu runtime
6. Možnosti specifické pro poskytovatele: Každý poskytovatel má vlastní výchozí typedDict (např. OpenAIChatOptions, OllamaChatOptions)
7. Žádné další dodatečné vlastnosti: Poskytovatelem specifické parametry jsou nyní hlavní typově definovaná pole

Výhody

• Zabezpečení typů: Automatické dokončování integrovaného vývojového prostředí (IDE) a kontrola typů pro všechny možnosti
• Flexibilita poskytovatele: Podpora parametrů specifických pro poskytovatele v den 1
• Čistější kód: Konzistentní předávání parametrů založených na diktování
• Jednodušší rozšíření: Vytvoření vlastních možností pro specializované případy použití (např. modely odůvodnění nebo jiné back-endy rozhraní API)

Průvodce migrací

1. Převod argumentů klíčových slov na diktování možností

Nejběžnější změnou je převod jednotlivých argumentů klíčových slov do slovníku options .

Před (argumenty klíčových slov):

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

Po (dikt s možnostmi):

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

Pokud předáte možnosti, které nejsou vhodné pro daného klienta, zobrazí se v integrovaném vývojovém prostředí (IDE) chyba typu.

2. Použití možností specifických pro poskytovatele (žádné další další_vlastnosti)

Pokud jste dříve chtěli předat parametry specifické pro zprostředkovatele, které nebyly součástí základní sady argumentů klíčových slov, museli jste použít additional_properties parametr:

Před (použitím additional_properties):

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

Za (přímé možnosti pomocí 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_id": "gpt-4",
        "temperature": 0.7,
        "reasoning_effort": "medium",  # Type checking or autocomplete
    },
)

Po (vytvoření vlastních podtříd pro nové parametry):

Nebo pokud se jedná o parametr, který ještě není součástí rozhraní Agent Framework (protože je nový nebo protože je vlastní pro s OpenAI kompatibilní back-end), můžete nyní vytvořit podtřídu a použít obecnou podporu.

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

Klíčovou výhodou je, že většina parametrů specifických pro poskytovatele je teď součástí slovníku typed options a poskytuje vám následující výhody:

• Automatické dokončování integrovaného vývojového prostředí (IDE) pro všechny dostupné možnosti
• Kontrola typů pro zachycení neplatných klíčů nebo hodnot
• Není potřeba dodatečných_vlastností pro známé parametry zprostředkovatele.
• Snadné rozšíření pro vlastní nebo nové parametry

3. Aktualizace konfigurace chatagentu

Inicializace a spouštění chatagentů se řídí stejným vzorem:

Před (argumenty klíčových slov v konstruktoru a spuštění):

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()

# Default options as keyword arguments on constructor
agent = ChatAgent(
    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 ChatAgent
from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions

client = OpenAIChatClient()
agent = ChatAgent(
    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. Možnosti specifické pro poskytovatele

Každý zprostředkovatel teď má vlastní typedDict pro možnosti, které jsou ve výchozím nastavení povolené. To vám umožní používat parametry specifické pro zprostředkovatele při plné typové bezpečnosti.

Příklad OpenAI:

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

Můžete ho ale také explicitně nastavit:

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. Vytváření vlastních možností pro specializované modely

Jednou z výkonných funkcí nového systému je možnost vytvářet vlastní možnosti TypedDict pro specializované modely. To je zvlášť užitečné pro modely, které mají jedinečné parametry, jako je například odůvodnění modelů s 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_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. Chat agent s nastavením

Obecné nastavení bylo také rozšířeno na agenty chatu:

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

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

a obecný parametr můžete zadat v klientovi i agentu, takže je to také platné:

from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient

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

6. Aktualizace vlastních implementací chatovacího klienta

Pokud jste implementovali vlastního chatovacího klienta rozšířením BaseChatClient, aktualizujte interní metody:

Before:

from agent_framework import BaseChatClient, ChatMessage, ChatOptions, ChatResponse

class MyCustomClient(BaseChatClient):
    async def _inner_get_response(
        self,
        *,
        messages: MutableSequence[ChatMessage],
        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, ChatMessage, 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[ChatMessage],
        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")
        # ...

Běžné vzory migrace

Vzor 1: Jednoduchá aktualizace parametrů

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

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

Model 2: Více parametrů

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

Model 3: Chatovací klient s nástroji

U chatovacích klientů tools je nyní umístěn v objektu možností:

# 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: Agent s nástroji a pokyny

Pro vytvoření agenta tools a instructions mohou zůstat jako argumenty klíčových slov. V případě run() je k dispozici pouze tools.

# Before
agent = ChatAgent(
    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 = ChatAgent(
    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",
    },
)

Vzor 5: parametry specifické pro poskytovatele

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

Shrnutí zásadních změn

Aspekt	Před	Po
Možnosti chatovacího klienta	Jednotlivé argumenty klíčových slov (temperature=0.7)	Jeden options slovník (options={"temperature": 0.7})
Chatovací klientské nástroje	tools=[...] argument klíčového slova	options={"tools": [...]}
Vytvoření agenta tools a instructions	Argumenty klíčových slov	Stále argumenty klíčového slova (beze změny)
Agent run()tools	Argument klíčového slova	Argument klíčového slova ( beze změny)
Agent run()instructions	Argument klíčového slova	Přesunuto do options={"instructions": ...}
Možnosti specifické pro zprostředkovatele	additional_properties={...}	Přímo zahrnuto v options slovníku
Výchozí možnosti agenta	Argumenty klíčových slov v konstruktoru	default_options={...}
Možnosti spuštění agenta	Argumenty klíčových slov pro run()	options={...} parametr
Klient píše	OpenAIChatClient()	OpenAIChatClient[CustomOptions]() (volitelné)
Agent píše	ChatAgent(...)	ChatAgent[CustomOptions](...) (volitelné)

Testování migrace

Aktualizace ChatClient

1. Vyhledejte všechna volání get_response() a get_streaming_response(), která používají argumenty klíčových slov, jako jsou model_id=, temperature=, tools= atd.
2. Přesunutí všech argumentů klíčových slov do slovníku options={...}
3. Přesuňte libovolné additional_properties hodnoty přímo do slovníku options

Aktualizace chatagentu

1. Vyhledání všech ChatAgent konstruktorů a run() volání používajících argumenty klíčového slova
2. Přesunutí argumentů klíčových slov u konstruktorů do default_options={...}
3. Přesuňte argumenty klíčových slov z run() na options={...}
4. Výjimka: tools a instructions mohou zůstat jako argumenty klíčových slov na ChatAgent.__init__() a create_agent()
5. Výjimka: tools může zůstat jako argument klíčového slova u run()

Aktualizace vlastního chatovacího klienta

1. Aktualizujte podpisy metod _inner_get_response() a _inner_get_streaming_response(): změňte parametr chat_options: ChatOptions na options: dict[str, Any]
2. Aktualizovat přístup k atributům (např. chat_options.model_id) na přístup k slovníku (např. options.get("model_id"))
3. (Volitelné) Pokud používáte nestandardní parametry: Definujte vlastní typeddict.
4. Přidání parametrů obecného typu do klientské třídy

Pro všechny

1. Spusťte kontrolu typů: Použijte mypy nebo pyright k zachycení chyb typu
2. Kompletní testování: Spuštěním aplikace ověřte funkčnost.

Podpora integrovaného vývojového prostředí (IDE

Nový systém založený na TypedDict poskytuje vynikající podporu integrovaného vývojového prostředí (IDE):

• Automatické dokončování: Získání návrhů pro všechny dostupné možnosti
• Kontrola typů: Zachycení neplatných klíčů možností v době vývoje
• Dokumentace: Když najedete myší na klíče, zobrazí se popisy.
• Specifické pro zprostředkovatele: Možnosti jednotlivých poskytovatelů zobrazují jenom relevantní parametry.

Další kroky

Pokud chcete zobrazit napsané diktování v akci pro případ použití modelů pro odůvodnění OpenAI s rozhraním API pro dokončování chatu, projděte si tuto ukázku.

Po dokončení migrace:

1. Prozkoumání možností specifických pro poskytovatele v dokumentaci k rozhraní API
2. Zkontrolovat aktualizované ukázky
3. Informace o vytváření vlastních chatovacích klientů

Další nápovědu najdete v dokumentaci k rozhraní Agent Framework nebo se spojte s komunitou.