在 Microsoft Foundry Toolkit 中使用代理检查器调试代理

Microsoft Foundry Toolkit for Visual Studio Code 中的代理检查器允许你向本地代理发送请求、检查模型和工具活动以及调试代码。 在部署更改之前，使用它来调查意外响应。

此工作流适用于 托管代理，这些代理在 Foundry 代理服务中运行自定义代码。 本地检查可帮助你调试该代码。 在投入生产使用之前，还应使用已部署智能体的运行时标识、配置和网络访问权限对其进行测试。

在本文中，你将连接到本地代理、调查请求并保存诊断事件。 主路径使用 Responses 协议。 可用视图取决于代理服务器提供的协议和诊断。

Prerequisites

• 带有当前公开版 Foundry Toolkit 扩展的 Visual Studio Code。 请参阅 安装 Foundry 工具包。
• 设置了依赖项、模型配置和凭据的本地代理项目。 若要从示例开始，请按照托管智能体快速入门的指引进行本地测试。
• 项目所需的调试器。 Python示例使用Python扩展以及debugpy。 其他语言和示例有不同的要求。

对于现有项目，Foundry Toolkit Copilot工具可以帮助准备配置。 查看生成的文件，并遵循项目的 README.md。 不要将其启动文件替换为通用配置。

Important

本地代理可以调用云模型和实时工具。 使用非敏感测试输入，检查工具权限，并将已配置服务的费用考虑在内。 检查器不会用模拟对象替换工具。

连接和调试

在连接检查器之前，请先启动智能体服务器。 使用项目生成的启动配置，以正确设置服务器、工作目录、解释器和调试器。

1. 使用文档中记录的调试配置启动智能体。 对于托管代理Python示例，请选择“调试本地代理 HTTP 服务器”，然后按 F5。
2. 如果未打开 Inspector，请在活动栏中选择 Foundry Toolkit，然后选择 开发人员工具>生成>代理 Inspector。
3. 检查 Inspector 标题栏中的端点。 当前Python基架使用http://localhost:8088。 对于其他服务器端口，请选择终结点旁边的铅笔按钮，输入端口，然后选择 “连接”。
4. 确认头部显示 “已连接”。 当终结点可访问时，检查器会自动检测响应或调用协议。
5. 在代理代码中设置断点，并在 Playground 中发送消息。 在执行暂停时检查变量，然后继续并查看响应。

单独打开检查器不会启动服务器或附加调试器。 生成的Python配置对调试器使用端口 5679，对代理 HTTP 请求使用端口 8088。 这些端口独立于 OTLP 跟踪端口。

连接到通用 Responses 端点

检查器可以连接到本地通用响应终结点，而无需完整的开发诊断接口。 可以检查服务器发送的响应事件，但工作流图及其输入和输出视图不可用。

成功的连接并不意味着服务器提供源位置、令牌使用情况或推理。

发送 HTTP 调用

当代理接受自定义请求正文而不是对话消息时，请使用 HTTP 调用。 服务器的请求格式和响应协议确定 Inspector 发送和显示结果的方式。

1. 连接到正在运行的 HTTP 调用程序服务器。 检查器自动检测协议。
2. 输入代理所需的请求正文。 如果服务器提供了兼容的 OpenAPI 规范，检查器可以自动生成一个示例。 发送前请先检查一遍；如果没有示例，请按照示例中的请求格式操作。
3. 选择输入旁边的 “请求设置” 齿轮，以便根据服务器的要求设置 Content-Type 和 Accept 。 例如，对 JSON 请求正文使用 application/json，当服务器支持流式响应时使用 text/event-stream。
4. 选择“ 发送 ”并检查响应状态和正文。
5. 在预览（显示格式化后的输出）和原始（显示底层响应）之间切换。 详细信息窗格还包括 I/O 和 LLM 调用。 模型、工具和令牌详细信息取决于已识别的服务器事件，因此并不是每个响应都会填充每个选项卡。

检查器处理正常的 HTTP 响应、服务器发送的事件流或异步响应。 对于异步 202 Accepted 响应，它会轮询调用，直到完成或失败。 选择响应格式不会向服务器添加流式处理或异步支持。

