Spouštění agentů

Abstrakce základního agenta zveřejňuje různé možnosti spuštění agenta. Volající se můžou rozhodnout zadat nula, jednu nebo mnoho vstupních zpráv. Volající si také můžou vybrat mezi streamováním a ne streamingem. Pojďme se podívat na různé scénáře použití.

Streamování a streamování bez streamování

Microsoft Agent Framework podporuje metody streamování i metody bez streamování pro spuštění agenta.

Pro jiné než streamování použijte metodu RunAsync .

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Pro streamování použijte metodu RunStreamingAsync .

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.Write(update);
}

Pro jiné než streamování použijte metodu run .

result = await agent.run("What is the weather like in Amsterdam?")
print(result.text)

Pro streamování použijte metodu run_stream .

async for update in agent.run_stream("What is the weather like in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

Možnosti spuštění agenta

Abstrakce základního agenta umožňuje předat objekt možností pro každé spuštění agenta, ale schopnost přizpůsobit spuštění na úrovni abstrakce je poměrně omezená. Agenti se můžou výrazně lišit, a proto neexistují skutečně běžné možnosti přizpůsobení.

V případech, kdy volající zná typ agenta, se kterým pracuje, je možné předat konkrétní možnosti pro povolení přizpůsobení spuštění.

Zde je například agent a ChatClientAgent je možné předat ChatClientAgentRunOptions objekt, který dědí z AgentRunOptions. Volající tak může poskytnout vlastní ChatOptions , které se sloučí s možnostmi na úrovni agenta před předáním integrovanému IChatClientChatClientAgent agentu.

var chatOptions = new ChatOptions() { Tools = [AIFunctionFactory.Create(GetWeather)] };
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", options: new ChatClientAgentRunOptions(chatOptions)));

Agenti Pythonu podporují přizpůsobení jednotlivých spuštění prostřednictvím parametru options . Možnosti se předávají jako TypedDict a lze je nastavit v době výstavby (prostřednictvím default_options) a podle běhu (prostřednictvím options). Každý poskytovatel má svou vlastní třídu TypedDict, která poskytuje úplné automatické dokončování IDE a kontrolu typů pro nastavení specifické pro zprostředkovatele.

Mezi běžné možnosti patří:

max_tokens: Maximální počet tokenů, které se mají vygenerovat
temperature: Řídí náhodnost při generování odpovědí.
model_id: Přepsání modelu pro toto konkrétní spuštění
top_p: Parametr vzorkování vzorků na vzorkování vzorků
response_format: Zadejte formát odpovědi (např. strukturovaný výstup).

Poznámka:

instructions Parametry tools zůstanou jako argumenty přímého klíčového slova a nepředají se prostřednictvím slovníkuoptions.

from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions

# Set default options at construction time
agent = OpenAIChatClient().as_agent(
    instructions="You are a helpful assistant",
    default_options={
        "temperature": 0.7,
        "max_tokens": 500
    }
)

# Run with custom options (overrides defaults)
# OpenAIChatOptions provides IDE autocomplete for all OpenAI-specific settings
options: OpenAIChatOptions = {
    "temperature": 0.3,
    "max_tokens": 150,
    "model_id": "gpt-4o",
    "presence_penalty": 0.5,
    "frequency_penalty": 0.3
}

result = await agent.run(
    "What is the weather like in Amsterdam?",
    options=options
)

# Streaming with custom options
async for update in agent.run_stream(
    "Tell me a detailed weather forecast",
    options={"temperature": 0.7, "top_p": 0.9},
    tools=[additional_weather_tool]  # tools is still a keyword argument
):
    if update.text:
        print(update.text, end="", flush=True)

Každý poskytovatel má svou vlastní třídu TypedDict (např OpenAIChatOptions. , AnthropicChatOptions, OllamaChatOptions), která zveřejňuje úplnou sadu možností podporovaných tímto poskytovatelem.

Pokud jsou k dispozici možnosti default_options pro jednotlivé spuštění i pro jednotlivá spuštění options , mají přednost a slučují se s výchozími nastaveními.

Typy odpovědí

Streamované i nestreamové odpovědi z agentů obsahují veškerý obsah vytvořený agentem. Obsah může obsahovat data, která nejsou výsledkem (tj. odpověď na otázku uživatele) z agenta. Mezi vrácená data patří volání nástroje funkcí, výsledky volání nástrojů funkcí, odůvodnění textu, aktualizace stavu a mnoho dalších.

Vzhledem k tomu, že ne veškerý vrácený obsah je výsledkem, je důležité při pokusu o izolaci výsledku od jiného obsahu hledat konkrétní typy obsahu.

Chcete-li extrahovat výsledek textu z odpovědi, je potřeba agregovat všechny TextContent položky ze všech ChatMessages položek. Pro zjednodušení je Text vlastnost k dispozici pro všechny typy odpovědí, které agregují všechny TextContent.

V případě nestreamovaného případu se vše vrátí v jednom AgentResponse objektu. AgentResponse umožňuje přístup k vytvořeným zpráv prostřednictvím Messages vlastnosti.

var response = await agent.RunAsync("What is the weather like in Amsterdam?");
Console.WriteLine(response.Text);
Console.WriteLine(response.Messages.Count);

V případě AgentResponseUpdate streamování se objekty streamují při jejich generování. Každá aktualizace může obsahovat část výsledku z agenta a také různé další položky obsahu. Podobně jako u případu bez streamování je možné pomocí Text vlastnosti získat část výsledku obsaženou v aktualizaci a přejít k podrobnostem prostřednictvím Contents vlastnosti.

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.WriteLine(update.Text);
    Console.WriteLine(update.Contents.Count);
}

