Antigravity CLI stream-json cheatsheet
agy --output-format stream-json writes one JSON object per line to stdout. Every line has an event field: init, step_update, result or command_result.
agy --output-format stream-json writes one JSON object per line to stdout. Every line has an event field:
init, step_update, result or command_result. The examples below are real lines from agy 1.3.1, 1.3.2
and 1.3.3, with paths and ids shortened and the tool list cut.
Things that differ from what you might expect
- There is no
errorevent. Failures arrive as aresultwithstatus: "ERROR", or as a non-zero exit with text on stderr.initis not always first, or present at all. An early failure (signed out, bad model) sends only aresultwith an emptyconversation_id.result.usage,num_turnsandduration_secondsare totals for the whole conversation, including earlier resumed runs.
Input
Untether starts agy with --input-format stream-json and writes one line to stdin, then closes it:
{"event":"user","message":{"content":"your prompt"}}
agy runs one turn per line. With stdin left open it answers each line with its own result and then waits, idle,
for the next; closing stdin ends it with exit code 0 (agy 1.3.5; the seam for live sessions,
#977). A /compact line, sent without
--disable-slash-commands, compacts the conversation: a system_message step and a checkpoint step, then a
SUCCESS result with an empty response and no new tokens. Nothing in the stream says how much smaller the context
got (agy 1.3.5). Untether passes that flag (and escapes a leading / in Plan first) on every run except a
/compact one (#1114):
{"event":"user","message":{"content":"/compact"}}
{"event":"step_update","step_update":{"conversation_id":"153b…","step_index":2,"state":"DONE","step_type":"user_input"}}
{"event":"step_update","step_update":{"conversation_id":"153b…","step_index":3,"state":"DONE","step_type":"system_message","duration_seconds":0.000237673}}
{"event":"step_update","step_update":{"conversation_id":"153b…","step_index":4,"state":"DONE","step_type":"checkpoint","duration_seconds":6.39104973}}
{"event":"result","result":{"conversation_id":"153b…","status":"SUCCESS","response":"","duration_seconds":18.26,"num_turns":2,"usage":{"input_tokens":7803,"output_tokens":27,"thinking_tokens":26,"cache_read_tokens":0,"total_tokens":7830}}}
init
{"event":"init","conversation_id":"90ca6744-e8d4-46d4-b5fc-64a30ae2fa6d","init":{"cwd":"/work/proj","tools":["ask_question","run_command","view_file","…"],"permission_mode":"request-review"}}
conversation_idis the resume id (a UUID).init.permission_modeis the policy agy is running under:request-review(default),strict,proceed-in-sandboxoralways-proceed(what--dangerously-skip-permissionsreports).init.modelis present from agy 1.3.2, only when--modelwas passed: it echoes the flag (for examplegemini-3.8-flash-low). With no--model, no line of the stream names the model.init.toolsis a long list of tool names; don’t rely on its contents.init.json_schemaechoes a--json-schemaargument (Untether doesn’t pass one).
step_update
One step is a numbered unit of work. state is ACTIVE, DONE or ERROR. step_type is user_input,
agent_response, tool, subagent, system_message, checkpoint, finish or unknown.
Your message:
{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":0,"state":"DONE","step_type":"user_input"}}
Answer text, streamed as deltas and then closed with per-step usage:
{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":1,"state":"ACTIVE","step_type":"agent_response","text_delta":"OK"}}
{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":1,"state":"DONE","step_type":"agent_response","text_delta":"\n","duration_seconds":2.23,"usage":{"input_tokens":13051,"output_tokens":1,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":13052}}}
A tool call, started and finished:
{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":2,"state":"ACTIVE","step_type":"tool","tool_name":"view_file","tool_info":{"name":"view_file","parameters":{"AbsolutePath":"/work/proj/notes.txt"}}}}
{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":2,"state":"DONE","step_type":"tool","tool_name":"view_file","duration_seconds":0.97,"tool_info":{"name":"view_file","parameters":{"AbsolutePath":"/work/proj/notes.txt"},"output":"2 lines, 20 bytes"}}}
tool_info carries name, parameters, and on completion output or error ({"type": …, "message": …}).
Tool names seen: run_command, view_file, write_to_file, replace_file_content,
multi_replace_file_content, sed_file, list_dir, find_by_name, grep_search, search_web,
read_url_content, call_mcp_tool, browser_*, invoke_subagent, ask_question, schedule, manage_task,
finish.
A blocked tool looks like a finished one
When agy’s permission policy blocks a tool (the headless default blocks shell, web and MCP calls), the step still
ends DONE, with no output and no error:
{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":4,"state":"ACTIVE","step_type":"tool","tool_name":"run_command","tool_info":{"name":"run_command","parameters":{"CommandLine":"echo probe-shell"}}}}
{"event":"step_update","step_update":{"conversation_id":"a46e…","step_index":4,"state":"DONE","step_type":"tool","tool_name":"run_command","duration_seconds":0.05,"tool_info":{"name":"run_command","parameters":{"CommandLine":"echo probe-shell"}}}}
Only the result says it was blocked, in denied_actions. agy 1.3.x ends the turn at the first blocked tool, and
writes a jetski: no output produced — a tool required the "command" permission … line to stderr.
A tool refused by a hook is different: its step ends ERROR with tool_info.error:
{"event":"step_update","step_update":{"conversation_id":"cb98…","step_index":11,"state":"ERROR","step_type":"tool","tool_name":"run_command","duration_seconds":0.38,"tool_info":{"name":"run_command","parameters":{"CommandLine":"echo denyme"},"error":{"type":"TOOL_ERROR","message":"tool call denied by pre-tool hook: …"}}}}
Subagents
{"event":"step_update","step_update":{"conversation_id":"4054…","step_index":2,"state":"ACTIVE","step_type":"subagent","tool_name":"invoke_subagent","subagent_info":{"subagents":[{"type_name":"research","role":"Secret Reader","initial_prompt":"Read notes.txt and reply with the secret word only."}]}}}
The DONE line adds each subagent’s own conversation_id and a log_uri. The subagent’s steps are not in the
parent stream.
That is agy 1.3.1. On 1.3.3 the spawn is a tool step while ACTIVE and becomes a subagent step only at
DONE, about 0.3 s later, while the subagents are still working:
{"event":"step_update","step_update":{"conversation_id":"0000…","step_index":2,"state":"ACTIVE","step_type":"tool","tool_name":"invoke_subagent","tool_info":{"name":"invoke_subagent","parameters":{"Subagents":[{"Model":"inherit","Prompt":"Read notes.txt …","Role":"Alpha","TypeName":"research","Workspace":"inherit"},{"Model":"inherit","Prompt":"Read hello.py …","Role":"Beta","TypeName":"research","Workspace":"inherit"}]}}}}
{"event":"step_update","step_update":{"conversation_id":"0000…","step_index":2,"state":"DONE","step_type":"subagent","tool_name":"invoke_subagent","duration_seconds":0.27,"subagent_info":{"subagents":[{"type_name":"research","role":"Alpha","initial_prompt":"…","conversation_id":"…","log_uri":"file://…/transcript.jsonl","workspace_uris":["file:///work/proj"]},{"type_name":"research","role":"Beta","initial_prompt":"…","conversation_id":"…"}]}}}
Each subagent finishing is one system_message step in the parent stream, with nothing to say which one (still so on
1.3.5; the sender is only in agy’s transcript file):
{"event":"step_update","step_update":{"conversation_id":"0000…","step_index":4,"state":"DONE","step_type":"system_message","duration_seconds":0.0004}}
Background commands, timers and daemons
- A background
run_commandstaysACTIVEuntil the command ends, and agy prints nothing else meanwhile (it holds the model’s reply). Itsparameterscarry onlyCommandLine;WaitMsBeforeAsyncandIsDaemonare not in the stream. - A
schedulestep (parameters:DurationSeconds,Prompt) staysACTIVEfor the timer’s whole life. - When either finishes, its
DONEline is followed by the held reply and asystem_messagestep. agy prints steps in order, so everything that happened while the step was open (replies, a subagent’ssystem_message) comes in one burst after itsDONE, and the timer’s own notice can come after a subagent’s (1.3.5). - A timer the model gives
TimerCondition(any, or a sender id) ends at the first matching message. The stream dropsTimerConditionfrom the parameters, but theDONEoutput names the sender, and that message (the nextsystem_message) is the timer’s only notice (#1086, agy 1.3.5):
{"event":"step_update","step_update":{"step_index":3,"state":"DONE","step_type":"tool","tool_name":"schedule","duration_seconds":7.84,"tool_info":{"name":"schedule","parameters":{"DurationSeconds":60,"Prompt":"Check on the subagents' progress"},"output":"Timer cancelled early: its early-termination condition (any) was met by a message from 0000…0003."}}}
A timer that runs its course ends with "output":"Finished waiting 30 seconds.".
manage_subagentstakesActionlist,kill(withConversationIds) orkill_all.kill_allanswersSuccessfully killed N subagent(s) and their descendants.(N counts idle children of earlier turns too) and is followed by nosystem_message(1.3.4, 1.3.5). Subagents stay alive, idle, after they report.- A daemon
run_commandnever reachesDONE: the nextagent_responseand theresultarrive while it is stillACTIVE, and the process is still running after agy exits (1.3.3).
finish
With a JSON schema, the finish tool goes ACTIVE as step_type: "tool" and DONE as step_type: "finish".
result
Success:
{"event":"result","result":{"conversation_id":"90ca…","status":"SUCCESS","response":"OK\n","duration_seconds":2.59,"num_turns":1,"usage":{"input_tokens":13051,"output_tokens":1,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":13052}}}
A turn that stopped at a blocked tool is still SUCCESS, with an empty response:
{"event":"result","result":{"conversation_id":"a46e…","status":"SUCCESS","response":"","duration_seconds":6.9,"num_turns":1,"usage":{"input_tokens":26430,"output_tokens":143,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":26573},"denied_actions":[{"action":"command","display_name":"RunCommand"}]}}
denied_actions[].action values seen or documented: command, unsandboxed, mcp, read_url, execute_url,
read_file, write_file.
A background task the model stops with manage_task (#1062, agy 1.3.3 and 1.3.4): the command’s step ends
DONE with an error, then the kill step names the task by step index. agy prints the step’s DONE only when the
kill lands (both lines arrive together), so with a short WaitMsBeforeAsync the gap can be under 5 s; 1.3.4 follows
the kill with a content-less system_message step (the task’s cancellation notice):
{"event":"step_update","step_update":{"step_index":2,"state":"DONE","step_type":"tool","tool_name":"run_command","tool_info":{"name":"run_command","parameters":{"CommandLine":"sleep 300"},"error":{"type":"TOOL_ERROR","message":"context canceled"}}}}
{"event":"step_update","step_update":{"step_index":4,"state":"DONE","step_type":"tool","tool_name":"manage_task","tool_info":{"name":"manage_task","parameters":{"Action":"kill","TaskId":"d84b…/task-2"},"output":"Task \"d84b…/task-2\" cancelled."}}}
Cancelled (SIGINT or SIGTERM): the open step never closes, and the result is
{"event":"result","result":{"conversation_id":"f40d…","status":"ERROR","response":"","error":"interrupted","duration_seconds":11.9,"num_turns":1,"usage":{"input_tokens":13082,"output_tokens":273,"thinking_tokens":179,"cache_read_tokens":0,"total_tokens":13355}}}
Cancelled while agy holds its answer for a background command (#1061, agy 1.3.3): nothing was printed
after the command’s ACTIVE step, and response is still "" although usage counts the model call that wrote
the answer. The answer is in the conversation: the next resumed turn can repeat it.
Signed out (no init, exit 1):
{"event":"result","result":{"conversation_id":"","status":"ERROR","response":"","error":"authentication failed or timed out","duration_seconds":0,"num_turns":0,"usage":{"input_tokens":0,"output_tokens":0,"thinking_tokens":0,"cache_read_tokens":0,"total_tokens":0}}}
result.usage is a running sum, not a context size: it adds every model call of the turn and, on a resumed
conversation, the earlier turns too (a five-call turn of 7,902 to 9,501 input tokens reports 42,593). Each model
call’s own figures are on its agent_response step:
{"event":"step_update","step_update":{"conversation_id":"90ca…","step_index":9,"state":"DONE","step_type":"agent_response","text_delta":"\n","duration_seconds":2.3,"usage":{"input_tokens":9501,"output_tokens":221,"thinking_tokens":81,"cache_read_tokens":0,"total_tokens":9722}}}
cache_read_tokens is reported apart from input_tokens (total_tokens is input + output). No field anywhere
in the stream names a context window, a limit or a maximum.
Other fields: structured_output and json_schema (with --json-schema). error is usually a string, but
Untether accepts any JSON value there so a structured error never loses the result. Statuses other than SUCCESS
and ERROR (CANCELED, WAITING, …) can appear.
Unknown conversation id
agy --conversation <unknown id> prints a warning on stderr, then carries on in a new conversation:
warning: conversation "00000000-1111-2222-3333-444444444444" not found
{"event":"init","conversation_id":"65f94e86-51cc-46d0-8aee-97c679364d8c","init":{"cwd":"/work/proj","tools":["…"],"permission_mode":"request-review"}}
The only signals are the stderr line and an init id that differs from the one asked for.
command_result
Slash commands run with agy -p /<command> answer with a command_result line and a zero-token result. Untether
uses three of them, none of which calls a model:
{"event":"command_result","command":{"name":"effort","data":{"adjustable":true,"current":"high","available":["low","medium","high"]}}}
/effort [--model=<model>](Untether always joins the value to the flag) — the effort levels a model accepts ({"adjustable": false}for a fixed-effort model)/usage— quotagroups, each withbuckets(windowsuch as5horweekly,remaining_fraction,reset_time)/config— agy’s effective settings (toolPermission,permissions.allow,allowNonWorkspaceAccess,modelProvider)
stderr
stderr is not JSON. The lines Untether reacts to are listed in the runner reference. agy’s
changelog also describes AGY_ERROR: {json} with exit 3 for a turn-level failure; its keys aren’t documented and
it hasn’t been captured live.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Finished, including a turn that stopped at a blocked tool |
| 1 | Error result (signed out, invalid model or effort, interrupted) |
| 2 | Bad command line (flags provided but not defined: …) |
| 3 | Turn-level model or agent failure (AGY_ERROR; from agy’s changelog, not captured live) |