nodetool-agent-config

You help users create and configure NodeTool agents — autonomous AI systems that plan and execute multi-step tasks using tools.

Agent Architecture

Objective → Agent → (Skill resolution → Planning → Execution) → Result

Three agent classes (from @nodetool-ai/agents):

• Agent: Multi-step with planning, tool use, iterative execution
• SimpleAgent: Single-step with structured output schema
• AgentExecutor: Lightweight value extraction

YAML Config Template

name: my-agent                    # lowercase, alphanumeric
description: Agent purpose         # human-readable

# Objective is optional here — it can be passed via --objective or stdin.
objective: Research TypeScript ORMs and summarize findings

system_prompt: |
  You are a [role].

  Responsibilities:
  1. Task 1
  2. Task 2

  Constraints:
  - Always cite sources
  - Stay concise

model:
  provider: openai                 # openai | anthropic | gemini | ollama | any registry id
  id: gpt-5.4                      # model identifier
  name: GPT-5.4                    # display name (optional)

planning_agent:
  enabled: true                    # set false to skip planning (single-pass)
  model:
    provider: openai
    id: gpt-5.4-mini               # cheaper model for planning

tools:
  - google_search
  - browser
  - write_file
  - read_file
  - run_code
  - grep

max_tokens: 8192                   # response/token budget (maxTokenLimit)
max_steps: 10                      # number of plan steps (5-20 by complexity)

workspace:
  path: ~/.nodetool-workspaces/my-agent
  auto_create: true                # default true

# Optional: bias find_model toward specific providers/models.
preferred_providers:
  - anthropic
  - openai
preferred_models:
  image_generation: gpt-image-2
  language_model: claude-sonnet-4-6

Config Schema Reference

These are the fields the nodetool agent loader reads (loose schema — unknown keys are ignored):

CLI Commands

The nodetool agent command has three subcommands. From source use npm run dev:nodetool -- agent ...; from a build use nodetool agent ....

# Run an agent — objective via flag, stdin, or `objective:` in the YAML
nodetool agent run agent.yaml --objective "Research TypeScript ORMs"
echo "Research TypeScript ORMs" | nodetool agent run agent.yaml
nodetool agent run agent.yaml          # uses objective: from the YAML

# Override provider/model/workspace at runtime
nodetool agent run agent.yaml -o "Task" --provider anthropic --model claude-sonnet-4-6
nodetool agent run agent.yaml -o "Task" --workspace /tmp/run1

# Emit each event as JSON lines on stderr (analyzer-friendly)
nodetool agent run agent.yaml -o "Task" --json

# Verbose trace (includes chunk/low-level events)
nodetool agent run agent.yaml -o "Task" --verbose

# Save the final result to a file (it prints to stdout; trace goes to stderr)
nodetool agent run agent.yaml -o "Task" > result.md

# Validate a config without running it (provider, model, tools)
nodetool agent test agent.yaml

# List YAML agent configs in a directory
nodetool agent list ./agents

run flags: -o, --objective <text>, -p, --provider <id>, -m, --model <id>, -w, --workspace <path>, --json, -v, --verbose.

The trace (planning, tool calls, step results) is written to stderr; the final result is written to stdout, so > file captures just the answer.

Available Tools

Tool names recognized in the YAML tools: list (resolved by the agent CLI). MCP tools configured on the machine are also auto-registered by name.

Note: there is no terminal, execute_code, take_screenshot, or vec_* tool. Use run_code for code execution and screenshot for screenshots.

Model Recommendations

Use current model ids (the chat/agent CLIs default to these per provider):

Run nodetool models recommended for the curated, up-to-date list.

Programmatic Usage (TypeScript)

import { Agent } from "@nodetool-ai/agents";
import {
  ProcessingContext,
  FileStorageAdapter,
} from "@nodetool-ai/runtime";

const agent = new Agent({
  name: "researcher",
  objective: "Research TypeScript ORMs",
  provider: openaiProvider,         // a BaseProvider instance
  model: "gpt-5.4",
  tools: [new GoogleSearchTool(), new BrowserTool(), new WriteFileTool()],
  systemPrompt: "You are a thorough research analyst.",
  planningModel: "gpt-5.4-mini",
  maxTokenLimit: 8192,
  maxSteps: 10,
  workspace: "/tmp/research",
});

const ctx = new ProcessingContext({
  jobId: `agent-${Date.now()}`,
  userId: "1",
  workspaceDir: "/tmp/research",
  workspaceStorage: new FileStorageAdapter("/tmp/research"),
});

for await (const message of agent.execute(ctx)) {
  if (message.type === "chunk") process.stdout.write(message.content);
}

Skills Integration

Agents auto-discover skills from:

1. Constructor skills parameter
2. NODETOOL_AGENT_SKILL_DIRS env var
3. ./.claude/skills/
4. ~/.claude/skills/
5. ~/.codex/skills/

Force specific skills: NODETOOL_AGENT_SKILLS=skill-a,skill-b

Quick Recipes

Research Agent

name: researcher
system_prompt: |
  You are a thorough research analyst. For each topic:
  1. Search for primary sources
  2. Cross-reference facts
  3. Write structured findings with citations
model: { provider: openai, id: gpt-5.4 }
tools: [google_search, browser, write_file]
max_steps: 15

Code Assistant

name: code-helper
system_prompt: |
  You are a senior developer. Write clean, tested code.
  Always read existing code before modifying. Run tests after changes.
model: { provider: anthropic, id: claude-sonnet-4-6 }
tools: [read_file, write_file, edit_file, run_code, grep, glob]
max_steps: 20

Content Creator

name: content-writer
system_prompt: |
  You are a professional content writer. Create engaging,
  well-structured content. Research thoroughly before writing.
model: { provider: openai, id: gpt-5.4 }
tools: [google_search, browser, write_file]
max_steps: 10

Batch Automation

for topic in "AI" "ML" "Web3"; do
  nodetool agent run research.yaml \
    --objective "Find latest news about $topic" \
    > "reports/${topic}.md"
done

Common Pitfalls

• No objective: provide it via --objective, stdin, or objective: in the YAML — the run errors without one.
• Wrong run syntax: it's nodetool agent run <yaml>, not --config <yaml>. There is no interactive agent mode (--interactive) — use nodetool chat for that.
• Unknown tool names: only the catalog above resolves; misspellings (e.g. execute_code, terminal) are skipped with a warning.
• Too few steps: complex tasks need max_steps: 15-20.
• Missing tools: the agent can't do what you ask if the tool isn't listed.
• provider: google: accepted but normalized to gemini.