V případě nestreamovaného případu se vše vrátí v jednom AgentResponse objektu. AgentResponse umožňuje přístup k vytvořeným zpráv prostřednictvím messages vlastnosti.

Chcete-li extrahovat výsledek textu z odpovědi, je potřeba agregovat všechny TextContent položky ze všech ChatMessage položek. Pro zjednodušení je Text vlastnost k dispozici pro všechny typy odpovědí, které agregují všechny TextContent.

response = await agent.run("What is the weather like in Amsterdam?")
print(response.text)
print(len(response.messages))

# Access individual messages
for message in response.messages:
    print(f"Role: {message.role}, Text: {message.text}")

V případě AgentResponseUpdate streamování se objekty streamují při jejich generování. Každá aktualizace může obsahovat část výsledku z agenta a také různé další položky obsahu. Podobně jako u případu bez streamování je možné pomocí text vlastnosti získat část výsledku obsaženou v aktualizaci a přejít k podrobnostem prostřednictvím contents vlastnosti.

async for update in agent.run_stream("What is the weather like in Amsterdam?"):
    print(f"Update text: {update.text}")
    print(f"Content count: {len(update.contents)}")

    # Access individual content items
    for content in update.contents:
        if hasattr(content, 'text'):
            print(f"Content: {content.text}")

Typy zpráv

Vstupy a výstupy z agentů jsou reprezentovány jako zprávy. Zprávy jsou rozdělené na položky obsahu.

Rozhraní Microsoft Agent Framework používá typy zpráv a obsahu poskytované abstrakcemi Microsoft.Extensions.AI . Zprávy jsou reprezentovány ChatMessage třídou a všechny třídy obsahu dědí ze základní AIContent třídy.

Existují různé AIContent podtřídy, které se používají k reprezentaci různých typů obsahu. Některé jsou poskytovány jako součást základních Microsoft.Extensions.AI abstrakcí, ale poskytovatelé mohou v případě potřeby také přidat své vlastní typy.

Tady je několik oblíbených typů z Microsoft.Extensions.AI:

Typ	Description
TextContent	Textový obsah, který může být vstupní, například od uživatele nebo vývojáře, a výstup z agenta. Obvykle obsahuje textový výsledek z agenta.
DataContent	Binární obsah, který může být vstupní i výstupní. Dá se použít k předávání obrázků, zvukových dat nebo dat videa do a z agenta (kde je to podporováno).
UriContent	Adresa URL, která obvykle odkazuje na hostovaný obsah, jako je obrázek, zvuk nebo video.
FunctionCallContent	Požadavek odvozované služby pro vyvolání nástroje funkce
FunctionResultContent	Výsledek vyvolání nástroje funkce.

Architektura agenta Pythonu agent_framework používá typy zpráv a obsahu z balíčku. Zprávy jsou reprezentovány ChatMessage třídou a všechny třídy obsahu dědí ze základní BaseContent třídy.

Existují různé BaseContent podtřídy, které se používají k reprezentaci různých typů obsahu:

Typ	Description
`TextContent`	Textový obsah, který může být vstupním i výstupním z agenta. Obvykle obsahuje textový výsledek z agenta.
`DataContent`	Binární obsah reprezentovaný jako identifikátor URI dat (například obrázky kódované v base64). Lze použít k předávání binárních dat do a z agenta.
`UriContent`	Identifikátor URI, který odkazuje na hostovaný obsah, jako je obrázek, zvukový soubor nebo dokument.
`FunctionCallContent`	Požadavek služby AI k vyvolání nástroje funkce
`FunctionResultContent`	Výsledek vyvolání nástroje funkce.
`ErrorContent`	Informace o chybě při zpracování se nezdaří.
`UsageContent`	Využití tokenů a fakturační údaje ze služby AI

Tady je postup, jak pracovat s různými typy obsahu:

from agent_framework import ChatMessage, TextContent, DataContent, UriContent

# Create a text message
text_message = ChatMessage(role="user", text="Hello!")

# Create a message with multiple content types
image_data = b"..."  # your image bytes
mixed_message = ChatMessage(
    role="user",
    contents=[
        TextContent("Analyze this image:"),
        DataContent(data=image_data, media_type="image/png"),
    ]
)

# Access content from responses
response = await agent.run("Describe the image")
for message in response.messages:
    for content in message.contents:
        if isinstance(content, TextContent):
            print(f"Text: {content.text}")
        elif isinstance(content, DataContent):
            print(f"Data URI: {content.uri}")
        elif isinstance(content, UriContent):
            print(f"External URI: {content.uri}")

Další kroky

Konverzace a vlákna s vícenásobným otáčením

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-01-15