Skip to content
LOPs logo LOPs
  1. OPERATORS
  2. CONTROLLERS

Tool TD Code

v1.0.0new

tool_td_code gives an Agent a single Python execution tool inside the live TouchDesigner project. Use it when an agent needs broad inspection or controlled scripting access and a narrower purpose-built tool is not enough.

What It Does

Section titled “What It Does”

The operator exposes one callable tool whose name is built from Tool Prefix and Tool Name. When enabled, the tool executes submitted Python with TouchDesigner globals available and session variables preserved between calls. It captures printed output and errors, truncates long responses by Max Output, and can append corrective Error Guidance when common failures occur.

Path restrictions and always-blocked safety patterns are checked before execution. Optional module injection can load Python text DATs from a Modules COMP into the execution namespace so agents can call prepared helper modules.

Typical Workflow

Section titled “Typical Workflow”
  1. Keep Enable Tool on only for agents that should have Python execution access.
  2. Set Tool Prefix and Tool Name so the exposed name is unique in the agent’s tool list.
  3. Leave Enable Path Restrictions on and review the Restricted Paths sequence for the project.
  4. Adjust Tool Description to describe the local workspace and expectations.
  5. Optionally enable Enable Modules and set Modules COMP to expose curated helper DATs.
  6. Inspect the agent’s returned stdout/error response after each call.

Inputs And Outputs

Section titled “Inputs And Outputs”
  • Inputs: No connector inputs. Agents call the exposed tool.
  • Outputs: No connector outputs. Execution results are returned through the tool response.

Agent Tool Use

Section titled “Agent Tool Use”

tool_td_code exposes GetTool() when Enable Tool is on. The default tool name is td_code. It gives an agent live Python execution with persistent session globals, optional multi-step frame-delayed execution, module globals, safety blocking, and stdout/stderr response capture.

Works Well With

Section titled “Works Well With”
  • agent: Calls the execution tool.
  • tool_td_mod: Use tool_td_mod for structured network edits and reserve tool_td_code for cases that need arbitrary Python.
  • tool_manager: Helps manage which tools are exposed to a given agent.
  • tool_parameter: Complements code execution with parameter-focused operations.

Gotchas

Section titled “Gotchas”
  • Session globals persist across calls. State from one task can affect later tasks.
  • The tool returns printed output, not arbitrary Python expression values.
  • Path restrictions match code text and can miss indirect references through variables.
  • Always-blocked safety patterns still apply when path restrictions are off.
  • Multi-step execution waits real TouchDesigner frames between steps, so results depend on network cooking timing.
  • Max Output truncates long responses; important details can be beyond the limit.

Parameters

Section titled “Parameters”

Tool

Section titled “Tool”
Tool Prefix (Toolprefix) op('tool_td_code').par.Toolprefix Str

Prefix for tool name (e.g. td -> td_code)

Default:
td
Tool Name (Toolname) op('tool_td_code').par.Toolname Str

Suffix after prefix. Default td_code.

Default:
code
Enable Tool (Enabletool) op('tool_td_code').par.Enabletool Toggle

Master switch. When off, GetTool returns None.

Default:
True
Max Output (Maxoutput) op('tool_td_code').par.Maxoutput Int

Truncate output at this char count

Default:
4000
Range:
0 to 1
Error Guidance (Guidance) op('tool_td_code').par.Guidance Toggle

Append corrective hints to error responses

Default:
True
Tool Description (Tooldescription) op('tool_td_code').par.Tooldescription Str

Base description exposed to agents. Module info appended when enabled.

Default:
Execute Python in a live TouchDesigner environment. All TD globals available (op, ops, ui, absTime, mod, run, etc.). me is this tool operator — use me.parent() to reach the workspace. Variables persist between calls. Use print() for output. For multi-step with frame delays: pass steps as a native array of {code, delayFrames} objects.

Restrictions

Section titled “Restrictions”
Enable Path Restrictions (Enablerestrict) op('tool_td_code').par.Enablerestrict Toggle

Block access to listed paths

Default:
True
Restricted Paths (Restrict) op('tool_td_code').par.Restrict Sequence
Default:
0
Path (Restrict0path) op('tool_td_code').par.Restrict0path Str
Default:
/local
Path (Restrict1path) op('tool_td_code').par.Restrict1path Str
Default:
/local
Path (Restrict2path) op('tool_td_code').par.Restrict2path Str
Default:
/local

Modules

Section titled “Modules”
Enable Modules (Enablemodules) op('tool_td_code').par.Enablemodules Toggle

Load Python text DATs from Modulescomp into session globals

Default:
True
Modules COMP (Modulescomp) op('tool_td_code').par.Modulescomp OP

COMP whose text DAT children are loaded as importable modules

Default:
"" (Empty String)

Changelog

Section titled “Changelog”
v1.0.02026-05-02
  • added docs/compose.json - added changelog and releases directory placeholders
  • Initial tool_td_code structure
Section titled “Related Operators”