Skip to main content

Tutorial: Build Your First Agent

From zero to a working Wunderland agent in 10 minutes.

This tutorial walks you through installing Wunderland, configuring your first agent, and having a conversation with it.

Prerequisites​

  • Node.js 20+ — Download
  • An LLM API key — OpenAI, Anthropic, Gemini, or OpenRouter (or use Ollama for free local inference)

Step 1: Install the CLI​

npm install -g wunderland

Verify the installation:

wunderland --version

Step 2: Create Your Agent​

The fastest way -- describe what you want in plain English:

wunderland create "A research agent that monitors Hacker News, summarizes top stories, and posts daily digests to Slack"

This uses AI to generate a complete agent configuration with:

  • Preset selection (research-assistant)
  • Skills (web-search, summarize, hacker-news)
  • Extensions (web-search, news-search, slack)
  • HEXACO personality traits
  • Security tier (balanced)

You'll see a preview with confidence scores. Confirm to scaffold the project.

Alternative: Create from a Preset​

wunderland init my-agent --preset research-assistant

Alternative: Interactive Mode​

# Choose between NL describe, preset, blank, or import
wunderland new

Step 3: Run Setup (if not using create)​

If you used wunderland create, your agent is already configured. Otherwise, run the setup wizard:

wunderland setup

The setup wizard walks you through:

  1. Mode — Choose QuickStart (recommended for first-timers)
  2. Agent name — Give your agent a name
  3. LLM provider — Select OpenAI, Anthropic, Gemini, Ollama, or OpenRouter
  4. API key — Paste your provider's API key
  5. Personality — Pick a preset (Balanced, Analytical, Creative, etc.)
  6. Channels — Select WebChat (default)
  7. RAG memory — Enable for conversation memory
  8. Voice — Optionally enable TTS/STT

After setup, your configuration is saved to ~/.wunderland/config.json and API keys to ~/.wunderland/.env.

Step 4: Verify Your Environment​

wunderland doctor

This checks your config, API keys, and provider connectivity. Everything should show green checkmarks.

Step 5: Start Chatting​

wunderland chat

You're now in an interactive chat session with your agent. Try:

You: What can you help me with?
You: Search the web for the latest TypeScript features
You: Summarize what you found
You: /help

Chat Commands​

CommandAction
/helpShow available commands
/toolsList available tools
/clearClear conversation history
/exitEnd the session
Ctrl+CInterrupt current operation

Step 6: Explore the TUI Dashboard​

wunderland

The TUI (terminal user interface) provides a visual dashboard:

  • Arrow keys to navigate
  • Enter to select
  • / to search (command palette)
  • ? for help
  • v for voice dashboard
  • t for onboarding tour
  • q to quit

Step 7: Scaffold a Project (Manual Path)​

For a more structured setup without the NL builder, scaffold a project directory:

wunderland init my-agent --preset research-assistant
cd my-agent

This creates:

my-agent/
├── agent.config.json    # Agent-specific configuration
├── workflows/           # Scheduled workflows
├── skills/              # Custom SKILL.md files
└── README.md

Start the agent server:

wunderland start

The server starts on http://localhost:3000/ by default. The startup output prints an admin secret (a UUID) used to authenticate with the web dashboard and HITL pages. You can set a persistent secret via the WUNDERLAND_HITL_SECRET env var or hitl.secret in agent.config.json. The dashboard provides six tabs -- Overview, Chat, HITL, Graph, Events, and Extensions -- with a light/dark mode toggle.

Then connect with chat:

wunderland chat

Step 8: Add Extensions​

Extend your agent with tools:

# Enable web search
wunderland extensions enable web-search

# Enable web browser for page content extraction
wunderland extensions enable web-browser

# List all available extensions
wunderland extensions list

Now your agent can search the web and read web pages during conversations.

Step 9: Test Voice (Optional)​

If you enabled voice during setup:

# Check voice provider status
wunderland voice status

# Test text-to-speech
wunderland voice test "Hello, I'm your Wunderland agent!"

# Check STT provider
wunderland voice stt

What's Next?​

You now have a working agent. Here's where to go from here:

Quick Reference​

# Agent creation
wunderland create "description"  # NL agent creation
wunderland new                   # Interactive entry point
wunderland init my-agent         # Scaffold from preset

# Core commands
wunderland setup          # Initial configuration
wunderland doctor         # Health check
wunderland chat           # Interactive chat
wunderland start          # Start agent server
wunderland                # TUI dashboard

# Voice
wunderland voice status   # Provider readiness
wunderland voice test "Hello"  # TTS smoke test

# Management
wunderland extensions list    # Available extensions
wunderland skills list        # Available skills
wunderland models             # Provider/model info
wunderland config set <key> <value>  # Change settings

# Help
wunderland help getting-started
wunderland help voice
wunderland help llm
wunderland help faq