Agent System | VexAI Docs

Overview

VexAI's agent system lets you create specialized AI agents, each with its own name, identity, instruction set, and curated list of allowed tools. Agents are invoked in one of two execution modes:

Sub-Agent Mode: called internally by the main bot; the user never interacts with the agent directly.
Hand-Over Mode: the agent takes over the conversation; the user talks directly to it.

ℹ️ Think of it this way

Sub-agents are like function calls: fire, get result, done. Hand-overs are like switching the pilot mid-flight. The agent takes full control of the conversation.

Two Execution Modes

Sub-Agent Mode

Called internally by the main bot. The sub-agent receives a task description, executes it using its allowed tools, and returns the result. The user doesn't interact directly; it works like a function call behind the scenes.

# The main bot internally calls a sub-agent
invoke_agent name:"research-agent" task:"Find the latest Node.js LTS version"
# → Agent runs, returns result, main bot continues

Hand-Over Mode

The agent takes over the entire conversation. The user talks directly to the agent until the session ends, either by timeout, message limit, or the user typing !exit.

# User asks for a handover
"Hand this over to the code-review agent"
# → Agent takes control, user chats with it directly
# → Type !exit to return to VexAI

💡 Choosing a mode

Use sub-agent for quick, automated tasks (lookups, calculations, data extraction). Use hand-over when the user needs an extended, specialized conversation (debugging sessions, guided workflows).

Creation Wizard

Agents are created through a guided interview process. When you ask VexAI to create an agent, it opens a structured wizard that walks through each configuration step:

Name: a unique identifier for the agent
Identity: the agent's persona and personality
Instructions: what the agent should do and how it should behave
Allowed Tools: which VexAI tools the agent can use
Execution Mode: sub-agent or hand-over

The wizard uses progress tracking so you always know which step you're on. Once complete, the agent definition is persisted to the database and available immediately.

ℹ️ Private channel

The creation wizard runs in a private channel to keep the interview focused and avoid cluttering public channels.

Planning Step

Before executing, agents generate a plan of attack. This pre-execution planning step improves tool selection accuracy and reduces wasted calls by thinking through the approach before acting.

The planning phase considers:

Which tools are available and relevant to the task
The optimal order of operations
Potential failure points and fallback strategies

Error Recovery

Agent execution includes built-in error recovery to handle tool failures gracefully:

Failure tracking: every failed tool call is recorded with its error context
Retry cap: a maximum of 2 retries per failed call prevents infinite loops
Contextual suggestions: on failure, the agent receives guidance about what went wrong and possible alternatives

⚠️ Retry limits

After 2 failed attempts at the same tool call, the agent will move on or abort. This prevents runaway execution when a tool is consistently failing.

Model-Specific Hints

Not all LLMs handle tool use the same way. VexAI includes prompt tuning for models that need extra help:

Model	Special Handling
Kimi	Model-specific instructions for tool formatting
MiniMax	Adapted prompt structure for tool selection
DeepSeek	Tuned instructions for consistent tool invocation
Qwen	Adjusted prompt format for reliable tool calls

💡 Other models

OpenAI, Anthropic, and most OpenRouter models work out of the box without additional hints.

Handover Safeguards

Hand-over sessions include multiple safety mechanisms to prevent runaway or stuck conversations:

Safeguard	Value	Description
Timeout	`30 minutes`	Session automatically ends after 30 minutes of total elapsed time
Message limit	`50 messages`	Session ends after 50 user messages
Periodic reminders	-	The agent periodically reminds the user about remaining limits
Escape hatch	`!exit`	User can type `!exit` at any time to immediately end the handover

🚨 Important

If a handover session times out, control returns to the main VexAI bot automatically. The conversation history is preserved.

Managing Agents

Slash Commands

Command	Description
`/agents list`	View all created agents
`/agents info <name>`	View detailed agent configuration
`/agents delete <name>`	Permanently remove an agent
`/agents toggle <name>`	Enable or disable an agent

Tools

Agents can also be managed programmatically through VexAI's tool system:

Tool	Description
`create_agent`	Launch the creation wizard
`invoke_agent`	Call an agent as a sub-agent
`handover_to_agent`	Start a hand-over session
`list_agents`	List all agents
`agent_info`	Get agent details
`delete_agent`	Delete an agent
`toggle_agent`	Enable/disable an agent

Sub-Agents (Background Execution)

Sub-agents are spawnable background agents that run autonomously, executing tasks without blocking the main conversation. They include a full task board for creating, updating, and tracking tasks across multiple sub-agents.

Safety Controls

Sub-agents operate under strict safety constraints to prevent destructive actions:

Control	Detail
Tool blacklist	`exec_command`, `ban`, `kick`, `purge`. Destructive tools are blocked
Max iterations	10 by default, hard cap at 20
Timeout	5-minute execution limit
Error tracking	Aborts after 2 consecutive failures of the same call

⚠️ Blacklisted tools

Sub-agents cannot run exec_command, ban, kick, or purge. These are blocked at the execution layer regardless of the agent's allowed tools list.

Lifecycle

Sub-agents follow a clear lifecycle:

Spawn: create a new sub-agent with a task
Check status: poll for progress and results
Cancel: terminate a running sub-agent
List all: view all active and completed sub-agents

Enabling Sub-Agents

Sub-agents are disabled by default. Enable them with either method:

# Via slash command
/subagents

# Via config tool
/config set subAgents.enabled true