Creating and Configuring Agents

Agents are the core abstraction in Nestor. Each agent has a role, an LLM adapter, a set of tools, and configurable guardrails.

Creating Agents

Use the CLI to create a new agent with an interactive wizard or flags:

# Interactive wizard
npx nestor-sh agent create

# With flags
npx nestor-sh agent create \
  --name coder \
  --adapter claude \
  --model claude-sonnet-4-6 \
  --description "A senior developer that writes clean TypeScript"

# List all agents
npx nestor-sh agent list

# Show agent config
npx nestor-sh agent config coder

Configuration

Agent configuration is stored in .nestor/agents/{name}.yaml. Here is a complete example:

# .nestor/agents/coder.yaml
name: coder
description: Senior TypeScript developer
adapter: claude
model: claude-sonnet-4-6

# System prompt / role instructions
instructions: |
  You are a senior TypeScript developer.
  Write clean, well-tested code.
  Always explain your reasoning.

# Tool access
tools:
  - file_read
  - file_write
  - shell_exec
  - web_search

# Guardrails
guardrails:
  max_iterations: 25
  max_tokens_per_turn: 8192
  require_approval:
    - file_write
    - shell_exec
  blocked_commands:
    - rm -rf
    - sudo

# Cost budget
budget:
  max_per_session: 5.00
  max_per_day: 20.00
  currency: USD

# Memory configuration
memory:
  enabled: true
  context_window: 200000
  rag_enabled: true

LLM Adapters

Nestor supports 7 LLM providers through a unified adapter interface:

All adapters implement the same LlmAdapter interface, so switching between providers is a one-line config change.

Model Router

The model router automatically selects the best model based on task complexity and budget:

# In agent config, use "auto" to enable routing
adapter: auto
model_preferences:
  - claude-sonnet-4-6   # preferred
  - gpt-4o              # fallback
  - ollama/llama3.2     # local fallback

Tools

Agents interact with the world through tools. Nestor provides built-in tools and supports custom tools via MCP (Model Context Protocol).

Built-in Tools

Requiring Approval

For sensitive tools, you can require user approval before execution:

guardrails:
  require_approval:
    - file_write      # ask before writing files
    - shell_exec      # ask before running commands

Skills

Skills are reusable capabilities defined as SKILL.md files with system prompts, tool configurations, and instructions.

# Install a skill from the registry
npx nestor-sh skill install code-reviewer

# Install from git
npx nestor-sh skill install https://github.com/user/my-skill.git

# List installed skills
npx nestor-sh skill list

Memory

Agents maintain memory across sessions using a combination of:

• Conversation memory — Full context within a session
• Long-term memory — Key facts persisted to SQLite
• RAG memory — Semantic search over your codebase with embeddings

memory:
  enabled: true
  context_window: 200000    # max tokens in context
  rag_enabled: true          # enable codebase RAG
  rag_paths:                 # directories to index
    - src/
    - docs/

Cost Budgets

Prevent runaway costs with per-session and per-day budgets:

budget:
  max_per_session: 5.00    # hard stop at $5/session
  max_per_day: 20.00       # daily limit across all sessions
  warn_at: 0.80            # warn at 80% of budget

When the budget is reached, the agent gracefully stops and reports its progress.

Hat System

New in v3.4.0, the Hat System provides 5 specialized personas that configure tools, instructions, and behavior in one flag:

# Use a hat in the shell
npx nestor-sh shell --hat security

# Use a hat for a mission
npx nestor-sh shell --hat osint
> Investigate the founders of Acme Corp

# Combine with agent selection
npx nestor-sh shell --agent coder --hat researcher

Each hat pre-configures the agent's system prompt, tool selection, and behavioral guidelines for its specialty. Hats can be combined with any agent and any LLM provider.

Trust Score

Every agent gets a trust score from A to F, computed from real execution history:

The score is based on:

• Accuracy — How often the agent produces correct results
• Safety — Whether guardrails were respected
• Cost Efficiency — Token usage relative to task complexity
• Reliability — Consistency across similar tasks

✎ Edit this page on GitHub · Last updated 2026-04-26