Microsoft Agent Framework Workflows – Kernkonzepte – Executors

Executors erben von der Executor<TInput, TOutput> Basisklasse. Jeder Executor verfügt über einen eindeutigen Bezeichner und kann bestimmte Nachrichtentypen verarbeiten.

Grundlegende Executorstruktur

using Microsoft.Agents.AI.Workflows;
using Microsoft.Agents.AI.Workflows.Reflection;

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

Es ist möglich, Nachrichten manuell zu senden, ohne einen Wert zurückzugeben:

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

Es ist auch möglich, mehrere Eingabetypen zu verarbeiten, indem die ConfigureRoutes Methode überschrieben wird:

internal sealed class SampleExecutor() : Executor("SampleExecutor")
{
    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
    {
        return routeBuilder
            .AddHandler<string>(this.HandleStringAsync)
            .AddHandler<int>(this.HandleIntAsync);
    }

    /// <summary>
    /// Converts input string to uppercase
    /// </summary>
    public async ValueTask<string> HandleStringAsync(string message, IWorkflowContext context)
    {
        string result = message.ToUpperInvariant();
        return result;
    }

    /// <summary>
    /// Doubles the input integer
    /// </summary>
    public async ValueTask<int> HandleIntAsync(int message, IWorkflowContext context)
    {
        int result = message * 2;
        return result;
    }
}

Es ist auch möglich, einen Executor aus einer Funktion mithilfe der BindExecutor Erweiterungsmethode zu erstellen:

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

Executors erben von der Executor Basisklasse. Jeder Executor verfügt über einen eindeutigen Bezeichner und kann bestimmte Nachrichtentypen mit Methoden verarbeiten, die mit dem @handler Dekorator versehen sind. Handler müssen die richtige Annotation haben, um den Typ der Nachrichten anzugeben, die sie verarbeiten können.

Grundlegende Executorstruktur

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.

        Note: The WorkflowContext is parameterized with the type this handler will
        emit. Here WorkflowContext[str] means downstream nodes should expect str.
        """
        await ctx.send_message(text.upper())

Es ist möglich, einen Executor aus einer Funktion mithilfe des @executor Dekorators zu erstellen:

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.

    Note: The WorkflowContext is parameterized with the type this handler will
    emit. Here WorkflowContext[str] means downstream nodes should expect str.
    """
    await ctx.send_message(text.upper())

Es ist auch möglich, mehrere Eingabetypen zu verarbeiten, indem mehrere Handler definiert werden:

class SampleExecutor(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.

        Note: The WorkflowContext is parameterized with the type this handler will
        emit. Here WorkflowContext[str] means downstream nodes should expect str.
        """
        await ctx.send_message(text.upper())

    @handler
    async def double_integer(self, number: int, ctx: WorkflowContext[int]) -> None:
        """Double the input integer and forward it to the next node.

        Note: The WorkflowContext is parameterized with the type this handler will
        emit. Here WorkflowContext[int] means downstream nodes should expect int.
        """
        await ctx.send_message(number * 2)

Das WorkflowContext Objekt

Das WorkflowContext Objekt stellt Methoden für die Interaktion mit dem Workflow während der Ausführung bereit. Der WorkflowContext Parameter wird mit dem Typ der Vom Handler ausgegebenen Meldungen und dem Ausgabetyp parametrisiert, der zurückgegeben werden kann.

Die am häufigsten verwendete Methode ist send_message, mit der der Handler Nachrichten an verbundene Executoren senden kann.

from agent_framework import WorkflowContext

class SomeHandler(Executor):

    @handler
    async def some_handler(message: str, ctx: WorkflowContext[str]) -> None:
        await ctx.send_message("Hello, World!")

Ein Handler kann yield_output verwenden, um Ausgaben zu erzeugen, die als Workflow-Ausgabe betrachtet werden, und als Ausgabeereignis an den Aufrufer zurückgegeben/gestreamt werden.

from agent_framework import WorkflowContext

class SomeHandler(Executor):

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

Wenn ein Handler weder Nachrichten sendet noch Ausgaben liefert, ist kein Typparameter erforderlich für WorkflowContext:

from agent_framework import WorkflowContext

class SomeHandler(Executor):

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