Agent CLI

The nodetool agent command runs autonomous AI agents from start to finish using a YAML configuration file. Agents use the planning agent architecture to break down tasks, execute them step-by-step, and achieve goals through tool usage and iterative refinement.

Overview

The agent CLI enables:

Autonomous execution: Run agents that plan and execute tasks independently
YAML configuration: Define agent behavior, models, and tools in configuration files
Planning agent integration: All agents use the planning agent for task decomposition
Tool orchestration: Agents can use multiple tools to accomplish complex goals
Workspace isolation: Each agent run has its own workspace for file operations

Basic Usage

Running an Agent

# Run agent with inline prompt
nodetool agent --config research-agent.yaml --prompt "Research the latest AI trends"

# Run agent with prompt from file
nodetool agent --config code-assistant.yaml --prompt-file task.txt

# Run agent interactively
nodetool agent --config content-creator.yaml --interactive

Command Options

--config FILE (required) — Path to agent YAML configuration file
--prompt TEXT — Inline prompt for the agent
--prompt-file FILE — Load prompt from a text file
--interactive / -i — Start interactive session with the agent
--workspace DIR — Override workspace directory from config
--max-iterations N — Override maximum planning iterations
--verbose / -v — Enable debug logging
--output FILE — Save agent output to file
--jsonl — Output in JSONL format for automation

Interactive Mode

In interactive mode, you can have multi-turn conversations with the agent:

nodetool agent --config research-agent.yaml --interactive

Agent initialized: research-assistant
Type your prompt or /help for commands

> Research quantum computing applications in cryptography

[Agent executes task with planning steps shown]

> Save that to a file called quantum-crypto.md

[Agent saves the research]

> /workspace
Workspace: ~/.nodetool-workspaces/research
Files: quantum-crypto.md

> /exit

Agent Configuration

YAML Structure

Agent configurations are defined in YAML files with the following structure:

# Agent identification
name: agent-name
description: Agent purpose and capabilities

# Core agent prompt
system_prompt: |
  Detailed instructions for agent behavior
  Multiple lines supported

# Model configuration
model:
  provider: openai     # AI provider
  id: gpt-4o          # Model identifier
  name: GPT-4o        # Display name (optional)

# Planning agent (always enabled)
planning_agent:
  enabled: true
  model:
    provider: openai
    id: gpt-4o-mini

# Available tools
tools:
  - google_search
  - browser
  - write_file
  - read_file

# Execution parameters
max_tokens: 8192
context_window: 8192
temperature: 0.7
max_iterations: 10

# Workspace
workspace:
  path: ~/.nodetool-workspaces/agent-name
  auto_create: true

Configuration Fields

Required Fields

name: Unique identifier for the agent
system_prompt: Instructions defining agent behavior
model: Primary model configuration with provider and id
planning_agent: Planning agent configuration (must have enabled: true)

Optional Fields

description: Human-readable description of the agent’s purpose
tools: List of tool names the agent can use (default: basic file operations)
max_tokens: Maximum token length for responses (default: 8192)
context_window: Size of the context window (default: 8192)
temperature: Response randomness, 0.0-1.0 (default: 0.7)
max_iterations: Maximum planning/execution cycles (default: 10)
workspace: Workspace configuration object

Model Configuration

The model field specifies which AI model to use:

model:
  provider: openai        # Provider name
  id: gpt-4o             # Model ID
  name: GPT-4o           # Display name (optional)

Supported providers:

openai — OpenAI models (GPT-4o, GPT-4o-mini, o1, etc.)
anthropic — Anthropic models (Claude 3.5 Sonnet, Claude 3 Opus, etc.)
google — Google models (Gemini 2.0 Flash, Gemini 1.5 Pro, etc.)
ollama — Local models via Ollama
Custom providers as configured in NodeTool

Planning Agent

The planning agent is always enabled and coordinates task execution:

planning_agent:
  enabled: true  # Required, must be true
  model:
    provider: openai
    id: gpt-4o-mini  # Can use different model than main agent

The planning agent:

Breaks down user prompts into subtasks
Determines tool usage and execution order
Monitors progress and adjusts strategy
Synthesizes results from multiple steps

