作者：卢建晖 - 微软高级云技术布道师
排版：Alan Wang

引言：AI 应用开发的新范式

在企业级 AI 应用开发中，我们常常面临这样一个困境：虽然基于云的大语言模型功能强大，但数据隐私、网络延迟和成本控制等问题使得许多场景难以落地。传统的本地小模型虽然轻量，但缺乏完整的开发、评估与编排框架。

Microsoft Foundry Local 与 Agent Framework（MAF）的结合，为这一困境提供了一个优雅的解决方案。本文将带你从零到一构建一个完整的深度研究智能体工作流，覆盖从模型安全评估、工作流编排、交互式调试到性能优化的全流程。

为什么选择 Foundry Local？

Foundry Local 不仅仅是一个本地模型运行时，更是 Microsoft AI 生态向边缘端的延伸：

• 隐私优先：所有数据与推理过程均在本地完成，满足严格的合规要求

• 零延迟：无需网络往返，适用于实时交互场景

• 成本可控：避免云 API 调用费用，适用于高频调用场景

• 快速迭代：本地开发与调试，缩短反馈周期

结合 Microsoft Agent Framework，你可以像使用 Azure OpenAI 一样构建复杂的智能体应用。

示例代码：

agent = FoundryLocalClient(model_id="qwen2.5-1.5b-instruct-generic-cpu:4").as_agent(
    name="LocalAgent",
    instructions="""You are an assistant.

Your responsibilities:
- Answering questions and providing professional advice
- Helping users understand concepts
- Offering users different suggestions
""",
)

如何评估智能体？

基于 Agent Framework 的评估示例，这里提供三种互补的评估方法，并在本仓库中提供相应的实现与配置：

红队测试（安全性与稳健性）

• 目的：使用系统化的对抗提示覆盖高风险内容，测试智能体的安全边界。

• 方法：对目标智能体实施多种攻击策略，覆盖暴力、仇恨 / 不公、色情内容及自残等风险类别。

自省机制（质量验证）

• 目的：让智能体对自身输出进行二次审查，检查事实一致性、覆盖度、引用完整性与回答结构。

• 方法：在任务输出后增加“反思轮”，由智能体基于固定维度进行自我评估与改进建议，并生成修订版本。

• 此内容在示例中暂时省略。

可观测性（性能指标）

• 目的：通过指标与分布式追踪衡量端到端延迟、阶段耗时与工具调用开销。

• 方法：启用 OpenTelemetry 上报工作流执行过程与工具调用情况。

完整的开发流程：从安全到生产

第一步：红队评估 —— 确保安全基线

在将任何模型投入生产之前，安全评估都是必不可少的一步。MAF 提供开箱即用的红队测试能力，并结合 Microsoft Foundry 完成红队评估：

# 01.foundrylocal_maf_evaluation.py
from azure.ai.evaluation.red_team import AttackStrategy, RedTeam, RiskCategory
from azure.identity import AzureCliCredential
from agent_framework_foundry_local import FoundryLocalClient

credential = AzureCliCredential()
agent = FoundryLocalClient(model_id="qwen2.5-1.5b-instruct-generic-cpu:4").as_agent(
    name="LocalAgent",
    instructions="""You are an assistant.

Your responsibilities:
- Answering questions and providing professional advice
- Helping users understand concepts
- Offering users different suggestions
""",
)

def agent_callback(query: str) -> str:
    async def _run():
        return await agent.run(query)
    response = asyncio.get_event_loop().run_until_complete(_run())
    return response.text

red_team = RedTeam(
    azure_ai_project=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=credential,
    risk_categories=[
        RiskCategory.Violence,
        RiskCategory.HateUnfairness,
        RiskCategory.Sexual,
        RiskCategory.SelfHarm,
    ],
    num_objectives=2,
)

results = await red_team.scan(
    target=agent_callback,
    scan_name="Qwen2.5-1.5B-Agent",
    attack_strategies=[
        AttackStrategy.EASY,
        AttackStrategy.MODERATE,
        AttackStrategy.CharacterSpace,
        AttackStrategy.ROT13,
        AttackStrategy.UnicodeConfusable,
        AttackStrategy.CharSwap,
        AttackStrategy.Morse,
        AttackStrategy.Leetspeak,
        AttackStrategy.Url,
        AttackStrategy.Binary,
        AttackStrategy.Compose([AttackStrategy.Base64, AttackStrategy.ROT13]),
    ],
    output_path="Qwen2.5-1.5B-Redteam-Results.json",
)

评估维度：

• 风险类别：暴力、仇恨 / 不公、色情内容、自残

• 攻击策略：编码混淆、字符替换、提示注入等

• 输出分析：生成详细风险评分卡与响应样本

评估结果以 JSON 格式保存，便于追溯与持续监控。该步骤确保模型在面对恶意输入时具备稳健型。

这是运行 01.foundrylocal_maf_evaluation.py 之后的截图。你可以通过调整提示词来改进结果。

第二步：深度研究工作流程设计 —— 多轮迭代智能

深度研究的核心在于“研究—评估—再研究”的迭代循环。MAF Workflows 让这一复杂逻辑变得清晰且可维护。

关键组件：

1. 研究智能体

• 配备 search_web 工具用于实时外部信息检索

• 在每一轮生成摘要并识别知识缺口

• 累积上下文以避免重复搜索

2. 迭代控制器

• 评估当前信息完整性

• 决策：继续深入 vs 生成报告

• 防止无限循环（设置最大轮次）

3. 最终报告

• 整合所有迭代发现

• 生成带引用的结构化报告

代码实现（简化版）：

from agent_framework import WorkflowBuilder
from agent_framework_foundry_local import FoundryLocalClient

workflow_builder = WorkflowBuilder(
    name="Deep Research Workflow",
    description="Multi-agent deep research workflow with iterative web search"
)

workflow_builder.register_executor(lambda: StartExecutor(state=state), name="start_executor")
workflow_builder.register_executor(lambda: ResearchAgentExecutor(), name="research_executor")
workflow_builder.register_executor(lambda: iteration_control, name="iteration_control")
workflow_builder.register_executor(lambda: FinalReportExecutor(), name="final_report")
workflow_builder.register_executor(lambda: OutputExecutor(), name="output_executor")

workflow_builder.register_agent(
    lambda: FoundryLocalClient(model_id="qwen2.5-1.5b-instruct-generic-cpu:4").as_agent(
        name="research_agent",
        instructions="...",
        tools=search_web,
        default_options={"temperature": 0.7, "max_tokens": 4096},
    ),
    name="research_agent",
)

workflow_builder.add_edge("start_executor", "research_executor")
workflow_builder.add_edge("research_executor", "research_agent")
workflow_builder.add_edge("research_agent", "iteration_control")
workflow_builder.add_edge(
    "iteration_control",
    "research_executor",
    condition=lambda decision: decision.signal == ResearchSignal.CONTINUE,
)
workflow_builder.add_edge(
    "iteration_control",
    "final_report",
    condition=lambda decision: decision.signal == ResearchSignal.COMPLETE,
)
workflow_builder.add_edge("final_report", "final_reporter_agent")
workflow_builder.add_edge("final_reporter_agent", "output_executor")

该设计的美妙之处在于：

• 模块化：每个执行器单一职责，易于测试与替换

• 可观测性：每个节点的输入输出均可追踪

• 可扩展性：轻松添加新工具或决策逻辑

第三步：DevUI 交互式调试 —— 让工作流程可视化

传统智能体调试往往是“黑盒”体验。MAF DevUI 将整个执行过程可视化：

python 02.foundrylocal_maf_workflow_deep_research_devui.py
DevUI starts at http://localhost:8093

DevUI 提供：

• 工作流拓扑图：直观展示节点与边关系

• 分步执行：查看每个节点的输入、输出与状态

• 实时注入：动态修改输入参数测试不同场景

• 日志聚合：统一查看所有智能体日志与工具调用

调试场景示例：

• 输入：“GPT-5.3-Codex vs Anthropic Claud 4.6”

• 观察：研究智能体在 3 轮中的搜索关键词演变

• 验证：迭代控制器的决策依据是否合理

• 检查：最终报告是否覆盖所有子主题

这种交互式体验大大缩短了从发现问题到解决问题的时间。

第四步：性能评估与优化 ——.NET Aspire 集成

