Yürütücüler

Yürütücüler, bir iş akışındaki iletileri işleyen temel yapı taşlarıdır. Bunlar, yazılan iletileri alan, işlemler gerçekleştiren ve çıkış iletileri veya olaylar üretebilen otonom işlem birimleridir.

Genel Bakış

Her yürütücü benzersiz bir tanımlayıcıya sahiptir ve belirli ileti türlerini işleyebilir. Yürütücüler şu olabilir:

• Özel mantıksal bileşenler : verileri işleme, API'leri çağırma veya iletileri dönüştürme
• Yapay zeka aracıları — yanıt oluşturmak için LLM'leri kullanın (bkz. İş Akışlarında Aracılar)

Önemli

C# dilinde yürütücü mesaj işleyicilerini tanımlamanın önerilen yolu, Executor sınıfından türetilmiş bir partial sınıfındaki yöntemlerde [MessageHandler] özniteliğini kullanmaktır. Bu, işleyici kaydı için derleme zamanı kaynak oluşturma sayesinde daha iyi performans, derleme zamanı doğrulaması ve Özgün AOT uyumluluğu sağlar.

Temel Yürütücü Yapısı

Yürütücüler Executor temel sınıfından türetilir ve [MessageHandler] özniteliğini işleyici yöntemlerini bildirmek için kullanır. Kaynak oluşturmayı etkinleştirmek için sınıfı işaretlenmelidir 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
    }
}

Ayrıca, bir değer döndürmeden iletileri el ile de gönderebilirsiniz:

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

Birden Çok Giriş Türü

Birden çok yöntem tanımlayarak birden çok [MessageHandler] giriş türünü işleyebilir:

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 Yürütücüleri

Uzantı yöntemini kullanarak BindExecutor bir işlevden yürütücü oluşturun:

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

Temel Yürütücü Yapısı

Yürütücüler Executor temel sınıfından devralır. Her bir yürütücü, @handler dekoratör ile süslenmiş yöntemleri kullanır. İşleyiciler, işledikleri ileti türlerini belirtmek için uygun tür açıklamalarına sahip olmalıdır.

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 Tabanlı Yürütücüler

@executor dekoratörünü kullanarak bir fonksiyondan yürütücü oluşturun.

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

Birden Çok Giriş Türü

Birden çok işleyici tanımlayarak birden çok giriş türünü işleyebilir:

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)

Açık Tür Parametreleri

Tür ek açıklamalarına alternatif olarak, türleri dekoratör parametreleri aracılığıyla açıkça belirtebilirsiniz:

Önemli

Açık tür parametrelerini kullanırken, dekoratör aracılığıyla tüm türleri belirtmeniz gerekir; açık parametreleri tür ek açıklamalarıyla karıştıramazsınız. input parametresi gereklidir output ve workflow_output isteğe bağlıdır.

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 Nesnesi

, WorkflowContext yürütme sırasında iş akışıyla etkileşime yönelik yöntemler sağlar:

• send_message — bağlı yürütücülere ileti gönderme
• yield_output — çağırana döndürülen/akışa alınan iş akışı çıkışlarını üretin

class OutputExecutor(Executor):

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

İşleyici ileti göndermez veya çıkış vermezse, tür parametresi gerekmez:

class LogExecutor(Executor):

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

Sonraki Adımlar

Kenarlar