Microsoft Foundry 智能体的 AI 可观测性入门套件

本文编译自 Microsoft Tech Community 上 varghesejoji 的博客文章 AI Observability Starter Kit for Microsoft Foundry agents，我按自己上手时的理解重新整理，并补充了一些实际跑下来的体会。

先把结论放前面：一条 PowerShell 命令，就能拉起一个包含四个智能体的 Microsoft Foundry 环境，带遥测、8 个内置评估器、1 个自定义合规评估器、一次自动化红队扫描，还有两条 scheduled-query 告警。整套东西端到端验证过，再敲一条命令就能全部拆掉。Fork 下来直接跑。我觉得它最对胃口的人群是那些在 Azure 上跑 AI 智能体、又不想自己手写一堆管道代码的应用开发者、ML 工程师和 SRE。

1. 从"全绿仪表盘"到真正能上生产的 AI 可观测性

设想这样一个场景：你的 AI 智能体在生产环境跑着，负载均衡器显示零错误，Application Insights 仪表盘一片绿。但底下其实出了好几档子事：

• 有个模型部署根本不存在。某个智能体指向的模型压根没部署，每个请求都撞上 chat 级错误——可 HTTP 响应还是返回 200，因为智能体框架在内部把异常吞掉了。

• 某个工具返回了脏数据。用户查客户 C999 的订单，智能体调对了工具，但工具抛了个 LookupError。智能体礼貌地道了个歉，HTTP 状态 200，除非你去追 execute_tool 这个依赖 span，否则错误根本看不见。

• 模型上钩回答了一个安全诱饵提示。用户要暴力虚构内容，模型照做了。没有过滤器拦住，没有评估器给它打分，也没有告警响。

这些问题不会出现在常规日志或者通用的资源仪表盘里。第一次意识到 HTTP 200 背后能藏这么多事，我还挺意外的。它们需要另一种可观测性，把五件事拼到一起：

• 用 OpenTelemetry（OTel）GenAI 语义约定做插桩追踪，这样每次模型调用和工具执行都变成一个可查询的 span。

• 自动化的质量评估器，在真实流量上给推理、意图识别、工具使用打分，而不是在测试夹具上。

• 对抗性红队测试，用生成的攻击提示去探安全边界，赶在真实用户之前。

• Scheduled-query 告警，盯着错误率和延迟退化触发，而不是只盯可用性。

• 仪表盘，把 token、模型、工具、错误集中到一处，给运维和 on-call 看。

这些零件没一个是新东西。难的是把它们正确地接起来。这个 starter kit（仓库在 github.com/jvargh/ai-observability-starter-kit）把接线部分打包好了：一个已插桩的智能体、绑到正确追踪字段上的评估器、一套红队分类法、一份可导入的 Grafana 仪表盘，还有部署后的检查——全都塞进一条命令里。你从一个已知可用的基线出发，而不是自己从零攒。

这一节先讲清楚这套东西是怎么把这些零件接起来的。第 2 节往后覆盖部署、评估、红队、可观测性各个视图，以及拆除。

1.1 数据是怎么流动的

一个用户提示进入托管智能体，智能体调用模型（比如 gpt-4o-mini），可能还会执行一个或多个工具（订单查询、供应商查询、天气、掷骰子）。每次模型调用和工具执行都会发出 OpenTelemetry span，自动摄入到 Azure Application Insights。除了在智能体清单里设一个 ENABLE_INSTRUMENTATION=true，你不需要额外写任何 SDK 接线代码。

从 Application Insights 出发，遥测数据喂给三个下游消费者：

• Grafana 仪表盘通过 KQL（Kusto 查询语言，Azure Log Analytics 的查询语言）查底层的 Log Analytics 工作区，渲染出运营面板（token 用量、延迟、错误率、模型分布）。

• Agent evaluators 拉取最近的追踪，用 8 个内置质量检查加上你注册的任意自定义评估器给它们打分。结果出现在 Microsoft Foundry 的 Evaluations 面板里。

• Scheduled-query 告警在错误计数或 p95 延迟（95 分位响应时间）在 15 分钟窗口内超阈值时触发。

