Bagikan melalui

Agen yang Sedang Aktif

Abstraksi Agen dasar mengekspos berbagai opsi untuk menjalankan agen. Penelepon dapat memilih untuk menyediakan nol, satu, atau banyak pesan input. Penelepon juga dapat memilih antara streaming dan non-streaming. Mari kita gali skenario penggunaan yang berbeda.

Streaming dan non-streaming

Microsoft Agent Framework mendukung metode streaming dan non-streaming untuk menjalankan agen.

Untuk non-streaming, gunakan RunAsync metode .

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

Untuk streaming, gunakan metode .RunStreamingAsync

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

Untuk non-streaming, gunakan run metode .

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

Untuk streaming, gunakan run metode dengan stream=True. Ini mengembalikan ResponseStream objek yang dapat diulang secara asinkron:

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

Objek ResponseStream yang dikembalikan oleh run(..., stream=True) mendukung dua pola konsumsi:

Pola 1: Iterasi asinkron — pembaruan proses saat tiba untuk tampilan real time:

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)

Pola 2: Finalisasi langsung — lewati iterasi dan dapatkan respons lengkap:

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

Pola 3: Gabungan — iterasi untuk tampilan real-time, lalu dapatkan hasil agregat:

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

Opsi operasi agen

Abstraksi agen dasar memang memungkinkan melewati objek opsi untuk setiap agen berjalan, namun kemampuan untuk menyesuaikan eksekusi pada tingkat abstraksi cukup terbatas. Agen dapat bervariasi secara signifikan dan oleh karena itu tidak ada opsi penyesuaian yang benar-benar umum.

Untuk kasus di mana penelepon mengetahui jenis agen yang bekerja dengan mereka, dimungkinkan untuk meneruskan jenis opsi tertentu untuk memungkinkan penyesuaian eksekusi.

Misalnya, di sini agen adalah ChatClientAgent dan dimungkinkan untuk meneruskan ChatClientAgentRunOptions objek yang mewarisi dari AgentRunOptions. Ini memungkinkan pemanggil untuk menyediakan kustom ChatOptions yang digabungkan dengan opsi tingkat agen apa pun sebelum diteruskan ke IChatClient yang ChatClientAgent dibangun.

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

Agen Python mendukung penyesuaian setiap eksekusi melalui options parameter . Opsi diteruskan sebagai TypedDict dan dapat diatur pada waktu konstruksi (melalui default_options) dan per-eksekusi (melalui options). Setiap penyedia memiliki kelas TypedDict sendiri yang menyediakan pelengkapan otomatis IDE lengkap dan pemeriksaan jenis untuk pengaturan khusus penyedia.

Opsi umum meliputi:

  • max_tokens: Jumlah maksimum token yang akan dihasilkan
  • temperature: Mengontrol keacakan dalam pembuatan respons
  • model_id: Mengambil alih model untuk eksekusi khusus ini
  • top_p: Parameter pengambilan sampel nukleus
  • response_format: Tentukan format respons (misalnya, output terstruktur)

Nota

Parameter tools dan instructions tetap sebagai argumen kata kunci langsung dan tidak diteruskan melalui options kamus.

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)

Setiap penyedia memiliki kelas TypedDict sendiri (misalnya, OpenAIChatOptions, , AnthropicChatOptionsOllamaChatOptions) yang mengekspos serangkaian opsi lengkap yang didukung oleh penyedia tersebut.

Ketika keduanya default_options dan per-eksekusi options disediakan, opsi per-eksekusi lebih diutamakan dan digabungkan dengan default.

Jenis respons

Respons streaming dan non-streaming dari agen berisi semua konten yang diproduksi oleh agen. Konten mungkin menyertakan data yang bukan hasilnya (yaitu, jawaban atas pertanyaan pengguna) dari agen. Contoh data lain yang dikembalikan termasuk panggilan alat fungsi, hasil dari panggilan alat fungsi, teks penalaran, pembaruan status, dan banyak lagi.

Karena tidak semua konten yang dikembalikan adalah hasilnya, penting untuk mencari jenis konten tertentu saat mencoba mengisolasi hasil dari konten lain.

