Testamentsexekutorer

Utförare är de grundläggande byggstenarna som bearbetar meddelanden i ett arbetsflöde. De är autonoma bearbetningsenheter som tar emot inskrivna meddelanden, utför åtgärder och kan generera utdatameddelanden eller händelser.

Översikt

Varje exekutor har en unik identifikator och kan hantera särskilda meddelandetyper. Utförare kan vara:

• Anpassade logikkomponenter – bearbeta data, anropa API:er eller transformera meddelanden
• AI-agenter – använd LLM:er för att generera svar (se Agenter i arbetsflöden)

Viktigt!

Det rekommenderade sättet att definiera körmeddelandehanterare i C# är att använda [MessageHandler] attributet på metoder i en partial klass som härleds från Executor. Detta använder generering av källkod vid kompileringstid för hanteringsregistrering, vilket ger bättre prestanda, kompileringstidsverifiering och native AOT-kompatibilitet.

Grundläggande körstruktur

Körarna härleds från basklassen Executor och använder [MessageHandler]-attributet för att deklarera hanteringsmetoder. Klassen måste markeras partial för att aktivera källgenerering.

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

Du kan också skicka meddelanden manuellt utan att returnera ett värde:

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

Flera indatatyper

Hantera flera indatatyper genom att definiera flera [MessageHandler] metoder:

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

Funktionsbaserade exekverare

Skapa en exekverare från en funktion med hjälp av BindExecutor tilläggsmetoden.

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

Grundläggande körstruktur

Utförare ärver från basklassen Executor . Varje exekutor använder metoder som är dekorerade med dekoratören @handler . Hanterarna måste ha rätt typanteckningar för att kunna ange de meddelandetyper som de bearbetar.

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 exekverare

Skapa en exekutor från en funktion med hjälp av dekoratören @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())

Flera indatatyper

Hantera flera indatatyper genom att definiera flera hanterare:

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)

Explicita typparametrar

Som ett alternativ till att skriva anteckningar kan du uttryckligen ange typer via dekoratörsparametrar:

Viktigt!

När du använder explicita typparametrar måste du ange alla typer via dekoratören – du kan inte blanda explicita parametrar med typanteckningar. Parametern input krävs output och workflow_output är valfri.

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

Tillhandahåller WorkflowContext metoder för att interagera med arbetsflödet under körningen:

• send_message — skicka meddelanden till anslutna köre
• yield_output — skapa arbetsflödesutdata som returneras/strömmas till anroparen

class OutputExecutor(Executor):

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

Om en hanterare varken skickar meddelanden eller ger utdata behövs ingen typparameter:

class LogExecutor(Executor):

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

Nästa steg

kanter