Skip to content

Custom Agents

Vector Companion's agent system is fully modular. You add, remove, or replace agents by editing config/config.py — no Python code changes required. Agents are created lazily from config data via build_agents() at startup.

Adding a New Agent

Step 1: Define the Agent in Config

Add an entry to the agent definitions in config/config.py:

AGENTS = [
    # ... existing agents ...
    {
        "name": "my_agent",
        "persona": "You are a helpful coding assistant.",
        "exaggeration": 0.5,       # TTS emotional range
        "cfg_weight": 3.0,         # Classifier-free guidance for TTS quality
        "think": "medium",         # False / "medium" / "high" / True
    },
]

Step 2: Restart the Application

Agents are created lazily at startup via build_agents(config, tool_host). After editing config, restart with python main.py. The new agent will appear in the Tauri sidebar's Agents panel.

Step 3: Test the Agent

  1. Open the Tauri desktop app
  2. Navigate to Sidebar → Agents panel
  3. Toggle your new agent as active
  4. Send a test message (voice or text)
  5. Verify the agent responds with the expected personality

How Agent Personalities Work

Each agent's personality is constructed from a minimal prompt via build_contextual_information():

Personality (system_prompt1) — Your agent's persona definition
Dialogue quality harness     — Shared TTS/plain-text rules (~100 chars)
Sentence count               — Between N and 4 sentences
Tool use guidance            — Inline instructions (no announcement, consecutive calls ok)
Mode status                  — Prepended when any modes active

No section headers ([SECTION] markers) are used — modern models adhere to concise, plain-text prompts.

Key Constraints

The dialogue quality harness enforces: - Max 4 sentences per response - Plain text only — no special formatting (TTS compatibility) - TTS awareness — agent knows output will be spoken aloud

Think Mode

Controls how much the agent reasons before responding:

Value Behavior
False No extended thinking, direct response
"medium" Moderate reasoning before responding
"high" Extended chain-of-thought reasoning
True Maximum thinking depth (equivalent to "high")

Think mode is normalized via normalize_agent_think() and synced across the ParamsPanel store, SSE events, and direct agent.think updates.

Agent Routing

When a message arrives, the system determines which agent responds:

  • Named mention ("hey Axis, ...") → Only that named agent responds
  • No name mentioned → Only the first active agent responds (subsequent agents skipped)
  • Tool calls → Attributed via caller=f"agent:{self.agent_name}"

Multiple agents can coexist, but only one responds per user message. Switch by mentioning a name or toggling activations in the sidebar.

Quality Testing

The persona integration test suite evaluates agent quality against automated criteria:

python -m tests.persona_integration.run_all --agents my_agent

Checks sentence count, markdown absence, stock phrase avoidance, and audio attribution. Results export as JSON to tests/persona_integration/results/.

Troubleshooting

Problem Solution
Agent not appearing in UI Check name is unique, restart app after config change
Wrong personality Verify persona string is descriptive (2–3 sentences)
Tool calls failing Check RealToolHost audit log for denial reasons
Monotone TTS Increase exaggeration (0.5–1.0) and cfg_weight (2.0–5.0)
Responses too long Prompt enforces max 4 sentences — check persona isn't contradicting this

See Also