Alur Kerja Microsoft Agent Framework - Menggunakan Alur Kerja sebagai Agen

Dokumen ini memberikan gambaran umum tentang cara menggunakan Alur Kerja sebagai Agen di Microsoft Agent Framework.

Gambaran Umum

Terkadang Anda telah membangun alur kerja canggih dengan beberapa agen, pelaksana kustom, dan logika kompleks - tetapi Anda ingin menggunakannya seperti agen lain. Itulah yang agen alur kerja biarkan Anda lakukan. Dengan membungkus alur kerja Anda sebagai Agent, Anda dapat berinteraksi dengannya melalui API yang sama akrab yang akan Anda gunakan untuk agen obrolan sederhana.

Manfaat Utama

Antarmuka Terpadu: Berinteraksi dengan alur kerja kompleks menggunakan API yang sama dengan agen sederhana
Kompatibilitas API: Mengintegrasikan alur kerja dengan sistem yang ada yang mendukung antarmuka Agen
Komposabilitas: Gunakan agen alur kerja sebagai blok penyusun dalam sistem agen yang lebih besar atau alur kerja lainnya
Manajemen Sesi: Memanfaatkan sesi agen perangkat lunak untuk status percakapan dan kelanjutan
Dukungan Streaming: Dapatkan pembaruan real-time saat alur kerja dijalankan

Cara Kerjanya

Saat Anda mengonversi alur kerja ke agen:

Alur kerja divalidasi untuk memastikan pelaksana mulainya dapat menerima jenis input yang diperlukan
Sesi dibuat untuk mengelola status percakapan
Pesan input dirutekan ke eksekutor mulai alur kerja
Peristiwa alur kerja dikonversi ke pembaruan respons agen
Permintaan input eksternal (dari RequestInfoExecutor) muncul sebagai panggilan fungsi

Persyaratan

Untuk menggunakan alur kerja sebagai agen, pelaksana mulai alur kerja harus dapat menangani IEnumerable<ChatMessage> sebagai input. Ini secara otomatis terpenuhi saat menggunakan eksekutor berbasis agen yang dibuat dengan AsAIAgent.

Membuat Agen Alur Kerja

AsAIAgent() Gunakan metode ekstensi untuk mengonversi alur kerja yang kompatibel menjadi agen:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

// Create agents
AIAgent researchAgent = chatClient.AsAIAgent("You are a researcher. Research and gather information on the given topic.");
AIAgent writerAgent = chatClient.AsAIAgent("You are a writer. Write clear, engaging content based on research.");
AIAgent reviewerAgent = chatClient.AsAIAgent("You are a reviewer. Review the content and provide a final polished version.");

// Build a sequential workflow
var workflow = new WorkflowBuilder(researchAgent)
    .AddEdge(researchAgent, writerAgent)
    .AddEdge(writerAgent, reviewerAgent)
    .Build();

// Convert the workflow to an agent
AIAgent workflowAgent = workflow.AsAIAgent(
    id: "content-pipeline",
    name: "Content Pipeline Agent",
    description: "A multi-agent workflow that researches, writes, and reviews content"
);

Parameter untuk AsAIAgent

Pengaturan	Tipe	Deskripsi
`id`	`string?`	Pengidentifikasi unik opsional untuk agen. Dibuat secara otomatis jika tidak disediakan.
`name`	`string?`	Nama tampilan opsional untuk agen.
`description`	`string?`	Deskripsi opsional tentang tujuan agen.
`executionEnvironment`	`IWorkflowExecutionEnvironment?`	Lingkungan eksekusi opsional. Disetel secara otomatis ke `InProcessExecution.OffThread` atau `InProcessExecution.Concurrent` berdasarkan konfigurasi alur kerja.
`includeExceptionDetails`	`bool`	Jika `true`, sertakan pesan pengecualian dalam konten kesalahan. Secara default menjadi `false`.
`includeWorkflowOutputsInResponse`	`bool`	Jika `true`, mengubah output alur kerja yang keluar menjadi konten untuk respons agen. Secara default menjadi `false`.

Menggunakan Agen Alur Kerja

Membuat Sesi

Setiap percakapan dengan agen alur kerja memerlukan sesi untuk mengelola status:

// Create a new session for the conversation
AgentSession session = await workflowAgent.CreateSessionAsync();

Eksekusi Tanpa Streaming

Untuk kasus penggunaan sederhana di mana Anda menginginkan respons lengkap:

var messages = new List<ChatMessage>
{
    new(ChatRole.User, "Write an article about renewable energy trends in 2025")
};

AgentResponse response = await workflowAgent.RunAsync(messages, session);

foreach (ChatMessage message in response.Messages)
{
    Console.WriteLine($"{message.AuthorName}: {message.Text}");
}

Eksekusi Streaming

Untuk pembaruan real time saat alur kerja dijalankan:

var messages = new List<ChatMessage>
{
    new(ChatRole.User, "Write an article about renewable energy trends in 2025")
};