在生产环境中，性能是不可忽视的维度。MAF 与 .NET Aspire 的集成提供企业级可观测性。

启用遥测：

# Configure OpenTelemetry
export OTLP_ENDPOINT="http://localhost:4317"

# Workflow automatically reports
- Latency: Time consumption of each executor
- Throughput: Concurrent request processing capacity
- Tool Usage: search_web call frequency and time consumption

关键指标：

• 端到端延迟：从用户输入到最终报告的时间

• 模型推理时间：本地模型响应速度

• 工具调用开销：外部 API（如搜索）的影响

• 内存使用情况：多轮迭代中的上下文累积

优化策略：

• 使用更小模型（如 Qwen2.5-1.5B）平衡速度与质量

• 缓存常见搜索结果以减少 API 调用

• 限制迭代深度避免过度研究

• 使用流式输出提升用户体验

通过分布式追踪，你可以精确定位瓶颈并进行数据驱动的优化决策。

实用指南：快速入门

GitHub Repo : https://github.com/microsoft/Agent-Framework-Samples/blob/main/09.Cases/FoundryLocalPipeline/?wt.mc_id=3reg_webpage_reactor

环境设置

# 1. Set environment variables
export FOUNDRYLOCAL_ENDPOINT="http://localhost:8000"
export FOUNDRYLOCAL_MODEL_DEPLOYMENT_NAME="qwen2.5-1.5b-instruct-generic-cpu:4"
export SERPAPI_API_KEY="your_serpapi_key"
export AZURE_AI_PROJECT_ENDPOINT="your_azure_endpoint"
export OTLP_ENDPOINT="http://localhost:4317"

# 2. Azure authentication (for evaluation)
az login

# 3. Install dependencies (example)
pip install azure-ai-evaluation azure-ai-evaluation[redteam] agent-framework agent-framework-foundry-local

三步启动

第一步：安全评估

python 01.foundrylocal_maf_evaluation.py
View results: Qwen2.5-1.5B-Redteam-Results.json

第二步：DevUI 模式（推荐）

python 02.foundrylocal_maf_workflow_deep_research_devui.py
Open in browser: http://localhost:8093
Enter research topic, observe iteration process

第三步：CLI 模式（生产环境）

python 02.foundrylocal_maf_workflow_deep_research_devui.py --cli
Directly output final report

架构见解：从模型到智能体的演进

该案例展示了现代 AI 应用开发的三个层级：

1. 模型层（基础层）：Foundry Local 提供可靠的推理能力

2. 智能体层：ChatAgent + Tools 封装业务逻辑

3. 编排层：MAF Workflows 处理复杂流程

传统开发往往止步于模型调用，而 MAF 让你站在更高抽象层级：

• 无需手动循环与状态管理

• 自动处理工具调用与结果解析

• 内置可观测性与错误处理

这种“框架优先”方法，是企业 AI 从 POC 走向生产的关键。

用例及扩展方向

当前方案适用于：

• 需要多轮信息综合的研究任务

• 对数据隐私敏感的企业场景

• 高频调用的成本优化需求

• 离线或弱网络环境

扩展方向：

• 多智能体协作：增加专家智能体（如数据分析师、代码生成器）

• 知识库集成：结合向量数据库检索私有文档

• 人工参与决策：在关键决策点增加人工审核

• 多模态支持：处理图像、PDF 等富媒体输入

总结：本地化人工智能的无限可能

Microsoft Foundry Local + Agent Framework 的组合证明，本地小模型同样可以构建生产级智能应用。通过这个深度研究案例，我们看到：

• 安全与控制：红队评估确保模型行为符合预期

• 高效编排：工作流让复杂逻辑清晰且可维护

• 快速迭代：DevUI 提供即时反馈，缩短开发周期

• 性能透明度：Aspire 集成让优化有据可依

更重要的是，该方案是开放且可组合的。你可以：

• 集成自定义工具（数据库查询、内部 API）

• 部署到边缘设备或私有云

AI 应用的未来不仅在云端，也在云边协同的灵活架构中。Foundry Local 为企业提供了一条务实路径，使每一位开发者都能构建既强大又可控的智能体系统。

相关资源

• Microsoft Agent Framework GitHub

• Microsoft Agent Framework 示例 GitHub

• Foundry Local 官方文档