Megosztás:

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

Ügynökfuttatá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().create_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)

Minden szolgáltató saját TypedDict osztálysal (pl. , , AnthropicChatOptions) OllamaChatOptionsrendelkezik, OpenAIChatOptionsamely 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 options is default_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 ChatMessage 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 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.

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

Ü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 ChatMessage osztály jelöli, és az összes tartalomosztály öröklődik az alaposztálytól BaseContent .

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

Típus Description
TextContent Szöveges tartalom, amely az ügynök bemenete és kimenete is lehet. Általában egy ügynök szöveges eredményét tartalmazza.
DataContent Bináris tartalom adat URI-ként (például base64 kódolású képek). Bináris adatok továbbíthatók az ügynöknek és az ügynöktől.
UriContent Olyan URI, amely az üzemeltetett tartalmakra, például egy képre, hangfájlra vagy dokumentumra mutat.
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 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}")

Következő lépések

Többfordulós beszélgetések és szálkezelés

  • Last updated on