await foreach (AgentResponseUpdate update in workflowAgent.RunStreamingAsync(messages, session))
{
    // Process streaming updates from each agent in the workflow
    if (!string.IsNullOrEmpty(update.Text))
    {
        Console.Write(update.Text);
    }
}

Menangani Permintaan Input Eksternal

Saat alur kerja berisi pelaksana yang meminta input eksternal (menggunakan RequestInfoExecutor), permintaan ini muncul sebagai panggilan fungsi dalam respons agen:

await foreach (AgentResponseUpdate update in workflowAgent.RunStreamingAsync(messages, session))
{
    // Check for function call requests
    foreach (AIContent content in update.Contents)
    {
        if (content is FunctionCallContent functionCall)
        {
            // Handle the external input request
            Console.WriteLine($"Workflow requests input: {functionCall.Name}");
            Console.WriteLine($"Request data: {functionCall.Arguments}");

            // Provide the response in the next message
        }
    }
}

Serialisasi dan Dimulainya Kembali Sesi

Sesi agen alur kerja dapat diserialisasikan untuk persistensi dan dilanjutkan nanti:

// Serialize the session state
JsonElement serializedSession = await workflowAgent.SerializeSessionAsync(session);

// Store serializedSession to your persistence layer...

// Later, resume the session
AgentSession resumedSession = await workflowAgent.DeserializeSessionAsync(serializedSession);

// Continue the conversation
await foreach (var update in workflowAgent.RunStreamingAsync(newMessages, resumedSession))
{
    Console.Write(update.Text);
}

Persyaratan

Untuk menggunakan alur kerja sebagai agen, pelaksana mulai alur kerja harus dapat menangani input pesan. Ini secara otomatis terpenuhi saat menggunakan Agent atau pelaksana berbasis agen.

Membuat Agen Alur Kerja

Panggil as_agent() pada alur kerja yang kompatibel mana pun untuk mengonversinya menjadi sebuah agen.

from agent_framework.foundry import FoundryChatClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential

# Create your chat client and agents
client = FoundryChatClient(
    project_endpoint="<your-endpoint>",
    model="<your-deployment>",
    credential=AzureCliCredential(),
)

researcher = client.as_agent(
    name="Researcher",
    instructions="Research and gather information on the given topic.",
)

writer = client.as_agent(
    name="Writer",
    instructions="Write clear, engaging content based on research.",
)

# Build a sequential workflow
workflow = SequentialBuilder(participants=[researcher, writer]).build()

# Convert the workflow to an agent
workflow_agent = workflow.as_agent(name="Content Pipeline Agent")

Parameter as_agent

Pengaturan	Tipe	Deskripsi
`name`	`str \| None`	Nama tampilan opsional untuk agen. Dibuat secara otomatis jika tidak disediakan.

Menggunakan Agen Alur Kerja

Membuat Sesi

Anda dapat secara opsional membuat sesi untuk mengelola status percakapan selama beberapa putaran.

# Create a new session for the conversation
session = await workflow_agent.create_session()

Nota

Sesi bersifat opsional. Jika Anda tidak meneruskan session ke run(), agen menangani status secara internal. Jika workflow.as_agent() dibuat tanpa context_providers, kerangka kerja menambahkan InMemoryHistoryProvider() secara default sehingga riwayat multi-giliran berfungsi langsung. Jika Anda menetapkan context_providers secara eksplisit, daftar tersebut digunakan sebagaimana adanya.

Eksekusi Tanpa Streaming

Untuk kasus penggunaan sederhana di mana Anda menginginkan respons lengkap:

# You can pass a plain string as input
response = await workflow_agent.run("Write an article about AI trends")

for message in response.messages:
    print(f"{message.author_name}: {message.text}")

Eksekusi Streaming

Untuk pembaruan real time saat alur kerja dijalankan:

async for update in workflow_agent.run(
    "Write an article about AI trends",
    stream=True,
):
    if update.text:
        print(update.text, end="", flush=True)

Menangani Permintaan Input Eksternal

Saat alur kerja berisi pelaksana yang meminta input eksternal (menggunakan request_info), permintaan ini muncul sebagai panggilan fungsi dalam respons agen. Panggilan fungsi menggunakan nama WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:

from agent_framework import Content, Message, WorkflowAgent

response = await workflow_agent.run("Process my request")

# Look for function calls in the response
human_review_function_call = None
for message in response.messages:
    for content in message.contents:
        if content.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:
            human_review_function_call = content

Memberikan Respons terhadap Permintaan yang Tertunda

Untuk melanjutkan eksekusi alur kerja setelah permintaan input eksternal, buat hasil fungsi dan kirim kembali:

if human_review_function_call:
    # Parse the request arguments
    request = WorkflowAgent.RequestInfoFunctionArgs.from_json(
        human_review_function_call.arguments
    )

    # Create a response (your custom response type)
    result_data = MyResponseType(approved=True, feedback="Looks good")

    # Create the function call result
    function_result = Content.from_function_result(
        call_id=human_review_function_call.call_id,
        result=result_data,
    )

    # Send the response back to continue the workflow
    response = await workflow_agent.run(Message("tool", [function_result]))

