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
| Range | Use Case |
|---|---|
| 10-30 | High priority — specific, unambiguous patterns |
| 30-60 | Medium — domain-specific but could overlap |
| 60-90 | Lower — 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