| +-- AiAgentTagDefinition (1)-- tag type definition
AiRetrieverQualityMetric (N) -- RAG quality scores, linked via gateway request ID
```
**Quality score join chain:** `AiAgentTagAssociation` (FK `AiAgentMomentId` + FK `AiAgentTagId`) -> `AiAgentTag.Value` (1-5 integer). The `AssociationReasonText` field contains the LLM-generated reasoning for the score.
{'name': 'InstructionAdherence', 'value': 'HIGH', 'explanation': 'This response adheres to the assigned instructions.'}
```
Check for adherence by searching for `'value': 'LOW'` in the output string.
-`step.input` contains the raw `input_text` and `output_text` that were evaluated
-`step.error` may contain the literal string `"None"` (not a real error)
- Does **not** count toward `action_error_count`
---
## Data Quality Notes
**`NOT_SET` sentinel.** Data Cloud uses `"NOT_SET"` for null/absent values. `AgentforceOptimizeService` strips this sentinel -- any field returning `null` in the JSON should be treated as absent.
**`TRUST_GUARDRAILS_STEP` error field.** May have the Python string `"None"` in the error field. This is **not** a real error -- treat it as absent. `action_error_count` is only incremented for `ACTION_STEP` errors.
**Null `end_time` / `duration_ms`.** Sessions and turns may have `null` for `end_time` when no session-end event was recorded. This is common and does not indicate a problem.
**`LLM_STEP` input/output format.** The `input` and `output` fields on `LLM_STEP` contain raw Python dict strings (the internal LlamaIndex representation), not valid JSON. Do not attempt to `JSON.parse()` these values. Only `ACTION_STEP` input/output is structured JSON.
**Participant ID format inconsistency.** The `ssot__AiAgentSessionParticipant__dlm` DMO stores `ssot__ParticipantId__c` as either 15-char or 18-char Salesforce IDs, inconsistently. `AgentforceOptimizeService.resolvePlannerIds()` automatically handles both formats.
---
## Data Space Name
Always run Phase 0 first to discover the correct Data Space `name` for the org. Use `sf api request rest "/services/data/v63.0/ssot/data-spaces" -o <org>` (no `--json` flag -- unsupported on this beta command). Never assume `'default'` without checking -- it is only a fallback if the API call fails.
---
## Agent Name Resolution Reference
The only Salesforce metadata object that should be queried directly is `GenAiPlannerDefinition` -- used exclusively for agent name resolution in the Routing step.
| Object | Purpose | When to query |
|---|---|---|
| `GenAiPlannerDefinition` | The agent definition | Routing step only -- to resolve `MasterLabel`, `DeveloperName`, and `Id` |
| `DataKnowledgeSpace` | Knowledge base container | Phase 1.5b Step 5 only -- if knowledge gaps are detected |
**Do NOT query these objects directly** -- use the `.agent` file instead:
-`GenAiPluginDefinition` (subagents) -- read from `.agent` file `subagent:` blocks
-`GenAiPluginInstructionDef` (instructions) -- read from `.agent` file `reasoning: instructions:` blocks
-`GenAiFunction` (actions) -- read from `.agent` file `reasoning: actions:` blocks
The `.agent` file is the single source of truth. All fixes should be applied to it and deployed via the Phase 3 deployment chain.
