Ügynökök futtatása

Az alapügynök absztrakciója különböző lehetőségeket tesz elérhetővé az ügynök futtatásához. A hívók dönthetnek úgy, hogy nulla, egy vagy több bemeneti üzenetet adnak meg. A hívók választhatnak a streamelés és a nem streamelés között is. Vizsgáljuk meg a különböző használati forgatókönyveket.

Streamelés és nem streamelés

A Microsoft Agent Framework mind a streamelési, mind a nem streamelési módszereket támogatja az ügynök futtatásához.

Nem streamelés esetén használja a metódust RunAsync .

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

Streameléshez használja a metódust RunStreamingAsync .

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

Nem streamelés esetén használja a metódust run .

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

Streameléshez használja a metódust a run következővel stream=True: . Ez egy ResponseStream aszinkron módon iterálható objektumot ad vissza:

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

ResponseStream

A ResponseStream visszaadott run(..., stream=True) objektum két használati mintát támogat:

1. minta: Aszinkron iteráció – valós idejű megjelenítéshez érkező folyamatfrissítések:

response_stream = agent.run("Tell me a story", stream=True)
async for update in response_stream:
    if update.text:
        print(update.text, end="", flush=True)

2. minta: Közvetlen véglegesítés – kihagyhatja az iterációt, és megkapja a teljes választ:

response_stream = agent.run("Tell me a story", stream=True)
final = await response_stream.get_final_response()
print(final.text)

3. minta: Kombinált – iterálás valós idejű megjelenítéshez, majd az összesített eredmény lekérése:

response_stream = agent.run("Tell me a story", stream=True)

# First, iterate to display streaming output
async for update in response_stream:
    if update.text:
        print(update.text, end="", flush=True)

# Then get the complete response (uses already-collected updates, does not re-iterate)
final = await response_stream.get_final_response()
print(f"\n\nFull response: {final.text}")
print(f"Messages: {len(final.messages)}")

Ügynök futtatási beállítások

Az alapügynök absztrakciója lehetővé teszi egy beállításobjektum átadását minden ügynökfuttatáshoz, azonban a futtatás absztrakciós szinten történő testreszabása meglehetősen korlátozott. Az ügynökök jelentősen eltérhetnek, ezért nem igazán gyakori testreszabási lehetőségek.

Azokban az esetekben, amikor a hívó ismeri az ügynök típusát, a futtatás testreszabásához megadhat típusspecifikus beállításokat.

Itt például az ügynök egy ChatClientAgent , és át lehet adni egy ChatClientAgentRunOptions olyan objektumot, amelytől AgentRunOptionsöröklődik. Ez lehetővé teszi, hogy a hívó olyan egyéni ChatOptions beállításokat adjon meg, amelyek egyesítve vannak az ügynökszintű beállításokkal, mielőtt átadják őket a IChatClientChatClientAgent beépítettnek.

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

A Python-ügynökök támogatják a paramétereken keresztüli futtatás testreszabását options . A beállítások TypedDict-ként vannak átadva, és az építési időpontban (via default_options) és futtatásonként (via options) is beállíthatók. Minden szolgáltató saját TypedDict osztálysal rendelkezik, amely teljes IDE automatikus kiegészítést és típusellenőrzést biztosít a szolgáltatóspecifikus beállításokhoz.

Gyakori lehetőségek a következők:

max_tokens: A létrehozandó jogkivonatok maximális száma
temperature: Szabályozza a véletlenszerűséget a válaszgenerálásban
model_id: Az adott futtatás modelljének felülbírálása
top_p: Mag mintavételezési paramétere
response_format: Adja meg a válaszformátumot (pl. strukturált kimenet)

Megjegyzés:

A tools paraméterek közvetlen instructions kulcsszóargumentumok maradnak, és nem kerülnek át a options szótáron keresztül.

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(
    "Tell me a detailed weather forecast",
    stream=True,
    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)

Minden szolgáltató saját TypedDict osztálysal (pl. , , OpenAIChatOptions) AnthropicChatOptionsrendelkezik, OllamaChatOptionsamely az adott szolgáltató által támogatott lehetőségek teljes készletét teszi elérhetővé.

Ha a futtatásonként és a futtatásonként default_options is options meg van adva, a futtatási beállítások elsőbbséget élveznek, és egyesülnek az alapértelmezett beállításokkal.

Választípusok

Az ügynököktől érkező streamelési és nem streamelési válaszok egyaránt tartalmazzák az ügynök által előállított összes tartalmat. A tartalom tartalmazhat olyan adatokat, amelyek nem az ügynök eredményének (vagyis a felhasználói kérdésre adott válasznak) adnak választ. Más visszaadott adatok közé tartoznak például a függvényeszközök hívásai, a függvényeszköz-hívások eredményei, az érvelés szövege, az állapotfrissítések és még sok más.

Mivel nem minden visszaadott tartalom az eredmény, fontos, hogy konkrét tartalomtípusokat keressen, amikor megpróbálja elkülöníteni az eredményt a többi tartalomtól.

A szöveges eredmény válaszból való kinyeréséhez az összes TextContent elem összes ChatMessages elemét összesíteni kell. Ennek egyszerűsítése érdekében egy Text tulajdonság minden olyan választípuson elérhető, amely összesíti az összeset TextContent.

A nem streamelt eset esetén minden egy AgentResponse objektumban jelenik meg. AgentResponse lehetővé teszi a létrehozott üzenetek elérését a Messages tulajdonságon keresztül.

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

A streamelési eset AgentResponseUpdate esetében az objektumok streamelése az előállításuk során történik. Az egyes frissítések tartalmazhatják az ügynök eredményének egy részét, valamint más tartalomelemeket is. A nem streamelt esethez hasonlóan a Text tulajdonság használatával lekérheti az eredménynek a frissítésben szereplő részét, és a tulajdonságon keresztül részletezheti a Contents részleteket.

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

A nem streamelt eset esetén minden egy AgentResponse objektumban jelenik meg. AgentResponse lehetővé teszi a létrehozott üzenetek elérését a messages tulajdonságon keresztül.

A szöveges eredmény válaszból való kinyeréséhez az összes TextContent elem összes Message elemét összesíteni kell. Ennek egyszerűsítése érdekében egy Text tulajdonság minden olyan választípuson elérhető, amely összesíti az összeset 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}")

A streamelési eset AgentResponseUpdate esetében a rendszer az objektumokat a visszaadott run(..., stream=True)módon streameli.ResponseStream Az egyes frissítések tartalmazhatják az ügynök eredményének egy részét, valamint más tartalomelemeket is. A nem streamelt esethez hasonlóan a text tulajdonság használatával lekérheti az eredménynek a frissítésben szereplő részét, és a tulajdonságon keresztül részletezheti a contents részleteket.

response_stream = agent.run("What is the weather like in Amsterdam?", stream=True)
async for update in response_stream:
    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}")

# Get the aggregated final response after streaming
final = await response_stream.get_final_response()
print(f"Complete text: {final.text}")

Üzenettípusok

Az ügynökök bemenete és kimenete üzenetként jelenik meg. Az üzenetek tartalomelemekre vannak felosztva.

A Microsoft Agent Framework az absztrakciók által Microsoft.Extensions.AI biztosított üzenetet és tartalomtípusokat használja. Az üzeneteket az ChatMessage osztály jelöli, és az összes tartalomosztály öröklődik az alaposztálytól AIContent .

Különböző AIContent alosztályok léteznek, amelyek különböző tartalomtípusok megjelenítésére szolgálnak. Néhányat az alap Microsoft.Extensions.AI absztrakciók részeként biztosítunk, de a szolgáltatók szükség esetén saját típusokat is hozzáadhatnak.

Az alábbiakban néhány népszerű típust Microsoft.Extensions.AItalál:

Típus	Description
TextContent	Szöveges tartalom, amely lehet például egy felhasználó vagy egy fejlesztő bemenete és az ügynök kimenete is. Általában egy ügynök szöveges eredményét tartalmazza.
DataContent	Bináris tartalom, amely lehet bemenet és kimenet is. Kép-, hang- vagy videoadatokat továbbíthat az ügynöknek (ahol támogatott).
UriContent	Olyan URL-cím, amely általában az üzemeltetett tartalomra mutat, például egy képre, hangra vagy videóra.
FunctionCallContent	Egy következtetési szolgáltatás kérése függvényeszköz meghívására.
FunctionResultContent	Egy függvényeszköz meghívásának eredménye.

A Python Agent Framework a csomagból származó agent_framework üzenet- és tartalomtípusokat használja. Az üzeneteket az Message osztály jelöli, és az összes tartalomosztály öröklődik az alaposztálytól Content .

Különböző Content alosztályok léteznek, amelyek különböző tartalomtípusok megjelenítésére szolgálnak:

Típus	Description
`Content`	Egyesített tartalomtípus gyári módszerekkel (`Content.from_text()`, `Content.from_data()`, ). `Content.from_uri()` A tulajdonság használatával ellenőrizze a `type` tartalom típusát ("text", "data", "uri").
`FunctionCallContent`	Egy AI-szolgáltatás kérése függvényeszköz meghívására.
`FunctionResultContent`	Egy függvényeszköz meghívásának eredménye.
`ErrorContent`	Hibainformációk a feldolgozás sikertelenségéről.
`UsageContent`	Jogkivonatok használati és számlázási adatai az AI-szolgáltatásból.

A különböző tartalomtípusok a következőképpen működnek:

from agent_framework import Message, Content

# Create a text message
text_message = Message(role="user", contents=["Hello!"])

# Create a message with multiple content types
image_data = b"..."  # your image bytes
mixed_message = Message(
    role="user",
    contents=[
        Content.from_text("Analyze this image:"),
        Content.from_data(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 content.type == "text":
            print(f"Text: {content.text}")
        elif content.type == "data":
            print(f"Data URI: {content.uri}")
        elif content.type == "uri":
            print(f"External URI: {content.uri}")

Következő lépések

Multimodális

Visszacsatolás

Hasznos volt ez az oldal?

Last updated on 2026-02-13