对于流式响应，单击停止会断开客户端流连接。 对于轮询调用， Cancel 会将取消请求发送到服务器。 这两个操作都不能保证代理进程或外部工具操作已停止。

此视图不是 WebSocket 客户端。 “活动协议”示例使用的是另一个测试环境。 请参阅 “选择其他协议或样本”，了解适当的本地测试路径。

使用检查器

首先，从一个用于验证你想了解的行为的请求开始。 例如，对于天气工具，请求需要该工具的信息，而不是模型在没有工具的情况下可以生成的常规答案。

1. 在 Playground 中发送请求并查看流式处理响应。
2. 使用详细信息选项卡查找缓慢或失败的操作。
3. 检查相关的事件或工具调用，修改代码或配置，然后重新发送请求。

按 Enter 发送或 Shift+Enter 以添加新行。 若要调出先前的请求，请将插入符号置于输入的开头，然后按 向上键。 在末尾按向下箭头，即可浏览较新的请求，并返回未发送的草稿。

在发送之前，可以编辑已撤回的请求。 输入历史记录是检查器中的一项便捷功能，并非用于持久存储已保存提示的存储空间。

View	使用它来
Overview	请参考延迟瀑布图和有序运行时间线。 选择所有运行或单次运行，以区分模型和工具的活动与运行间隔时间。
令 牌	审查报告中所述的输入和输出令牌使用情况。 缺少使用数据并不意味着结果为零个令牌。
Events	检查已解析的 Responses 事件，包括错误、函数调用和结果。 按事件类型或 JSON 内容进行搜索，并按类别进行筛选。
工具	检查按响应运行分组的工具调用，包括状态、调用 ID、参数和结果。

响应页脚在提供时显示模型、持续时间、令牌使用情况和时间戳信息。 当智能体生成推理文本和推理摘要时，它们会分别显示在可折叠的独立区域中。 检查器不会生成缺失的推理，也不会披露模型提供商未返回的信息。

检查工具和权限

使用 工具 检查代理是否使用预期参数调用预期的工具并收到结果。 成功的模型响应并不能证明工具已运行。 如果代码使用模拟，则显示的结果仍然是模拟结果。

当响应因等待模型上下文协议 (MCP) 批准或 OAuth 授权而暂停时，待处理的请求会显示在消息输入框上方。 仅授予你希望允许的访问权限。

对于 MCP 工具调用，请选择 “显示参数”，查看输入，然后选择 “批准” 或 “拒绝”。 全部批准和全部拒绝适用于待处理的请求，并非永久性的工具批准策略。

对于 OAuth 许可，请完成浏览器授权和检查器确认：

1. 针对待处理的请求，请选择打开同意书。
2. 在浏览器中完成授权，返回检查器，然后选择已同意。 若要拒绝授权，请选择“ 取消 ”。
3. 处理剩余的同意书请求。 仅在完成所有打开的请求的授权后，才使用 “全部完成”。

单独打开同意页面不会恢复请求。 检查器会在再次检查服务器之前，等待每项待处理同意的决定。 如果服务器仍需要授权，请求可能会重新出现。

检查后续工具结果，而不仅仅是审批，以确认完成。 有关连接和身份验证设置，请参阅 工具目录。 不要仅仅为了让诊断错误消失而更改工具凭据或权限。

检查工作流和源代码

对于受支持的 Microsoft Agent Framework 工作流，开发服务器可以提供工作流诊断和源位置。 检查器使用此信息来显示执行图并帮助你导航到代码。

1. 选择一个工作流节点来检查可用的输入和输出。
2. 双击节点以打开其源位置。
3. 设置断点并重复请求以检查调试器中的操作。

可以在 Playground 中测试 LangGraph 工作流，但不支持工作流可视化。 没有工作流元数据的服务器仍可返回有用的响应事件。

调查 Copilot 故障

请使用事件中的错误处理操作，为 GitHub Copilot 准备一个针对性强的请求，而不是复制整个对话内容。

