Pelaksana

Pelaksana adalah blok penyusun mendasar yang memproses pesan dalam alur kerja. Mereka adalah unit pemrosesan otonom yang menerima pesan yang ditik, melakukan operasi, dan dapat menghasilkan pesan output atau peristiwa.

Gambaran Umum

Setiap pelaksana memiliki pengidentifikasi unik dan dapat menangani jenis pesan tertentu. Pelaksana dapat berupa:

• Komponen logika kustom — memproses data, memanggil API, atau mengubah pesan
• Agen AI — gunakan LLM untuk menghasilkan respons (lihat Agen dalam Alur Kerja)

Penting

Cara yang disarankan untuk menentukan handler pesan eksekutor di C# adalah dengan menggunakan [MessageHandler] atribut pada metode dalam partial kelas yang berasal dari Executor. Ini menggunakan pembuatan sumber waktu kompilasi untuk pendaftaran handler, memberikan performa yang lebih baik, validasi waktu kompilasi, dan kompatibilitas AOT Asli.

Struktur Pelaksana Dasar

Eksekutor berasal dari kelas dasar Executor dan menggunakan atribut [MessageHandler] untuk mendeklarasi metode handler. Kelas harus ditandai partial untuk mengaktifkan pembuatan sumber.

using Microsoft.Agents.AI.Workflows;

internal sealed partial class UppercaseExecutor() : Executor("UppercaseExecutor")
{
    [MessageHandler]
    private ValueTask<string> HandleAsync(string message, IWorkflowContext context)
    {
        string result = message.ToUpperInvariant();
        return ValueTask.FromResult(result); // Return value is automatically sent to connected executors
    }
}

Anda juga dapat mengirim pesan secara manual tanpa mengembalikan nilai:

internal sealed partial class UppercaseExecutor() : Executor("UppercaseExecutor")
{
    [MessageHandler]
    private async ValueTask HandleAsync(string message, IWorkflowContext context)
    {
        string result = message.ToUpperInvariant();
        await context.SendMessageAsync(result); // Manually send messages to connected executors
    }
}

Beberapa Jenis Input

Tangani beberapa jenis input dengan mendefinisikan beberapa [MessageHandler] metode:

internal sealed partial class SampleExecutor() : Executor("SampleExecutor")
{
    [MessageHandler]
    private ValueTask<string> HandleStringAsync(string message, IWorkflowContext context)
    {
        return ValueTask.FromResult(message.ToUpperInvariant());
    }

    [MessageHandler]
    private ValueTask<int> HandleIntAsync(int message, IWorkflowContext context)
    {
        return ValueTask.FromResult(message * 2);
    }
}

Eksekutor Berbasis Fungsi

Buat pelaksana dari fungsi menggunakan BindExecutor metode ekstensi:

Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
var uppercase = uppercaseFunc.BindExecutor("UppercaseExecutor");

Struktur Pelaksana Dasar

Eksekutor mewarisi dari kelas dasar Executor. Setiap pelaksana menggunakan metode yang dihiasi dengan @handler dekorator. Pengendali harus memiliki anotasi tipe yang tepat untuk menentukan jenis pesan yang diproses.

from agent_framework import (
    Executor,
    WorkflowContext,
    handler,
)

class UpperCase(Executor):

    @handler
    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
        """Convert the input to uppercase and forward it to the next node."""
        await ctx.send_message(text.upper())

Eksekutor Berbasis Fungsi

Buat eksekutor dari fungsi menggunakan dekorator @executor:

from agent_framework import (
    WorkflowContext,
    executor,
)

@executor(id="upper_case_executor")
async def upper_case(text: str, ctx: WorkflowContext[str]) -> None:
    """Convert the input to uppercase and forward it to the next node."""
    await ctx.send_message(text.upper())

Beberapa Jenis Input

Tangani beberapa jenis input dengan menentukan beberapa handler:

class SampleExecutor(Executor):

    @handler
    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
        await ctx.send_message(text.upper())

    @handler
    async def double_integer(self, number: int, ctx: WorkflowContext[int]) -> None:
        await ctx.send_message(number * 2)

Parameter Jenis Eksplisit

Sebagai alternatif untuk mengetik anotasi, Anda dapat menentukan jenis secara eksplisit melalui parameter dekorator:

Penting

Saat menggunakan parameter jenis eksplisit, Anda harus menentukan semua jenis melalui dekorator — Anda tidak dapat mencampur parameter eksplisit dengan anotasi jenis. Parameter input diperlukan; output dan workflow_output bersifat opsional.

class ExplicitTypesExecutor(Executor):

    @handler(input=str, output=str)
    async def to_upper_case(self, text, ctx) -> None:
        await ctx.send_message(text.upper())

    @handler(input=str | int, output=str)
    async def handle_mixed(self, message, ctx) -> None:
        await ctx.send_message(str(message).upper())

    @handler(input=str, output=int, workflow_output=bool)
    async def process_with_workflow_output(self, message, ctx) -> None:
        await ctx.send_message(len(message))
        await ctx.yield_output(True)

Objek WorkflowContext

WorkflowContext menyediakan metode-metode untuk berinteraksi dengan alur kerja selama pelaksanaannya.

• send_message — mengirim pesan ke pelaksana yang terhubung
• yield_output — menghasilkan output alur kerja yang dikembalikan/dialirkan ke pemanggil

class OutputExecutor(Executor):

    @handler
    async def handle(self, message: str, ctx: WorkflowContext[Never, str]) -> None:
        await ctx.yield_output("Hello, World!")

Jika handler tidak mengirim pesan atau menghasilkan output, parameter jenis tidak diperlukan:

class LogExecutor(Executor):

    @handler
    async def handle(self, message: str, ctx: WorkflowContext) -> None:
        print("Doing some work...")

Langkah selanjutnya

Tepi