agent-run/schemas/step.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
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-run.dev/schemas/step.json",
  "title": "Step",
  "description": "A single step within an agent run — a reasoning block, tool call, or error.",
  "type": "object",
  "required": ["id", "type", "started_at"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique step identifier within the run."
    },
    "type": {
      "type": "string",
      "enum": ["reasoning", "tool_call", "tool_result", "message", "error", "handoff"],
      "description": "What kind of step this is."
    },
    "tool_name": {
      "type": ["string", "null"],
      "description": "Name of the tool called (for tool_call/tool_result steps)."
    },
    "mcp_server": {
      "type": ["string", "null"],
      "description": "MCP server that provided the tool, if applicable."
    },
    "input_preview": {
      "type": ["string", "null"],
      "maxLength": 500,
      "description": "Truncated preview of the step input (for observability without leaking full prompts)."
    },
    "output_preview": {
      "type": ["string", "null"],
      "maxLength": 500,
      "description": "Truncated preview of the step output."
    },
    "success": {
      "type": ["boolean", "null"],
      "description": "Whether this step succeeded (for tool calls)."
    },
    "error": {
      "type": ["string", "null"],
      "description": "Error message if the step failed."
    },
    "started_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp."
    },
    "ended_at": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "duration_ms": {
      "type": ["integer", "null"],
      "minimum": 0,
      "description": "Wall-clock duration of this step."
    },
    "tokens_used": {
      "type": ["integer", "null"],
      "minimum": 0,
      "description": "Total tokens consumed by this step (input + output)."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Extension point for step-specific data."
    }
  },
  "additionalProperties": false
}