Available Tools

Tools extend agent capabilities. Common tools include:

File Operations:

write_file — Write content to files
read_file — Read file contents
list_directory — List directory contents
delete_file — Delete files

Web Research:

google_search — Search the web
browser — Browse and extract web content

Code Execution:

execute_code — Run Python/JavaScript code
terminal — Execute shell commands

Additional Tools:

grep — Search within files
image_generation — Generate images
audio_generation — Generate audio

Example tool configuration:

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

Workspace Configuration

The workspace is a sandboxed directory for agent file operations:

workspace:
  path: ~/.nodetool-workspaces/my-agent  # Workspace location
  auto_create: true                       # Create if doesn't exist

If not specified, defaults to ~/.nodetool-workspaces/<agent-name>.

Example Configurations

Research Agent

See examples/agents/research-agent.yaml for a complete research agent configuration.

nodetool agent \
  --config examples/agents/research-agent.yaml \
  --prompt "Research the impact of AI on software development"

Code Assistant

See examples/agents/code-assistant.yaml for a coding agent.

nodetool agent \
  --config examples/agents/code-assistant.yaml \
  --prompt "Create a Python script to analyze log files"

Content Creator

See examples/agents/content-creator.yaml for a content generation agent.

nodetool agent \
  --config examples/agents/content-creator.yaml \
  --prompt "Write a blog post about sustainable technology"

Use Cases

Automated Research

nodetool agent \
  --config research-agent.yaml \
  --prompt "Research competitors in the AI workflow space" \
  --output research-report.md

The agent will:

Plan a research strategy
Search for relevant information
Browse competitor websites
Extract and organize findings
Generate a comprehensive report

Code Generation and Refactoring

nodetool agent \
  --config code-assistant.yaml \
  --prompt "Refactor the utils.py file to improve performance"

The agent will:

Read and analyze the code
Identify performance bottlenecks
Plan refactoring steps
Implement improvements
Test changes

Content Pipeline

nodetool agent \
  --config content-creator.yaml \
  --prompt "Create 5 social media posts about our new feature" \
  --output posts.json \
  --jsonl

The agent will:

Research the feature
Plan content strategy
Generate multiple post variants
Format and save outputs

Advanced Usage

Custom Prompts with Context

nodetool agent \
  --config research-agent.yaml \
  --prompt "$(cat context.txt) - Based on this context, analyze market trends"

Chaining Agent Runs

# Research phase
nodetool agent --config research-agent.yaml \
  --prompt "Research topic X" \
  --output research.md

# Writing phase
nodetool agent --config content-creator.yaml \
  --prompt "Write article based on: $(cat research.md)"

Automation Scripts

#!/bin/bash
# Daily research automation

for topic in "AI" "ML" "Web3"; do
  nodetool agent \
    --config research-agent.yaml \
    --prompt "Find latest news about $topic" \
    --output "reports/${topic}-$(date +%Y%m%d).md" \
    --jsonl
done

Environment Variables

Configure via environment variables:

export NODETOOL_WORKSPACE=~/my-workspace
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

nodetool agent --config agent.yaml --prompt "Task"

Interactive Commands

When running with --interactive, these commands are available:

/help — Show available commands
/workspace — Show workspace path and files
/tools — List available tools
/config — Show current configuration
/clear — Clear conversation history
/save [file] — Save conversation to file
/exit — Exit interactive session

Output Formats

Standard Output

Default human-readable output with formatting:

nodetool agent --config agent.yaml --prompt "Task"

[Planning] Breaking down task into 3 steps...
[Step 1/3] Searching for information...
[Tool: google_search] Found 5 relevant results
[Step 2/3] Analyzing results...
[Step 3/3] Generating summary...

Final Output:
[Agent response here]

JSONL Output

Machine-readable JSONL format for automation:

nodetool agent --config agent.yaml --prompt "Task" --jsonl

{"type":"planning","step":1,"total":3,"description":"Searching for information"}
{"type":"tool","name":"google_search","status":"success","results":5}
{"type":"planning","step":2,"total":3,"description":"Analyzing results"}
{"type":"planning","step":3,"total":3,"description":"Generating summary"}
{"type":"output","content":"[Agent response here]"}
{"type":"complete","status":"success","iterations":3}

File Output

Save output to file:

nodetool agent --config agent.yaml --prompt "Task" --output result.txt

Best Practices

System Prompt Design

Be specific and structured:

system_prompt: |
  You are a [role].
  
  Your responsibilities:
  1. [Task 1]
  2. [Task 2]
  
  Workflow:
  1. [Step 1]
  2. [Step 2]
  
  Guidelines:
  - [Guideline 1]
  - [Guideline 2]

Include tool usage instructions:

system_prompt: |
  Tools Available:
  - google_search: Use for finding information
  - write_file: Save important findings
  
  When researching:
  1. Use google_search to find sources
  2. Extract relevant information
  3. Use write_file to save findings

Model Selection

Choose appropriate models:

Planning agent: Use fast, cost-effective models (gpt-4o-mini, claude-3-haiku)
Main agent: Use powerful models for complex reasoning (gpt-4o, claude-3.5-sonnet)
Code tasks: Models with large context windows (claude-3.5-sonnet)
Creative tasks: Higher temperature settings (0.8-1.0)
Analytical tasks: Lower temperature settings (0.0-0.3)

Tool Configuration

Start minimal, add as needed:

# Start with basics
tools:
  - write_file
  - read_file

# Add capabilities progressively
tools:
  - write_file
  - read_file
  - google_search  # When research needed
  - browser        # When detailed web content needed

Iteration Limits

Set appropriate limits:

Simple tasks: 5-8 iterations
Research tasks: 10-15 iterations
Complex projects: 15-20 iterations
Exploratory tasks: 20+ iterations

max_iterations: 10  # Prevent infinite loops while allowing completion

Troubleshooting

Agent Doesn’t Complete Task

Increase iterations:

max_iterations: 20  # Give agent more cycles

Improve system prompt:

system_prompt: |
  # Add more specific instructions
  # Break down expected workflow
  # Clarify success criteria

Tool Errors

Check tool availability:

nodetool agent --config agent.yaml --interactive
> /tools

Verify tool configuration in system prompt and tools list.

Performance Issues

Use faster models for planning:

planning_agent:
  model:
    provider: openai
    id: gpt-4o-mini  # Fast and cost-effective

Reduce context window for simpler tasks:

context_window: 4096  # Smaller for faster processing

Rate Limiting

Add delays or use local models:

model:
  provider: ollama
  id: llama3.2:3b  # Local model, no rate limits

Security Considerations

Workspace Isolation

Agents operate in isolated workspaces:

workspace:
  path: ~/.nodetool-workspaces/agent-name  # Sandboxed directory
  auto_create: true

Best practices:

Use dedicated workspace per agent
Regularly clean up old workspaces
Review agent outputs before moving to production directories

Tool Permissions

Limit tool access to what’s necessary:

# Restrictive
tools:
  - read_file
  - write_file

# Permissive (use cautiously)
tools:
  - read_file
  - write_file
  - terminal
  - execute_code

API Key Security

Use environment variables for API keys:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Never commit keys to configuration files.

Global Chat & Agents — Agent system overview
Chat CLI — Interactive chat interface
NodeTool CLI — Complete CLI reference
Agent Configuration Examples — Sample configurations

Agent CLI

Overview

Basic Usage

Running an Agent

Command Options

Interactive Mode

Agent Configuration

YAML Structure

Configuration Fields

Required Fields

Optional Fields

Model Configuration

Planning Agent

Available Tools

Workspace Configuration

Example Configurations

Research Agent

Code Assistant

Content Creator

Use Cases

Automated Research

Code Generation and Refactoring

Content Pipeline

Advanced Usage

Custom Prompts with Context

Chaining Agent Runs

Automation Scripts

Environment Variables

Interactive Commands

Output Formats

Standard Output

JSONL Output

File Output

Best Practices

System Prompt Design

Model Selection

Tool Configuration

Iteration Limits

Troubleshooting

Agent Doesn’t Complete Task

Tool Errors

Performance Issues

Rate Limiting

Security Considerations

Workspace Isolation

Tool Permissions

API Key Security

Related Documentation

See Also