Executive summary
An agentic trace should connect a stable task and case to the originating principal, executing workload, agent and model versions, context references, planning steps, policy decisions, tool contracts, verified external effects, state transitions, human decisions, artifacts, budgets, retries, reconciliation, and stop reason. Sensitive prompts, retrieved documents, and tool payloads should be opt-in rather than the default. The schema in this article is a LongTermCapabilities operating model that can map to emerging OpenTelemetry GenAI conventions without depending on one framework's log format.
Decision relevance: Define the minimum trace evidence needed to explain, evaluate, secure, operate, and recover one agentic workflow.
Machine-readable template
Agent observability trace schema
{
"schema": "longtermcapabilities-agentic-trace/v1",
"trace_id": "trace-example",
"task": {
"task_id": "task-example",
"case_id": "case-example",
"goal": "Produce a public-safe evidence summary for human review.",
"state": "completed",
"created_at": "RFC3339 timestamp",
"completed_at": "RFC3339 timestamp"
},
"identity": {
"originating_principal": "user-or-service-id",
"workload_identity": "agent-workload-id",
"delegation_chain": []
},
"versions": {
"agent": "agent-name@version",
"model": "provider-model-version",
"prompt_or_policy": "policy-bundle-version",
"tool_registry": "registry-version"
},
"spans": [
{
"span_id": "span-1",
"parent_span_id": null,
"operation": "invoke_agent",
"started_at": "RFC3339 timestamp",
"ended_at": "RFC3339 timestamp",
"status": "ok",
"attributes": {
"agent_id": "stable-agent-id",
"objective_class": "evidence-summary",
"input_reference": "redacted-or-hashed-reference"
}
},
{
"span_id": "span-2",
"parent_span_id": "span-1",
"operation": "policy_decision",
"status": "allow",
"attributes": {
"policy_decision_id": "decision-id",
"scope": [
"read:public-evidence"
]
}
},
{
"span_id": "span-3",
"parent_span_id": "span-1",
"operation": "execute_tool",
"status": "ok",
"attributes": {
"tool_id": "evidence.search",
"tool_version": "1.0.0",
"effect_class": "observe",
"idempotency_key": null,
"result_reference": "artifact-id",
"effect_verified": true
}
},
{
"span_id": "span-4",
"parent_span_id": "span-1",
"operation": "human_review",
"status": "approved",
"attributes": {
"reviewer_role": "Evidence Owner",
"decision_record_id": "decision-record-id"
}
}
],
"artifacts": [
{
"artifact_id": "artifact-id",
"type": "summary",
"content_hash": "sha256",
"classification": "public-safe"
}
],
"budgets": {
"elapsed_ms": 1200,
"model_tokens": 2400,
"tool_calls": 1,
"estimated_cost": "recorded-by-runtime"
},
"recovery": {
"retry_count": 0,
"reconciled": true,
"stop_reason": "goal_completed"
},
"privacy": {
"raw_prompt_retained": false,
"raw_tool_payload_retained": false,
"retention_class": "operational-trace"
}
}Trace the complete task, not only model calls
Model spans explain latency and token use. They do not independently explain why a tool was authorized, whether its effect happened, what state changed, which human approved it, or how an uncertain outcome was reconciled.
OpenTelemetry defines common semantic conventions for telemetry, and its GenAI repository now covers GenAI clients, MCP, and provider-specific conventions. The agent span document is explicitly development-stage, so internal evidence contracts should be stable even while external conventions evolve. [S1] [S2] [S3]
Trace identifiers and causal links
Use stable trace, task, case, span, artifact, policy decision, tool call, effect, and human decision identifiers. Preserve parent-child and link relationships when work becomes asynchronous, delegated, retried, or resumed after human input.
Separate content from evidence metadata
Do not capture prompts, retrieved documents, tool arguments, and outputs by default merely because the observability platform can. Record hashes, classifications, references, sizes, result identifiers, and policy decisions when those are sufficient. Apply explicit opt-in, redaction, access, and retention controls to content capture.
Include business-state verification
A tool-call span should record accepted, completed, rejected, partial, or unknown effect status and the independent evidence used to verify the effect. This enables safe retry and supports recovery when transport success diverges from business completion.
Derive operational measures
From traces, derive task completion, escalation, duplicate effects, unknown outcomes, tool failure, policy denial, reviewer delay, queue age, non-progress loops, total cost, reconciliation time, and correctness recovery. Do not reduce all behavior to model latency or a single quality score.
Research boundary
The schema is a public engineering template, not an official OpenTelemetry schema. Attribute names and stability in external specifications can change; implementations should track the current normative and development status before adoption.
Sources
Sources support the linked statements and terminology. They do not certify a system, establish buyer intent, or convert this research into a formal assurance.
- OpenTelemetry Semantic ConventionsOpenTelemetry · Accessed 2026-08-01
Open telemetry specification
- OpenTelemetry GenAI Semantic ConventionsOpenTelemetry · Accessed 2026-08-01
Open telemetry specification repository
- Semantic Conventions for GenAI Agent and Framework SpansOpenTelemetry · Accessed 2026-08-01
Development-stage open telemetry specification
- Inside the LLM Call: GenAI Observability with OpenTelemetryOpenTelemetry · Accessed 2026-08-01
Open telemetry guidance
- Agent2Agent Protocol Specification 1.0A2A Protocol · Accessed 2026-08-01
Open technical specification
- A2A Streaming and Asynchronous OperationsA2A Protocol · Accessed 2026-08-01
Open technical guidance
- Challenges to the Monitoring of Deployed AI SystemsNIST · Accessed 2026-08-01
Government technical report
- Log Analysis Is Necessary for Credible Evaluation of AI AgentsarXiv · Accessed 2026-08-01
Research paper