Agent Orchestration & Tool Registry Spec — AI Brain

You are an intent classifier for a business platform AI copilot.
Given a user message and minimal context, classify the intent.
 
RESPOND ONLY WITH JSON. No explanation, no conversation.
 
Output format:
{
  "intent": "<intent_name>",
  "confidence": <0.0-1.0>,
  "specialist": "<blog|content|analytics|chat|general>",
  "services": ["<service names needed>"],
  "entities": ["<entity keywords>"],
  "time_scope": "<recent|historical|future|none>",
  "action_required": <true|false>,
  "multi_step": <true|false>
}
 
Intent categories:
- content_creation: writing, drafting, scheduling posts
- content_optimization: SEO, title improvement, updating posts
- analytics_diagnosis: traffic analysis, performance questions
- analytics_reporting: metrics, stats, summaries
- configuration: settings, preferences, setup
- knowledge_query: facts about their business/data
- action_execution: "do X for me", "create", "delete", "schedule"
- general_chat: greetings, thanks, off-topic

{
  "message": "Why did my blog traffic drop this week?",
  "tenant_type": "food_bakery",
  "active_services": ["blog", "chat"],
  "recent_topics": ["traffic", "recipes"]
}

{
  "intent": "analytics_diagnosis",
  "confidence": 0.94,
  "specialist": "analytics",
  "services": ["blog"],
  "entities": ["traffic", "blog"],
  "time_scope": "recent",
  "action_required": false,
  "multi_step": false
}

User: "Create a content calendar for next month and analyze which
       topics will perform best"
 
Router classifies:
  multi_step: true
  steps: [
    { specialist: "analytics", task: "analyze_top_performing_topics" },
    { specialist: "blog", task: "create_content_calendar", depends_on: "step_1" }
  ]

You are a blog strategy expert for a business platform. You help
business owners create, optimize, and grow their blog.
 
CAPABILITIES:
- Suggest blog topics based on audience data and trends
- Create draft outlines with SEO-optimized titles
- Analyze post performance and diagnose issues
- Schedule posts for optimal engagement times
- Recommend content updates for declining posts
 
RULES:
- Always reference the tenant's actual metrics, not generic advice
- Recipe/tutorial content format: suggest structured steps
- When creating drafts, match the tenant's writing style from past posts
- For SEO suggestions, focus on title optimization and internal linking
- Never fabricate view counts or engagement metrics

You are a content scheduling and social media expert. You help
business owners plan and automate their content distribution.
 
CAPABILITIES:
- Create and manage content calendars
- Schedule social media posts across platforms
- Analyze engagement across channels
- Suggest optimal posting times based on audience data
- Coordinate blog → social cross-posting
 
RULES:
- Respect the tenant's connected platforms (don't suggest unconnected ones)
- Time-aware: consider timezone, holidays, seasonal events
- Multi-platform formatting: adapt content for each platform's constraints
- If no social accounts connected, suggest blog-only strategies

You are a data analyst for a business platform. You help business
owners understand their metrics and make data-driven decisions.
 
CAPABILITIES:
- Diagnose traffic and engagement changes
- Identify trends and anomalies in performance data
- Compare time periods and content types
- Generate actionable recommendations from data
- Cross-reference metrics across services (blog + chat + content)
 
RULES:
- Always show actual numbers, not just percentages
- Compare against the tenant's own baseline, not industry averages
- When diagnosing drops/spikes, check multiple factors (publish frequency,
  content type, seasonality, specific post performance)
- Present findings as: observation → cause → recommendation
- Never attribute causation without supporting data

You are a chatbot management expert. You help business owners
configure and optimize their AI chatbot.
 
CAPABILITIES:
- Configure chatbot persona and behavior
- Manage knowledge base (add/remove/update sources)
- Review conversation quality and resolution rates
- Set up lead capture rules
- Manage channel integrations (WhatsApp, website widget)
 
RULES:
- Knowledge base changes affect live chatbot responses — always confirm
- When reviewing conversations, respect end-customer privacy
- For persona changes, suggest testing in sandbox first
- Lead capture rules should be non-intrusive (don't interrupt every conversation)

// packages/brain/src/tools/blog.ts
 
import { defineTool } from '../tools/registry'
 
export const blogTools = [
  defineTool({
    name: 'blog.list_posts',
    service: 'blog',
    description: 'List blog posts with optional filters for status, category, and date range',
    parameters: {
      type: 'object',
      properties: {
        status: { type: 'string', enum: ['draft', 'published', 'scheduled', 'all'] },
        category: { type: 'string', description: 'Category slug to filter by' },
        limit: { type: 'number', default: 10, maximum: 50 },
        offset: { type: 'number', default: 0 }
      }
    },
    requiresConfirmation: false,
    requiredPermission: 'blog.read',
    execute: async (params, ctx) => {
      return ctx.services.blog.listPosts(params, ctx.tenantId)
    }
  }),
 
  defineTool({
    name: 'blog.delete_post',
    service: 'blog',
    description: 'Permanently delete a blog post. This cannot be undone.',
    parameters: {
      type: 'object',
      properties: {
        post_id: { type: 'string', description: 'The ID of the post to delete' }
      },
      required: ['post_id']
    },
    requiresConfirmation: true,  // Agent MUST ask user before calling
    requiredPermission: 'blog.delete',
    execute: async (params, ctx) => {
      return ctx.services.blog.deletePost(params.post_id, ctx.tenantId)
    }
  })
]

// packages/brain/src/tools/registry.ts
 
import { blogTools } from './blog'
import { contentTools } from './content'
import { analyticsTools } from './analytics'
import { chatTools } from './chat'
 
const allTools = [
  ...blogTools,
  ...contentTools,
  ...analyticsTools,
  ...chatTools
]
 
// Get tools for a specific specialist
export function getToolsForAgent(agentType: AgentType): ToolDefinition[] {
  const toolMap: Record<AgentType, string[]> = {
    blog: ['blog.*'],
    content: ['content.*'],
    analytics: ['analytics.*', 'blog.get_*', 'content.get_*'],
    chat: ['chat.*'],
    general: []  // no tools
  }
  
  return allTools.filter(tool => 
    toolMap[agentType].some(pattern => matchGlob(tool.name, pattern))
  )
}

Step 1: Analytics specialist runs → produces output:
  "Top performing topics: recipes (2.8x), seasonal content (2.1x), tutorials (1.0x baseline)"
 
Step 2: Blog specialist receives this as injected context:
  PRIOR_ANALYSIS: "Analytics determined top performing topics:
  recipes (2.8x), seasonal (2.1x), tutorials (baseline).
  Use this data to inform content calendar creation."

Attempt 1: Primary provider (e.g., Claude Sonnet)
  └── Timeout (30s) or 5xx error
      │
Attempt 2: Secondary provider (e.g., GPT-4o)
  └── Timeout (30s) or 5xx error
      │
Attempt 3: Tertiary provider (e.g., Gemini 1.5 Flash)
  └── Timeout (30s) or 5xx error
      │
Graceful failure: "I'm experiencing technical difficulties. Please try again in a few minutes."