mcpField
S
sf-ai-agentforce-observability

sf-ai-agentforce-observability

github.com/jaganproAgent 工作流4241.3k 次安装26 周前更新
代码仓库

关于 sf-ai-agentforce-observability

sf-ai-agentforce-observability 是用于提取和分析 Salesforce Agentforce 会话追踪遥测数据的技能，支持基于追踪记录调试 Agent，并使用 Parquet 和 Polars 分析大型数据集。

主要功能

  1. 01通过 Data 360 API 提取会话追踪数据
  2. 02将遥测数据保存为 Parquet 文件
  3. 03使用 Polars 分析大型数据集
  4. 04重建会话时间线
  5. 05排查路由、失败与延迟问题

适用场景

  1. 01查看 Agentforce 会话量和时长
  2. 02定位主题路由不匹配及操作失败
  3. 03查找 Agent 会话中的延迟热点

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jaganpro/sf-skills --skill sf-ai-agentforce-observability

安装后在 Claude Code 中输入/sf-ai-agentforce-observability确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
CREDITS.md
LICENSE
README.md
assets/analysis/
message-timeline.py
session-summary.py
step-distribution.py
assets/queries/
interactions.sql
messages.sql
sessions.sql
steps.sql
hooks/scripts/
suggest-analysis.py
validate-extraction.py
references/
agent-execution-lifecycle.md
analysis-cookbook.md
analysis-examples.md
auth-setup.md
basic-extraction.md
billing-and-troubleshooting.md
builder-trace-api.md
cli-reference.md
client-demo-queries.md
data-model-reference.md
debugging-sessions.md
filtered-extraction.md
polars-cheatsheet.md
query-patterns.md
troubleshooting.md
scripts/
__init__.py
analyzer.py

详细介绍

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

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

此技能负责的任务

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

  • Data 360 / 会话追踪提取
  • Agentforce 遥测数据中的 .parquet 文件
  • 重建会话时间线
  • 基于追踪数据调试主题路由、操作失败或延迟
  • 使用 Polars / PyArrow 分析大型遥测数据集

以下情况请交由其他技能处理：

必须满足的先决条件

提取前，请确认：

  • 已启用 Data 360
  • 已启用会话追踪
  • Salesforce 标准数据模型版本符合要求
  • 已在组织中启用 Einstein / Agentforce 功能
  • 已配置用于访问 Data 360 的 JWT / ECA 身份验证

如果缺少身份验证配置，请转交给：

详细设置指南：

此技能处理的内容

核心存储 / 分析模型
  • 通过 Data 360 API 提取
  • 使用 Parquet 提高存储效率
  • 使用 Polars 对大型数据集进行延迟分析
核心 STDM 实体

至少需要处理以下内容：

  • 会话
  • 交互 / 轮次
  • 交互步骤
  • 时刻
  • 消息

GenAI 信任层 / 审计记录也可能与内容质量和生成调试相关。

完整架构：

首先收集必要的上下文

询问或推断：

  • 目标组织别名
  • 时间窗口或日期范围
  • 是否需要筛选 Agent
  • 目标是提取数据、汇总分析，还是调试单个会话
  • 提取数据的输出位置
  • 用户是否已在磁盘上保存 Parquet 文件

推荐工作流

1. 验证设置和身份验证

确认 Data 360 追踪数据可用，并且 JWT/ECA 身份验证正常工作。

2. 选择提取模式
需求默认方法
最近的遥测数据快照提取最近 N 天的数据
有针对性的调查按日期和 Agent 筛选后提取
某个对话出现故障提取或调试单个会话树
持续使用情况分析增量提取
3. 提取为 Parquet

使用 scripts/ 下提供的脚本，不要重新实现提取逻辑。

4. 使用 Polars 分析

常见分析目标：

  • 会话数量和时长
  • 主题分布
  • 操作步骤失败情况
  • 延迟热点
  • 会话中止 / 升级模式
  • 会话级时间线重建
5. 将发现转化为后续行动

常见结果：

  • 主题不匹配 → 改进路由或描述
  • 操作失败 → 检查 Flow / Apex 实现
  • 延迟问题 → 优化下游操作路径
  • 测试覆盖缺口 → 添加有针对性的 Agent 测试

高优先级操作规则

  • 将 STDM 视为只读遥测数据
  • 预期数据摄取存在延迟；这并非完美的实时调试方式
  • 使用日期筛选和有针对性的提取，避免不必要的数据量 / 查询成本
  • 持久化分析时优先使用 Parquet，而非临时 JSON
  • 对大型数据集使用 Polars 延迟计算模式

常见问题：

  • 误以为缺少数据就代表没有问题，而实际可能只是未启用追踪
  • 不设置日期或 Agent 筛选条件就运行大范围查询
  • 在此技能中尝试修复 Agent，而不是转交给编写 / 测试技能

输出格式

完成后，按以下顺序报告：

  1. 提取或分析了哪些数据
  2. 范围（组织、日期、Agent 筛选条件、会话 ID）
  3. 关键发现
  4. 可能的根本原因
  5. 建议的下一项技能 / 后续操作

建议格式：

Observability task: <extract / analyze / debug-session>
Scope: <org, dates, agents, session ids>
Artifacts: <directories / parquet files>
Findings: <latency, routing, action, quality, abandonment patterns>
Root cause: <best current explanation>
Next step: <testing, agent fix, flow fix, apex fix>

跨技能集成

需求委派给原因
身份验证 / JWT 设置sf-connected-appsData 360 访问
修复 Agent 路由 / 行为sf-ai-agentscript编写修正
正式回归 / 覆盖率测试sf-ai-agentforce-testing可复现的测试循环
基于 Flow 的操作调试sf-flow声明式修复
基于 Apex 的操作调试sf-debug 或 sf-apex代码 / 日志调查

参考索引

从这里开始
数据模型 / 查询
分析 / 调试
身份验证 / 故障排除

评分指南

分数含义
90+有强有力的遥测数据支持的诊断
75–89有参考价值的分析，只有少量缺漏
60–74可见信息不完整
< 60证据不足；收集更多遥测数据

评论

支持 Markdown