agentic-schema-review / data /trajectory.schema.json
christian-hoang-04's picture
Restore Space content after accidental deletion
0f66c7c verified
Raw History Blame Contribute Delete
17.5 kB
{
"$schema": "http://json-schema.org/draft-07/schema#",
"version": "trajectory_0.3.0",
"title": "EEE Agent Trajectory",
"type": "object",
"description": "Schema for an agent execution trajectory. Event IDs are unique within a trajectory document; event ordering in the events array is serialization order, while parent_event_ids express causal links.",
"required": ["schema_version", "trajectory_id", "actors", "events"],
"properties": {
"schema_version": {
"type": "string",
"description": "Version of the trajectory format used by this document."
},
"session_id": {
"type": "string",
"description": "Run-scoped identifier shared by trajectory documents that belong to one session."
},
"trajectory_id": {
"type": "string",
"description": "Stable identifier for this trajectory document and the scope of its event IDs."
},
"actors": {
"type": "array",
"minItems": 1,
"description": "Registry of participants whose IDs may be referenced by events.",
"items": { "$ref": "#/definitions/actor" }
},
"tools": {
"type": "array",
"description": "Registry of tools available to the agent.",
"items": { "$ref": "#/definitions/tool" }
},
"links": {
"type": "array",
"description": "Related trajectory documents, such as subagents, continuations, or branches.",
"items": { "$ref": "#/definitions/trajectory_link" }
},
"omitted_calls": {
"type": "array",
"description": "Tool or model calls intentionally or unavoidably left out of a partial log.",
"items": { "$ref": "#/definitions/omitted_call" }
},
"events": {
"type": "array",
"minItems": 1,
"description": "Serialized events in this trajectory. Use event IDs and parent_event_ids for references and causal order.",
"items": { "$ref": "#/definitions/event" }
},
"extra": {
"type": "object",
"description": "Source-specific trajectory metadata not represented by the common fields."
}
},
"additionalProperties": false,
"definitions": {
"module_reference": {
"type": "object",
"description": "Reference to a trajectory stored separately from the containing record.",
"required": ["type", "uri"],
"properties": {
"type": { "const": "module_reference" },
"uri": {
"type": "string",
"format": "uri-reference",
"description": "URI or relative path to the referenced trajectory."
},
"media_type": { "type": "string" },
"format": { "type": "string", "description": "Trajectory encoding or interchange format, e.g. ATIF or JSONL." },
"schema_uri": { "type": "string", "format": "uri-reference" },
"schema_version": { "type": "string" },
"sha256": {
"type": "string",
"pattern": "^[A-Fa-f0-9]{64}$",
"description": "Optional SHA-256 digest of the referenced file."
}
},
"additionalProperties": false
},
"actor": {
"type": "object",
"required": ["actor_id", "kind", "name"],
"properties": {
"actor_id": { "type": "string", "description": "Stable ID referenced by an event's actor_id." },
"kind": { "type": "string", "enum": ["agent", "user", "system", "tool", "other"] },
"name": { "type": "string", "description": "Agent or participant name, e.g. claude-code." },
"version": { "type": ["string", "null"] },
"model_id": { "type": "string", "description": "Model identifier backing this actor, when applicable." },
"model_revision": { "type": "string", "description": "Revision or immutable version of the model, when known." },
"configuration": { "type": "object", "description": "Actor settings relevant to interpreting the run." }
},
"additionalProperties": false
},
"tool": {
"type": "object",
"required": ["tool_id", "name"],
"properties": {
"tool_id": { "type": "string", "description": "Registry ID referenced by tool_call events." },
"name": { "type": "string", "description": "Tool name, e.g. bash." },
"version": { "type": ["string", "null"] },
"input_schema": { "type": "object", "description": "JSON Schema for the tool's arguments." },
"output_schema": { "type": "object", "description": "JSON Schema for the tool's output." }
},
"additionalProperties": false
},
"trajectory_link": {
"type": "object",
"required": ["relation", "target"],
"properties": {
"relation": { "type": "string", "enum": ["subagent", "continuation", "branch"] },
"trigger_event_id": { "type": "string", "description": "Event in this trajectory that caused or continued the linked trajectory." },
"target": {
"description": "Linked trajectory, embedded or referenced.",
"oneOf": [
{ "$ref": "#" },
{ "$ref": "#/definitions/module_reference" }
]
}
},
"additionalProperties": false
},
"omitted_call": {
"type": "object",
"required": ["call_id", "reason"],
"properties": {
"call_id": { "type": "string" },
"reason": { "type": "string", "description": "Why the tool or model call is absent from the recorded events." }
},
"additionalProperties": false
},
"usage": {
"type": "object",
"description": "One resource measurement. Use name to distinguish measures such as input_tokens, output_tokens, or provider-specific cost units.",
"required": ["type", "value", "unit"],
"properties": {
"type": { "type": "string", "enum": ["token", "cost", "time", "other"] },
"name": { "type": "string" },
"value": { "type": "number", "minimum": 0 },
"unit": { "type": "string", "description": "Unit for value, such as tokens, USD, or milliseconds." },
"provider": { "type": "string" }
},
"additionalProperties": false
},
"timing": {
"type": "object",
"description": "Timing measurements in milliseconds; include any values available from the source.",
"properties": {
"start_ms": { "type": "number", "minimum": 0 },
"end_ms": { "type": "number", "minimum": 0 },
"duration_ms": { "type": "number", "minimum": 0 }
},
"anyOf": [
{ "required": ["start_ms"] },
{ "required": ["end_ms"] },
{ "required": ["duration_ms"] }
],
"additionalProperties": false
},
"part": {
"description": "Text or a typed content part. Object parts may carry source-specific fields such as text, media references, or structured payloads.",
"oneOf": [
{ "type": "string" },
{
"type": "object",
"required": ["type"],
"properties": { "type": { "type": "string" } }
}
]
},
"message": {
"type": "object",
"required": ["role"],
"properties": {
"role": { "type": "string" },
"actor_id": { "type": "string" },
"content": {},
"parts": { "type": "array", "items": { "$ref": "#/definitions/part" } },
"name": { "type": "string" },
"tool_call_id": { "type": "string" },
"tool_calls": { "type": "array", "items": { "type": "object" } }
}
},
"token_data": {
"type": "object",
"properties": {
"tokenizer": { "type": "string" },
"tokenizer_revision": { "type": "string" },
"prompt_token_ids": { "type": "array", "items": { "type": "integer" } },
"completion_token_ids": { "type": "array", "items": { "type": "integer" } },
"logprobs": {
"type": "array",
"description": "Optional numeric or structured token log probabilities as provided by the source."
}
}
},
"event_common": {
"type": "object",
"required": ["event_id", "type", "parent_event_ids", "is_copied_context"],
"properties": {
"event_id": { "type": "string", "description": "Stable ID unique within trajectory_id." },
"type": {
"type": "string",
"enum": ["tool_call", "tool_result", "model_call", "observation", "state", "final", "context_change", "approval"]
},
"actor_id": { "type": "string", "description": "Participant ID from the actors registry, when available." },
"parent_event_ids": {
"type": "array",
"items": { "type": "string" },
"description": "Events that caused this event; separate from serialization order."
},
"is_copied_context": {
"type": "boolean",
"description": "Whether this event contains context copied from another context, such as a subagent handoff."
},
"extra": { "type": "object", "description": "Source-specific event data not represented by the common fields." }
}
},
"event": {
"oneOf": [
{ "$ref": "#/definitions/tool_call_event" },
{ "$ref": "#/definitions/tool_result_event" },
{ "$ref": "#/definitions/model_call_event" },
{ "$ref": "#/definitions/observation_event" },
{ "$ref": "#/definitions/state_event" },
{ "$ref": "#/definitions/final_event" },
{ "$ref": "#/definitions/context_change_event" },
{ "$ref": "#/definitions/approval_event" }
]
},
"tool_call_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["call_id", "tool_id", "tool_name", "arguments", "dispatch"],
"properties": {
"type": { "const": "tool_call" },
"call_id": { "type": "string", "description": "ID paired with the corresponding tool_result." },
"tool_id": { "type": "string", "description": "Tool registry entry." },
"tool_name": { "type": "string", "description": "Name of the tool as invoked." },
"arguments": { "description": "JSON arguments passed to the tool." },
"dispatch": { "type": "string", "enum": ["model", "deterministic", "unknown"] },
"inference_id": { "type": "string", "description": "Model call that produced this tool call." },
"usage": { "type": "array", "items": { "$ref": "#/definitions/usage" } },
"timing": { "$ref": "#/definitions/timing" }
},
"allOf": [
{
"if": { "properties": { "dispatch": { "const": "model" } } },
"then": { "required": ["inference_id"] }
}
]
}
]
},
"tool_result_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["call_id", "status"],
"properties": {
"type": { "const": "tool_result" },
"call_id": { "type": "string", "description": "ID of the tool_call this result answers." },
"status": { "type": "string", "enum": ["completed", "error", "interrupted"] },
"parts": { "type": "array", "items": { "$ref": "#/definitions/part" } },
"structured_output": { "description": "Machine-readable JSON output from the tool." },
"error": { "type": "string" },
"usage": { "type": "array", "items": { "$ref": "#/definitions/usage" } },
"timing": { "$ref": "#/definitions/timing" }
},
"allOf": [
{
"if": { "properties": { "status": { "const": "completed" } } },
"then": { "required": ["parts"] }
},
{
"if": { "properties": { "status": { "enum": ["error", "interrupted"] } } },
"then": { "required": ["error"] }
}
]
}
]
},
"model_call_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["inference_id", "model_id", "input_capture", "output_capture", "status"],
"properties": {
"type": { "const": "model_call" },
"inference_id": { "type": "string", "description": "Identity shared by events produced by this inference." },
"model_id": { "type": "string" },
"model_revision": { "type": "string" },
"provider": { "type": "string" },
"configuration": { "type": "object", "description": "Sampling and other request settings." },
"input_messages": { "type": "array", "items": { "$ref": "#/definitions/message" } },
"input_capture": { "type": "string", "enum": ["full", "partial", "unavailable"] },
"capture_reason": { "type": "string", "description": "Why the model input capture is partial or unavailable." },
"output_parts": { "type": "array", "items": { "$ref": "#/definitions/part" } },
"output_capture": { "type": "string", "enum": ["full", "unavailable"] },
"output_capture_reason": { "type": "string", "description": "Why model output was unavailable." },
"status": { "type": "string", "enum": ["completed", "error", "interrupted"] },
"error": { "type": "string" },
"finish_reason": { "type": "string" },
"llm_call_count": { "type": "integer", "minimum": 1 },
"token_data": { "$ref": "#/definitions/token_data" },
"usage": { "type": "array", "items": { "$ref": "#/definitions/usage" } },
"timing": { "$ref": "#/definitions/timing" }
},
"allOf": [
{
"if": { "properties": { "input_capture": { "const": "full" } } },
"then": { "required": ["input_messages"] }
},
{
"if": { "properties": { "input_capture": { "enum": ["partial", "unavailable"] } } },
"then": { "required": ["capture_reason"] }
},
{
"if": { "properties": { "output_capture": { "const": "full" } } },
"then": { "required": ["output_parts"] }
},
{
"if": { "properties": { "output_capture": { "const": "unavailable" } } },
"then": { "required": ["output_capture_reason"] }
},
{
"if": { "properties": { "status": { "enum": ["error", "interrupted"] } } },
"then": { "required": ["error"] }
}
]
}
]
},
"observation_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["parts"],
"properties": {
"type": { "const": "observation" },
"parts": { "type": "array", "items": { "$ref": "#/definitions/part" } },
"processing_ids": { "type": "array", "items": { "type": "string" } }
}
}
]
},
"state_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["state"],
"properties": {
"type": { "const": "state" },
"state": {},
"state_schema_uri": { "type": "string", "format": "uri-reference" }
}
}
]
},
"final_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["parts"],
"properties": {
"type": { "const": "final" },
"parts": { "type": "array", "items": { "$ref": "#/definitions/part" } },
"processing_ids": { "type": "array", "items": { "type": "string" } },
"candidate_id": { "type": "string" },
"inference_id": { "type": "string" }
}
}
]
},
"context_change_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["operation"],
"properties": {
"type": { "const": "context_change" },
"operation": { "type": "string", "enum": ["summarize", "compact", "trim", "reset", "checkpoint", "restore"] },
"before_event_ids": { "type": "array", "items": { "type": "string" } },
"after_parts": { "type": "array", "items": { "$ref": "#/definitions/part" } },
"tokens_before": { "type": "integer", "minimum": 0 },
"tokens_after": { "type": "integer", "minimum": 0 },
"reason": { "type": "string" }
}
}
]
},
"approval_event": {
"allOf": [
{ "$ref": "#/definitions/event_common" },
{
"type": "object",
"required": ["call_id", "decision"],
"properties": {
"type": { "const": "approval" },
"call_id": { "type": "string", "description": "Tool call under review." },
"decision": { "type": "string", "enum": ["approve", "modify", "reject", "escalate", "terminate"] },
"reason": { "type": "string" },
"modified_arguments": { "description": "Replacement JSON arguments when decision is modify." }
},
"allOf": [
{
"if": { "properties": { "decision": { "const": "modify" } } },
"then": { "required": ["modified_arguments"] }
}
]
}
]
}
}
}