⏩ 使用 GitHub 模型 (.NET) 的顺序代理工作流程

📋 高级顺序处理教程

本笔记本演示了使用 Microsoft Agent Framework for .NET 和 GitHub 模型的顺序工作流模式。您将学习如何构建复杂的分步处理管道，其中代理按特定顺序执行，每个阶段都基于前一阶段的结果。

🎯 学习目标

🔄 顺序处理架构

  • 线性工作流程设计：创建具有明确依赖性的分步处理管道
  • 状态管理：维护跨连续工作流程阶段的上下文和数据流
  • GitHub 模型集成：在多阶段 .NET 工作流程中利用 GitHub 的 AI 模型
  • 企业管道模式：构建生产就绪的顺序处理系统

🏗️ 高级序列模式

  • 阶段控制处理：在工作流程阶段之间实施验证检查点
  • 上下文保存：在所有阶段维护状态和积累的知识
  • 错误传播：在顺序处理链中优雅地处理故障
  • 性能优化：以最小的开销实现高效的顺序执行

🏢 企业顺序应用程序

  • 文档处理管道：多阶段文档分析、转换和验证
  • 质量保证工作流程：顺序审查、验证和批准流程
  • 内容制作流程：研究→写作→编辑→评论→出版
  • 业务流程自动化：具有明确阶段依赖性的多步骤业务工作流程

⚙️ 先决条件和设置

📦 所需的 NuGet 包

.NET 顺序工作流程的基本包：

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- Core AI Framework -->
<PackageReference Include="Microsoft.Extensions.AI" Version="9.9.0" />

<!-- Client Model Abstractions -->
<PackageReference Include="System.ClientModel" Version="1.6.1.0" />

<!-- Azure Identity and Async LINQ Support -->
<PackageReference Include="Azure.Identity" Version="1.15.0" />
<PackageReference Include="System.Linq.Async" Version="6.0.3" />

<!-- Local Agent Framework References -->
<!-- Microsoft.Agents.AI.dll - Core agent abstractions -->
<!-- Microsoft.Agents.AI.OpenAI.dll - GitHub Models integration -->

🔑 GitHub 模型配置

环境设置（.env 文件）：

1
2
3
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_ENDPOINT=https://models.inference.ai.azure.com
GITHUB_MODEL_ID=gpt-4o-mini

配置管理：

1
2
3
4
5
// Load environment variables securely
Env.Load("../../../.env");
var githubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN");
var githubEndpoint = Environment.GetEnvironmentVariable("GITHUB_ENDPOINT");
var modelId = Environment.GetEnvironmentVariable("GITHUB_MODEL_ID");

🏗️ 顺序工作流程架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
graph TD
    A[Initial Input] --> B[Stage 1: Analysis Agent]
    B --> C[Checkpoint 1]
    C --> D[Stage 2: Processing Agent]
    D --> E[Checkpoint 2]
    E --> F[Stage 3: Validation Agent]
    F --> G[Final Output]
    
    H[State Context] --> B
    H --> D
    H --> F
    
    I[GitHub Models API] --> B
    I --> D
    I --> F

关键组件：

  • 顺序代理：每个处理阶段的专用代理
  • 状态上下文：维护跨阶段积累的数据和决策
  • 检查点：阶段之间的验证点，以确保质量和一致性
  • GitHub 模型客户端：跨所有工作流程阶段一致的 AI 模型访问

🎨 顺序工作流设计模式

📝 文档处理管道

1
Raw Document → Content Extraction → Analysis → Validation → Structured Output

🎯 内容创建工作流程

1
Brief/Requirements → Research → Content Creation → Review → Final Polish

🔍 质量保证管道

1
Initial Review → Technical Validation → Compliance Check → Final Approval

💼 商业智能工作流程

1
Data Collection → Processing → Analysis → Report Generation → Distribution

🏢 企业连续效益

🎯 可靠性和质量

  • 确定性处理：通过结构化阶段获得一致、可重复的结果
  • 质量门：验证检查点确保每个阶段的质量
  • 错误隔离：一个阶段中的问题不会传播到后续阶段
  • 审计跟踪：完整跟踪每个阶段的决策和转变

📈 可扩展性和性能

  • 模块化设计：每个阶段都可以独立优化
  • 资源管理：AI模型资源跨阶段高效分配
  • 状态优化：阶段之间的状态转移最少，以获得最佳性能
  • 并行阶段组：多个顺序工作流程可以并行运行

🔒 安全与合规性

  • 阶段级安全：不同处理阶段的不同安全策略
  • 数据验证：确保每个检查点的数据完整性和合规性
  • 访问控制：不同工作流程阶段的精细权限
  • 监管合规性：通过结构化处理满足监管要求

📊 监控与分析

  • 阶段级指标：每个工作流程阶段的性能监控
  • 瓶颈识别：识别并优化缓慢阶段
  • 质量指标：跟踪每个阶段的质量和成功率
  • 流程优化：基于阶段级分析的持续改进

让我们构建强大的顺序 AI 处理管道！ 🚀

💻 运行代码

完整的实现可在 02.dotnet-agent-framework-workflow-ghmodel-sequential.cs 中找到。该文件演示了三阶段家具分析工作流程：

  1. 第一阶段 - 销售代理：分析家具图片并提供购买建议
  2. 第 2 阶段 - 价格代理：提供详细的定价细目和预算选项
  3. 第3阶段-报价代理：生成Markdown格式的专业报价文档

🏗️ 工作流程架构

1
Image Input → Sales Analysis → Price Estimation → Quote Generation → Final Output

Each agent:

  • Receives the output from the previous stage as context
  • Builds upon previous analysis with specialized expertise
  • Maintains workflow continuity through state management

🚀 Running the Example

Prerequisites:

  • Place a furniture image at ../imgs/home.png (or update the imgPath variable)
  • Configure your .env file with GitHub Models credentials
1
2
3
4
5
# Make the script executable (Unix/Linux/macOS)
chmod +x 02.dotnet-agent-framework-workflow-ghmodel-sequential.cs

# Run the sequential workflow
./02.dotnet-agent-framework-workflow-ghmodel-sequential.cs

Or on Windows:

1
dotnet run 02.dotnet-agent-framework-workflow-ghmodel-sequential.cs

📝 预期输出

工作流程将：

  1. 销售代理：从图像中识别家具物品并提供建议
  2. 价格代理：添加详细的定价分析，包括预算等级和购物建议
  3. 报价代理：综合所有信息生成格式化的报价文档

最终输出将是基于图像分析的全面、专业的家具报价。

🔧 自定义选项

修改代理行为：

1
2
// Adjust agent instructions to change their focus
const string SalesAgentInstructions = "Your custom instructions...";

更改顺序流程：

1
2
3
4
5
6
// Add or reorder workflow stages
var workflow = new WorkflowBuilder(salesagent)
    .AddEdge(salesagent, priceagent)
    .AddEdge(priceagent, quoteagent)
    .AddEdge(quoteagent, newAgent)  // Add another stage
    .Build();

使用不同的输入：

1
2
3
4
// Process text instead of images
ChatMessage userMessage = new ChatMessage(ChatRole.User, [
    new TextContent("Analyze pricing for a modern living room set")
]);

🎯 实际应用

这种顺序模式非常适合：

  • 电子商务：产品分析→定价→报价生成
  • 房地产：房产分析 → 估值 → 清单创建
  • 保险：索赔分析→评估→报价生成
  • 内容创作：研究→写作→编辑→出版

🔍 理解状态流

序列中的每个代理接收：

  • 原始输入：初始用户消息（图像+文本）
  • 先前的代理输出：对话历史记录中所有先前的代理响应
  • 累积上下文：整个工作流程中维护的完整状态

这使得复杂的多阶段处理成为可能，其中每个代理都建立在所有先前阶段的综合上下文之上。