routing

Routing - Complete API Reference

Route messages to specialized agents, configure channel bindings, and manage tool access policies.

---

Chat Commands

Agent Management

/​agents                                     List available agents
/​agent trading                              Switch to trading agent
/​agent research                             Switch to research agent
/​agent main                                 Switch to main agent
/​agent status                               Current agent info

Channel Bindings

/​bind trading                               Bind channel to trading agent
/​bind research                              Bind channel to research agent
/​unbind                                     Remove channel binding
/​bindings                                   List all bindings

Tool Policies (Admin)

/​tools                                      List available tools
/​tools allow <agent> <tool>                 Allow tool for agent
/​tools deny <agent> <tool>                  Deny tool for agent
/​tools policy <agent>                       View agent's tool policy

---

TypeScript API Reference

Create Routing Service

import { createRoutingService } from 'clodds/​routing';

const routing = createRoutingService({
  // Default agent
  defaultAgent: 'main',

  // Agent definitions
  agents: {
    main: {
      name: 'Main',
      description: 'General assistant',
      model: 'claude-3-sonnet',
      systemPrompt: 'You are a helpful trading assistant...',
      allowedTools: ['*'],  // All tools
    },
    trading: {
      name: 'Trading',
      description: 'Order execution specialist',
      model: 'claude-3-haiku',
      systemPrompt: 'You execute trades efficiently...',
      allowedTools: ['execute', 'portfolio', 'markets', 'feeds'],
    },
    research: {
      name: 'Research',
      description: 'Market analysis expert',
      model: 'claude-3-opus',
      systemPrompt: 'You provide deep market analysis...',
      allowedTools: ['web-search', 'web-fetch', 'markets', 'news'],
    },
    alerts: {
      name: 'Alerts',
      description: 'Notification handler',
      model: 'claude-3-haiku',
      systemPrompt: 'You manage price alerts...',
      allowedTools: ['alerts', 'feeds'],
    },
  },

  // Storage
  storage: 'sqlite',
  dbPath: './​routing.db',
});

Route Message

// Route determines best agent
const route = await routing.route({
  message: 'Buy 100 shares of Trump YES',
  channelId: 'telegram-123',
  userId: 'user-456',
});

console.log(`Routed to: ${route.agent}`);
console.log(`Confidence: ${route.confidence}`);
console.log(`Reason: ${route.reason}`);

Get Available Agents

const agents = routing.getAgents();

for (const [id, agent] of Object.entries(agents)) {
  console.log(`${id}: ${agent.name}`);
  console.log(`  ${agent.description}`);
  console.log(`  Model: ${agent.model}`);
  console.log(`  Tools: ${agent.allowedTools.join(', ')}`);
}

Add Custom Agent

routing.addAgent({
  id: 'defi',
  name: 'DeFi Specialist',
  description: 'Solana and EVM DeFi expert',
  model: 'claude-3-sonnet',
  systemPrompt: 'You are an expert in DeFi protocols...',
  allowedTools: ['solana', 'evm', 'bridge', 'portfolio'],
  patterns: [
    /​swap|dex|liquidity|pool/​i,
    /​solana|jupiter|raydium/​i,
    /​uniswap|1inch|bridge/​i,
  ],
});

Update Agent

routing.updateAgent('trading', {
  model: 'claude-3-sonnet',  // Upgrade model
  allowedTools: [...currentTools, 'futures'],
});

Channel Bindings

// Bind channel to specific agent
await routing.addBinding({
  channelId: 'telegram-trading-group',
  agentId: 'trading',
});

// Get binding for channel
const binding = await routing.getBinding('telegram-trading-group');
console.log(`Channel bound to: ${binding?.agentId || 'default'}`);

// List all bindings
const bindings = await routing.getBindings();
for (const b of bindings) {
  console.log(`${b.channelId} → ${b.agentId}`);
}

// Remove binding
await routing.removeBinding('telegram-trading-group');

Tool Policies

// Check if tool is allowed for agent
const allowed = routing.isToolAllowed('trading', 'web-search');
console.log(`web-search allowed for trading: ${allowed}`);

// Get allowed tools for agent
const tools = routing.getAllowedTools('trading');
console.log(`Trading agent tools: ${tools.join(', ')}`);

// Update tool policy
routing.setToolPolicy('trading', {
  allow: ['execute', 'portfolio', 'futures'],
  deny: ['web-search', 'browser'],
});

---

Built-in Agents

---

Routing Rules

Messages are routed based on:

1. Channel binding — If channel is bound, use that agent
2. Pattern matching — Match against agent patterns
3. Keyword detection — Trading terms → trading agent
4. Default fallback — Use main agent

Pattern Examples

{
  trading: [/​buy|sell|order|position|close/​i],
  research: [/​analyze|research|explain|why/​i],
  alerts: [/​alert|notify|when|watch/​i],
}

---

Tool Categories

---

Workspace Isolation

Each agent can have isolated workspace:

routing.addAgent({
  id: 'research',
  workspace: {
    directory: '/​tmp/​research',
    allowedPaths: ['/​tmp/​research/​**'],
    sandboxed: true,
  },
});

---

Best Practices

1. Use fast models for trading — Haiku for time-sensitive operations
2. Restrict tools appropriately — Trading agent doesn't need browser
3. Channel bindings — Dedicated channels for specific workflows
4. Custom agents — Create specialized agents for your use case
5. Monitor routing — Check logs to see routing decisions