sf-ai-agentforce-observability：Agentforce 会话追踪提取与分析

当用户需要基于追踪（trace-based）的可观测性能力，而不仅仅是测试时，请使用该技能：提取会话追踪数据模型（STDM）记录、处理 Parquet 数据集、重建会话时间线、分析主题/动作延迟，或基于 Data 360 遥测数据调试智能体行为。

该技能主导任务的适用场景

当工作涉及以下内容时，请使用 sf-ai-agentforce-observability：

• Data 360 / 会话追踪数据提取
• 来自 Agentforce 遥测的 .parquet 文件
• 会话时间线重建
• 基于追踪的调试（如主题路由异常、动作失败、延迟问题）
• 基于 Polars / PyArrow 的大规模遥测数据集分析

当用户处于以下情形时，请移交至其他技能：

• 对智能体进行正式测试 → sf-ai-agentforce-testing
• 调试 Apex 日志 → sf-debug
• 编写或重新配置智能体本身 → sf-ai-agentforce 或 sf-ai-agentscript

必需的前置条件

执行提取前，请确认以下条件均已满足：

• Data 360 已启用
• 会话追踪（Session Tracing）已启用
• Salesforce 标准数据模型（Standard Data Model）版本足够新
• 组织（org）中已启用 Einstein / Agentforce 功能
• 已为 Data 360 访问配置 JWT / ECA 认证

若认证缺失，请移交至：

• sf-connected-apps

深度配置指南：

• references/auth-setup.md

该技能支持的数据与工具

核心存储与分析模型

• 通过 Data 360 API 执行提取
• 采用 Parquet 实现高效存储
• 使用 Polars 进行大规模惰性（lazy）分析

核心 STDM 实体

至少需围绕以下实体开展工作：

• session
• interaction / turn
• interaction step
• moment
• message

GenAI Trust Layer / 审计记录也可能与内容质量评估及生成过程调试相关。

完整数据模型定义：

• references/data-model-reference.md

需优先获取的上下文信息

请主动询问或推断以下信息：

• 目标 org 别名
• 时间窗口或日期范围
• 是否指定智能体过滤条件
• 目标是数据提取、汇总分析，还是单一会话调试
• 提取数据的输出位置
• 用户本地磁盘是否已存在 Parquet 文件

推荐工作流程

1. 验证环境与认证状态

确认 Data 360 追踪功能可用，且 JWT/ECA 认证正常工作。

2. 选择提取模式

3. 提取至 Parquet

请直接使用 scripts/ 目录下提供的脚本，而非重新实现提取逻辑。

4. 使用 Polars 进行分析

常见分析目标包括：

• 会话数量与持续时间
• 主题分布
• 动作步骤失败情况
• 延迟热点（latency hotspots）
• 放弃率 / 升级模式（abandonment / escalation patterns）
• 会话级时间线重建

5. 将分析结果转化为后续行动

典型产出包括：

• 主题不匹配 → 优化路由策略或主题描述
• 动作失败 → 检查 Flow / Apex 实现
• 延迟问题 → 优化下游动作调用路径
• 测试覆盖缺口 → 补充针对性的智能体测试

高价值运维准则

• 将 STDM 视为只读遥测数据
• 预期存在数据摄入延迟；本技能不适用于精确实时调试
• 务必使用日期过滤与定向提取，避免无谓的数据量与查询开销
• 持久化分析应优先选用 Parquet，而非临时 JSON 格式
• 处理大规模数据集时，请采用 Polars 的惰性计算模式（lazy patterns）

常见误区：

• 将数据缺失误判为无问题，而实际可能仅因未启用追踪功能
• 未加日期或智能体过滤即执行大范围宽泛查询
• 试图在本技能内直接修复智能体逻辑，而非移交至智能体编写/测试相关技能

输出格式

任务结束时，请按如下顺序汇报：

1. 所提取或分析的数据内容
2. 分析范围（org、日期、智能体过滤条件、会话 ID 列表）
3. 关键发现
4. 可能的根本原因
5. 建议的下一技能或具体操作

推荐输出结构示例：

Observability task: 
Scope: 
Artifacts: 
Findings: 
Root cause: 
Next step: 

跨技能协同集成

参考文档地图

入门必读

• README.md
• references/basic-extraction.md
• references/filtered-extraction.md
• references/cli-reference.md

数据模型与查询

• references/data-model-reference.md
• references/query-patterns.md
• references/client-demo-queries.md

分析与调试

• references/analysis-cookbook.md
• references/analysis-examples.md
• references/debugging-sessions.md
• references/polars-cheatsheet.md
• references/agent-execution-lifecycle.md

认证与故障排查

• references/auth-setup.md
• references/troubleshooting.md
• references/billing-and-troubleshooting.md
• references/builder-trace-api.md
• scripts/

评分指南