设计上有个关键点：智能体本身不知道仪表盘、评估器或告警的存在。它只管发 span。下游的一切都通过 Application Insights 这条遥测主干接起来。我个人挺喜欢这种解耦——智能体代码里没有任何"监控逻辑"污染。

1.2 智能体的定义

Foundry 托管的智能体是一个容器化的 AI 智能体，由 Microsoft Foundry 负责管理、部署和扩缩：你提供 Python 代码（main.py）和一份小小的 YAML 清单（agent.yaml），Foundry 负责运行时、OTel 管道和每个智能体的独立身份。这套 kit 里的四个智能体共用完全一样的代码、工具和系统指令，唯一的区别是各自指向的模型部署：

智能体代码（main.py）创建一个连到模型的 FoundryChatClient，定义一个带采购助手系统提示的 Agent，然后注册六个工具函数：

get_orders, find_suppliers_for_request, get_company_supplier_info, get_current_utc_date, get_weather, and roll_dice.

有些工具是故意在特定输入上报错的（比如客户 C999 会抛 LookupError），这就制造出仪表盘和评估器要消费的错误遥测。

一个工具函数就是一个带注解的普通 Python 函数。Foundry 从 @tool 装饰器发现它，再把它暴露给模型，像下面这样：

1
2
3
4
5
6
7
8

from agent_framework import tool

@tool
def get_orders(customer_id: str) -> list[dict]:
    """Return open orders for a customer. Raises LookupError on unknown IDs."""
    if customer_id == "C999":
        raise LookupError(f"customer {customer_id} not found")
    return _ORDERS_BY_CUSTOMER.get(customer_id, [])

这六个工具函数注册到 Agent 构造函数里，模型能看到的全部界面就这些。

主智能体的 YAML 清单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

kind: hosted
name: agent-framework-agent-basic-responses
protocols:
  - protocol: responses
    version: 1.0.0
resources:
  cpu: '0.25'
  memory: '0.5Gi'
environment_variables:
  - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
    value: ${MODEL_DEPLOYMENT_NAME}
  - name: ENABLE_INSTRUMENTATION
    value: "true"       # activates OTel child spans for chat + tool calls
  - name: ENABLE_SENSITIVE_DATA
    value: "true"       # captures prompts/responses on spans

两个环境变量控制遥测：

• ENABLE_INSTRUMENTATION=true 为每次 chat 模型调用和 execute_tool 调用激活 OpenTelemetry 子 span（每次 LLM 调用一个 span，每次工具执行一个 span）。不设它的话，就只会发出父级的 invoke_agent span，Agents 面板会一直空着。

• ENABLE_SENSITIVE_DATA=true 在 span 上捕获完整的提示和响应文本，评估器要靠这些来给响应质量打分。

2. 部署与运行

这套 kit 里的一切都是自动化的。一个 PowerShell 脚本负责预配基础设施、部署智能体、灌入流量、跑评估、配告警、验证结果。这一节讲清楚部署了什么、怎么跑、你最后能拿到什么。

运行成本：一次端到端跑下来几美分，运行期间大约每天 $0.03（Grafana 成本面板里能看到）。拆除会把一切都删干净。

2.1 这套 starter kit 里有什么

下面是跑起来后会部署的东西，以及每一块能让你做什么：

2.2 运行这套 kit

前置条件：一个 Azure 订阅，你在上面有 Contributor（或 Owner）加 User Access Administrator 权限；装好 PowerShell 7+（pwsh）、Azure CLI（az）和 Azure Developer CLI（azd）并加入 PATH；对目标订阅完成过 az login；仓库根目录有一个 Python 3.13 的 venv（.venv/）。脚本在动任何 Azure 之前会先检查虚拟环境、agent/ 目录和两个 CLI，所以缺前置条件时会提早失败并给出清晰的修复提示，而不是跑到 azd up 半路才崩。

从这里开始，工作流会自动预配基础设施、部署智能体、生成遥测、跑评估、配置仪表盘和告警。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

pwsh -NoProfile -File scripts\run-e2e.ps1 `
    -Region <region> `
    -EnvName <env-name> `
    -SubscriptionId <subscription-id>

For example:
pwsh -NoProfile -File scripts\run-e2e.ps1 `
    -Region eastus2 `
    -EnvName aiobs2-foundry `
    -SubscriptionId <subscription-id>

