api-workflows
Call nodetool.workflows, nodetool.jobs or nodetool.nodes from a code action: list, validate, save, run, debug and version workflow graphs, wait on background jobs, and look up or probe node types. Load before the first call into these namespaces.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 635
- Forks
- 91
01 前言 Front Matter
- name
- api-workflows
- description
- Call nodetool.workflows, nodetool.jobs or nodetool.nodes from a code action: list, validate, save, run, debug and version workflow graphs, wait on background jobs, and look up or probe node types. Load before the first call into these namespaces.
03 SKILL.md 正文
nodetool.workflows, nodetool.jobs, nodetool.nodes
These three namespaces cover saved graphs, the runs they start, and the node
catalog a graph is built from. How to design a graph is
nodetool-workflow-builder. This skill is the call reference.
Every method takes an id as the full id or its 12-character prefix, and every method throws when its backing tool is not on this belt.
nodetool.workflows
| Call | Does | Answers |
|---|---|---|
list({workflow_type, query, limit}) |
Lists workflows. workflow_type is "user" (default), "example" or "all". |
{workflows: [{id, name, description, tags}]} — an envelope, not an array |
get(id) |
Reads one workflow with its graph. | The workflow record |
create(name, graph, {description, tags, access, project_id}) |
Saves a new workflow. graph is a DSL result, {nodes, edges}, or a workflow record. create({name, graph}) also works. |
The saved workflow with its id |
validate(idOrGraph) |
Checks a graph against the node registry without a run. | {ok, issues}. Throws when the graph has errors, so a broken graph cannot reach a paid run. |
run(id, params, {interactive, node_ids, reuse_results}) |
Runs and blocks until the run settles. | The run result. With interactive: true, a failed node returns status: "escalated". |
start(id, params, {node_ids, reuse_results}) |
Starts a run and returns at once. | A receipt {job_id, id, status: "running"} |
debug(id, params, {interactive, node_ids, reuse_results, include_graph, log_limit}) |
Runs and reports. | {workflow_id, run, job, workflow}. An escalated debug answers {workflow_id, run} with the escalation under run. |
resolve(sessionId, escalationId, action, {outputs, reason, apply_to}) |
Answers an escalation. | The next escalation, or the final report |
example("<package>/<name>") |
Loads a shipped example with its graph. A bare name reads from nodetool-base. |
The example workflow |
versions(id, {limit}), getVersion(id, n) |
Lists and reads snapshots. | Version rows, newest first |
snapshot(id, {name, description}) |
Saves the current graph as a manual version. | The new version number |
restore(id, n) |
Rolls the graph back. The graph it replaces is snapshotted first, so a restore can be undone. | — |
deleteVersion(id, n) |
Deletes one snapshot. This cannot be undone. | — |
open(id?) |
Opens the editable object model of a graph that is open in the editor. Throws when no editor tools are on the belt. | A workflow object: addNode, connect, commit() |
node_ids runs only those nodes and what they need upstream. Unrelated
branches and downstream nodes are not executed or billed. An upstream
generator that already produced output in this workflow is fed that output
instead of running again, unless reuse_results: false. This is the cheapest
way to re-run one repaired node.
The debug report
debug answers {workflow_id, run, job, workflow}:
run.statusis the verdict of the run, andrun.errornames the failure.run.outputsis keyed by output name. Each name holds an array of the values it emitted, so readrun.outputs.summary[0], notrun.outputs.summary.run.verdict.issueslists what went wrong, node by node.jobcarries the status, the cost and the logs.
Escalations
An interactive run parks on a failed node and answers status: "escalated"
with a session_id, an escalation_id and escalation.allowedActions. The actions
are retry, substitute (with {outputs}, only when the escalation has a
candidateOutput), skip, end_stream and fail (with {reason}).
apply_to: "signature" also answers later failures with the same signature.
run answers the escalation at the top level. debug nests it under run,
so drive the loop with run. resolve answers the next escalation or the
final report, both at the top level. Write the whole loop in one action:
let report = await nodetool.workflows.run(id, params, { interactive: true });
while (report.status === "escalated") {
report = await nodetool.workflows.resolve(report.session_id, report.escalation_id, "skip");
}
return { status: report.status, error: report.error, issues: report.verdict?.issues };
An unanswered escalation fails the run when its decision timeout expires.
Rules
- A saved graph is not a run. When the user asked for results, call
run. - Validate before
createand before a paid run.validatethrows on errors, and its message lists the errors only. - A
*_modelproperty left unset fails validation. Assign(await nodetool.models.pick(capability)).ref. createchecks model properties. An unknown provider or model id is refused and not saved.
nodetool.jobs
A job is one execution of a workflow, and a render of a timeline is a job too.
| Call | Answers |
|---|---|
list({workflow_id, limit}) |
Job rows with status, timing, error and the names of the outputs. The values are not in the list. |
get(idOrReceipt) |
One job, with the outputs once it has settled |
logs(idOrReceipt, {limit}) |
The log tail. It answers for a failed job too, with the failure under job_error. |
wait(idOrReceipt, {timeoutMs, pollMs}) |
Polls until the status is completed, failed, cancelled or error, then answers the job. On a timeout it throws with the last status. |
Every call takes the id string or the receipt that start() answered.
Start, do other work, then wait, all in one action:
const receipt = await nodetool.workflows.start(id, { prompt: "a fox" });
// … other work in the same action …
const settled = await nodetool.jobs.wait(receipt, { timeoutMs: 300000 });
return { status: settled.status, outputs: settled.outputs };
Do not write one get() per action. wait is the polling loop. A code
action stops after 600 s, so keep timeoutMs well under 600000 and call
wait again in the next action when the job is still running.
nodetool.nodes
| Call | Does | Answers |
|---|---|---|
search(query, {n_results, namespace, input_type, output_type, include_provider_nodes}) |
Searches the catalog. query is a string or an array of terms. |
{total, results}. The node type of a result is on type, not node_type. |
info(type) |
Reads one node type: properties, inputs, outputs, defaults. | The node metadata |
list({namespace, limit}) |
Browses a namespace. An unknown namespace answers with the namespaces that exist. | Node rows |
run(type, inputs) |
Runs ONE node with a property bag, with no workflow. | The outputs, keyed by slot |
- Never guess a node type. Search, then read
infofor the exact property names before you wire the node. - Provider nodes (
openai.*,fal.*and others) are hidden unless you passinclude_provider_nodes: true. Pass it only when the user named a provider. runis the cheapest probe of what a node does. Try one node before you put it in a graph.- To call nodes as functions inside an action, import them from
@nodetool-ai/sandbox-flow. To author a graph, import them from@nodetool-ai/sandbox-dsl.nodetool-js-scriptingcovers both packs.
04 同仓库更多 Skills
humanizer
Rewrite AI-sounding text so it reads like the writer without changing what it says. Use when editing or reviewing prose for AI tells: not-X-but-Y contrasts, one-line closers, staged openers, forced triads, dashes everywhere, inflated claims, sales language, stock AI words, bold labels, or filler.
nodetool
Use the NodeTool MCP server to build, validate, run, and debug visual AI workflows, and to work with assets, collections, and jobs. Use when the user mentions NodeTool or asks for a workflow graph, a node, or a media generation run on their NodeTool server.
wan-2-6-prompting
Prompt Alibaba's Wan 2.6 video — text-to-video with a global style line plus timing-bracketed shots, and image-to-video that describes only what changes over time. Covers the shot-mode switch per provider, the prompt budget, negative prompts, motion intensity wording, audio input and prompt expansion. Use whenever the model id names a Wan 2.6 video route (alibaba/wan-2.6/text-to-video, alibaba/wan-2.6/image-to-video, wan-video/wan-2.6-t2v, wan-video/wan-2.6-i2v, wan-video/wan2.6-i2v-flash) on generate_video, animate_image or a TextToVideo node. Not for Wan 2.5 or 2.7, or the Wan 2.6 image routes.
video-workflow
Build a reusable NodeTool video workflow for batches or repeated inputs. For a single finished piece, use a storyboard skill.
video-clone
Analyze a reference video and recreate its shot structure with a new product or cast in NodeTool.
video-audio-continuity
Keep sound continuous across a multi-scene piece cut from generated video — why one clip per scene hard-cuts the audio at every boundary, when to write all the scenes into a single generation instead, the sound-design vocabulary that survives a provider's copyright filter, and how to check the length, the aspect ratio and the mix of what came back. Use when a piece has more than one scene and the video model writes its own audio (Seedance 2, Veo 3, MiniMax H3, Kling 2.6 and later), or when a cut's sound drops out at the shot changes.