目录阶段一创建 站在 GitHub Models 的肩膀上阶段二测试与调试 DevUI阶段三交付与交互 AG-UIAG-UI 支持的功能实现示例阶段四性能追踪 OpenTelemetry 快速配置 可视化选项架构概览总结 构建你的“效率闭环”最终思考资源作者卢建晖 - 微软高级云技术布道师排版Alan Wang在 Agentic AI 爆发式发展的时代我们追求的早已不只是“更强大的模型”——而是一次真正能让开发者睡个好觉的开发体验。在本地构建 Agent 的过程中我们长期面临三大核心挑战黑盒式执行我的 Agent 到底在想什么为什么卡住不动调试太难了交互孤岛Agent 已经写好了但我要如何快速给业务方 / 客户演示一个“好看又能用”的界面产品化太难了性能盲区到底消耗了多少 Token延迟出在哪里优化太难了今天我将通过 Microsoft Agent Framework Samples 中一个经典示例 —— GHModel.AI带你拆解一套真正解决这些痛点的“黄金三角”开发体系DevUI、AG-UI与OpenTelemetry。让我们一起看看这套强大组合如何打通 Agent 本地开发的完整生命周期。GHModel.AIhttps://github.com/microsoft/Agent-Framework-Samples/tree/main/09.Cases/GHModel.AI/?wt.mc_id3reg_webpage_reactor阶段一创建 站在 GitHub Models 的肩膀上在GHModel.AI这个案例中我们首先要解决的是 Agent 的「大脑」问题。传统的本地开发往往受限于算力不足或者被昂贵的 API Key 成本所束缚。而这个案例非常巧妙地借助了 GitHub Models。作为一名技术布道者我必须强烈推荐这套组合零门槛接入直接使用 GitHub 账号即可调用 GPT-4o、Llama 3 等前沿模型无需复杂的 Azure 配置也无需绑定信用卡。统一 SDK 抽象通过 Agent Framework 提供的抽象层我们只需改动几行代码就可以自由切换不同的模型后端。在这个案例的代码结构中你会发现 Agent 的定义方式变得异常清晰不再是杂乱无章的 Python / C# 代码而是结构化、声明式的 Agent 定义。Python# Python - Create Agents with GitModels from agent_framework.openai import OpenAIChatClient chat_client OpenAIChatClient( base_urlos.environ.get(GITHUB_ENDPOINT), # GitHub Models API endpoint api_keyos.environ.get(GITHUB_TOKEN), # Authentication token model_idos.environ.get(GITHUB_MODEL_ID) # Selected AI model ) # Create Concierge Agent CONCIERGE_AGENT_NAMES Concierge CONCIERGE_AGENT_INSTRUCTIONS You are an are hotel concierge who has opinions about providing the most local and authentic experiences for travelers. The goal is to determine if the front desk travel agent has recommended the best non-touristy experience for a traveler. If so, state that it is approved. If not, provide insight on how to refine the recommendation without using a specific example. concierge_agent chat_client.create_agent( instructionsCONCIERGE_AGENT_INSTRUCTIONS, nameCONCIERGE_AGENT_NAMES, ) # Create FrontDesk Agent FRONTEND_AGENT_NAMES FrontDesk FRONTEND_AGENT_INSTRUCTIONS You are a Front Desk Travel Agent with ten years of experience and are known for brevity as you deal with many customers. The goal is to provide the best activities and locations for a traveler to visit. Only provide a single recommendation per response. Youre laser focused on the goal at hand. Dont waste time with chit chat. Consider suggestions when refining an idea. frontend_agent chat_client.create_agent( instructionsFRONTEND_AGENT_INSTRUCTIONS, nameFRONTEND_AGENT_NAMES, ) # Create Workflow frontend_executor AgentExecutor(frontend_agent, idfrontend_agent) concierge_executor AgentExecutor(concierge_agent, idconcierge_agent) workflow ( WorkflowBuilder() .set_start_executor(frontend_executor) .add_edge(frontend_executor, concierge_executor) .build() ).NET// .NET - Creat Agents with GitHub Models var openAIOptions new OpenAIClientOptions() { Endpoint new Uri(github_endpoint) }; var openAIClient new OpenAIClient(new ApiKeyCredential(github_token), openAIOptions); var chatClient openAIClient.GetChatClient(github_model_id).AsIChatClient(); conststring ReviewerAgentName Concierge; conststring ReviewerAgentInstructions You are an are hotel concierge who has opinions about providing the most local and authentic experiences for travelers. The goal is to determine if the front desk travel agent has recommended the best non-touristy experience for a traveler. If so, state that it is approved. If not, provide insight on how to refine the recommendation without using a specific example. ; conststring FrontDeskAgentName FrontDesk; conststring FrontDeskAgentInstructions You are a Front Desk Travel Agent with ten years of experience and are known for brevity as you deal with many customers. The goal is to provide the best activities and locations for a traveler to visit. Only provide a single recommendation per response. Youre laser focused on the goal at hand. Dont waste time with chit chat. Consider suggestions when refining an idea. ; var reviewerAgentBuilder new AIAgentBuilder(chatClient.CreateAIAgent( name: ReviewerAgentName, instructions: ReviewerAgentInstructions)); var frontDeskAgentBuilder new AIAgentBuilder(chatClient.CreateAIAgent( name: FrontDeskAgentName, instructions: FrontDeskAgentInstructions)); AIAgent reviewerAgent reviewerAgentBuilder.Build(serviceProvider); AIAgent frontDeskAgent frontDeskAgentBuilder.Build(serviceProvider); // Create Workflow var workflow new WorkflowBuilder(frontDeskAgent) .AddEdge(frontDeskAgent, reviewerAgent) .Build();阶段二测试与调试 DevUI这是本文的重头戏。过去我们调试 Agent 只能靠print()和无休止的控制台日志“猜问题”而现在我们有了 DevUI。DevUI 是什么它是 Agent Framework 中专为开发者打造的一款“内循环开发工具”。当GHModel.AI运行时DevUI 会为你提供一个可视化控制台思维链可视化你再也不用去猜为什么 Agent 选择了工具 A 而不是 B。在 DevUI 中你可以像看流程图一样清楚看到每一个 Reasoning、Action 和 Observation 步骤。这不仅是调试工具而是对 Agent 行为的“X 光透视”。实时状态监控Agent 的内存里到底存了什么上下文有没有溢出DevUI 支持实时查看对话状态帮你快速定位“幻觉”的根源。Pythoncd GHModel.Python.AI/GHModel.Python.AI.Workflow.DevUI pip install agent-framework agent-framework-devui python-dotenv python main.py # Browser opens automatically at http://localhost:8090.NETcd GHModel.dotNET.AI/GHModel.dotNET.AI.Workflow.DevUI dotnet run # DevUI: https://localhost:50516/devui # OpenAI API: https://localhost:50516/v1/responses阶段三交付与交互 AG-UI调试结束后老板说“能不能给我个链接我也想试试”此时此刻千万不要手写 React 前端。你真正需要的是 ——AG-UI。那么AG-UI 解决什么问题它是一套标准化的Agent–User 交互协议。在 GHModel.AI 这个案例中通过集成 AG-UI开箱即用的前端能力Agent Framework 可以直接暴露符合 AG-UI 协议的接口。任何支持 AG-UI 的前端例如 CopilotKit 提供的组件都可以直接连接你的本地 Agent。流式响应与生成式 UI它不仅支持文本流式输出还支持服务端推送 UI 组件。这意味着Agent 可以根据内容在前端动态渲染图表、表格或卡片等组件 —— 无需为每种场景单独硬编码前端页面。AG-UI 支持的功能✅ 流式响应SSE✅ 后端工具渲染✅ 人机协同审批机制✅ 共享状态同步✅ 与 CopilotKit 无缝集成CopilotKithttps://copilotkit.ai/?wt.mc_id3reg_webpage_reactor实现示例Python 服务器# Server — Register AG-UI endpoint from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint from workflow import workflow app FastAPI() agent workflow.as_agent(nameTravel Agent) add_agent_framework_fastapi_endpoint(app, agent, /).NET 服务器// Program.cs — ASP.NET Core AG-UI endpoint registration using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore; var builder WebApplication.CreateBuilder(args); builder.Services.AddAGUI(); var app builder.Build(); AIAgent workflowAgent ChatClientAgentFactory.CreateTravelAgenticChat(); app.MapAGUI(/, workflowAgent); await app.RunAsync();从 DevUI 到 AG-UI本质上是一次从“开发者视角”到“用户视角”的无缝切换。我们可以借助 CopilotKit 来构建 UI。阶段四性能追踪 OpenTelemetry在 Agent 正式上线之前除了“能不能跑”我们还必须回答两个问题“够快吗贵不贵”这正是OpenTelemetryOTel登场的地方。在 Agent Framework 中OpenTelemetry 是原生内置支持的。在 GHModel.AI 的代码中通常只需一行配置例如AddOpenTelemetry或setup_observability即可启用分布式追踪当一个请求进入系统经过路由、Guardrails、调用 GitHub Models再返回结果时OTel 会生成完整的火焰图你可以精准看到网络 I/O 花了多少时间LLM 的 Token 生成耗时多少本地业务逻辑处理耗时多少成本可视化结合 OTel Metrics我们可以监控 Token 消耗速率。这在从 GitHub Models免费 / 原型阶段迁移到 Azure OpenAI付费 / 生产阶段时对成本预估至关重要。 快速配置Python# Enable telemetry in one line from agent_framework.observability import setup_observability from agent_framework import setup_logging setup_observability() setup_logging().NET// OpenTelemetry configuration var tracerProvider Sdk.CreateTracerProviderBuilder() .AddSource(*Microsoft.Agents.AI) .AddOtlpExporter(options options.Endpoint new Uri(http://localhost:4317)) .Build();环境变量ENABLE_OTELtrue ENABLE_SENSITIVE_DATAtrue # Enable sensitive data logging in dev OTLP_ENDPOINThttp://localhost:4317 # Aspire Dashboard / OTLP Collector APPLICATIONINSIGHTS_CONNECTION_STRING... # Azure Application Insights (optional) 可视化选项平台用例快速开始Aspire 仪表盘本地开发docker run --rm -d -p 18888:18888 -p 4317:18889 mcr.microsoft.com/dotnet/aspire-dashboard:latest应用洞察生产环境监控设置 APPLICATIONINSIGHTS_CONNECTION_STRINGGrafana 仪表盘高级可视化Agent Overviewhttps://aka.ms/amg/dash/af-agent/?wt.mc_id3reg_webpage_reactorWorkflow Overviewhttps://aka.ms/amg/dash/af-workflow/?wt.mc_id3reg_webpage_reactor架构概览总结 构建你的“效率闭环”回顾 GHModel.AI 的案例它不仅是一份代码示例 —— 更展示了现代智能体开发的最佳实践架构层级工具用途模型层GitHub Models借助免费的前沿模型快速验证想法调试层DevUI获得 “上帝视角”快速迭代逻辑展示层AG-UI标准化输出结果秒级生成用户界面可观测性层OpenTelemetry基于数据驱动优化告别主观猜测最终思考我鼓励每一位 Agent 开发者深入 Agent-Framework-Samples 的代码世界。别再用记事本调试 AI 了——拿起这些现代化“武器”去构建下一代智能应用吧借助GitHub Models实现快速原型开发通过DevUI进行可视化调试利用AG-UI达成流畅的用户交互再结合OpenTelemetry提供企业级可观测性 —— 这一系列工具的组合标志着我们构建智能体应用的方式迎来了范式转变。你的 Agent 开发旅程从这里启程。未来是Agentic的让我们一起去创造它Agent-Framework-Sampleshttps://github.com/microsoft/Agent-Framework-Samples/?wt.mc_id3reg_webpage_reactor资源Microsoft Agent Frameworkhttps://github.com/microsoft/agent-framework/?wt.mc_id3reg_webpage_reactorMicrosoft Agent Framework 示例https://github.com/microsoft/Agent-Framework-Samples/?wt.mc_id3reg_webpage_reactorMicrosoft Agent Framework DevUI 示例https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/devui/?wt.mc_id3reg_webpage_reactorMicrosoft Agent Framework 可观测性指南https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/observability/?wt.mc_id3reg_webpage_reactor引入地址
技术速递｜基于 Microsoft Agent Framework 的 Agentic 开发“黄金三角”
目录阶段一创建 站在 GitHub Models 的肩膀上阶段二测试与调试 DevUI阶段三交付与交互 AG-UIAG-UI 支持的功能实现示例阶段四性能追踪 OpenTelemetry 快速配置 可视化选项架构概览总结 构建你的“效率闭环”最终思考资源作者卢建晖 - 微软高级云技术布道师排版Alan Wang在 Agentic AI 爆发式发展的时代我们追求的早已不只是“更强大的模型”——而是一次真正能让开发者睡个好觉的开发体验。在本地构建 Agent 的过程中我们长期面临三大核心挑战黑盒式执行我的 Agent 到底在想什么为什么卡住不动调试太难了交互孤岛Agent 已经写好了但我要如何快速给业务方 / 客户演示一个“好看又能用”的界面产品化太难了性能盲区到底消耗了多少 Token延迟出在哪里优化太难了今天我将通过 Microsoft Agent Framework Samples 中一个经典示例 —— GHModel.AI带你拆解一套真正解决这些痛点的“黄金三角”开发体系DevUI、AG-UI与OpenTelemetry。让我们一起看看这套强大组合如何打通 Agent 本地开发的完整生命周期。GHModel.AIhttps://github.com/microsoft/Agent-Framework-Samples/tree/main/09.Cases/GHModel.AI/?wt.mc_id3reg_webpage_reactor阶段一创建 站在 GitHub Models 的肩膀上在GHModel.AI这个案例中我们首先要解决的是 Agent 的「大脑」问题。传统的本地开发往往受限于算力不足或者被昂贵的 API Key 成本所束缚。而这个案例非常巧妙地借助了 GitHub Models。作为一名技术布道者我必须强烈推荐这套组合零门槛接入直接使用 GitHub 账号即可调用 GPT-4o、Llama 3 等前沿模型无需复杂的 Azure 配置也无需绑定信用卡。统一 SDK 抽象通过 Agent Framework 提供的抽象层我们只需改动几行代码就可以自由切换不同的模型后端。在这个案例的代码结构中你会发现 Agent 的定义方式变得异常清晰不再是杂乱无章的 Python / C# 代码而是结构化、声明式的 Agent 定义。Python# Python - Create Agents with GitModels from agent_framework.openai import OpenAIChatClient chat_client OpenAIChatClient( base_urlos.environ.get(GITHUB_ENDPOINT), # GitHub Models API endpoint api_keyos.environ.get(GITHUB_TOKEN), # Authentication token model_idos.environ.get(GITHUB_MODEL_ID) # Selected AI model ) # Create Concierge Agent CONCIERGE_AGENT_NAMES Concierge CONCIERGE_AGENT_INSTRUCTIONS You are an are hotel concierge who has opinions about providing the most local and authentic experiences for travelers. The goal is to determine if the front desk travel agent has recommended the best non-touristy experience for a traveler. If so, state that it is approved. If not, provide insight on how to refine the recommendation without using a specific example. concierge_agent chat_client.create_agent( instructionsCONCIERGE_AGENT_INSTRUCTIONS, nameCONCIERGE_AGENT_NAMES, ) # Create FrontDesk Agent FRONTEND_AGENT_NAMES FrontDesk FRONTEND_AGENT_INSTRUCTIONS You are a Front Desk Travel Agent with ten years of experience and are known for brevity as you deal with many customers. The goal is to provide the best activities and locations for a traveler to visit. Only provide a single recommendation per response. Youre laser focused on the goal at hand. Dont waste time with chit chat. Consider suggestions when refining an idea. frontend_agent chat_client.create_agent( instructionsFRONTEND_AGENT_INSTRUCTIONS, nameFRONTEND_AGENT_NAMES, ) # Create Workflow frontend_executor AgentExecutor(frontend_agent, idfrontend_agent) concierge_executor AgentExecutor(concierge_agent, idconcierge_agent) workflow ( WorkflowBuilder() .set_start_executor(frontend_executor) .add_edge(frontend_executor, concierge_executor) .build() ).NET// .NET - Creat Agents with GitHub Models var openAIOptions new OpenAIClientOptions() { Endpoint new Uri(github_endpoint) }; var openAIClient new OpenAIClient(new ApiKeyCredential(github_token), openAIOptions); var chatClient openAIClient.GetChatClient(github_model_id).AsIChatClient(); conststring ReviewerAgentName Concierge; conststring ReviewerAgentInstructions You are an are hotel concierge who has opinions about providing the most local and authentic experiences for travelers. The goal is to determine if the front desk travel agent has recommended the best non-touristy experience for a traveler. If so, state that it is approved. If not, provide insight on how to refine the recommendation without using a specific example. ; conststring FrontDeskAgentName FrontDesk; conststring FrontDeskAgentInstructions You are a Front Desk Travel Agent with ten years of experience and are known for brevity as you deal with many customers. The goal is to provide the best activities and locations for a traveler to visit. Only provide a single recommendation per response. Youre laser focused on the goal at hand. Dont waste time with chit chat. Consider suggestions when refining an idea. ; var reviewerAgentBuilder new AIAgentBuilder(chatClient.CreateAIAgent( name: ReviewerAgentName, instructions: ReviewerAgentInstructions)); var frontDeskAgentBuilder new AIAgentBuilder(chatClient.CreateAIAgent( name: FrontDeskAgentName, instructions: FrontDeskAgentInstructions)); AIAgent reviewerAgent reviewerAgentBuilder.Build(serviceProvider); AIAgent frontDeskAgent frontDeskAgentBuilder.Build(serviceProvider); // Create Workflow var workflow new WorkflowBuilder(frontDeskAgent) .AddEdge(frontDeskAgent, reviewerAgent) .Build();阶段二测试与调试 DevUI这是本文的重头戏。过去我们调试 Agent 只能靠print()和无休止的控制台日志“猜问题”而现在我们有了 DevUI。DevUI 是什么它是 Agent Framework 中专为开发者打造的一款“内循环开发工具”。当GHModel.AI运行时DevUI 会为你提供一个可视化控制台思维链可视化你再也不用去猜为什么 Agent 选择了工具 A 而不是 B。在 DevUI 中你可以像看流程图一样清楚看到每一个 Reasoning、Action 和 Observation 步骤。这不仅是调试工具而是对 Agent 行为的“X 光透视”。实时状态监控Agent 的内存里到底存了什么上下文有没有溢出DevUI 支持实时查看对话状态帮你快速定位“幻觉”的根源。Pythoncd GHModel.Python.AI/GHModel.Python.AI.Workflow.DevUI pip install agent-framework agent-framework-devui python-dotenv python main.py # Browser opens automatically at http://localhost:8090.NETcd GHModel.dotNET.AI/GHModel.dotNET.AI.Workflow.DevUI dotnet run # DevUI: https://localhost:50516/devui # OpenAI API: https://localhost:50516/v1/responses阶段三交付与交互 AG-UI调试结束后老板说“能不能给我个链接我也想试试”此时此刻千万不要手写 React 前端。你真正需要的是 ——AG-UI。那么AG-UI 解决什么问题它是一套标准化的Agent–User 交互协议。在 GHModel.AI 这个案例中通过集成 AG-UI开箱即用的前端能力Agent Framework 可以直接暴露符合 AG-UI 协议的接口。任何支持 AG-UI 的前端例如 CopilotKit 提供的组件都可以直接连接你的本地 Agent。流式响应与生成式 UI它不仅支持文本流式输出还支持服务端推送 UI 组件。这意味着Agent 可以根据内容在前端动态渲染图表、表格或卡片等组件 —— 无需为每种场景单独硬编码前端页面。AG-UI 支持的功能✅ 流式响应SSE✅ 后端工具渲染✅ 人机协同审批机制✅ 共享状态同步✅ 与 CopilotKit 无缝集成CopilotKithttps://copilotkit.ai/?wt.mc_id3reg_webpage_reactor实现示例Python 服务器# Server — Register AG-UI endpoint from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint from workflow import workflow app FastAPI() agent workflow.as_agent(nameTravel Agent) add_agent_framework_fastapi_endpoint(app, agent, /).NET 服务器// Program.cs — ASP.NET Core AG-UI endpoint registration using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore; var builder WebApplication.CreateBuilder(args); builder.Services.AddAGUI(); var app builder.Build(); AIAgent workflowAgent ChatClientAgentFactory.CreateTravelAgenticChat(); app.MapAGUI(/, workflowAgent); await app.RunAsync();从 DevUI 到 AG-UI本质上是一次从“开发者视角”到“用户视角”的无缝切换。我们可以借助 CopilotKit 来构建 UI。阶段四性能追踪 OpenTelemetry在 Agent 正式上线之前除了“能不能跑”我们还必须回答两个问题“够快吗贵不贵”这正是OpenTelemetryOTel登场的地方。在 Agent Framework 中OpenTelemetry 是原生内置支持的。在 GHModel.AI 的代码中通常只需一行配置例如AddOpenTelemetry或setup_observability即可启用分布式追踪当一个请求进入系统经过路由、Guardrails、调用 GitHub Models再返回结果时OTel 会生成完整的火焰图你可以精准看到网络 I/O 花了多少时间LLM 的 Token 生成耗时多少本地业务逻辑处理耗时多少成本可视化结合 OTel Metrics我们可以监控 Token 消耗速率。这在从 GitHub Models免费 / 原型阶段迁移到 Azure OpenAI付费 / 生产阶段时对成本预估至关重要。 快速配置Python# Enable telemetry in one line from agent_framework.observability import setup_observability from agent_framework import setup_logging setup_observability() setup_logging().NET// OpenTelemetry configuration var tracerProvider Sdk.CreateTracerProviderBuilder() .AddSource(*Microsoft.Agents.AI) .AddOtlpExporter(options options.Endpoint new Uri(http://localhost:4317)) .Build();环境变量ENABLE_OTELtrue ENABLE_SENSITIVE_DATAtrue # Enable sensitive data logging in dev OTLP_ENDPOINThttp://localhost:4317 # Aspire Dashboard / OTLP Collector APPLICATIONINSIGHTS_CONNECTION_STRING... # Azure Application Insights (optional) 可视化选项平台用例快速开始Aspire 仪表盘本地开发docker run --rm -d -p 18888:18888 -p 4317:18889 mcr.microsoft.com/dotnet/aspire-dashboard:latest应用洞察生产环境监控设置 APPLICATIONINSIGHTS_CONNECTION_STRINGGrafana 仪表盘高级可视化Agent Overviewhttps://aka.ms/amg/dash/af-agent/?wt.mc_id3reg_webpage_reactorWorkflow Overviewhttps://aka.ms/amg/dash/af-workflow/?wt.mc_id3reg_webpage_reactor架构概览总结 构建你的“效率闭环”回顾 GHModel.AI 的案例它不仅是一份代码示例 —— 更展示了现代智能体开发的最佳实践架构层级工具用途模型层GitHub Models借助免费的前沿模型快速验证想法调试层DevUI获得 “上帝视角”快速迭代逻辑展示层AG-UI标准化输出结果秒级生成用户界面可观测性层OpenTelemetry基于数据驱动优化告别主观猜测最终思考我鼓励每一位 Agent 开发者深入 Agent-Framework-Samples 的代码世界。别再用记事本调试 AI 了——拿起这些现代化“武器”去构建下一代智能应用吧借助GitHub Models实现快速原型开发通过DevUI进行可视化调试利用AG-UI达成流畅的用户交互再结合OpenTelemetry提供企业级可观测性 —— 这一系列工具的组合标志着我们构建智能体应用的方式迎来了范式转变。你的 Agent 开发旅程从这里启程。未来是Agentic的让我们一起去创造它Agent-Framework-Sampleshttps://github.com/microsoft/Agent-Framework-Samples/?wt.mc_id3reg_webpage_reactor资源Microsoft Agent Frameworkhttps://github.com/microsoft/agent-framework/?wt.mc_id3reg_webpage_reactorMicrosoft Agent Framework 示例https://github.com/microsoft/Agent-Framework-Samples/?wt.mc_id3reg_webpage_reactorMicrosoft Agent Framework DevUI 示例https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/devui/?wt.mc_id3reg_webpage_reactorMicrosoft Agent Framework 可观测性指南https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/observability/?wt.mc_id3reg_webpage_reactor引入地址
