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 untuk status percakapan, titik pemeriksaan, dan melanjutkan kembali
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 pesan obrolan
Sesi dibuat untuk mengelola status percakapan dan titik pemeriksaan
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 ChatClientAgent atau pelaksana berbasis agen lainnya.

Membuat Agen Alur Kerja

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

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

// First, build your workflow
var workflow = AgentWorkflowBuilder
    .CreateSequentialPipeline(researchAgent, writerAgent, reviewerAgent)
    .Build();

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

Parameter AsAgent

Pengaturan	Tipe	Description
`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.
`checkpointManager`	`CheckpointManager?`	Manajer titik pemeriksaan opsional untuk persistensi di seluruh sesi.
`executionEnvironment`	`IWorkflowExecutionEnvironment?`	Lingkungan eksekusi opsional. Disetel secara otomatis ke `InProcessExecution.OffThread` atau `InProcessExecution.Concurrent` berdasarkan konfigurasi alur kerja.

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.GetNewSessionAsync();

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 = session.Serialize();

// 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);
}

Pembuatan Checkpoint dengan Agen Alur Kerja

Aktifkan checkpointing agar status alur kerja dipertahankan setiap kali proses dimulai ulang.

// Create a checkpoint manager with your storage backend
var checkpointManager = new CheckpointManager(new FileCheckpointStorage("./checkpoints"));

// Create workflow agent with checkpointing enabled
AIAgent workflowAgent = workflow.AsAgent(
    id: "persistent-workflow",
    name: "Persistent Workflow Agent",
    checkpointManager: checkpointManager
);

Persyaratan

Untuk menggunakan alur kerja sebagai agen, pelaksana mulai alur kerja harus dapat menangani list[ChatMessage] sebagai input. Ini secara otomatis terpenuhi saat menggunakan ChatAgent atau AgentExecutor.

Membuat Agen Alur Kerja

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

from agent_framework import WorkflowBuilder, ChatAgent
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

# Create your chat client and agents
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())

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

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

# Build your workflow
workflow = (
    WorkflowBuilder()
    .set_start_executor(researcher)
    .add_edge(researcher, writer)
    .build()
)

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

Parameter as_agent

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

Menggunakan Agen Alur Kerja

Membuat Utas

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

# Create a new thread for the conversation
thread = workflow_agent.get_new_thread()

Eksekusi Tanpa Streaming

Untuk kasus penggunaan sederhana di mana Anda menginginkan respons lengkap:

from agent_framework import ChatMessage, Role

messages = [ChatMessage(role=Role.USER, content="Write an article about AI trends")]

response = await workflow_agent.run(messages, thread=thread)

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

Eksekusi Streaming

Untuk pembaruan real time saat alur kerja dijalankan:

messages = [ChatMessage(role=Role.USER, content="Write an article about AI trends")]

async for update in workflow_agent.run_stream(messages, thread=thread):
    # Process streaming updates from each agent in the workflow
    if update.text:
        print(update.text, end="", flush=True)

Menangani Permintaan Input Eksternal

Saat alur kerja berisi pelaksana yang meminta input eksternal (menggunakan RequestInfoExecutor), permintaan ini muncul sebagai panggilan fungsi. Agen alur kerja melacak permintaan yang tertunda dan mengharapkan respons sebelum melanjutkan:

from agent_framework import (
    FunctionCallContent,
    FunctionApprovalRequestContent,
    FunctionApprovalResponseContent,
)

async for update in workflow_agent.run_stream(messages, thread=thread):
    for content in update.contents:
        if isinstance(content, FunctionApprovalRequestContent):
            # The workflow is requesting external input
            request_id = content.id
            function_call = content.function_call

            print(f"Workflow requests input: {function_call.name}")
            print(f"Request data: {function_call.arguments}")

            # Store the request_id to provide a response later

# Check for pending requests
if workflow_agent.pending_requests:
    print(f"Pending requests: {list(workflow_agent.pending_requests.keys())}")

Memberikan Respons terhadap Permintaan yang Tertunda

Untuk melanjutkan eksekusi alur kerja setelah permintaan input eksternal:

# Create a response for the pending request
response_content = FunctionApprovalResponseContent(
    id=request_id,
    function_call=function_call,
    approved=True,
)

response_message = ChatMessage(
    role=Role.USER,
    contents=[response_content],
)

# Continue the workflow with the response
async for update in workflow_agent.run_stream([response_message], thread=thread):
    if update.text:
        print(update.text, end="", flush=True)

Contoh Lengkap

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

import asyncio
from agent_framework import (
    ChatAgent,
    ChatMessage,
    Role,
)
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework._workflows import SequentialBuilder
from azure.identity import AzureCliCredential


async def main():
    # Set up the chat client
    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())

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

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

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

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

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

    # Create a thread and run the workflow
    thread = workflow_agent.get_new_thread()
    messages = [ChatMessage(role=Role.USER, content="Write about quantum computing")]

    print("Starting workflow...")
    print("=" * 60)

    current_author = None
    async for update in workflow_agent.run_stream(messages, thread=thread):
        # 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 metode mana yang Anda gunakan:

run(): Mengembalikan yang AgentResponse berisi hasil lengkap setelah alur kerja selesai
run_stream(): Menghasilkan AgentResponseUpdate objek saat alur kerja dijalankan, memberikan pembaruan real time

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

Peristiwa Alur Kerja	Respons dari Agen
`AgentResponseUpdateEvent`	Diteruskan sebagai `AgentResponseUpdate` (streaming) atau digabungkan ke dalam `AgentResponse` (non-streaming)
`RequestInfoEvent`	Dikonversi ke `FunctionCallContent` dan `FunctionApprovalRequestContent`
Peristiwa lain	Disertakan dalam `raw_representation` untuk pengamatan

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-01-28

Bagikan melalui

Alur Kerja Microsoft Agent Framework - Menggunakan Alur Kerja sebagai Agen

Gambaran Umum

Manfaat Utama

Cara Kerjanya

Persyaratan

Membuat Agen Alur Kerja

Parameter AsAgent

Menggunakan Agen Alur Kerja

Membuat Sesi

Eksekusi Tanpa Streaming

Eksekusi Streaming

Menangani Permintaan Input Eksternal

Serialisasi dan Dimulainya Kembali Sesi

Pembuatan Checkpoint dengan Agen Alur Kerja

Persyaratan

Membuat Agen Alur Kerja

Parameter as_agent

Menggunakan Agen Alur Kerja

Membuat Utas

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: