Dela via

Agenter som körs

Basabstraktionen av agenten visar olika alternativ för att köra agenten. Anropare kan välja att ange noll, ett eller flera indatameddelanden. Uppringare kan också välja mellan direktuppspelning och icke-direktuppspelning. Nu ska vi gå in på de olika användningsscenarierna.

Direktuppspelning och icke-direktuppspelning

Microsoft Agent Framework stöder både strömningsmetoder och icke-strömningsmetoder för att köra en agent.

Använd metoden för RunAsync icke-direktuppspelning.

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

Använd metoden för RunStreamingAsync direktuppspelning.

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

Använd metoden för run icke-direktuppspelning.

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

För direktuppspelning använder du run metoden med stream=True. Detta returnerar ett ResponseStream objekt som kan itereras asynkront:

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

Objektet ResponseStream som returneras av run(..., stream=True) stöder två förbrukningsmönster:

Mönster 1: Asynkron iteration – bearbeta uppdateringar när de tas emot för realtidsvisning:

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)

Mönster 2: Direkt slutförande – hoppa över iteration och få det fullständiga svaret:

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

Mönster 3: Kombinerat – iterera för realtidsvisning och hämta sedan det aggregerade resultatet:

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

Alternativ för agentkörning

Basagentabstraktionen tillåter att ett alternativobjekt skickas för varje agentkörning, men möjligheten att anpassa en körning på abstraktionsnivå är ganska begränsad. Agenter kan variera avsevärt och därför finns det inte riktigt vanliga anpassningsalternativ.

I de fall där anroparen känner till vilken typ av agent de arbetar med går det att skicka typspecifika alternativ för att tillåta anpassning av körningen.

Här är agenten till exempel en ChatClientAgent och det är möjligt att skicka ett ChatClientAgentRunOptions objekt som ärver från AgentRunOptions. Detta gör att anroparen kan ange anpassade ChatOptions som sammanfogas med alla alternativ på agentnivå innan de IChatClient skickas till den som ChatClientAgent är byggd på.

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

Python-agenter stöder anpassning av varje körning via parametern options . Alternativen skickas som en TypedDict och kan anges vid både byggtid (via default_options) och per körning (via options). Varje provider har en egen TypedDict-klass som tillhandahåller fullständig IDE-automatisk komplettering och typkontroll för providerspecifika inställningar.

Vanliga alternativ är:

  • max_tokens: Maximalt antal token som ska genereras
  • temperature: Styr slumpmässighet i svarsgenerering
  • model_id: Åsidosätt modellen för den här specifika körningen
  • top_p: Nucleus samplingsparameter
  • response_format: Ange svarsformatet (t.ex. strukturerade utdata)

Anmärkning

Parametrarna tools och instructions förblir som direkta nyckelordsargument och skickas inte via options ordlistan.

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)

Varje provider har en egen TypedDict-klass (t.ex. OpenAIChatOptions, , AnthropicChatOptions, OllamaChatOptions) som exponerar den fullständiga uppsättningen alternativ som stöds av providern.

När både default_options och per körning options tillhandahålls har alternativen per körning företräde och sammanfogas med standardvärdena.

Svarstyper

Både direktuppspelnings- och icke-direktuppspelningssvar från agenter innehåller allt innehåll som produceras av agenten. Innehållet kan innehålla data som inte är resultatet (dvs. svaret på användarfrågan) från agenten. Exempel på andra data som returneras är funktionsverktygsanrop, resultat från funktionsverktygsanrop, resonemangstext, statusuppdateringar och många fler.

Eftersom inte allt innehåll som returneras är resultatet är det viktigt att leta efter specifika innehållstyper när du försöker isolera resultatet från det andra innehållet.

Om du vill extrahera textresultatet från ett svar måste alla TextContent objekt från alla ChatMessages objekt aggregeras. För att förenkla detta är en Text egenskap tillgänglig för alla svarstyper som aggregerar alla TextContent.

För fallet med icke-direktuppspelning returneras allt i ett AgentResponse objekt. AgentResponse ger åtkomst till de producerade meddelandena via egenskapen Messages .

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

För strömningsfallet AgentResponseUpdate strömmas objekt när de skapas. Varje uppdatering kan innehålla en del av resultatet från agenten och även olika andra innehållsobjekt. På samma sätt som fallet med icke-direktuppspelning är det möjligt att använda Text egenskapen för att hämta den del av resultatet som ingår i uppdateringen och öka detaljnivån via Contents egenskapen.

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

För fallet med icke-direktuppspelning returneras allt i ett AgentResponse objekt. AgentResponse ger åtkomst till de producerade meddelandena via egenskapen messages .

Om du vill extrahera textresultatet från ett svar måste alla TextContent objekt från alla Message objekt aggregeras. För att förenkla detta är en Text egenskap tillgänglig för alla svarstyper som aggregerar alla 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}")

För strömningsfallet AgentResponseUpdate strömmas objekt när de skapas via returnerade ResponseStream av run(..., stream=True). Varje uppdatering kan innehålla en del av resultatet från agenten och även olika andra innehållsobjekt. På samma sätt som fallet med icke-direktuppspelning är det möjligt att använda text egenskapen för att hämta den del av resultatet som ingår i uppdateringen och öka detaljnivån via contents egenskapen.

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

Meddelandetyper

Indata och utdata från agenter representeras som meddelanden. Meddelanden delas upp i innehållsobjekt.

Microsoft Agent Framework använder de meddelande- och innehållstyper som tillhandahålls av abstraktionerna Microsoft.Extensions.AI . Meddelanden representeras av ChatMessage klassen och alla innehållsklasser ärver från basklassen AIContent .

Det finns olika AIContent underklasser som används för att representera olika typer av innehåll. Vissa tillhandahålls som en del av basabstraktionerna Microsoft.Extensions.AI , men leverantörer kan också lägga till sina egna typer, där det behövs.

Här är några populära typer från Microsoft.Extensions.AI:

Typ Description
TextContent Textinnehåll som kan vara både indata, till exempel från en användare eller utvecklare, och utdata från agenten. Innehåller vanligtvis textresultatet från en agent.
DataContent Binärt innehåll som kan vara både indata och utdata. Kan användas för att skicka bild-, ljud- eller videodata till och från agenten (där det stöds).
UriContent En URL som vanligtvis pekar på värdbaserat innehåll, till exempel en bild, ett ljud eller en video.
FunctionCallContent En begäran från en slutsatsdragningstjänst om att anropa ett funktionsverktyg.
FunctionResultContent Resultatet av ett funktionsverktygsanrop.

Python Agent Framework använder meddelande- och innehållstyper från agent_framework paketet. Meddelanden representeras av Message klassen och alla innehållsklasser ärver från basklassen Content .

Det finns olika Content underklasser som används för att representera olika typer av innehåll:

Typ Description
Content Enhetlig innehållstyp med fabriksmetoder (Content.from_text(), Content.from_data(), Content.from_uri()). Använd egenskapen type för att kontrollera innehållstypen ("text", "data", "uri").
FunctionCallContent En begäran från en AI-tjänst om att anropa ett funktionsverktyg.
FunctionResultContent Resultatet av ett funktionsverktygsanrop.
ErrorContent Felinformation när bearbetningen misslyckas.
UsageContent Information om tokenanvändning och fakturering från AI-tjänsten.

Så här fungerar du med olika innehållstyper:

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

Nästa steg

Multimodal

  • Last updated on