sf-ai-agentforce-observability

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: sf-ai-agentforce-observability
description: >
  Agentforce session tracing extraction and analysis.
  TRIGGER when: user extracts STDM data from Data Cloud, analyzes agent session
  traces, debugs agent conversations via telemetry, or works with .parquet files
  from Agentforce.
  DO NOT TRIGGER when: testing agents (use sf-ai-agentforce-testing), Apex debug
  logs (use sf-debug), or building agents (use sf-ai-agentforce).
license: MIT
compatibility: "Requires Data 360 enabled org with Agentforce Session Tracing"
metadata:
  version: "1.0.0"
  author: "Jag Valaiyapathy"
  data_model: "Session Tracing Data Model (STDM)"
  storage_format: "Parquet (via PyArrow)"
  analysis_library: "Polars"
---

# sf-ai-agentforce-observability: Agentforce Session Tracing Extraction & Analysis

Use this skill when the user needs **trace-based observability**, not just testing: extract Session Tracing Data Model (STDM) records, work with Parquet datasets, reconstruct session timelines, analyze topic/action latency, or debug agent behavior from Data 360 telemetry.

## When This Skill Owns the Task

Use `sf-ai-agentforce-observability` when the work involves:
- Data 360 / Session Tracing extraction
- `.parquet` files from Agentforce telemetry
- session timeline reconstruction
- trace-driven debugging of topic routing, action failures, or latency
- Polars / PyArrow-based analysis of large telemetry datasets

Delegate elsewhere when the user is:
- formally testing agents → [sf-ai-agentforce-testing](../sf-ai-agentforce-testing/SKILL.md)
- debugging Apex logs → [sf-debug](../sf-debug/SKILL.md)
- authoring or reconfiguring the agent itself → [sf-ai-agentforce](../sf-ai-agentforce/SKILL.md) or [sf-ai-agentscript](../sf-ai-agentscript/SKILL.md)

---

## Prerequisites That Must Exist

Before extraction, verify:
- Data 360 is enabled
- Session Tracing is enabled
- the Salesforce Standard Data Model version is sufficient
- Einstein / Agentforce capabilities are enabled in the org
- JWT / ECA auth for Data 360 access is configured

If auth is missing, hand off to:
- [sf-connected-apps](../sf-connected-apps/SKILL.md)

Deep setup guide:
- [references/auth-setup.md](references/auth-setup.md)

---

## What This Skill Works With

### Core storage / analysis model
- extraction via Data 360 APIs
- Parquet for storage efficiency
- Polars for large-scale lazy analysis

### Core STDM entities
At minimum, expect work around:
- session
- interaction / turn
- interaction step
- moment
- message

GenAI Trust Layer / audit records may also be relevant for content-quality and generation debugging.

Full schema:
- [references/data-model-reference.md](references/data-model-reference.md)

---

## Required Context to Gather First

Ask for or infer:
- target org alias
- time window or date range
- agent filter, if any
- whether the goal is extraction, summary analysis, or single-session debugging
- output location for extracted data
- whether the user already has Parquet files on disk

---

## Recommended Workflow

### 1. Verify setup and auth
Confirm Data 360 tracing exists and JWT/ECA auth is working.

### 2. Choose the extraction mode
| Need | Default approach |
|---|---|
| recent telemetry snapshot | extract last N days |
| focused investigation | filtered extraction by date and agent |
| one broken conversation | extract or debug a single session tree |
| ongoing usage analytics | incremental extraction |

### 3. Extract to Parquet
Use the provided scripts under `scripts/` rather than reimplementing extraction logic.

### 4. Analyze with Polars
Common analysis goals:
- session volume and duration
- topic distribution
- action step failures
- latency hotspots
- abandonment / escalation patterns
- session-level timeline reconstruction

### 5. Convert findings into next actions
Typical outcomes:
- topic mismatch → improve routing or descriptions
- action failure → inspect Flow / Apex implementation
- latency issue → optimize downstream action path
- test gap → add ta