다음을 통해 공유

실행자

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

개요

각 실행기는 고유 식별자를 가지며 특정 메시지 유형을 처리할 수 있습니다. 실행기는 다음과 같은 형식일 수 있습니다.

  • 사용자 지정 논리 구성 요소 - 데이터 처리, API 호출 또는 메시지 변환
  • AI 에이전트 - LLM을 사용하여 응답 생성( 워크플로의 에이전트 참조)

중요합니다

C#에서 실행기 메시지 처리기를 정의하는 권장 방법은 Executor를 상속받는 클래스의 partial 메서드에 [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);
    }
}

기능 기반 실행기

확장 메서드를 사용하여 함수에서 실행기를 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())

함수 기반 실행기

데코레이터 @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...")

다음 단계:

엣지

  • Last updated on