Agent Safety: Busy Editor, Jobs and Rollback
Let your AI check that the Unreal editor is free, run long commands in the background, and undo everything it changed in one step.
Loading…
Let your AI check that the Unreal editor is free, run long commands in the background, and undo everything it changed in one step.
An AI agent works fast and does not see your screen. These commands let it check that the editor is free before it acts, run long work in the background, and take back everything it changed in one step. They need plugin 2.18.0 and cfa 3.19.0 or later, and they work on Unreal Engine 5.6, 5.7 and 5.8.
1. Is the editor free?
cfa get_editor_state2. Start a session before the work:
cfa begin_agent_session --name tidy-materials3. When you are done, keep the work, or undo all of it:
cfa end_agent_session
cfa rollback_agent_sessionget_editor_state answers at once, even while the editor is stuck in a dialog or a progress bar, because it never waits for the editor's main thread. It says what the editor is doing now and whether a new command would run:
idle Free. A command runs at once.
starting Just launched, not ticking yet. Wait a moment.
running_command A CodeFizz command is running (running_command names it).
dialog An editor dialog waits for a person (dialog gives its title).
system_dialog A file or folder picker is open.
slow_task A progress bar is up, for example a long import.
halted_at_breakpoint Play stopped at a Blueprint breakpoint.
stalled The editor has done no work for a long time.{
"state": "idle",
"ready": true,
"queued_commands": 0,
"playing": false,
"seconds_since_tick": 0,
"jobs": 0
}When a file picker, a progress bar or a frozen editor holds up the main thread, a new command is not left to wait until it times out. It is refused within a few seconds, with nothing changed, and the reply says why. Your AI can then ask you to close the dialog, or try again when get_editor_state shows idle.
{
"status": "error",
"error": "Not run: A system dialog (a file or folder picker) is open in the editor. 'get_world_info' made no changes. Ask the user to close the dialog or wait for the editor, then retry (get_editor_state shows when it is free).",
"retryable": true,
"made_no_changes": true
}A command that is already running is never stopped. Only commands that have not started yet are refused.
start_job queues any command and returns a job id at once, so your AI can do other work and collect the reply later. A job that has not started yet can be cancelled. A running job finishes, because stopping it part way would leave half a change.
Start a job:
cfa start_job --command build_navigationWait up to 60 seconds for it, then read its reply:
cfa get_job --job-id 3 --wait-seconds 60Cancel a job that is still queued:
cfa cancel_job --job-id 4List the jobs of this editor:
cfa list_jobsPass the command's own parameters as a JSON object, for example cfa start_job --command export_asset_thumbnail --params '{"asset_path":"/Game/Props/SM_Crate"}'.
An agent session records every CodeFizz command from the moment it begins: the assets it created, the ones it changed, the ones it saved and the ones it deleted. When the work is done you keep it, or undo all of it with one command.
Only one session runs at a time. A second one is refused while the first is open.
cfa begin_agent_session --name tidy-materialsThe lists name every asset by path. undo.user_steps counts edits you made yourself in the same time.
cfa get_agent_sessionend_agent_session keeps every change. rollback_agent_session undoes the session's steps without keeping a redo, then deletes the assets the session created.
cfa end_agent_session
cfa rollback_agent_session{
"verdict": "pass_with_warnings",
"undone": 3,
"removed_assets": ["/Game/Tidy/M_New.M_New"],
"saved_on_disk": ["/Game/Props/M_Crate"],
"deleted_not_restored": []
}saved_on_disk lists assets the agent saved: the editor is back to before the session, but the file on disk keeps the agent's version until you save that asset again. deleted_not_restored lists assets the agent deleted, which undo cannot bring back.
--include-user-edits to undo those too); a level load or the memory limit reset the undo history; or a step created or destroyed something that undo cannot reverse cleanly. The reply says which one it was.Outside a session, each change a command makes is still a single named step in the editor's undo history, such as CFA: set_material_properties, so one Ctrl+Z takes it back. A command that fails undoes its own work before it replies.
Read the undo history, with what each step touched:
cfa get_undo_history --detailsUndo the last step:
cfa undo