agent-transcript-format-v1.md

Specification — Agent Trajectory Transcript Format (v1.0)

This specification defines the JSON Lines (JSONL) schema for recording observable agent execution trajectories (transcript.jsonl).

---

1. File Format

Transcripts MUST be stored in JSON Lines (.jsonl) format where each line represents a single step in the agent trajectory.

---

2. Event Line Schema

{
  "step_index": 1,
  "timestamp": "2026-08-06T14:00:00Z",
  "source": "MODEL",
  "type": "PLANNER_RESPONSE",
  "status": "DONE",
  "content": "I will read main.go to inspect CLI subcommands.",
  "tool_calls": [
    {
      "tool_name": "view_file",
      "args": { "AbsolutePath": "d:/project/kitwork/main.go" },
      "exit_code": 0
    }
  ]
}

Field Definitions

Field	Type	Description
step_index	Integer	1-indexed sequential step counter
timestamp	String (ISO 8601)	UTC execution timestamp
source	Enum	USER_EXPLICIT, MODEL, SYSTEM
type	Enum	USER_INPUT, PLANNER_RESPONSE, TOOL_RESULT
status	Enum	RUNNING, DONE, ERROR
tool_calls	Array	Array of tool call objects invoked during the step