ANSWER HUB
RunLedger agent protocol
The agent protocol is newline-delimited JSON over stdin/stdout so RunLedger can drive tasks and replay tools deterministically.
Direct Answer
Implement the RunLedger agent protocol as JSONL over stdio: the runner sends task_start and tool_result, and the agent replies with tool_call and final_output.
Quick Decision
| Use RunLedger when | Consider alternatives when |
|---|---|
| You can control the agent process I/O. | You cannot modify the agent or intercept stdout. |
| You need deterministic tool replay in CI. | You only need offline unit tests without tools. |
| You want strict CI gates on tool behavior. | You only need manual review. |
Message types
- Runner ? Agent: task_start, tool_result
- Agent ? Runner: tool_call, final_output, optional log/task_error
- JSON must go to stdout; human logs belong on stderr.
Important
Stdout must be parseable JSONL; send human logs to stderr.
Minimal exchange
jsonl
{"type":"task_start","task_id":"t1","input":{"ticket":"reset"}}
{"type":"tool_call","tool":"search_docs","args":{"query":"reset password"}}
{"type":"tool_result","tool":"search_docs","result":{"hits":3}}
{"type":"final_output","output":{"answer":"..."}}Tradeoffs
- Requires a thin adapter around your agent runtime.
- Strict stdout rules mean logs must be routed to stderr.
- Protocol changes require coordinated updates across agents.
When NOT to use RunLedger
Avoid RunLedger if you cannot modify the agent process or cannot separate structured output from logs.