agent-run/schemas/agent-run.json at main · builderz-labs/agent-run · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-run.dev/schemas/agent-run.json",
  "title": "AgentRun",
  "description": "A single execution of an AI agent — the atomic unit of agent observability.",
  "type": "object",
  "required": ["id", "agent_id", "status", "started_at", "steps", "cost", "provenance"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique run identifier (UUID v7 recommended for sortability)."
    },
    "agent_id": {
      "type": "string",
      "description": "Identifier for the agent that executed this run."
    },
    "agent_name": {
      "type": "string",
      "description": "Human-readable agent name."
    },
    "model": {
      "type": "string",
      "description": "Model identifier used for this run (e.g., 'claude-sonnet-4-5-20250514')."
    },
    "provider": {
      "type": "string",
      "description": "LLM provider (e.g., 'anthropic', 'openai', 'google')."
    },
    "runtime": {
      "type": "string",
      "description": "Agent runtime that produced this run (e.g., 'claude-code', 'codex', 'oneclaw', 'custom')."
    },
    "runtime_version": {
      "type": "string",
      "description": "Version of the agent runtime."
    },
    "trigger": {
      "type": "string",
      "enum": ["manual", "cron", "webhook", "agent", "pipeline", "queue"],
      "description": "What initiated this run."
    },
    "parent_run_id": {
      "type": ["string", "null"],
      "description": "If this run was triggered by another agent run, the parent's ID."
    },
    "task_id": {
      "type": ["string", "null"],
      "description": "Task this run is associated with, if any."
    },
    "status": {
      "type": "string",
      "enum": ["pending", "running", "completed", "failed", "cancelled", "timeout"],
      "description": "Current status of the run."
    },
    "outcome": {
      "type": ["string", "null"],
      "enum": ["success", "failed", "partial", "abandoned", null],
      "description": "Result quality of the run (distinct from status — a run can complete but fail its objective)."
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the run started."
    },
    "ended_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "ISO 8601 timestamp when the run ended."
    },
    "duration_ms": {
      "type": ["integer", "null"],
      "minimum": 0,
      "description": "Total wall-clock duration in milliseconds."
    },
    "steps": {
      "type": "array",
      "items": { "$ref": "step.json" },
      "description": "Ordered sequence of steps the agent took during this run."
    },
    "tools_available": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of tool names available to the agent during this run."
    },
    "cost": {
      "$ref": "cost.json",
      "description": "Token usage and cost for this run."
    },
    "provenance": {
      "$ref": "provenance.json",
      "description": "Cryptographic provenance record for this run."
    },
    "eval": {
      "oneOf": [
        { "$ref": "eval.json" },
        { "type": "null" }
      ],
      "description": "Evaluation result, if this run was scored."
    },
    "error": {
      "type": ["string", "null"],
      "description": "Error message if the run failed."
    },
    "git_branch": {
      "type": ["string", "null"],
      "description": "Git branch the agent was working on."
    },
    "git_commit": {
      "type": ["string", "null"],
      "description": "Git commit SHA at the start of the run."
    },
    "workspace_id": {
      "type": ["string", "null"],
      "description": "Workspace or tenant scope for multi-tenant deployments."
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Free-form tags for categorization."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Extension point for runtime-specific data."
    }
  },
  "additionalProperties": false
}