Uruchamianie agentów

Abstrakcja agenta podstawowego uwidacznia różne opcje uruchamiania agenta. Osoby wywołujące mogą podać zero, jeden lub wiele komunikatów wejściowych. Osoby wywołujące mogą również wybierać między przesyłaniem strumieniowym i bez przesyłania strumieniowego. Przyjrzyjmy się różnym scenariuszom użycia.

Przesyłanie strumieniowe i nie przesyłane strumieniowo

Program Microsoft Agent Framework obsługuje metody przesyłania strumieniowego i nieprzesyłania strumieniowego na potrzeby uruchamiania agenta.

W przypadku braku przesyłania strumieniowego RunAsync użyj metody .

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

W przypadku przesyłania strumieniowego RunStreamingAsync użyj metody .

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

W przypadku braku przesyłania strumieniowego run użyj metody .

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

W przypadku przesyłania strumieniowego run_stream użyj metody .

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

Opcje uruchamiania agenta

Abstrakcja agenta podstawowego umożliwia przekazywanie obiektu opcji dla każdego uruchomienia agenta, jednak możliwość dostosowania przebiegu na poziomie abstrakcji jest dość ograniczona. Agenci mogą się znacznie różnić i dlatego nie ma naprawdę typowych opcji dostosowywania.

W przypadku, gdy obiekt wywołujący zna typ agenta, z którym pracują, można przekazać określone opcje typu w celu umożliwienia dostosowywania przebiegu.

Na przykład agent jest elementem ChatClientAgent i można przekazać ChatClientAgentRunOptions obiekt, który dziedziczy z AgentRunOptionselementu . Dzięki temu obiekt wywołujący może udostępnić niestandardowe ChatOptions , które są scalane z dowolnymi opcjami na poziomie agenta przed przekazaniem do IChatClient elementu, na który ChatClientAgent jest oparty.

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

Agenci języka Python obsługują przekazywanie argumentów słów kluczowych w celu dostosowania każdego przebiegu. Dostępne opcje zależą od typu agenta, ale ChatAgent obsługuje wiele parametrów klienta czatu, które można przekazać do metod run i run_stream .

Typowe opcje obejmują ChatAgent :

max_tokens: Maksymalna liczba tokenów do wygenerowania
temperature: Kontroluje losowość w generowaniu odpowiedzi
model: zastąpić model dla tego konkretnego przebiegu
tools: Dodaj dodatkowe narzędzia tylko dla tego przebiegu
response_format: Określ format odpowiedzi (np. dane wyjściowe ze strukturą)

# Run with custom options
result = await agent.run(
    "What is the weather like in Amsterdam?",
    temperature=0.3,
    max_tokens=150,
    model="gpt-4o"
)

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

Jeśli są dostępne zarówno ustawienia domyślne na poziomie agenta, jak i opcje na poziomie uruchamiania, opcje na poziomie uruchamiania mają pierwszeństwo.

Typy odpowiedzi

Zarówno odpowiedzi przesyłane strumieniowo, jak i nie przesyłane strumieniowo z agentów zawierają całą zawartość utworzoną przez agenta. Zawartość może zawierać dane, które nie są wynikiem (tj. odpowiedzią na pytanie użytkownika) od agenta. Przykłady innych zwracanych danych obejmują wywołania narzędzi funkcji, wyniki wywołań narzędzi funkcji, tekst rozumowania, aktualizacje stanu i wiele innych.

Ponieważ nie zwracana jest cała zwracana zawartość, ważne jest, aby wyszukać określone typy zawartości podczas próby odizolowania wyniku od innej zawartości.

Aby wyodrębnić wynik tekstu z odpowiedzi, wszystkie TextContent elementy ze wszystkich ChatMessages elementów muszą zostać zagregowane. Aby uprościć ten proces, udostępniamy Text właściwość dla wszystkich typów odpowiedzi, które agregują wszystkie TextContenttypy .

W przypadku przypadku braku przesyłania strumieniowego wszystko jest zwracane w jednym AgentRunResponse obiekcie. AgentRunResponse umożliwia dostęp do wygenerowanych komunikatów za pośrednictwem Messages właściwości .

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