1. 查找失败的事件，并在共享它们之前检查其详细信息中是否包含敏感内容。
2. 在出现故障的事件旁边选择修复，以针对该故障准备一条提示信息。 对于多个失败，请使用搜索和类别筛选器缩小列表范围，然后选择“使用 Copilot 解决”。 此操作包括可见的故障。
3. 在发送之前，请查看 GitHub Copilot 对话助手中准备好的提示。 查看任何建议的更改，然后重新运行原始代理请求以确认结果。

这些操作不需要 OTLP 收集器。 准备诊断提示不会修复代理或重新运行失败的操作。

保存诊断事件

保存事件快照，以便将故障情况与后续运行结果进行对比，或分享针对性的重现步骤。

1. 在 “事件”中，使用搜索字段和类别筛选器缩小列表范围。
2. 选择 “复制可见事件” 以将筛选的事件复制为 JSONL。 或者，选择“ 下载可见事件 ”以在 VS Code 中打开导出。
3. 对于已打开的导出文件，请在关闭文档之前，使用文件>另存为，将副本保存到你控制的位置。 已打开的导出文件是一个临时文件，并非永久下载。

该快照包含你选择该操作时可见的事件，而不包含正在运行的智能体的未来事件。 它不能保存代理版本、部署代码或创建云跟踪历史记录。

注意

事件可以包括提示、响应、工具参数、结果和错误详细信息。 在保存或分享导出文件之前，请先审查并删除敏感内容。

开始新的对话

选择“ 清除聊天 ”以启动新对话并清除聊天、事件和详细信息状态。 首先导出所需的任何诊断事件。 刷新同一连接的代理会保留其检查状态，而更改代理会清除过时状态。

对于响应，Clear Chat 在响应主动流式传输时处于禁用状态。 当轮次因等待批准或同意而暂停时，该选项仍然可用。 这不是一个让你的代理停止的通用命令。

不要依赖本地检查器状态作为持久聊天存档。 服务器负责对话持久化，这在本地开发与已部署的托管代理之间可能有所不同。 清除检查器不会删除本地收集或存储在 Application Insights 中的跟踪。

Inspector 和跟踪的不同之处

检查器通过 HTTP 与本地服务器通信，并流式传输响应事件。 兼容的开发服务器还提供单独的诊断流，用于工作流程详情和源导航。 调试器会独立地附加到你正在运行的进程。

这些实时诊断不需要本地 OTLP 收集器。 检查器的 “跟踪” 选项卡将打开单独的跟踪查看器。 它不会将协议事件转换为存储的 OpenTelemetry Span。

若要收集 Span 以供以后分析，请配置 本地跟踪。 对于已部署的智能体，请使用托管智能体跟踪。

在本地测试后， 部署托管代理。 单独测试它，因为它的标识、环境和网络访问不同于你的本地进程。

Troubleshooting

Issue	需要检查的事项
检查器无法连接。	检查代理终端是否存在启动错误。 确认解释器、依赖项和 HTTP 端口，然后重新连接到服务器报告的端口。 打开检查器不会启动该进程。
请求成功，但未命中断点。	确认调试器已附加到为请求提供服务的进程，并使用正确的源目录。 有关 Python，请参阅调试与故障排除。
缺少图形或源导航。	确认服务器和工作流提供开发诊断和源位置。 Generic Responses 检查不提供这些功能。 LangGraph 工作流无需工作流可视化也可在 Playground 中运行。
工具结果缺失。	检查 Events 中是否存在失败和挂起的审批。 确认请求需要一个工具，并且该工具已配置并可访问。
缺少 Token 或推理详情。	检查模型和服务器发出的内容。 检查器只能显示用户提供的信息。
远程图像被阻止。	仅当你希望检查器从远程主机获取图片时，才选择加载远程图片。 此显示权限并非工具审批。 不支持的 URL 或内容仍可能无法加载。 图片缺失并不一定意味着智能体请求失败。
响应流中断。	查看部分响应和失败详细信息。 如果需要，请重新连接，并在重试前查看待审批项。 重试可以重复已执行的工具操作。
Inspector 有事件，但跟踪查看器为空。	协议事件和 OTLP span 不同。 配置插桩并启动收集器。

相关内容

• 在 Foundry Toolkit 中收集和检查跟踪。
• 在 VS Code 中创建托管代理工作流。
• 使用Azure开发人员 CLI 启动基于浏览器的代理检查器。