執行人

執行程式是在工作流程中處理訊息的基本建置區塊。 它們是自主處理單元，可接收類型化訊息、執行作業，並可產生輸出訊息或事件。

概觀

每個執行器都有一個唯一的標識符，可以處理特定的訊息類型。 遺囑執行人可以是：

• 自訂邏輯元件 — 處理資料、呼叫 API 或轉換訊息
• AI 代理 — 使用大型語言模型（LLMs）來產生回應（參見 工作流程中的代理）

這很重要

在 C# 中定義執行器訊息處理器的建議方法是在一個由 Executor 衍生的類別的方法上使用 [MessageHandler] 屬性。 此系統使用編譯時的原始碼生成進行處理程序註冊，提供更佳的效能、編譯時驗證及 AOT 原生相容。

基本執行器結構

執行程序源自 Executor 基底類別，並使用 屬性 [MessageHandler] 來宣告處理器方法。 類別必須被標記 partial 以啟用原始碼產生。

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

你也可以手動發送訊息而不回傳一個值：

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

多重輸入類型

透過定義多種 [MessageHandler] 方法來處理多種輸入類型：

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

Function-Based 執行器

使用 BindExecutor 擴充方法從函式建立執行器：

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

基本執行器結構

執行程式繼承自 Executor 基類。 每個執行者都使用由 @handler 修飾器修飾的方法。 處理器必須具備適當的型別註解，以指定其所處理的訊息類型。

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())

Function-Based 執行器

使用 @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())

多重輸入類型

處理多種類型的輸入可透過定義多個處理常式來實現。

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)

明確型別參數

作為類型註解的替代方案，你可以透過裝飾器參數明確指定類型：

這很重要

使用明確型別參數時，必須透過裝飾器指定 所有 型別——不能將明確參數與型別註解混用。 input該參數為必備;output且workflow_output為可選。

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)

WorkflowContext 物件

在執行期間，WorkflowContext 提供與工作流程互動的方法：

• send_message — 向連接的執行者發送訊息
• yield_output — 產生回傳/串流給呼叫者的工作流程輸出

class OutputExecutor(Executor):

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

如果處理器既不發送訊息也不輸出，則不需要類型參數：

class LogExecutor(Executor):

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

後續步驟

邊緣