W przypadku przypadku AgentRunResponseUpdate przesyłania strumieniowego obiekty są przesyłane strumieniowo w miarę ich tworzenia. Każda aktualizacja może zawierać część wyniku agenta, a także różne inne elementy zawartości. Podobnie jak w przypadku braku przesyłania strumieniowego, można użyć Text właściwości , aby pobrać część wyniku zawartego w aktualizacji i przejść do szczegółów za pośrednictwem Contents właściwości .

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

Aby wyodrębnić wynik tekstu z odpowiedzi, wszystkie TextContent elementy ze wszystkich ChatMessage elementów muszą zostać zagregowane. Aby uprościć ten proces, udostępniamy text właściwość dla wszystkich typów odpowiedzi, które agregują wszystkie TextContenttypy .

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

W przypadku przypadku AgentRunResponseUpdate przesyłania strumieniowego obiekty są przesyłane strumieniowo w miarę ich tworzenia. Każda aktualizacja może zawierać część wyniku agenta, a także różne inne elementy zawartości. Podobnie jak w przypadku braku przesyłania strumieniowego, można użyć text właściwości , aby pobrać część wyniku zawartego w aktualizacji i przejść do szczegółów za pośrednictwem contents właściwości .

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 komunikatów

Dane wejściowe i wyjściowe z agentów są reprezentowane jako komunikaty. Wiadomości są podzielone na elementy zawartości.

Program Microsoft Agent Framework używa typów komunikatów i zawartości udostępnianych przez Microsoft.Extensions.AI abstrakcje. Komunikaty są reprezentowane przez klasę ChatMessage , a wszystkie klasy zawartości dziedziczą z klasy bazowej AIContent .

Istnieją różne AIContent podklasy, które są używane do reprezentowania różnych typów zawartości. Niektóre są udostępniane jako część abstrakcji podstawowych Microsoft.Extensions.AI , ale dostawcy mogą również dodawać własne typy, w razie potrzeby.

Oto kilka popularnych typów:Microsoft.Extensions.AI

Typ	Description
TekstContent	Zawartość tekstowa, która może być danymi wejściowymi, np. od użytkownika lub dewelopera, oraz danymi wyjściowymi agenta. Zazwyczaj zawiera wynik tekstowy agenta.
DataContent	Zawartość binarna, która może być zarówno danymi wejściowymi, jak i wyjściowymi. Może służyć do przekazywania danych obrazu, audio lub wideo do i z agenta (gdzie jest obsługiwana).
Identyfikator URIContent	Adres URL, który zazwyczaj wskazuje hostowaną zawartość, taką jak obraz, dźwięk lub wideo.
FunctionCallContent	Żądanie przez usługę wnioskowania w celu wywołania narzędzia funkcji.
FunctionResultContent	Wynik wywołania narzędzia funkcji.

Struktura agenta języka Python używa typów komunikatów i zawartości z agent_framework pakietu. Komunikaty są reprezentowane przez klasę ChatMessage , a wszystkie klasy zawartości dziedziczą z klasy bazowej BaseContent .

Istnieją różne BaseContent podklasy, które są używane do reprezentowania różnych typów zawartości:

Typ	Description
`TextContent`	Zawartość tekstowa, która może być zarówno danymi wejściowymi, jak i wyjściowymi agenta. Zazwyczaj zawiera wynik tekstowy agenta.
`DataContent`	Zawartość binarna reprezentowana jako identyfikator URI danych (np. obrazy zakodowane w formacie base64). Może służyć do przekazywania danych binarnych do i z agenta.
`UriContent`	Identyfikator URI wskazujący hostowaną zawartość, taką jak obraz, plik audio lub dokument.
`FunctionCallContent`	Żądanie przez usługę sztucznej inteligencji w celu wywołania narzędzia funkcji.
`FunctionResultContent`	Wynik wywołania narzędzia funkcji.
`ErrorContent`	Informacje o błędzie podczas przetwarzania kończą się niepowodzeniem.
`UsageContent`	Informacje o użyciu tokenu i rozliczeniach z usługi sztucznej inteligencji.

Oto jak pracować z różnymi typami zawartości:

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

Dalsze kroki

Konwersacje wielowątkowa i wątkowe

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-01