ComfyUI

The ComfyUI LOP bridges TouchDesigner and ComfyUI, letting you load any ComfyUI workflow, control its parameters from the TD parameter panel, queue generations, and browse completed outputs — all while a live WebSocket connection streams progress in real time. The operator also exposes a GetTool() method so an Agent LOP can trigger generations and adjust workflow parameters autonomously.

Requirements

• A running ComfyUI server (local at http://127.0.0.1:8188 or Comfy.org Cloud)
• Python packages: aiohttp, requests, Pillow (for TOP → image conversion)
• For Comfy.org Cloud: a valid API key from platform.comfy.org/profile/api-keys

Input / Output

Inputs

None — all configuration is via parameter panel. Image inputs for nodes like LoadImage are supplied through dynamically generated workflow parameters (see Workflow Parameters below).

Outputs

• Output 1 (TOP): Live display of the most recently selected generation from history.
• Output 2 (DAT): Table of completed job outputs (file paths or text) parsed from the internal history table.

Usage Examples

Connecting and Running a First Generation

1. On the Config page, set Server to your ComfyUI server URL (default http://127.0.0.1:8188). Enable Auto Connect if you want the operator to connect automatically on startup.
2. Pulse Connect. The Status field at the top of the ComfyUI page will update to show the connection state.
3. On the ComfyUI page under the Workflow section, browse to your workflow JSON file (or a PNG with embedded workflow metadata) using the File parameter.
4. Pulse Load to parse the workflow. Dynamic parameters for every editable node input will appear below the workflow header on the same page.
5. Adjust the generated parameters (prompts, seeds, sampler settings, etc.) as needed.
6. Pulse Generate to queue the workflow. The Progress field will update with step counts as ComfyUI executes.

Browsing Outputs on the History Page

After a generation completes, switch to the History page:

• Use the Job slider or < Prev Job / Next Job > pulses to step through completed generations.
• If a job produced multiple images, use the Output slider or < Prev / Next > pulses to switch between them.
• Enable Auto Jump to New to automatically jump to the newest job when it completes.
• The Output 1 wire from the operator shows the currently selected image.

Continuous Generation (Keep Generating)

1. On the ComfyUI page, set Post-Gen to randomize and enter *seed* in the Filter field to randomize any seed parameters after each generation.
2. Enable Keep Generating.
3. Pulse Generate once to start. The operator will automatically re-queue after each completed job.
4. To stop, pulse Interrupt or Clear Queue, or toggle Keep Generating off.

Using Comfy.org Cloud

1. On the Config page, set Server to https://cloud.comfy.org.
2. Under the Comfy.org Cloud section, paste your API key into the API Key field. It is saved to ChatTD’s KeyManager automatically and will not be visible in plain text after entry.
3. Pulse Connect — the connection uses WSS and authenticates via the stored key.

Workflow Parameters

When a workflow is loaded, the operator inspects every node’s editable inputs and creates corresponding TD parameters dynamically on the ComfyUI page, grouped under the workflow file name as a section header. Parameter types mirror the ComfyUI input types:

• String inputs → Str parameters
• Integer / float inputs → Int / Float parameters with range from the node definition
• Menu inputs (samplers, schedulers, etc.) → Menu parameters
• Seed inputs → Int with a large range (0–999999999)
• Image inputs → TOP, File, or StrMenu reference, depending on the Input Type setting on the Config page

Load Mode controls what happens when you reload or swap workflows:

• preserve — matching parameters (by name) keep their current values, including TOP references. Useful when iterating on the same workflow.
• fresh — all parameters are reset to their defaults from the workflow file.

If a parameter appears to be missing or stale after editing the workflow externally, pulse Rebuild Parameters on the Config page to regenerate them.

Image Inputs

The Input Type setting on the Config page determines how image-type workflow parameters (e.g., LoadImage, LoadImageMask) appear:

• top — Each image input becomes a TOP reference parameter. On generate, the connected TOP is captured and uploaded to ComfyUI automatically. Requires Pillow.
• file — Each image input becomes a file path parameter. The file is uploaded to ComfyUI on generate.
• strmenu — Each image input becomes a string menu showing images already present in ComfyUI’s input folder. Use this when managing files externally.

For workflows using base64 image nodes (Base64ImageInput, ETN_LoadImageBase64), the TOP or file is converted to base64 and sent inline rather than uploaded.

Output Modes

Set Output Mode on the Config page:

• local_file — References ComfyUI’s output files by path. Requires ComfyUI Folder to be set so the operator can resolve the correct output directory.
• download — Fetches output files via the ComfyUI API and saves them to the Folder specified under the Output section. Use this for remote servers or when files are not directly accessible on disk.

Enable Save Previews to also capture intermediate preview images sent over the WebSocket during sampling.

Agent Tool Integration

🔧 GetTool Enabled 1 tool

This operator exposes 1 tool that allow Agent and Gemini Live LOPs to trigger ComfyUI generations and optionally set workflow parameters before executing.

Use the Tool Debugger operator to inspect exact tool definitions, schemas, and parameters.

When connected to an Agent LOP, the ComfyUI operator exposes a single tool whose name is set by the Tool Name field on the Config page (default: generate_image). The agent can call this tool to queue a generation, optionally passing parameter values to update the workflow before running.

Three Tool Mode options control how the tool behaves:

Mode	Description
auto	Exposes filtered workflow parameters as optional tool arguments. Agent can call with no arguments (just run it) or pass values to override parameters.
execute_only	No parameters exposed — agent just triggers a generation with whatever is currently set.
params_only	Exposes parameters like auto but the agent decides which to set; execution is not automatic.

The Parameter Filter field controls which workflow parameters are visible to the agent. Leave empty to expose all parameters, or use space-separated patterns with TouchDesigner wildcard syntax (e.g., *prompt* *seed* to expose only prompt and seed inputs, ^*image* to exclude image parameters).

Allow Tool Updates must be enabled for agent-provided parameter values to actually be applied before generation runs.

Tool description

The agent tool’s description is read from an internal editable DAT inside the operator. If you need to give the agent specific instructions about your workflow (what the workflow produces, which parameters matter most), open the operator and edit the tool_description DAT directly.

Troubleshooting

“Not connected” error when pulsing Generate Pulse Connect on the Config page first, or enable Auto Connect so the operator connects on startup.

“No workflow loaded” error Set a workflow File path on the ComfyUI page and pulse Load before generating.

Dynamic parameters are missing or wrong after editing the workflow Pulse Rebuild Parameters on the Config page to regenerate parameters from the current workflow file.

Image input parameters are empty and generation fails If Input Type is top, connect a TOP to each image parameter that was generated on the ComfyUI page. If Input Type is file, enter a valid file path. The operator validates image inputs before queuing and will log errors per missing input.

local_file mode shows no output Set ComfyUI Folder on the Config page to the root of your ComfyUI installation (the folder containing the output/ directory). Without this the operator cannot resolve output file paths.

Comfy.org Cloud connection fails Confirm your API key is valid (get one from platform.comfy.org/profile/api-keys) and that the Server field is exactly https://cloud.comfy.org. After pasting the key, it is stored in ChatTD’s KeyManager — the field will show API KEY SAVED (KeyManager) when successful.

Generation appears stuck with no progress Pulse Interrupt to stop the current job, or Clear Queue to cancel all pending jobs. Then pulse Reset Operator on the Config page if the operator state appears corrupted. This disconnects, clears all history and queue data, and returns the operator to a clean state.

Parameters

ComfyUI

Status (Status) op('comfyui').par.Status Str

Current status

Default:

"" (Empty String)

Workflow Header

File (Workflowfile) op('comfyui').par.Workflowfile File

ComfyUI workflow JSON file (API format or full workflow)

Default:

"" (Empty String)

Load Mode (Workflowloadmode) op('comfyui').par.Workflowloadmode Menu

Preserve: keep matching param values (TOP refs, etc). Fresh: clear all values.

Default:

preserve

Options:

preserve, fresh

Load (Loadworkflow) op('comfyui').par.Loadworkflow Pulse

Load and parse the workflow file

Default:

False

Generate Header

Generate (Generate) op('comfyui').par.Generate Pulse

Queue generation with current parameters

Default:

False

Interrupt (Interrupt) op('comfyui').par.Interrupt Pulse

Stop current generation

Default:

False

Clear Queue (Clearqueue) op('comfyui').par.Clearqueue Pulse

Clear all pending generations

Default:

False

Clear Workflow (Clearworkflow) op('comfyui').par.Clearworkflow Pulse

Default:

False

Progressdisplay (Progressdisplay) op('comfyui').par.Progressdisplay Str

Generation progress

Default:

"" (Empty String)

Post-Gen (Postgenmode) op('comfyui').par.Postgenmode Menu

Action to apply to matching params after generation

Default:

none

Options:

none, randomize, increment, decrement

Filter (Postgenfilter) op('comfyui').par.Postgenfilter Str

Wildcard pattern for params to modify (e.g., *seed*)

Default:

"" (Empty String)

Keep Generating (Keepgenerating) op('comfyui').par.Keepgenerating Toggle

Continuously generate after each completion

Default:

False

(no workflow loaded) Header

Config

Connection Header

ComfyUI Folder (Comfyuibasefolder) op('comfyui').par.Comfyuibasefolder Folder

Path to ComfyUI installation folder (contains output/, temp/, etc). Required for local_file mode.

Default:

"" (Empty String)

Server (Serverurl) op('comfyui').par.Serverurl StrMenu

Local ComfyUI server or Comfy.org Cloud (requires API key and subscription)

Default:

"" (Empty String)

Menu Options:

• http://127.0.0.1:8188 (http://127.0.0.1:8188)
• https://cloud.comfy.org (https://cloud.comfy.org)

Auto Connect (Autoconnect) op('comfyui').par.Autoconnect Toggle

Automatically connect on init

Default:

False

Connect (Connect) op('comfyui').par.Connect Pulse

Connect to ComfyUI server

Default:

False

Disconnect (Disconnect) op('comfyui').par.Disconnect Pulse

Disconnect from server

Default:

False

Image Inputs Header

Input Type (Imagepartype) op('comfyui').par.Imagepartype Menu

TOP (default), file path, or ComfyUI image list

Default:

top

Options:

top, file, strmenu

Output Header

Folder (Outputfolder) op('comfyui').par.Outputfolder Folder

Where to save images (empty = project folder)

Default:

"" (Empty String)

Output Mode (Outputmode) op('comfyui').par.Outputmode Menu

local_file: reference ComfyUI output paths. download: fetch outputs via API to local folder.

Default:

local_file

Options:

local_file, download

Save Previews (Savepreviews) op('comfyui').par.Savepreviews Toggle

Save intermediate preview images during generation (rare use case).

Default:

False

Agent Integration Header

Parameter Filter (Apiparfilter) op('comfyui').par.Apiparfilter Str

Which params agents can control (* = all)

Default:

"" (Empty String)

Allow Tool Updates (Allowtoolparamupdates) op('comfyui').par.Allowtoolparamupdates Toggle

Let agent tool calls modify parameters

Default:

False

Comfy.org Cloud Header

API Key (Comfyorgapikey) op('comfyui').par.Comfyorgapikey Str

Comfy.org API key for cloud nodes (Gemini, ChatGPT, etc). Get from platform.comfy.org/profile/api-keys

Default:

"" (Empty String)

Debug Header

Enable Logging (Enablelogging) op('comfyui').par.Enablelogging Toggle

Log to console and tables

Default:

False

Rebuild Parameters (Refreshparams) op('comfyui').par.Refreshparams Pulse

Rebuild dynamic workflow parameters

Default:

False

Tool Name (Toolname) op('comfyui').par.Toolname Str

Name of the tool exposed to agents

Default:

"" (Empty String)

Tool Mode (Toolmode) op('comfyui').par.Toolmode Menu

auto: expose filtered params, execute_only: no params required, params_only: expose params but agent decides

Default:

auto

Options:

auto, execute_only, params_only

Reset Operator (Resetop) op('comfyui').par.Resetop Pulse

Default:

False

History

Jobinfo (Jobinfo) op('comfyui').par.Jobinfo Str

Job information

Default:

"" (Empty String)

Currentfile (Currentfile) op('comfyui').par.Currentfile Str

Current file path

Default:

"" (Empty String)

Job (Jobindex) op('comfyui').par.Jobindex Int

Select completed generation (1 = most recent)

Default:

0

Range:

1 to 1

Slider Range:

1 to 1

Output (Outputindex) op('comfyui').par.Outputindex Int

Select output image from job

Default:

0

Range:

1 to 1

Slider Range:

1 to 1

< Prev Job (Prevjob) op('comfyui').par.Prevjob Pulse

Go to previous job

Default:

False

Next Job > (Nextjob) op('comfyui').par.Nextjob Pulse

Go to next job

Default:

False

< Prev (Prevoutput) op('comfyui').par.Prevoutput Pulse

Previous output in current job

Default:

False

Next > (Nextoutput) op('comfyui').par.Nextoutput Pulse

Next output in current job

Default:

False

Auto Jump to New (Autojumptonewjob) op('comfyui').par.Autojumptonewjob Toggle

Automatically select newest job when new outputs arrive

Default:

False

Changelog

v0.1.02026-03-12

• Extract workflow, parameters, images, history into src/ modules - Add PNG workflow loading with embedded ComfyUI metadata - Add Keep Generating mode for continuous generation - Refactor client_id handling and WebSocket connection
• Add proper README with description, developer notes - Fix manifest.json description - Add extends field for util-base-lop
• Initial commit

Related Operators

• Agent