Contoh Lengkap

Berikut adalah contoh lengkap yang menunjukkan agen alur kerja dengan output streaming:

import asyncio
import os

from agent_framework.foundry import FoundryChatClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential


async def main():
    # Set up the chat client
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    )

    # Create specialized agents
    researcher = client.as_agent(
        name="Researcher",
        instructions="Research the given topic and provide key facts.",
    )

    writer = client.as_agent(
        name="Writer",
        instructions="Write engaging content based on the research provided.",
    )

    reviewer = client.as_agent(
        name="Reviewer",
        instructions="Review the content and provide a final polished version.",
    )

    # Build a sequential workflow
    workflow = SequentialBuilder(participants=[researcher, writer, reviewer]).build()

    # Convert to a workflow agent
    workflow_agent = workflow.as_agent(name="Content Creation Pipeline")

    # Run the workflow
    print("Starting workflow...")
    print("=" * 60)

    current_author = None
    async for update in workflow_agent.run(
        "Write about quantum computing",
        stream=True,
    ):
        # Show when different agents are responding
        if update.author_name and update.author_name != current_author:
            if current_author:
                print("\n" + "-" * 40)
            print(f"\n[{update.author_name}]:")
            current_author = update.author_name

        if update.text:
            print(update.text, end="", flush=True)

    print("\n" + "=" * 60)
    print("Workflow completed!")


if __name__ == "__main__":
    asyncio.run(main())

Memahami Konversi Peristiwa

Saat alur kerja berjalan sebagai agen, peristiwa alur kerja dikonversi ke respons agen. Jenis respons tergantung pada cara Anda memanggil run():

run(): Mengembalikan yang AgentResponse berisi hasil lengkap setelah alur kerja selesai
run(..., stream=True): Mengembalikan iterable asinkron dari objek AgentResponseUpdate saat alur kerja dijalankan, menyediakan pembaruan waktu nyata.

Selama eksekusi, peristiwa alur kerja internal dipetakan ke respons agen sebagai berikut:

Peristiwa Alur Kerja	Respons dari Agen
`event.type == "output"`	Diteruskan sebagai `AgentResponseUpdate` (streaming) atau digabungkan ke dalam `AgentResponse` (non-streaming)
`event.type == "request_info"`	Dikonversi ke konten panggilan fungsi menggunakan `WorkflowAgent.REQUEST_INFO_FUNCTION_NAME`
Peristiwa lain	Diabaikan (hanya alur kerja-internal)

Konversi ini memungkinkan Anda menggunakan antarmuka agen standar sambil masih memiliki akses ke informasi alur kerja terperinci saat diperlukan.

Kasus Penggunaan

1. Rangkaian Agen Kompleks

Bungkus alur kerja multi-agen sebagai agen tunggal untuk digunakan dalam aplikasi:

User Request --> [Workflow Agent] --> Final Response
                      |
                      +-- Researcher Agent
                      +-- Writer Agent  
                      +-- Reviewer Agent

2. Komposisi Agen

Gunakan agen alur kerja sebagai komponen dalam sistem yang lebih besar:

Agen alur kerja dapat digunakan sebagai alat oleh agen lain
Beberapa agen alur kerja dapat diorkestrasi bersama-sama
Agen alur kerja dapat disarangkan dalam alur kerja lain

3. Integrasi API

Mengekspos alur kerja kompleks melalui API yang mengharapkan antarmuka Agen standar, memungkinkan:

Antarmuka obrolan yang menggunakan alur kerja backend canggih
Integrasi dengan sistem berbasis agen yang ada
Migrasi bertahap dari agen sederhana ke alur kerja yang kompleks

Langkah Selanjutnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-12

Bagikan melalui

Alur Kerja Microsoft Agent Framework - Menggunakan Alur Kerja sebagai Agen

Gambaran Umum

Manfaat Utama

Cara Kerjanya

Persyaratan

Membuat Agen Alur Kerja

Parameter untuk AsAIAgent

Menggunakan Agen Alur Kerja

Membuat Sesi

Eksekusi Tanpa Streaming

Eksekusi Streaming

Menangani Permintaan Input Eksternal

Serialisasi dan Dimulainya Kembali Sesi

Persyaratan

Membuat Agen Alur Kerja

Parameter as_agent

Menggunakan Agen Alur Kerja

Membuat Sesi

Eksekusi Tanpa Streaming

Eksekusi Streaming

Menangani Permintaan Input Eksternal

Memberikan Respons terhadap Permintaan yang Tertunda

Contoh Lengkap

Memahami Konversi Peristiwa

Kasus Penggunaan

1. Rangkaian Agen Kompleks

2. Komposisi Agen

3. Integrasi API

Langkah Selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: