AI Agent可观测性：在钉钉生态中构建透明、可控的智能体服务

引言：当AI Agent成为企业数字员工

随着生成式AI技术的爆发，AI Agent正从概念走向大规模企业级应用。在钉钉这样的超级工作平台上，AI Agent扮演着"数字员工"的角色，深度嵌入审批、客服、数据分析、知识问答等核心业务流程。然而，当企业将关键业务交由AI Agent处理时，一个根本性问题随之浮现：我们如何"看见"并理解这些智能体的内部运作？

传统的应用监控（APM）和日志系统，难以应对AI Agent的非确定性、长上下文、工具调用链等新特性。AI Agent可观测性（AI Agent Observability）应运而生，它旨在为开发者和业务管理者提供一套完整的"透视"能力，涵盖从用户意图理解、思维链推理、工具执行到最终响应的全过程。

本文将从典铭云赛作为钉钉核心服务商的视角，结合我们实践中总结的FDE（框架-数据-体验）服务模式 ，深入探讨如何在钉钉生态中为企业构建高效、可靠的AI Agent可观测性体系。

什么是AI Agent可观测性？

可观测性（Observability）源于控制理论，指通过系统外部输出来推断其内部状态的能力。对于AI Agent，这意味着我们需要超越简单的"输入-输出"日志，捕获其决策过程中的关键信号。

一个完整的AI Agent可观测性体系应包含三个核心支柱：

链路追踪（Tracing）：完整记录单次用户会话中，AI Agent的完整"思考"与"行动"链条。这包括：
- 用户意图解析：原始Query经过Prompt工程处理后的实际意图。
- 思维链（CoT）：大模型内部的推理步骤（如果可获取）。
- 工具调用（Tool Calling）：调用了哪些API、数据库或函数，传入参数与返回结果。
- 多轮对话上下文：历史对话对当前决策的影响。
指标度量（Metrics）：量化AI Agent的性能与成本，例如：
- 性能指标：响应延迟（Latency）、每秒处理请求数（TPS）。
- 质量指标：任务完成率、工具调用成功率、用户满意度（通过反馈收集）。
- 成本指标：Token消耗量（区分输入/输出）、API调用费用。
- 业务指标：通过Agent处理的工单数量、审批效率提升百分比。
日志与事件（Logging & Events）：记录详细的运行时信息与关键事件，用于调试与审计：
- 结构化日志：每次LLM调用的请求与响应体（可脱敏）、工具执行的输入输出。
- 异常事件：模型调用失败、工具异常、内容安全拦截。
- 会话事件：会话开始、主题识别、会话结束。

#mermaid-svg-nUSwH0WMHoXVbdDz{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-nUSwH0WMHoXVbdDz .error-icon{fill:#552222;}#mermaid-svg-nUSwH0WMHoXVbdDz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-nUSwH0WMHoXVbdDz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-nUSwH0WMHoXVbdDz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-nUSwH0WMHoXVbdDz .marker.cross{stroke:#333333;}#mermaid-svg-nUSwH0WMHoXVbdDz svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-nUSwH0WMHoXVbdDz p{margin:0;}#mermaid-svg-nUSwH0WMHoXVbdDz .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz .cluster-label text{fill:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz .cluster-label span{color:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz .cluster-label span p{background-color:transparent;}#mermaid-svg-nUSwH0WMHoXVbdDz .label text,#mermaid-svg-nUSwH0WMHoXVbdDz span{fill:#333;color:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz .node rect,#mermaid-svg-nUSwH0WMHoXVbdDz .node circle,#mermaid-svg-nUSwH0WMHoXVbdDz .node ellipse,#mermaid-svg-nUSwH0WMHoXVbdDz .node polygon,#mermaid-svg-nUSwH0WMHoXVbdDz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-nUSwH0WMHoXVbdDz .rough-node .label text,#mermaid-svg-nUSwH0WMHoXVbdDz .node .label text,#mermaid-svg-nUSwH0WMHoXVbdDz .image-shape .label,#mermaid-svg-nUSwH0WMHoXVbdDz .icon-shape .label{text-anchor:middle;}#mermaid-svg-nUSwH0WMHoXVbdDz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-nUSwH0WMHoXVbdDz .rough-node .label,#mermaid-svg-nUSwH0WMHoXVbdDz .node .label,#mermaid-svg-nUSwH0WMHoXVbdDz .image-shape .label,#mermaid-svg-nUSwH0WMHoXVbdDz .icon-shape .label{text-align:center;}#mermaid-svg-nUSwH0WMHoXVbdDz .node.clickable{cursor:pointer;}#mermaid-svg-nUSwH0WMHoXVbdDz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-nUSwH0WMHoXVbdDz .arrowheadPath{fill:#333333;}#mermaid-svg-nUSwH0WMHoXVbdDz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-nUSwH0WMHoXVbdDz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-nUSwH0WMHoXVbdDz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-nUSwH0WMHoXVbdDz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-nUSwH0WMHoXVbdDz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-nUSwH0WMHoXVbdDz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-nUSwH0WMHoXVbdDz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-nUSwH0WMHoXVbdDz .cluster text{fill:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz .cluster span{color:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-nUSwH0WMHoXVbdDz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-nUSwH0WMHoXVbdDz rect.text{fill:none;stroke-width:0;}#mermaid-svg-nUSwH0WMHoXVbdDz .icon-shape,#mermaid-svg-nUSwH0WMHoXVbdDz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-nUSwH0WMHoXVbdDz .icon-shape p,#mermaid-svg-nUSwH0WMHoXVbdDz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-nUSwH0WMHoXVbdDz .icon-shape .label rect,#mermaid-svg-nUSwH0WMHoXVbdDz .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-nUSwH0WMHoXVbdDz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-nUSwH0WMHoXVbdDz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-nUSwH0WMHoXVbdDz :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} "用户向钉钉AI Agent提问"
"可观测性数据采集层"
"链路追踪

Tracing"
"指标度量

Metrics"
"日志与事件

Logging"
"思维链记录"
"工具调用图谱"
"会话链路可视化"
"性能面板

延迟/TPS"
"质量看板

成功率/满意度"
"成本分析

Token/API费用"
"调试日志查询"
"异常告警"
"审计报表"
"统一可观测性平台"
"开发者

问题排查与优化"
"运维人员

监控与告警"
"业务负责人

效果分析与决策"

钉钉生态下的独特挑战与机遇

在钉钉平台部署和观测AI Agent，面临一系列独特场景：

多端入口与统一身份：Agent可能通过群聊、单聊、工作台、审批流等多种渠道被触发，但需要基于统一的钉钉用户身份体系串联所有行为链路。
丰富的开放能力：钉钉提供了消息、待办、日历、审批、钉盘等大量OpenAPI。Agent对这些工具的调用过程必须被清晰记录，以验证其操作合规性与准确性。
企业级安全与合规：所有交互数据需满足企业数据不出域、隐私保护等要求。可观测性方案本身必须具备数据脱敏、访问控制等安全特性。
与钉钉原生体验融合：可观测性的结果呈现（如管理后台、数据报表）最好能与钉钉管理后台或宜搭低代码平台集成，降低管理员的学习成本。

机遇在于，钉钉的开放生态和标准化接口，恰恰为构建统一的可观测性数据模型提供了基础。例如，所有工具调用都可以规范化为"钉钉API调用"事件进行采集。

典铭云赛的FDE服务模式实践

作为钉钉的深度服务商，典铭云赛在服务众多企业客户的过程中，沉淀出了FDE（Framework-Data-Experience）服务模式，并将其应用于AI Agent可观测性领域。

1. Framework（框架）：提供开箱即用的采集与接入框架

我们提供轻量化的SDK和Agent框架插件，让开发者在构建钉钉AI Agent时，能以最低成本接入可观测性。

python 复制代码

# 示例：在钉钉AI Agent应用初始化时集成可观测性SDK
from dianming_observability_sdk import ObservabilityClient, DingTalkHook

def create_agent():
    # 初始化客户端，传入钉钉企业信息
    obs_client = ObservabilityClient(
        corp_id="your_corp_id",
        agent_id="your_agent_id",
        # 自动挂钩钉钉消息事件、API调用事件
        hooks=[DingTalkHook()]
    )
    
    # 创建Agent，SDK会自动装饰工具函数和LLM调用
    agent = create_dingtalk_agent(
        name="财务审批助手",
        observability_client=obs_client
    )
    return agent

该框架会自动完成：

会话链路标识 ：自动关联钉钉的chatId, userId, msgId。
工具调用埋点 ：对Agent使用的@Function或工具装饰器进行自动埋点，记录输入、输出、耗时。
LLM调用拦截：记录向大模型发送的Prompt和返回的Completion，计算Token消耗。

2. Data（数据）：构建统一的可观测性数据平台

采集到的原始数据经过清洗、脱敏、关联后，存入专为AI Agent场景优化的数据模型中。

sql 复制代码

-- 简化的可观测性核心数据表示例
CREATE TABLE ai_agent_trace (
    trace_id VARCHAR(64) PRIMARY KEY, -- 全局唯一链路ID
    session_id VARCHAR(64), -- 钉钉会话ID
    user_id VARCHAR(64), -- 钉钉用户ID
    agent_name VARCHAR(128), -- Agent名称
    start_time TIMESTAMP,
    end_time TIMESTAMP,
    status ENUM('success', 'failure', 'partial'),
    total_token_usage INT, -- 总Token消耗
    total_latency_ms INT -- 总耗时
);

CREATE TABLE trace_span (
    span_id VARCHAR(64) PRIMARY KEY,
    trace_id VARCHAR(64),
    parent_span_id VARCHAR(64),
    span_type ENUM('llm_call', 'tool_call', 'knowledge_retrieval', 'reasoning'),
    operation_name VARCHAR(256), -- 例如："call_openai_gpt4", "approve_leave_request"
    start_time TIMESTAMP,
    duration_ms INT,
    input_text TEXT, -- 输入（可脱敏）
    output_text TEXT, -- 输出（可脱敏）
    metadata JSON -- 扩展信息，如模型名称、工具参数
);

基于此数据模型，我们可以轻松回答以下问题：

"昨天'财务助手'处理的所有报销审批中，平均每个会话调用了多少次钉钉审批API？"
"哪个工具函数耗时最长，成为性能瓶颈？"
"用户'张三'上周与Agent的对话中，有哪些问题因知识库缺失而未能解决？"

3. Experience（体验）：面向不同角色的价值呈现

数据只有被理解和使用才能产生价值。我们为不同角色提供差异化的数据体验：

开发者/运维者 ：提供类似分布式链路追踪的可视化界面，可以下钻查看单次会话的完整思维链和工具调用树，快速定位调用超时或异常的根本原因。
AI训练师/产品经理 ：提供质量分析看板，关注任务完成率、用户反馈（如钉钉消息的"点赞/点踩"）、意图识别准确率等，用于持续优化Prompt和Agent工作流。
企业管理员/财务 ：提供成本与效能报表，展示各部门、各Agent的Token消耗趋势、API调用费用，并与业务成果（如流程自动化率、客服问题解决率）关联分析，计算AI投入产出比（ROI）。

核心价值：从"黑盒"到"白盒"，驱动智能体持续进化

构建AI Agent可观测性体系，最终是为了实现三个层面的价值闭环：

稳定性保障：实时监控Agent健康度，对异常错误、响应延迟、工具失败等进行预警，确保企业关键业务流不被中断。
性能与成本优化：通过分析链路数据，识别无效的LLM调用、冗余的工具步骤，优化工作流设计，从而降低Token消耗，提升响应速度。
效果迭代与业务赋能：通过分析用户与Agent的成功/失败交互案例，不断优化知识库、Prompt模板和工具集，让Agent越用越"聪明"，真正成为提升员工效率的业务助手。

总结与展望

在钉钉生态中，AI Agent不再是孤立的聊天机器人，而是融入组织血脉的"数字同事"。可观测性是管理好这位"同事"的必备能力。它让不可控的AI变得可控，让不可解释的决策变得有迹可循。

典铭云赛基于FDE服务模式，将可观测性从"附加功能"变为"基础设施"，帮助企业在享受AI Agent带来的效率红利时，也能拥有十足的掌控感与安全感。未来，随着智能体能力的进一步复杂化（如多Agent协作、自主规划），可观测性体系也将向更细粒度、更富语义的方向演进，成为企业AI战略中不可或缺的基石。

立即行动：如果您正在或计划在钉钉上部署AI Agent，建议在项目设计初期就将可观测性纳入架构考量。从第一条链路被记录开始，您就踏上了构建可信、可靠、可进化智能体的正确道路。