工作流生成器和执行

工作流将执行器和边缘关联到定向图中,并管理执行。 它协调执行程序调用、消息路由和事件流式处理。

生成工作流

工作流是使用 WorkflowBuilder 类构造的,该类提供用于定义工作流结构的 Fluent API:

using Microsoft.Agents.AI.Workflows;

var processor = new DataProcessor();
var validator = new Validator();
var formatter = new Formatter();

// Build workflow
WorkflowBuilder builder = new(processor); // Set starting executor
builder.AddEdge(processor, validator);
builder.AddEdge(validator, formatter);
var workflow = builder.Build();

工作流是使用WorkflowBuilder类构造的。

from agent_framework import WorkflowBuilder

processor = DataProcessor()
validator = Validator()
formatter = Formatter()

# Build workflow
builder = WorkflowBuilder(start_executor=processor)
builder.add_edge(processor, validator)
builder.add_edge(validator, formatter)
workflow = builder.build()

在生成时验证期间,处理程序可以使用裸容器批注,如 list、dict、tuple 或 Sequence。 它可以接受使用相应参数化容器的输出,例如 list[str]。

该 workflow 包提供基于图形的执行模型,执行程序通过边缘进行连接。

  • 执行程序 - 接收输入和生成输出的处理单元
  • Edge - 将一个执行程序的输出连接到另一个执行程序的输入
  • 生成器 - 通过定义执行器和边缘来构造工作流
  • 运行 - 使用给定输入执行工作流

此函数生成文本处理工作流,而无需模型或凭据:

import (
    "slices"
    "strings"

    "github.com/microsoft/agent-framework-go/workflow"
)

func buildWorkflow() (*workflow.Workflow, error) {
    uppercase := workflow.NewExecutor(
        "UppercaseExecutor", strings.ToUpper,
    ).Bind()

    reverse := workflow.NewExecutor(
        "ReverseExecutor", func(input string) string {
            runes := []rune(input)
            slices.Reverse(runes)
            return string(runes)
        },
    ).Bind()

    return workflow.NewBuilder(uppercase).
        AddEdge(uppercase, reverse).
        WithOutputFrom(reverse).
        Build()
}

WithOutputFrom(reverse) 以工作流输出的形式公开反向执行程序的结果。 无论输出指定如何,Edge 仍会将大写结果传递给反向执行器。

将 buildWorkflow 返回的工作流传递给下面的任一执行函数。 对于输入 "Hello, World!",两者都打印 Workflow output: !DLROW ,OLLEH。

工作流执行

工作流支持流式处理和非流式处理执行模式:

using Microsoft.Agents.AI.Workflows;

// Streaming execution — get events as they happen
StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, inputMessage);
await foreach (WorkflowEvent evt in run.WatchStreamAsync())
{
    if (evt is ExecutorCompletedEvent executorComplete)
    {
        Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
    }

    if (evt is WorkflowOutputEvent outputEvt)
    {
        Console.WriteLine($"Workflow completed: {outputEvt.Data}");
    }
}

// Non-streaming execution — wait for completion
Run result = await InProcessExecution.RunAsync(workflow, inputMessage);
foreach (WorkflowEvent evt in result.NewEvents)
{
    if (evt is WorkflowOutputEvent outputEvt)
    {
        Console.WriteLine($"Final result: {outputEvt.Data}");
    }
}
# Streaming execution — get events as they happen
async for event in workflow.run(input_message, stream=True):
    if event.type == "output":
        print(f"Workflow completed: {event.data}")

# Non-streaming execution — wait for completion
events = await workflow.run(input_message)
print(f"Final result: {events.get_outputs()}")

当你希望在事件发生时即时获取事件,请使用RunStreaming。 传递调用方上下文,以便将取消信号传递到工作流,在迭代结束后检查其错误,并在完成时关闭运行:

import (
    "context"
    "errors"
    "fmt"

    "github.com/microsoft/agent-framework-go/workflow"
    "github.com/microsoft/agent-framework-go/workflow/inproc"
)

func runStreaming(
    ctx context.Context, wf *workflow.Workflow,
) (err error) {
    stream, err := inproc.Default.RunStreaming(ctx, wf, "Hello, World!")
    if err != nil {
        return err
    }
    defer func() {
        err = errors.Join(err, stream.Close(context.WithoutCancel(ctx)))
    }()

    for evt, streamErr := range stream.WatchStream(ctx) {
        if streamErr != nil {
            return streamErr
        }
        switch event := evt.(type) {
        case workflow.OutputEvent:
            fmt.Printf("Workflow output: %v\n", event.Output)
        case workflow.ErrorEvent:
            return event.Error
        case workflow.ExecutorFailedEvent:
            return fmt.Errorf("executor %q failed: %w",
                event.ExecutorID, event.Error)
        }
    }
    return ctx.Err()
}

外部请求尚未完成时,WatchStream会等待。 对于需要人工输入的工作流,请处理请求事件或使用WatchUntilHalt在暂停时返回。 请参阅 工作流事件。

使用Run前进到下一个暂停点,然后检查收集的事件。 运行在等待外部输入时可能会暂停,而不仅仅是在其工作完成时:

import (
    "context"
    "errors"
    "fmt"

    "github.com/microsoft/agent-framework-go/workflow"
    "github.com/microsoft/agent-framework-go/workflow/inproc"
)

func runToHalt(
    ctx context.Context, wf *workflow.Workflow,
) (err error) {
    run, err := inproc.Default.Run(ctx, wf, "Hello, World!")
    if err != nil {
        return err
    }
    defer func() {
        err = errors.Join(err, run.Close(context.WithoutCancel(ctx)))
    }()

    for evt := range run.NewEvents() {
        switch event := evt.(type) {
        case workflow.OutputEvent:
            fmt.Printf("Workflow output: %v\n", event.Output)
        case workflow.ErrorEvent:
            return event.Error
        case workflow.ExecutorFailedEvent:
            return fmt.Errorf("executor %q failed: %w",
                event.ExecutorID, event.Error)
        }
    }

    for evt := range run.OutgoingEvents() {
        if evt, ok := evt.(workflow.ExecutorCompletedEvent); ok {
            fmt.Printf("%s: %v\n", evt.ExecutorID, evt.Result)
        }
    }
    return ctx.Err()
}

每次调用NewEvents()时,它都会推进其书签。 第二个循环使用OutgoingEvents()重播累积的执行器事件,而不是尝试使用NewEvents()再次消费这些事件。

这些函数在观察到结果后关闭其运行。 如果你的应用程序需要发送更多消息或在暂停后恢复运行,请保持该运行打开。

请参阅工作流事件,了解完整的消费者、输出分类和暂停语义。

Tip

有关完整的可运行示例,请参阅 工作流示例 。

工作流验证

工作流生成器在执行之前验证图。 确切检查取决于 SDK 和可用的类型元数据:

  • 类型兼容性:检查连接的执行程序之间声明的消息协议,其中提供了元数据。
  • 图连接性:检查已注册的执行程序是否可从启动执行程序访问。
  • 执行程序绑定:检查是否存在所需的执行程序注册。
  • 边验证:根据构建器的规则检查无效连接和重复边。

Go Build() 拒绝未解析的绑定、无法访问的已注册执行器、重复的无条件边,以及不兼容的已声明消息类型。 条件路由和动态协议仍需要运行时测试。

类型验证可以创建临时执行器实例以检查其协议。 如果无法检查工厂或协议,则会跳过该兼容性检查。 成功的构建并不能保证执行器创建或每次消息传递在运行时都成功。 处理运行创建、事件迭代和工作流失败事件中的错误。

BuildWithOptions(workflow.BuildOptions{DisableOrphanValidation: true}) 仅禁用孤立执行程序检查。 其他验证仍在运行。

执行模型:超级步骤

该框架使用经过修改的 Pregel 执行模型 , 这是一种批量同步并行 (BSP) 方法,采用基于超步骤的处理。

Supersteps 的工作原理

工作流执行被组织为离散的超级步。 每个超级步骤:

  1. 从上一个超级步收集所有待处理消息
  2. 基于边缘定义将消息路由到目标执行程序
  3. 在超级步骤中并发运行所有目标执行程序
  4. 等待所有执行程序完成后再推进(同步屏障)
  5. 将执行程序发出的所有新消息排队,以用于下一个超级步
Superstep N:
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Collect All    │───▶│  Route Messages │───▶│  Execute All    │
│  Pending        │    │  Based on Type  │    │  Target         │
│  Messages       │    │  & Conditions   │    │  Executors      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                       │
                                                       │ (barrier: wait for all)
┌─────────────────┐    ┌─────────────────┐             │
│  Start Next     │◀───│  Emit Events &  │◀────────────┘
│  Superstep      │    │  New Messages   │
└─────────────────┘    └─────────────────┘

同步屏障

最重要的特征是超级步骤之间的同步屏障。 已触发的执行器可以在一个超步内并发运行,但工作流在它们完成之前不会前进到下一个超步。

这会影响扇出模式:如果扇出到多个路径(一个具有执行程序链,另一个具有单个长时间运行的执行程序),则链式路径在长时间运行的执行程序完成之前无法前进。

为什么选择超级步?

BSP 模型提供重要保证:

  • 定义的步骤边界:在超级步骤期间发出的消息将排队等待后续处理。
  • 检查点边界:启用检查点的工作流在超级步骤边界处保存执行状态。
  • 缓冲状态更新:排队的工作流状态更改在超级步骤之间提交。

这些保证并不规定同一超步内并发执行器之间的执行顺序或事件顺序。 同步对应用程序拥有的共享状态的访问,而不是假设超级步骤屏障会阻止所有竞态。

使用 Superstep 模型

如果需要真正独立且互不阻塞的并行路径,可以将顺序步骤合并到单个执行程序中。 不要将step1 → step2 → step3逻辑链接起来,而是将其合并到一个单一的执行器中。 然后,两个并行路径在单个超级步骤中执行。

后续步骤

相关主题: