How I Built 20 AI Agents for WhatsApp — and Open-Sourced Everything

// ai-providers.ts — simplified provider failover chain
const PROVIDER_CHAIN: AIProvider[] = [
  {
    name: 'groq',
    client: new Groq({ apiKey: process.env.GROQ_API_KEY }),
    model: 'llama-3.1-70b-versatile',
    maxTokens: 8192,
  },
  {
    name: 'cerebras',
    client: new Cerebras({ apiKey: process.env.CEREBRAS_API_KEY }),
    model: 'llama3.1-70b',
    maxTokens: 8192,
  },
  {
    name: 'sambanova',
    client: new SambaNova({ apiKey: process.env.SAMBANOVA_API_KEY }),
    model: 'Meta-Llama-3.1-70B-Instruct',
    maxTokens: 4096,
  },
  {
    name: 'mistral',
    client: new MistralClient(process.env.MISTRAL_API_KEY),
    model: 'mistral-large-latest',
    maxTokens: 8192,
  },
];

async function getAIResponse(
  messages: ChatMessage[],
  tools?: ToolDefinition[]
): Promise<AIResponse> {
  for (const provider of PROVIDER_CHAIN) {
    try {
      const response = await provider.client.chat.completions.create({
        model: provider.model,
        messages,
        tools,
        tool_choice: tools?.length ? 'auto' : undefined,
        max_tokens: provider.maxTokens,
      });
      return { provider: provider.name, response };
    } catch (err) {
      console.warn(`[AI] Provider ${provider.name} failed, trying next...`, err);
    }
  }
  throw new Error('All AI providers exhausted');
}

// tool-dispatcher.ts — dispatcher core + agent loop
type ToolHandler = (
  args: Record<string, unknown>,
  context: AgentContext
) => Promise<ToolResult>;

const TOOL_REGISTRY: Record<string, ToolHandler> = {
  book_table:         handlers.bookTable,
  check_availability: handlers.checkAvailability,
  get_menu:           handlers.getMenu,
  create_ticket:      handlers.createTicket,
  get_appointment:    handlers.getAppointment,
  // ... 25+ more across 20 verticals
};

async function dispatchTool(
  toolCall: ToolCall,
  context: AgentContext
): Promise<ToolResult> {
  const handler = TOOL_REGISTRY[toolCall.function.name];
  if (!handler) return { error: `Unknown tool: ${toolCall.function.name}` };

  const args = JSON.parse(toolCall.function.arguments);
  const validated = validateToolArgs(toolCall.function.name, args);
  if (!validated.ok) return { error: validated.error };

  return handler(validated.args, context);
}

// Agent loop: keep calling tools until the LLM stops asking for them
async function chatChainWithTools(
  messages: ChatMessage[],
  tools: ToolDefinition[],
  context: AgentContext
): Promise<string> {
  let response = await getAIResponse(messages, tools);

  while (response.tool_calls?.length) {
    const toolResults = await Promise.all(
      response.tool_calls.map(tc => dispatchTool(tc, context))
    );
    messages.push(
      { role: 'assistant', content: null, tool_calls: response.tool_calls },
      ...toolResults.map((r, i) => ({
        role: 'tool' as const,
        tool_call_id: response.tool_calls![i].id,
        content: JSON.stringify(r),
      }))
    );
    response = await getAIResponse(messages, tools);
  }

  return response.choices[0].message.content ?? '';
}

// pii-anonymizer.ts
interface PIIMap {
  [placeholder: string]: string; // '[PHONE_1]' -> '+39 333 1234567'
}

function anonymizeMessage(text: string): { anonymized: string; map: PIIMap } {
  const map: PIIMap = {};
  const counter = { PERSON: 0, PHONE: 0, EMAIL: 0, ID: 0 };

  const anonymized = text
    .replace(FISCAL_CODE_REGEX, (match) => {
      const key = `[ID_${++counter.ID}]`;
      map[key] = match;
      return key;
    })
    .replace(PHONE_REGEX, (match) => {
      const key = `[PHONE_${++counter.PHONE}]`;
      map[key] = match;
      return key;
    })
    .replace(EMAIL_REGEX, (match) => {
      const key = `[EMAIL_${counter.EMAIL++}]`;
      map[key] = match;
      return key;
    });

  return { anonymized, map };
}

// Restore real values in tool args before execution
function deanonymizeToolArgs(
  args: Record<string, unknown>,
  map: PIIMap
): Record<string, unknown> {
  return JSON.parse(
    JSON.stringify(args).replace(
      /\[(?:PERSON|PHONE|EMAIL|ID)_\d+\]/g,
      (ph) => map[ph] ?? ph
    )
  );
}

// autonomy-gate.ts
const TOOL_RISK: Record<string, 'low' | 'medium' | 'high'> = {
  get_menu:           'low',
  check_availability: 'low',
  book_table:         'medium',
  cancel_reservation: 'high',
  process_refund:     'high',
  send_notification:  'medium',
};

async function gateToolExecution(
  toolName: string,
  context: AgentContext
): Promise<{ allowed: boolean; reason?: string }> {
  const risk = TOOL_RISK[toolName] ?? 'medium';

  if (risk === 'low') return { allowed: true };

  if (risk === 'high' && !context.userConfirmed) {
    return {
      allowed: false,
      reason: `Action "${toolName}" requires explicit user confirmation.`,
    };
  }

  if (risk === 'medium' && context.autonomyLevel < 2) {
    return {
      allowed: false,
      reason: `Action "${toolName}" requires autonomy level >= 2.`,
    };
  }

  return { allowed: true };
}