---
cuppy_hub: salesforce
cuppy_path: reference/agentforce/agent-observability.md
cuppy_section: docs
cuppy_doc: CKRV-D4MF
cuppy_doc_uuid: 3f897003-8851-45e8-984f-9268b647743a
cuppy_permalink: https://cuppy.io/salesforce/d/CKRV-D4MF
cuppy_version: 2
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/salesforce/docs/reference/agentforce/agent-observability
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: ffe87a8e6aad0210df3b00b5f59a813654a794b46615dadda537e2e37ada0d42
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# Agent observability

| Question | Look at |
|---|---|
| Why did my draft agent pick that subagent or action? | Preview traces, read with `sf agent trace` |
| Why did my Apex action fail inside the agent? | Live preview with `--apex-debug`, then the Apex Replay Debugger |
| What happened in production yesterday? | Session Tracing in Data 360 |
| Does my agent still pass after a change? | Agent tests (`reference/agentforce/agent-testing.md`) |

## Preview traces (development)

Every `sf agent preview` turn records a trace in the project: `.sfdx/agents/<agent>/sessions/<sessionId>/traces/<planId>.json`, per Salesforce's sf-skills. Keep `.sfdx/` out of git. Transcripts save to `./temp/agent-preview` (`--output-dir` changes it).

```bash
sf agent trace list --agent Steward_Agent --since 2026-10-23
sf agent trace read --session-id <id>                                  # per-turn summary
sf agent trace read --session-id <id> --format detail --dimension actions --turn 2
sf agent trace read --session-id <id> --format raw                     # the JSON, for your own analysis
sf agent trace delete --older-than 7d --no-prompt
```

| `--dimension` (with `--format detail`) | Shows |
|---|---|
| `actions` | Each action run: name, inputs, output, latency |
| `grounding` | The LLM's reasoning steps |
| `routing` | Moves between subagents, and why |
| `errors` | Every error in the session |

**Raw trace steps** (the `plan[]` array), per sf-skills:

| Step type | Holds |
|---|---|
| `NodeEntryStateStep` | The subagent entered |
| `EnabledToolsStep` | Which tools were visible (check `available when`) |
| `BeforeReasoningIterationStep` | The actions about to run |
| `ReasoningStep` | Grounding category and reason |
| `VariableUpdateStep` | Each variable's old value, new value and why it changed |
| `PlannerResponseStep` | The reply, with its safety score |

If parsing fails, the trace schema may have changed: "Try "--format raw" to access unprocessed trace data."

`--apex-debug` on `sf agent preview` captures Apex debug logs during a live preview. Replay them in VS Code with the Apex Replay Debugger.

## Production: Session Tracing in Data 360

**Turn it on:** in Setup, search for **Einstein Generative AI**, open **Einstein Audit, Analytics, and Monitoring Setup**, and turn on **Agentforce Session Tracing** and **Audit and Feedback**. Data 360 must be provisioned. Sessions are then stored in the Session Trace Data Model, queryable with Data 360 SQL (`reference/data360/object-model-and-apis.md`).

| Object (`ssot__<Name>__dlm`) | One row per | Useful fields |
|---|---|---|
| `AiAgentSession` | Conversation | start and end, channel, end type, final variables |
| `AiAgentSessionParticipant` | Agent or user in it | `AiAgentApiName` (filter on this) |
| `AiAgentInteraction` | Turn | `TopicApiName` (the subagent), timings, telemetry trace ID |
| `AiAgentInteractionMessage` | Message | `Input` or `Output`, text |
| `AiAgentInteractionStep` | Step | type (`TOPIC_STEP`, `LLM_STEP`, `ACTION_STEP`, `TRUST_GUARDRAILS_STEP`, `SESSION_END`), name, input, output, error, variables before and after |
| `AiAgentMoment` + `AiAgentTagAssociation` → `AiAgentTag` | User intent | LLM summaries of request and response, a 1–5 quality score with its reasoning |

The full prompt and response of each LLM step are in `GenAIGatewayRequest__dlm.prompt__c` and `GenAIGeneration__dlm.responseText__c`. They are joined on the step's gateway request and generation IDs, and filled only when **Audit and Feedback** is on. They can contain customer data, so treat access to them like access to the conversations.

**Export one session as OpenTelemetry (beta):**
- `GET /services/data/v66.0/einstein/audit/otel/{session-id}` with an OAuth token from an External Client App returns OTLP `ResourceSpans`.
- Only sessions that started in the last **72 hours** are available, and only one session per request.
- Salesforce Connect API rate limits apply.

**Event logs:** `enable_enhanced_event_logs: True` in the Agent Script `config` block, or `--enrich-logs true` on `sf agent generate agent-spec`, adds conversation data to the agent's event logs.

**Alerts:** Salesforce's `agentforce-observe` skill also manages Agent Health Monitoring alerts. The hub hasn't verified that API.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->