{"slug": "til-jsonl-is-the-format-ai-agents-were-missing", "title": "TIL: JSONL Is the Format AI Agents Were Missing", "summary": "Cloudflare's post on orchestrating AI code review across thousands of merge requests highlights JSONL as the response surface for unreliable, long-running agent processes, where each line is a complete JSON object that remains parseable even if the process crashes mid-stream. JSONL's line-based format enables crash-safe parsing, appendability, streaming, and concurrency, making it ideal for agent orchestration, fine-tuning datasets, and structured logging. The format is already used by OpenAI, Anthropic, Gemini, Llama, Mistral, and agent runtimes like OpenCode and Claude Code.", "body_md": "# JSONL Is the Format AI Agents Were Missing\n\nToday I finally understood why JSONL keeps showing up in agent tooling. I used it years ago for big data files and never thought much of it. This week I read Cloudflare’s post on orchestrating AI code review across thousands of merge requests, and the same line kept popping up: every agent process emits JSONL on stdout. That clicked. JSONL is not just a file format here. It is a response surface for unreliable processes.\n\n## The Problem With Plain JSON Here\n\nStandard JSON wraps a dataset inside one array or object. A parser has to see the closing `]`\n\nbefore it can give you a single record. For an agent orchestration job that runs up to 25 minutes across seven concurrent LLM sessions, that is a bad deal. If the process runs out of memory or crashes halfway, you get zero parseable output. Exactly when you need the debug logs, they are unparseable.\n\n```\n[\n  { \"event\": \"step_start\", \"agent\": \"coordinator\", \"ts\": 1722816000 },\n  { \"event\": \"step_finish\", \"agent\": \"security\", \"tokens\": 8421 },\n  /* process dies here, no closing bracket */\n]\n```\n\nThat whole blob is invalid JSON. The two records before the crash are gone.\n\n## JSONL Just Gives You the Records\n\nJSONL (JSON Lines) drops the enclosing brackets. Each line is one complete, valid JSON object. Read a line, parse it, move on. No buffering the whole stream into memory. No waiting on a bracket that may never come.\n\n```\n{\"event\": \"step_start\", \"agent\": \"coordinator\", \"ts\": 1722816000}\n{\"event\": \"step_finish\", \"agent\": \"security\", \"tokens\": 8421}\n```\n\nThe process dies after line 2? You still have line 1 and line 2. Cloudflare pipes OpenCode with `--format json`\n\nso all stdout arrives as JSONL events, then buffers and flushes every 100 lines (or 50ms) to save disk from a stream of `appendFileSync`\n\ncalls.\n\n## Why This Maps to Agents So Well\n\n| Property | Plain JSON | JSONL |\n|---|---|---|\n| Crash-safe parsing | No, whole doc invalid | Yes, each line independent |\n| Appendable | No, rewrite the file | Yes, just write a new line |\n| Streamable mid-write | No, need the close | Yes, consumers read as you go |\n| Split across workers | No fixed boundaries | Line breaks are valid split points |\n| Corrupted record impact | Breaks the whole file | Skip the bad line, keep going |\n| Diff-friendly | One blob, messy diffs | `git diff` works line by line |\n\nThis is exactly the shape of agent work: long-running, crash-prone, streaming, concurrent. You spawn sub-agents that may take minutes, may hit `max_tokens`\n\n, may hang for 60 seconds then die. You need a format where partial output is still output.\n\n## Where You Will Already See It\n\n- Fine-tuning datasets for OpenAI, Anthropic, Gemini, Llama, and Mistral use JSONL. Each line is one training example: an instruction-response pair or a multi-turn conversation.\n- Structured loggers like\n`pino`\n\n,`structlog`\n\n, and`zap`\n\nemit one JSON object per line so aggregators can index entries without re-parsing the whole file. - OpenCode, Claude Code, and similar agent runtimes expose JSONL event streams on stdout so orchestrators can pull token usage, errors, and truncation signals in real time.\n\n## Reading a JSONL Stream in Python\n\nThe pattern stays the same regardless of language: read line by line, parse each line, never hold the whole file.\n\n``` python\nimport json\n\nwith open(\"events.jsonl\", \"r\") as f:\n    for line in f:\n        line = line.strip()\n        if not line:\n            continue\n        try:\n            event = json.loads(line)\n        except json.JSONDecodeError:\n            continue  # skip corrupted line, keep the rest\n        yield event\n```\n\nThat `continue`\n\non a bad line is the whole point. One corrupt record does not sink the file.\n\n## What I Learned\n\n- JSONL exists because plain JSON forces you to close the whole document before any record is parseable, which is the wrong trade for long-running and crash-prone processes.\n- For agent orchestration, JSONL is not just storage. It is the streaming response surface between a parent process and several concurrent LLM sessions.\n- Corrupt one line in JSONL and you lose one record. Corrupt one byte in a JSON array and you lose everything after it.\n- Every major fine-tuning API ships datasets as JSONL because each training example is an independent unit, and append-and-go beats rewrite-the-array.\n- If you are building anything that emits structured output from an LLM agent, start with JSONL. Re-inventing it is a tax, and every agent stack already speaks it.", "url": "https://wpnews.pro/news/til-jsonl-is-the-format-ai-agents-were-missing", "canonical_source": "https://kondasamy.com/til/2026/jsonl-for-ai-agent-workloads/", "published_at": "2026-08-05 00:00:00+00:00", "updated_at": "2026-08-10 19:04:35.691069+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "developer-tools"], "entities": ["Cloudflare", "OpenCode", "Claude Code", "OpenAI", "Anthropic", "Gemini", "Llama", "Mistral"], "alternates": {"html": "https://wpnews.pro/news/til-jsonl-is-the-format-ai-agents-were-missing", "markdown": "https://wpnews.pro/news/til-jsonl-is-the-format-ai-agents-were-missing.md", "text": "https://wpnews.pro/news/til-jsonl-is-the-format-ai-agents-were-missing.txt", "jsonld": "https://wpnews.pro/news/til-jsonl-is-the-format-ai-agents-were-missing.jsonld"}}