AGENT SKILL

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.status is the verdict of the run, and run.error names the failure.
  • run.outputs is keyed by output name. Each name holds an array of the values it emitted, so read run.outputs.summary[0], not run.outputs.summary.
  • run.verdict.issues lists what went wrong, node by node.
  • job carries 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 create and before a paid run. validate throws on errors, and its message lists the errors only.
  • A *_model property left unset fails validation. Assign (await nodetool.models.pick(capability)).ref.
  • create checks 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 info for the exact property names before you wire the node.
  • Provider nodes (openai.*, fal.* and others) are hidden unless you pass include_provider_nodes: true. Pass it only when the user named a provider.
  • run is 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-scripting covers both packs.

04 同仓库更多 Skills

nodetool-ai
nodetool-ai/nodetool

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.

★ 635
nodetool-ai
nodetool-ai/nodetool

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.

开发工程师Skill与智能体开发
★ 635
nodetool-ai
nodetool-ai/nodetool

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.

图像与多媒体
★ 635
nodetool-ai
nodetool-ai/nodetool

video-workflow

Build a reusable NodeTool video workflow for batches or repeated inputs. For a single finished piece, use a storyboard skill.

图像与多媒体Skill与智能体开发
★ 635
nodetool-ai
nodetool-ai/nodetool

video-clone

Analyze a reference video and recreate its shot structure with a new product or cast in NodeTool.

图像与多媒体
★ 635
nodetool-ai
nodetool-ai/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.

图像与多媒体
★ 635