Headless mode
A machine-readable contract for non-Python harnesses.
--mode json and --mode jsonl make agentino run emit a structured contract
on stdout instead of prettified markdown — the same shape pi --print,
codex exec --json and claude -p --output-format stream-json provide.
$ agentino run agents.yml -m "List open invoices" --mode json
{"type":"final","text":"…","tools_used":["list_invoices"],
"tool_outputs":["…"],"usage":{"prompt_tokens":1200,"completion_tokens":85},
"model":"gpt-5.4-codex","elapsed_ms":2254}
Which mode
json emits exactly one envelope, at the end. Right when you want the answer
and nothing else.
jsonl streams events as they happen and then the same final envelope. Right
when something is watching and should show progress.
The envelope
Always the last line, in both modes.
| Field | |
|---|---|
type | Always final — the marker that tells a jsonl reader to stop |
text | The reply |
tools_used | Tool names, in the order they ran |
tool_outputs | What each returned, truncated to 2000 characters |
usage | prompt_tokens and completion_tokens, summed over the turn |
model | Which model answered |
elapsed_ms | Wall time for the whole run |
The stream
One JSON object per line in jsonl mode. Every record has a type; the rest
depends on it.
type | Carries |
|---|---|
tool_start | name, and args when the call had any |
tool_result | data — the tool's output, truncated to 2000 characters |
text | delta — a chunk of the reply as it is generated |
llm_response | usage for that call, and trace when AGENTINO_LLM_TRACE is set |
done | The run finished |
A reader that does not recognise a type should ignore the line rather than
fail: the set grows, and the envelope is what matters.
Why this exists
So a harness that is not written in Python can use an agentino agent without embedding a Python runtime. Shell out, read stdout, parse one line. That is how Runspace's four CLI runtimes work in the other direction, and it is why an agent written here can be dropped into an IDE extension or a polyglot stack without a service in between.
Everything an ANSI-rendered run would show is in the envelope, so nothing is lost by going headless — including which tools ran, what they returned, and what the turn cost.