Record one event when the run finishes
Send the event when your application knows the final result. Check the stored fields before using them in a dashboard or evaluation.
- 1
Run completes
The application knows the final status, tools, handoff, duration, tokens, and cost.
- 2
Send the event
Send only the fields and identifiers you have approved. Leave prompts and tool payloads out.
- 3
Check the test event
Inspect required types, privacy fields, retries, and one known alternate outcome.
- 4
Compare results
Query quality, reliability, and cost per result by feature and release.
Grain
One terminal outcome per logical agent run.
Owner
Agent orchestrator after the product outcome is determined
Emit when
After success, failure, cancellation, or human handoff becomes final.
Field contract
Field types and data to exclude
Keep field names and types stable once production queries depend on them. Document optional fields and add them only when they answer a specific question.
| Field | Type | Required | Privacy | Meaning |
|---|---|---|---|---|
| timestamp_utc | timestamp | yes | non-sensitive | UTC time when the operation finishes. |
| event_id | string | yes | non-sensitive | Stable unique identifier used for deduplication. |
| release | string | yes | non-sensitive | Application or service version that emitted the event. |
| account_id | string | yes | pseudonymous | Stable internal account identifier, never an email or name. |
| run_id | string | yes | pseudonymous | Stable identifier shared by approved step-level events. |
| workflow | string | yes | non-sensitive | Versioned product workflow handled by the agent. |
| status | string | yes | non-sensitive | Success, failed, cancelled, or human_handoff. |
| tool_call_count | number | yes | non-sensitive | Total tool calls in the logical run. |
| estimated_cost_usd | number | no | non-sensitive | Versioned estimated provider cost allocation. |
| task_completed | boolean | yes | non-sensitive | Reviewed product-level success definition. |
Synthetic JSON event
{
"timestamp_utc": "2026-07-29T09:29:40Z",
"event_id": "evt_agent_01",
"account_id": "acct_8f31",
"release": "2026.07.3",
"run_id": "run_f28c",
"workflow": "support_resolution_v3",
"status": "success",
"tool_call_count": 3,
"estimated_cost_usd": 0.021,
"task_completed": true
}Privacy review
Review identifiers before ingestion
This example uses synthetic identifiers. Pseudonymous values can still be personal data, and review fields can expose business or provider context. Apply your own consent, retention, access, residency, and deletion requirements.
account_id: pseudonymousrun_id: pseudonymous
Validation checklist
Test the schema before building a dashboard
- Send one known ai_agent_run_completed fixture after the documented outcome boundary.
- Verify all 9 required fields arrive with the documented types.
- Retry the same event identifier and confirm the chosen deduplication behavior.
- Send a controlled failure or alternate outcome when the workflow supports one.
- Run the related SQL over a fixed window and reconcile the result to the fixture.
Common mistakes
Record one result per row
- Emitting ai_agent_run_completed before agent orchestrator after the product outcome is determined knows the final outcome.
- Mixing different kinds of results in one table, which makes counts and rates ambiguous.
- Replacing controlled categories with raw URLs, payloads, prompts, or error text.
- Changing a field type in place after saved queries and dashboards depend on it.
- Adding identifiers without a documented investigation, access, and retention need.
Use the contract
Query the event and set up monitoring
Related contracts
Send a test event before production traffic
Create a free API key, send the synthetic event, and inspect the inferred table before connecting a live workflow.