Getting Started with the AI Assistant

This guide walks you through setting up your first AI assistant in 5-10 minutes.

---

What is the AI Assistant?

The AI Assistant is an autonomous helper that lives inside your Evennia game. Unlike chatbots that respond to each message one-by-one, the assistant runs continuously on a "tick loop" - think of it like a heartbeat. Every few seconds (configurable), the assistant wakes up, checks if anything needs attention, decides what to do, and takes action.

This design means the assistant can:

• Execute in-game commands (building, managing objects, inspecting the world)
• Respond to admin messages on a private channel
• Work on multi-step tasks autonomously
• Maintain memory and context across conversations

---

Prerequisites

Before starting, you'll need:

1. A running Evennia server (v4.0+)

   • See Evennia's Getting Started guide if you haven't set one up yet

2. An LLM API key from one of:

   • OpenRouter (recommended - access to multiple providers)
   • OpenAI
   • Anthropic

3. 5-10 minutes of time

---

Step 1: Add Commands to Your Game

Edit mygame/commands/default_cmdsets.py and add the AI commands to your character cmdset:

from evennia.contrib.base_systems.ai import (
    CmdAssistant,      # aisetup - main management
    CmdAIHistory,      # aihistory - view/clear history
    CmdAIInteract,     # aiinteract - bidirectional interaction
    CmdAIGoal,         # aigoal - goal management
)

class CharacterCmdSet(default_cmds.CharacterCmdSet):
    def at_cmdset_creation(self):
        super().at_cmdset_creation()
        self.add(CmdAssistant())
        self.add(CmdAIHistory())
        self.add(CmdAIInteract())
        self.add(CmdAIGoal())

Note: There are additional optional commands (CmdAIAudit, CmdAIMemory) for advanced features. Start with the basics above.

---

Step 2: Reload Evennia

evennia reload

Or from inside the game:

> reload

---

Step 3: Create Your Assistant

Log in as an admin and run:

> aisetup/init mybot

This creates three connected components:

• AssistantScript: The "brain" that runs the tick loop
• AssistantCharacter: An in-game character (lives in Limbo) that can execute commands
• AssistantChannel: A private admin channel for communication

You should see output like:

Created AssistantScript 'mybot_script' with dbref #42
Created AssistantCharacter 'mybot' with dbref #43
Created AssistantChannel 'mybot_channel'
Assistant 'mybot' initialized and linked.

---

Step 4: Configure the LLM Provider

The assistant needs to know which LLM to use. We'll use OpenRouter, which gives you access to models from OpenAI, Anthropic, Google, and more.

Get an OpenRouter API Key

1. Go to openrouter.ai
2. Sign up or log in
3. Go to Keys in your dashboard
4. Create a new key and copy it

Configure the Assistant

> aisetup/config mybot set llm_provider openrouter
> aisetup/config mybot set llm_auth_token sk-or-v1-YOUR_KEY_HERE
> aisetup/config mybot set llm_model openai/gpt-4o-mini

Available models via OpenRouter:

Model	Best For
openai/gpt-4o-mini	Fast, affordable, good for testing
openai/gpt-4o	Strong reasoning, higher cost
anthropic/claude-3.5-sonnet	Excellent for code and nuanced tasks
anthropic/claude-3-haiku	Very fast, good for simple tasks
google/gemini-1.5-flash	Fast, large context window

Tip: Start with openai/gpt-4o-mini for testing - it's fast and affordable.

---

Step 5: Start the Assistant

> aisetup/start mybot

You should see:

Started assistant 'mybot' (tick rate: 5s)

The assistant is now running! It will "wake up" every 5 seconds to check for messages and decide what to do.

---

Step 6: Talk to Your Assistant

The assistant communicates via its dedicated channel. Join it and send a message:

> mybot Hello! Can you tell me about this room?

Wait a few seconds (up to the tick rate), and you'll see a response:

[mybot_channel] mybot: I'm inspecting the room you're in...
[mybot_channel] mybot: You're in Limbo (#1). It's a simple room with no special features.

Understanding the Tick Model: The assistant doesn't respond instantly. It processes messages on its tick cycle. If the tick rate is 5 seconds, you might wait up to 5 seconds for a response. This is intentional - the assistant is designed for autonomous operation, not real-time chat.

---

What Can It Do Out of the Box?

Your assistant has access to 26 built-in tools:

Communication

Tool	What It Does
channel_send	Send messages to its channel
say, pose, emit	Speak or emote in a room
page, whisper	Send private messages

World Inspection

Tool	What It Does
search_object	Find objects and characters by name or dbref
inspect_location	Get details about a room
get_attributes	Read object attributes
get_tags	Read object tags
search_by_tag	Find objects by tag

World Modification

Tool	What It Does
command	Execute any in-game command
set_attribute	Set an object's attribute
add_tag, remove_tag	Manage object tags
spawn_prototype	Create objects from prototypes
execute_batchcode	Run Python code (powerful!)

Self-Management

Tool	What It Does
add_goal, update_goal, decompose_goal	Manage tasks and goals
add_session_memory	Remember facts for this session
create_project, swap_project	Organize work into projects
add_journal_entry	Write to its personal journal

Documentation

Tool	What It Does
doc_lookup	Search Evennia's API documentation

---

Example: Give It a Task

Try asking the assistant to do something:

> mybot Please create a simple room called "Test Chamber" and describe it.

The assistant will:

1. Use execute_batchcode or command to create the room
2. Set the room's description
3. Report back what it did

---

Stopping and Managing the Assistant

Stop the Assistant

> aisetup/stop mybot

Check Status

> aisetup mybot

Shows current configuration, running state, and recent activity.

View Conversation History

> aihistory mybot

Clear History

> aihistory/clear mybot

Server Restarts

The assistant's state persists across server reloads and restarts:

• Conversation history is saved
• Configuration is preserved
• After restart, run aisetup/start mybot to resume

---

What Happens During Each Tick?

When the assistant's tick fires (every 5 seconds by default):

1. Check for events: Are there new messages on the channel?
2. Build context: Gather conversation history, goals, and memory
3. Call the LLM: "Here's what's happening. What should we do?"
4. Execute decision: If the LLM says to use a tool, execute it
5. Record result: Log what happened for next tick

If there are no new messages, the assistant enters "autonomous" mode - it might work on goals, reflect, or simply wait.

---

Common Issues

"Assistant not responding"

• Check if it's running: aisetup mybot
• Verify LLM configuration: aisetup/config mybot
• Make sure your API key is valid

"Rate limit errors"

• OpenRouter and other providers have rate limits
• Wait a minute and try again
• Consider upgrading your API tier

"Emergency stop triggered"

• This happens after 3 consecutive failures
• Clear it with: aisetup/reset mybot
• Then restart: aisetup/start mybot

For more troubleshooting, see User-Guide-04-Troubleshooting.

---

Next Steps

Now that you have a working assistant, you can:

• Customize its behavior: See User-Guide-02-Configuration-and-Customization for changing tick rates, prompts, and memory settings
• Add advanced features: See User-Guide-03-Advanced-Capabilities for sub-agents, custom tools, and RAG
• Explore the architecture: See Architecture-Overview to understand how everything works under the hood

---

Quick Reference

Command	Purpose
aisetup/init <name>	Create new assistant
aisetup/start <name>	Start the assistant
aisetup/stop <name>	Stop the assistant
aisetup <name>	Check status
aisetup/config <name>	View configuration
aisetup/config <name> set <key> <value>	Change configuration
aihistory <name>	View conversation history
<name> <message>	Send message to assistant channel

---

Last updated: 2025-12-09