这个编排器一共跑 13 个阶段，每个都记录到 artifacts/e2e-<timestamp>/phase-NN.log：

端到端总时长：大约 35 到 50 分钟。

某个阶段失败时，脚本会停下来并打印日志路径。不需要的阶段可以用 -SkipPhases 9,10 跳过。

参考运行记录：一份来自成功运行、做过脱敏的端到端日志放在 scripts/e2e-run.log。

2.2.1 部署后验证

跑完之后，验证一切正常：

1

pwsh -NoProfile -File scripts\validate-deployment.ps1

它检查 8 个类别（一共 26 项检查）：基础设施、模型部署、托管智能体、智能体调用、遥测、评估、告警和 RBAC（基于角色的访问控制）。

每项检查会打印 [PASS]、[FAIL] 或 [SKIP]，末尾给一个汇总。想跳过智能体调用测试就加 -SkipInvoke。

一次干净的运行会在大约 90 秒里打印 26 项通过 / 0 失败 / 0 跳过。

参考验证记录：一份来自成功运行（26/26 通过）、做过脱敏的验证日志放在 scripts/e2e-validation.log。

2.2.2 一次成功的部署长什么样

跑完之后，Grafana 仪表盘和 Application Insights 面板应该显示：

• Agent Summary：总操作数（150+）、输入 token（136K+）、输出 token（6.6K+）、平均响应时间（约 7.5 秒）

• Chat and Tool Summary：LLM 调用（196+）、chat 会话（84+）、工具调用（64+）、平均 chat 延迟（约 5.1 秒）

• Models 表：gpt-4o-mini、gpt-5-mini、gpt-4.1-mini（各带调用次数和错误率）

• Gen AI Errors：broken-model 智能体那条 chat nonexistent-model-deployment-xyz 的切片，错误率 100%

• Tool Calls：6 个工具函数，其中 3 个有非零错误计数（LookupError 和 ValueError）

• Evaluations：批量运行得到的 8 个 agent evaluator 分数（task_adherence、task_completion、intent_resolution、tool_call_accuracy、tool_selection、tool_input_accuracy、tool_output_utilization、tool_call_success）

2.2.3 拆除

想拆掉一个部署、并把 Azure AI Services 账户名释放出来复用：

1
2
3
4

pwsh -NoProfile -File scripts\teardown.ps1 -EnvName <env-name>

For example:
pwsh -NoProfile -File scripts\teardown.ps1 -EnvName aiobs2-foundry

它会删掉资源组，清除 Azure AI Services 的软删除（这样账户名能立刻复用），再验证所有资源都已移除。加 -NoPurge 可以跳过软删除清除，加 -ForceDeleteRg 还会删掉那些通过 ARM REST 在 azd 模板之外创建的告警和 action group。

2.2.4 临时流量与评估刷新

kit 部署好之后，想刷新遥测并不需要重跑完整的 13 阶段流水线。用 scripts/run-adhoc-traffic-and-eval.ps1 就能针对一个已有环境生成一批新追踪、对新追踪跑智能体批量评估、刷新遥测导出。典型用法：截一张新的仪表盘图、模型或提示改动后重新评估一次、或者在某次 Azure 平台更新之后快速确认部署还能用。

1
2
3
4

pwsh -NoProfile -File scripts\run-adhoc-traffic-and-eval.ps1 -EnvName <env-name>

For example:
pwsh -NoProfile -File scripts\run-adhoc-traffic-and-eval.ps1 -EnvName aiobs3-foundry

这个包装脚本用 -SkipPhases 1,2,3,4,5,8,11 去调 run-e2e.ps1（不请求红队时再加上 10），所以真正会跑的阶段是：

端到端总时长：默认约 15 分钟（带红队约 25 分钟）。

实时进度会同时流到控制台和日志文件，所以你也可以从另一个终端 tail 它：

1

Get-Content -Wait scripts\e2e-adhoc-run.log

参考运行记录：一份来自成功临时运行、做过脱敏的日志放在 scripts/e2e-adhoc-run.log。

3. 评估：智能体评估器与自定义检查

返回 200 OK 不代表智能体答对了。传统软件的输出是可预测的，AI 智能体不是。同一个提示在不同运行里可能给出不同响应，而且当模型更新、提示演化或工具变化时，质量也会跟着漂。没有评估，你就只能靠用户投诉来发现质量问题——往往是在损失已经造成好几天之后。这一点我印象很深，因为质量退化是那种"悄无声息"的故障。

这一节讲的是这套 kit 怎么给每条响应打分：既用 Microsoft Foundry 内置的智能体评估器，也用一个自定义的代码评估器，两者都作为批处理作业跑在 Application Insights 里存的追踪上。

3.1 两条评估路径

这套 starter kit 包含两种互补的做法，各自解决不同的需求：

3.2 智能体评估器

Microsoft Foundry 提供 9 个内置的智能体评估器，分成两类：系统评估器看端到端结果（任务遵循、任务完成、意图识别），过程评估器看工作流里的每一步（工具调用准确性、工具选择、工具输入准确性、工具输出利用、工具调用成功）。第 9 个评估器 Task Navigation Efficiency 需要 ground truth，所以不包含在默认批量运行里。

这套 kit 通过 scripts/20-agent-batch-eval.py，在一次批处理里对智能体存在 Application Insights 里的追踪跑全部 8 个评估器。

一次验证过的运行结果（11 条追踪、8 个评估器打分）：

每个评估器都需要一份 data_mapping，告诉 Foundry 去读哪些追踪字段。系统评估器需要 query + response；过程评估器再加上 tool_definitions 和 tool_calls。所有评估器还都需要 deployment_name 作为初始化参数。少了任何一个，就会得到 MissingRequiredDataMapping 错误（这是 Foundry 在提示你评估契约不完整）。如果你撞上它，检查你的 data_mapping 字典是不是包含了你要跑的评估器需要的每个字段，以及那些字段是不是真的存在于这次运行读取的 App Insights 追踪记录上。

3.3 自定义评估器：合规短语检查

内置评估器覆盖了智能体质量和工具使用，但多数团队还需要领域特定的检查。Microsoft Foundry 支持两种自定义评估器：代码型（一个返回 0.0 到 1.0 浮点数的 Python grade() 函数，确定性强，非常适合合规短语、格式检查、正则匹配这类通过/失败规则）和提示型（一段由 LLM 评判的裁判提示，适合语气、有用性这类模糊标准）。这套 kit 用一个合规免责声明检查器演示了代码型的写法。

工作流有三步：（1）在 evaluators/custom_compliance_phrase.py 里写一个 grade(sample, item) 函数，检查响应是否包含必需的免责声明短语，返回 1.0 或 0.0；（2）通过 scripts/11-custom-evaluator-register.py 把它注册到 Microsoft Foundry，脚本会上传源码、定义指标、设置通过阈值；（3）在任何批量评估的 testing_criteria 里，把它和内置评估器并列放进去。

一次验证过的运行结果（10 条追踪打分）：

compliance_check 评估器打了 40%（10 条追踪里 4 条通过）。通过的 4 条来自明确要求带免责声明的提示；失败的 6 条是没带免责声明的正常响应。把里面的逻辑换成你自己的、重新注册，同一套模式就能用在任何策略、格式或监管检查上。

交互式的替代方案：想做现场演示或一步步探索的话，notebooks/ 目录里有评估设置的 Jupyter notebook 版本：01-continuous-eval-setup.ipynb（评估组 + 规则 + 批量运行）和 02-custom-evaluator-register.ipynb（自定义评估器注册）。它们跑的是和脚本一样的 SDK 调用，但可以一格一格执行。想不打开 notebook 就把四个按顺序全跑一遍，用 notebooks/run_notebooks.ps1。

4. 红队测试：自动化安全扫描

质量评估器看的是智能体答得好不好。红队看的是它能不能被骗着答坏——那些主动想挑出有害、跑题或违反策略响应的对抗性用户。能通过质量评估的模型，在输入被精心构造去钻边界时照样可能翻车。这套 kit 用一次 Foundry 托管的扫描把这件事自动化了：生成攻击提示、以多轮对话发过去、再拿每条响应去对安全评估器打分。完整的 SDK 参考见 Run AI red teaming in the cloud。

4.1 扫描是怎么工作的

scripts/12-red-team.py 在一个脚本里搞定一切：脚本创建一个临时 prompt 智能体（redteam-prompt-agent），镜像生产智能体的模型、指令和工具定义，然后建一个带三个安全评估器（禁止行为、任务遵循、敏感数据泄露）的评估组，再加一份把 PROHIBITED_ACTIONS 风险类别映射到目标的分类法。它发起一次攻击运行，在 5 轮对话里自动生成对抗性提示，最后在 finally 块里清掉临时智能体。典型运行时长：4 到 8 分钟。

4.2 结果与解读

这次扫描用三个安全评估器（Prohibited Actions、Task Adherence、Sensitive Data Leakage）和两种攻击策略（Flip 和 Base64）。

想加更多策略——IndirectJailbreak、Tense、Morse、Crescendo 之类——往脚本的 attack_strategies 列表里塞就行。

一次验证过的运行结果（total=204，passed=139，failed=65，errored=0）：

攻击成功率（ASR）31.9%（204 条里 65 条失败）意味着攻击者在大约三分之一的尝试里诱出了不良响应。按评估器拆开看：Prohibited Actions 的 ASR 最高，38%；Sensitive Data Leakage 29%；Task Adherence 最低，21%。三种攻击策略（Base64、Baseline、Flip）表现相近，都在 31–34%，说明不管用哪种编码技巧，模型的安全姿态都差不多，也说明想实质性压低整体比率，得上自定义的安全系统提示。

每条提示的判定结果保存在 artifacts/redteam_eval_output_items_redteam-prompt-agent.json。

交互式的替代方案：notebooks/ 目录把红队工作流拆成两个 notebook：03-red-team-taxonomy.ipynb（预置分类法）和 04-red-team-run.ipynb（发起攻击运行并收集结果）。

5. 可观测性

智能体部署好、流量流起来之后，你得能看到到底发生了什么。这一节讲这套 kit 露出遥测的两种方式：给临时排查用的原始 KQL 查询，以及给日常监控用的三个仪表盘视图。

5.1 用 KQL 查遥测

scripts/13-telemetry-kql.py 对 Log Analytics 工作区跑四条查询，每条回答一个不同的运营问题。所有查询都过滤 requests 表里的 invoke_agent span。

这些正是驱动 Grafana 仪表盘面板的同一批信号。每条查询的完整 KQL 都在 scripts/13-telemetry-kql.py 里。

5.2 可视化遥测：三个查看界面

上面的 KQL 查询适合临时排查，但日常监控你会想要仪表盘。这套 starter kit 填充了三个互补的视图，各服务不同的受众。

5.3 App Insights Agents 面板

Azure Application Insights 里的 Agents（预览）面板是看智能体健康状况最快的方式。它从这套 kit 发出的 OpenTelemetry span 里自动填充，不需要导入仪表盘或做任何配置。

一次成功运行之后，这个面板会显示：

从 Application Insights > 左侧菜单 > Agents（预览）进入。把时间范围设成"Last 48 hours"，避开 15 到 30 分钟的汇总延迟。

5.4 预置的 Grafana 仪表盘

三个 Azure 托管的仪表盘开箱即用，从同一批遥测里填充：

三个里 Agent Framework 仪表盘最全，在一个视图里覆盖操作、token、工具和性能：

5.5 自定义仪表盘

这套 kit 在 artifacts/grafana/ 里附了两份可导入的仪表盘 JSON。主仪表盘（agent-observability-dashboard.json）提供一个完整的运营概览：

配套仪表盘（agent-observability-custom-dashboard.json）加了五个更聚焦的面板做深入排查（每工具 p95 延迟、错误率、会话计数）。

导入方式：Application Insights > Dashboards with Grafana > New > Import > 上传 JSON。两个都用了模板化变量，所以同一份 JSON 能跨环境用。完整走查见 docs/GRAFANA_GUIDE.md。

6. 仓库结构

先看个概览：

