nodetool-agent-config

name	nodetool-agent-config
description	Create and configure NodeTool agent YAML configs, set up agent tools, system prompts, planning agents, and workspace isolation. Use when user asks to create an agent config, write YAML for an agent, configure agent tools, set up autonomous execution, or work with the agent CLI.

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:

• 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

system_prompt: |
  You are a [role].

  Responsibilities:
  1. Task 1
  2. Task 2

  Workflow:
  1. Step 1
  2. Step 2

  Constraints:
  - Always cite sources
  - Stay concise

model:
  provider: openai                # openai | anthropic | google | ollama
  id: gpt-4o                     # model identifier
  name: GPT-4o                   # display name (optional)

planning_agent:
  enabled: true
  model:
    provider: openai
    id: gpt-4o-mini              # use cheaper model for planning

tools:
  - google_search
  - browser
  - write_file
  - read_file
  - execute_code
  - terminal
  - grep

max_tokens: 8192
context_window: 8192
temperature: 0.7                  # 0.0-1.0 (analytical=0.0-0.3, creative=0.8-1.0)
max_iterations: 10                # 5-20 depending on task complexity

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

Config Schema Reference

Field	Type	Required	Default	Notes
name	string	Yes	—	Lowercase alphanumeric
description	string	No	—	Human-readable
system_prompt	string	Yes	—	YAML multiline |
model.provider	enum	Yes	—	openai, anthropic, google, ollama
model.id	string	Yes	—	Model identifier
model.name	string	No	—	Display name
planning_agent.enabled	bool	Yes	true	Must be true
planning_agent.model.*	—	No	same as main	Override for planning
tools	string[]	No	[read_file, write_file]	Available tools
max_tokens	int	No	8192	Response limit
context_window	int	No	8192	Context size
temperature	float	No	0.7	0.0–1.0
max_iterations	int	No	10	Execution loops
workspace.path	string	No	~/.nodetool-workspaces/	Sandbox dir
workspace.auto_create	bool	No	true	Create if missing

CLI Commands

# Run with prompt
nodetool agent --config agent.yaml --prompt "Research TypeScript ORMs"

# From file
nodetool agent --config agent.yaml --prompt-file task.txt

# Interactive mode
nodetool agent --config agent.yaml --interactive

# Save output
nodetool agent --config agent.yaml --prompt "Task" --output result.md

# JSONL output
nodetool agent --config agent.yaml --prompt "Task" --jsonl

# Verbose (debug)
nodetool agent --config agent.yaml --prompt "Task" --verbose

Interactive Commands

Command	Purpose
/help	Show commands
/workspace	Show workspace path
/tools	List available tools
/config	Show configuration
/clear	Clear history
/save [file]	Save conversation
/exit	Exit session

Available Tools

Tool	Description
read_file	Read file contents
write_file	Write/create files
list_directory	List directory contents
google_search	Web search
google_news	News search
google_images	Image search
browser	Browse web pages
screenshot	Take screenshots
execute_code	Run code snippets
terminal	Shell commands
grep	Search file contents
calculator	Math calculations
statistics	Statistical analysis
vec_text_search	Vector text search
vec_index	Index documents
vec_hybrid_search	Hybrid vector search
extract_pdf_text	Extract PDF text
convert_pdf_to_markdown	PDF to Markdown

Model Recommendations

Use Case	Provider	Model	Notes
Planning (cheap)	openai	gpt-4o-mini	Fast, inexpensive
Planning (cheap)	anthropic	claude-3-haiku	Fast alternative
Planning (cheap)	google	gemini-2.0-flash	Google fast tier
Main (powerful)	openai	gpt-4o	Best all-around
Main (powerful)	anthropic	claude-3.5-sonnet	Strong reasoning
Creative	any	any	temperature 0.8–1.0
Analytical	any	any	temperature 0.0–0.3
Local/offline	ollama	llama3, mistral	No API key needed

Programmatic Usage (TypeScript)

import { Agent } from "@nodetool-ai/core";

const agent = new Agent({
  name: "researcher",
  objective: "Research TypeScript ORMs",
  provider: openaiProvider,
  model: "gpt-4o",
  tools: [new GoogleSearchTool(), new BrowserTool(), new WriteFileTool()],
  workspace: "/tmp/research",
  maxSteps: 10,
  maxStepIterations: 5,
});

for await (const message of agent.execute(context)) {
  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-4o }
tools: [google_search, browser, write_file]
max_iterations: 15
temperature: 0.3

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-3.5-sonnet }
tools: [read_file, write_file, terminal, grep]
max_iterations: 20
temperature: 0.2

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-4o }
tools: [google_search, browser, write_file]
max_iterations: 10
temperature: 0.8

Batch Automation

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

Common Pitfalls

• Missing planning_agent.enabled: true: Planning is required
• Too few iterations: Complex tasks need max_iterations: 15-20
• Wrong temperature: Analytical tasks fail with high temperature
• Missing tools: Agent can't do what you ask if the tool isn't listed
• No workspace: File tools need workspace.auto_create: true