Domain AgentsCreating Agents

Creating Agents

You can extend KULVEX by creating custom domain agents.

Agent Structure

Create a new file in core/agents/domain/:

# core/agents/domain/my_agent.py
from core.agents.domain.base import BaseAgent, ExecutionResult
 
class MyAgent(BaseAgent):
    name = "my_agent"
    priority = 95  # Lower = higher priority
    description = "Handles my custom domain"
 
    patterns = [
        r"my custom trigger",
        r"do the thing",
    ]
 
    tools = ["my_tool_1", "my_tool_2"]
 
    async def handle(self, message: str, context: dict) -> ExecutionResult:
        # Simple pattern → template response (no LLM)
        if "status" in message.lower():
            data = await self._get_status()
            return self._template(f"Status: {data}")
 
        # Complex query → execute tools + synthesize with LLM
        results = await self._execute_tools(message)
        return await self._synthesize(message, results)
 
    async def _get_status(self):
        # Your custom logic here
        return "all good"

Register the Agent

Add your agent to the router in core/agents/domain/router.py:

from core.agents.domain.my_agent import MyAgent
 
# In AgentRouter.__init__:
self.agents.append(MyAgent())
self.agents.sort(key=lambda a: a.priority)

Priority Guidelines

RangeUse Case
10-30High priority — specific, unambiguous patterns
30-60Medium — domain-specific but could overlap
60-90Lower — catch-all or broad patterns
90+Custom/user agents

Tips

  • Keep patterns specific to avoid stealing messages from other agents
  • Use _template() for simple queries — it’s instant and doesn’t consume GPU
  • Use _synthesize() sparingly — only when you need natural language generation
  • Test with the API: curl "http://localhost:9100/api/ai/agents/detect?message=your test"

Coming Soon: Agent Builder UI

A visual agent builder at kulvex.ai/agents is planned, allowing you to create agents without code:

  • Define name, role, tools, instructions, and triggers
  • Visual configuration — no Python required
  • One-click deployment