Submits ComfyUI workflows via POST /prompt, subscribes to /ws for execution events, fetches results from /history, and supports targeted reruns via partial_execution_targets. Use when an agent needs to run, observe, interrupt, or partially re-execute a ComfyUI prompt.
The only Skill in the system that speaks raw HTTP + WebSocket to ComfyUI. Every other Skill (capability Skills, planner, repair, checkpoint) ultimately calls the scripts bundled here.
executing, progress, executed,
execution_error, execution_interrupted) for ReAct repairprompt_id from /historypartial_execution_targetsprompt_id)/object_info (cached)/freeDo not use this Skill to author prompt JSON — capability Skills
(generating-images, inpainting-regions, …) produce prompts via template +
patch and then pipe the JSON into scripts/submit_prompt.py.
COMFYUI_BASE_URL env var (default http://127.0.0.1:8188)COMFYUI_WS_URL env var (default ws://127.0.0.1:8188/ws)ComfyUI-Agent/host/.cache/object_info.jsonNo API key. No custom_node install. The host talks to ComfyUI as an external
HTTP service; this is a hard boundary — see CLAUDE.md anti-patterns.
reference/| File | What it documents |
|---|---|
reference/api.md | Endpoint catalog mirroring ComfyUI_workflow.md §2 — every HTTP surface the scripts here wrap. |
reference/error-payloads.md | node_errors (pre-execution) schema + execution_error (runtime WS) 7-field payload. Read this before touching repairing-workflows. |
scripts/All scripts are runnable standalone. They exit non-zero only on transport-layer failures; protocol errors are returned as JSON on stdout.
| Script | Wraps | Input | Output |
|---|---|---|---|
submit_prompt.py | POST /prompt | stdin JSON {prompt, prompt_id?, client_id?, extra_data?, partial_execution_targets?} | {prompt_id, number, node_errors} on success, {error, node_errors} on validation failure |
subscribe_ws.py | GET /ws (WebSocket) | --client-id flag; optional --prompt-id filter (see notes below) | one JSON line per event to stdout; exits when the filtered prompt reaches executing with node=null / execution_error / execution_interrupted |
get_object_info.py | GET /object_info | optional --node-class | JSON on stdout. Filesystem-cached; invalidated when ComfyUI restart is detected. Cache path overridable via COMFYUI_AGENT_OBJECT_INFO_CACHE. Cache-write failures log to stderr and still emit a single JSON document on stdout. |
get_history.py | GET /history/{prompt_id} | --prompt-id | {outputs, meta} on stdout |
interrupt.py | POST /interrupt | optional --prompt-id for targeted cancel | {ok: true} or {error} |
free.py | POST /free | none | {ok: true} or {error} |
subscribe_ws.pyterminal event: the ComfyUI protocol signals "graph finished" with anexecutingframe whosedata.nodeisnull(not anexecutedframe — that is a per-node progress event). The script therefore exits on the first of:executingwithnode=nullfor the target prompt,execution_error, orexecution_interrupted. Seescripts/subscribe_ws.py::_is_prompt_terminal.
--prompt-idfilter semantics: when a prompt id is supplied the filter passes through (a) per-prompt frames whosedata.prompt_idmatches, plus (b) global frames with nodata.prompt_idat all (e.g.statusqueue-depth,crystools.*telemetry). Frames belonging to a different prompt are dropped. Global frames are kept because they carry session-level signal the host still needs.
compile.py (capability Skill) → prompt.json
→ submit_prompt.py < prompt.json # returns {prompt_id}
→ subscribe_ws.py --prompt-id $ID # stream events until executed
→ get_history.py --prompt-id $ID # fetch outputs
submit_prompt.py # node_errors non-empty → feed to repairing-workflows
or
subscribe_ws.py # execution_error event → feed {node_id, exception_message, current_inputs} to repair
→ repairing-workflows patches prompt.json
→ submit_prompt.py with partial_execution_targets=[affected_output_node]
Every script must:
{error: {type, message}} on stdout.prompt_id explicitly.execution_error WS event — see
CLAUDE.md anti-pattern "every execution_error must reach the repair loop".knowledge/workflows/ComfyUI_workflow.md §2 (control surface), §3 (prompt
JSON shape), §4.1 (submission flow), §4.4 (WebSocket events), §5
(/object_info fields)knowledge/plans/v1/plan_v1.md §6 Group A (this Skill's description),
§7 (integration contract)knowledge/plans/v1/todo.md §4 (Stage 1 tasks and acceptance)