Untuk mengekstrak hasil teks dari respons, semua TextContent item dari semua ChatMessages item perlu diagregasi. Untuk menyederhanakan ini, Text properti tersedia di semua jenis respons yang menggabungkan semua TextContent.

Untuk kasus non-streaming, semuanya dikembalikan dalam satu AgentResponse objek. AgentResponse memungkinkan akses ke pesan yang dihasilkan melalui Messages properti .

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

Untuk kasus streaming, AgentResponseUpdate objek dialirkan saat diproduksi. Setiap pembaruan mungkin berisi bagian dari hasil dari agen, dan juga berbagai item konten lainnya. Mirip dengan kasus non-streaming, dimungkinkan untuk menggunakan Text properti untuk mendapatkan bagian dari hasil yang terkandung dalam pembaruan, dan menelusuri detail melalui Contents properti .

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

Untuk kasus non-streaming, semuanya dikembalikan dalam satu AgentResponse objek. AgentResponse memungkinkan akses ke pesan yang dihasilkan melalui messages properti .

Untuk mengekstrak hasil teks dari respons, semua TextContent item dari semua Message item perlu diagregasi. Untuk menyederhanakan ini, Text properti tersedia di semua jenis respons yang menggabungkan semua 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}")

Untuk kasus streaming, AgentResponseUpdate objek dialirkan saat diproduksi melalui yang ResponseStream dikembalikan oleh run(..., stream=True). Setiap pembaruan mungkin berisi bagian dari hasil dari agen, dan juga berbagai item konten lainnya. Mirip dengan kasus non-streaming, dimungkinkan untuk menggunakan text properti untuk mendapatkan bagian dari hasil yang terkandung dalam pembaruan, dan menelusuri detail melalui contents properti .

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

Jenis pesan

Input dan output dari agen diwakili sebagai pesan. Pesan dibagi menjadi item konten.

Microsoft Agent Framework menggunakan jenis pesan dan konten yang disediakan oleh Microsoft.Extensions.AI abstraksi. Pesan diwakili oleh ChatMessage kelas dan semua kelas konten yang diwarisi dari kelas dasar AIContent .

Ada berbagai AIContent subkelas yang digunakan untuk mewakili berbagai jenis konten. Beberapa disediakan sebagai bagian dari abstraksi dasar Microsoft.Extensions.AI , tetapi penyedia juga dapat menambahkan jenisnya sendiri, jika diperlukan.

Berikut adalah beberapa jenis populer dari Microsoft.Extensions.AI:

Tipe Deskripsi
TextContent Konten tekstual yang dapat berupa input, misalnya, dari pengguna atau pengembang, dan output dari agen. Biasanya berisi hasil teks dari agen.
DataContent Konten biner yang dapat berupa input dan output. Dapat digunakan untuk meneruskan data gambar, audio, atau video ke dan dari agen (jika didukung).
UriContent URL yang biasanya menunjuk pada konten yang dihosting seperti gambar, audio, atau video.
FunctionCallContent Permintaan oleh layanan inferensi untuk memanggil alat fungsi.
FunctionResultContent Hasil pemanggilan alat fungsi.

Python Agent Framework menggunakan jenis pesan dan konten dari agent_framework paket. Pesan diwakili oleh Message kelas dan semua kelas konten yang diwarisi dari kelas dasar Content .

Ada berbagai Content subkelas yang digunakan untuk mewakili berbagai jenis konten:

Tipe Deskripsi
Content Jenis konten terpadu dengan metode pabrik (Content.from_text(), , Content.from_data()Content.from_uri()). type Gunakan properti untuk memeriksa tipe konten ("teks", "data", "uri").
FunctionCallContent Permintaan oleh layanan AI untuk memanggil alat fungsi.
FunctionResultContent Hasil pemanggilan alat fungsi.
ErrorContent Informasi kesalahan saat pemrosesan gagal.
UsageContent Informasi penggunaan dan penagihan token dari layanan AI.

Berikut cara bekerja dengan jenis konten yang berbeda:

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

Langkah selanjutnya

Multimodal

  • Last updated on