Microsoft 에이전트 프레임워크 워크플로 핵심 개념 - 실행기

이 문서에서는 Microsoft 에이전트 프레임워크 워크플로 시스템의 실행기 구성 요소를 자세히 살펴봅니다.

개요

실행기는 워크플로에서 메시지를 처리하는 기본 구성 요소입니다. 형식화된 메시지를 수신하고 작업을 수행하며 출력 메시지 또는 이벤트를 생성할 수 있는 자율 처리 단위입니다.

실행기는 Executor<TInput, TOutput> 기본 클래스를 상속합니다. 각 실행기는 고유 식별자를 가지며 특정 메시지 유형을 처리할 수 있습니다.

기본 실행기 구조

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

값을 반환하지 않고 메시지를 수동으로 보낼 수 있습니다.

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

메서드를 재정의하여 여러 입력 형식을 처리할 수도 있습니다 ConfigureRoutes .

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

확장 메서드를 사용하여 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.

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

데코레이터를 사용하여 @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.

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

여러 처리기를 정의하여 여러 입력 형식을 처리할 수도 있습니다.

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)

WorkflowContext 개체

개체는 WorkflowContext 실행 중에 처리기가 워크플로와 상호 작용할 수 있는 메서드를 제공합니다. 처리 WorkflowContext 기가 내보낼 메시지의 형식과 생성할 수 있는 출력 형식으로 매개 변수화됩니다.

가장 일반적으로 사용되는 메서드는 send_message처리기가 연결된 실행기에 메시지를 보낼 수 있도록 하는 메서드입니다.

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!")

처리기는 워크플로 출력으로 간주되고 출력 이벤트로 호출자에게 반환/스트리밍되는 출력을 생성하는 데 사용할 yield_output 수 있습니다.

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!")

처리기가 메시지를 보내거나 출력을 생성하지 않는 경우 다음을 위한 WorkflowContext형식 매개 변수가 필요하지 않습니다.

from agent_framework import WorkflowContext

class SomeHandler(Executor):

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

다음 단계

• 워크플로에서 실행기가 연결되는 방법을 이해하려면 Edge에 대해 알아봅니다.