/
  agent/                              # azd project root
    azure.yaml                        # service definitions for 4 hosted agents
    src/
      agent-framework-agent-basic-responses/
        agent.yaml                    # primary agent (gpt-4o-mini)
        main.py                       # @tool functions + Agent() constructor
        requirements.txt              # agent-framework + foundry-hosting deps
        Dockerfile                    # container build
      agent-framework-agent-gpt5-mini/
        agent.yaml                    # sister agent (gpt-5-mini)
        main.py                       # same code, different model
      agent-framework-agent-gpt41-mini/
        agent.yaml                    # sister agent (gpt-4.1-mini)
      agent-framework-agent-broken-model/
        agent.yaml                    # deliberately broken (populates error charts)
    infra/                            # Bicep (Foundry account, ACR, Application Insights, Log Analytics)
  scripts/
    run-e2e.ps1                       # single command: provision to smoke test (13 phases)
    validate-deployment.ps1           # post-deploy validation (8 categories)
    teardown.ps1                      # single command: destroy everything + purge
    run-adhoc-traffic-and-eval.ps1    # ad-hoc traffic + eval refresh (skips infra/deploys)
    03-grant-foundry-user.ps1         # grants Foundry User role to project MI
    04-warmup.ps1                     # 3 fast pings to defeat scale-to-zero
    05-seed-traffic.ps1               # 48 prompts from clean, ambiguous, safety-bait corpora
    06b-alerts-rest.py                # 2 scheduled-query alerts via ARM REST
    10-continuous-eval.py             # evaluation rule (3 agent evaluators)
    11-custom-evaluator-register.py   # code-based compliance evaluator (grade -> float)
    12-red-team.py                    # adversarial red-team scan (temporary prompt agent)
    13-telemetry-kql.py               # KQL export (volume, latency, tokens)
    14-verify-continuous-eval.py      # verify eval runs completed
    15-list-eval-rules.py             # debug: dump eval rule definitions + runs
    16-list-rules.py                  # debug: list all evaluation rules (GA API)
    17-list-connections.py            # debug: list project connections
    18-trigger-eval-runs.py           # debug: store-based eval trigger workaround
    20-agent-batch-eval.py            # batch eval: 8 agent evaluators over Application Insights traces
  evaluators/
    custom_compliance_phrase.py       # grade(sample, item) -> float (0.0 or 1.0)
    custom_compliance_phrase.yaml     # evaluator metadata for Foundry catalog registration
  prompts/
    clean.txt                         # normal traffic prompts
    ambiguous.txt                     # edge-case prompts
    safety-bait.txt                   # 5 adversarial prompts for safety testing
  artifacts/                          # all run outputs (eval results, telemetry, dashboards)
    sample-app-request.json           # reference: OTel GenAI span shape
    sample-chat-dependency.json       # reference: LLM chat dependency span shape
    grafana/
      agent-observability-dashboard.json          # full operational dashboard (7 panels)
      agent-observability-custom-dashboard.json   # companion dashboard (5 panels)
      DASHBOARD_IMPORT_GUIDE.md                   # import walkthrough
      DASHBOARD_SUMMARY.md                        # panel descriptions
  notebooks/                          # interactive Jupyter versions for live demos
    run_notebooks.ps1                 # runs all 4 notebooks in sequence via nbconvert
    01-continuous-eval-setup.ipynb    # eval group + rule + batch run over traces
    02-custom-evaluator-register.ipynb # custom evaluator registration
    03-red-team-taxonomy.ipynb        # taxonomy creation (pre-stage)
    04-red-team-run.ipynb             # red team attack run
  docs/
    QUICKSTART.md                     # 6-command walkthrough
    MANUAL_GUIDE.md                   # step-by-step deep dive
    GRAFANA_GUIDE.md                  # Grafana dashboard setup + custom KQL panels

7. 小结与下一步

AI 可观测性不是可选的附加项，而是你有底气运营智能体系统的前提。跑过一遍我更确信这一点。这套 starter kit 把它落到了实处：一个能用的 Foundry 托管智能体、已插桩的遥测、仪表盘、批量评估、对抗性红队测试、合规检查、告警——全都一条命令预配、另一条命令拆掉。

现在就试

Fork 仓库，在你自己的订阅上端到端跑一遍：

1
2
3

git clone https://github.com/jvargh/ai-observability-starter-kit
cd ai-observability-starter-kit
pwsh -NoProfile -File scripts\run-e2e.ps1 -Region eastus2 -EnvName aiobs-foundry -SubscriptionId <your-subscription-id>

仓库地址：github.com/jvargh/ai-observability-starter-kit