Building Production AI Agents with Claude API: A Complete Guide

// app/api/bellabot/route.ts
import Anthropic from '@anthropic-ai/sdk';
import { NextResponse } from 'next/server';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

export async function POST(request: Request) {
  try {
    const { transcript, context, callerInfo } = await request.json();

    const message = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      temperature: 0.3, // Low temp for consistency
      system: `You are BellaBot, a professional call screening assistant for VIXI.

Your role:
- Greet callers warmly and professionally
- Identify their reason for calling
- Qualify if they're a potential client (budget $5k+, timeline <90 days)
- Book appointments for qualified leads
- Politely deflect spam/sales calls

Personality: Professional, warm, efficient. Never robotic.

Current business hours: Mon-Fri 9AM-5PM CST
Available appointment slots: {context.availableSlots}

If qualified lead: "I'd love to schedule a consultation with Carlos. What works better for you - this Thursday at 2 PM or Friday at 10 AM?"
If not qualified: "Thank you for your interest. I'll have someone follow up via email within 24 hours."
If spam: "We're not interested, but thank you for calling. Have a great day!"`,
      messages: [
        {
          role: 'user',
          content: `Call transcript so far:
${transcript}

Caller identified as: ${callerInfo.name || 'Unknown'}
Caller phone: ${callerInfo.phone || 'Unknown'}

What should BellaBot say next? Provide ONLY the response, no explanations.`
        }
      ]
    });

    const response = message.content[0].text;

    // Extract intent for routing
    const intent = await extractIntent(response, transcript);

    // Log to Supabase for training data
    await logInteraction({
      transcript,
      response,
      intent,
      callerInfo,
      timestamp: new Date().toISOString(),
    });

    return NextResponse.json({
      response,
      intent,
      shouldTransfer: intent === 'qualified_hot_lead',
    });

  } catch (error) {
    console.error('BellaBot error:', error);

    // Fallback response
    return NextResponse.json({
      response: "I apologize, I'm having technical difficulties. Let me transfer you to someone who can help.",
      intent: 'error',
      shouldTransfer: true,
    });
  }
}

async function extractIntent(response: string, transcript: string) {
  // Simple keyword matching for intent classification
  // In production, I use a separate Claude call for this
  const lowerResponse = response.toLowerCase();

  if (lowerResponse.includes('schedule') || lowerResponse.includes('appointment')) {
    return 'qualified_lead';
  } else if (lowerResponse.includes('not interested') || lowerResponse.includes('no thanks')) {
    return 'not_qualified';
  } else if (lowerResponse.includes('transfer')) {
    return 'qualified_hot_lead';
  }

  return 'information_gathering';
}

// Retell webhook handler
// app/api/retell/webhook/route.ts

export async function POST(request: Request) {
  const { event, call_id, transcript, caller_id } = await request.json();

  if (event === 'speech_completed') {
    // User finished speaking, generate agent response
    const response = await fetch(`${process.env.NEXT_PUBLIC_URL}/api/bellabot`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        transcript,
        context: {
          availableSlots: await getAvailableSlots(),
          callerId: caller_id,
        },
        callerInfo: {
          phone: caller_id,
          name: await lookupCallerName(caller_id),
        },
      }),
    });

    const { response: agentText, shouldTransfer } = await response.json();

    // Send response back to Retell for TTS
    return NextResponse.json({
      response: agentText,
      actions: shouldTransfer ? ['transfer_to_number:+1234567890'] : [],
      end_call: false,
    });
  }

  return NextResponse.json({ success: true });
}

system: `You are a lead qualification agent.

For each lead, think through:
1. Budget: Do they have $5k+ to spend? (look for explicit mentions or company size indicators)
2. Timeline: Do they need a solution within 90 days? (urgency language, current pain points)
3. Fit: Does their problem match our services? (compare to service list)

Show your reasoning in <thinking> tags, then provide final qualification in <result> tags.

Example:
<thinking>
- Budget: Mentioned "$50k marketing budget" → HIGH
- Timeline: Said "need this ASAP" and "Q1 launch" → HIGH
- Fit: Looking for "lead gen automation" which matches our n8n service → HIGH
Overall: QUALIFIED
</thinking>

<result>
Qualified: Yes
Score: 9/10
Reason: High budget, urgent timeline, perfect service fit
Next Action: Schedule discovery call
</result>`

messages: [
  {
    role: 'user',
    content: `Lead: "We're a B2B SaaS company spending about $8k/month on Google Ads but can't track ROI. Need better attribution by end of Q1. Can you help?"`
  }
]

system: `When handling spam/sales calls, be polite but firm:

Example 1:
Caller: "Hi, I'm calling about your car's extended warranty..."
You: "We're not interested, but thank you for calling. Have a great day!" [END CALL]

Example 2:
Caller: "I'd like to speak to the owner about SEO services we offer..."
You: "We have an agency partner for that already, but I appreciate you reaching out. Take care!" [END CALL]

Example 3:
Caller: "This is Rachel from card services..."
You: "Not interested, thanks!" [END CALL]

Never engage with spam. Never be rude. Always end professionally.`

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  system: `Respond with JSON only:
{
  "response": "What you say to the caller",
  "intent": "qualified_lead | not_qualified | needs_info | spam",
  "confidence": 0.0-1.0,
  "nextAction": "schedule | transfer | email_followup | end_call",
  "extractedData": {
    "company": "string or null",
    "budget": "number or null",
    "timeline": "string or null"
  }
}`,
  messages: [{ role: 'user', content: transcript }]
});

const parsed = JSON.parse(message.content[0].text);
// Now you can programmatically route based on intent

// lib/prompts/bellabot-v3.ts
export const BELLABOT_SYSTEM_PROMPT_V3 = `
You are BellaBot v3.2.1
Last updated: 2026-02-15

[Full system prompt here...]

Changelog:
- v3.2.1: Added handling for international callers
- v3.2.0: Improved spam detection accuracy
- v3.1.5: Added appointment rescheduling logic
`;

// Usage
import { BELLABOT_SYSTEM_PROMPT_V3 } from '@/lib/prompts/bellabot-v3';

const message = await anthropic.messages.create({
  system: BELLABOT_SYSTEM_PROMPT_V3,
  // ...
});

// 1. Create Retell agent (one-time setup)
const retellAgent = await fetch('https://api.retellai.com/create-agent', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RETELL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_name: 'BellaBot',
    voice_id: 'elevenlabs-rachel', // Choose from Retell voice catalog
    language: 'en-US',
    webhook_url: 'https://yourdomain.com/api/retell/webhook',
    initial_message: 'Hi! This is Bella with VIXI. How can I help you today?',
    response_timeout: 5000, // 5s silence before prompting user
  }),
});

// 2. Your webhook receives events
// app/api/retell/webhook/route.ts
import { anthropic } from '@/lib/anthropic';

export async function POST(request: Request) {
  const event = await request.json();

  switch (event.event_type) {
    case 'call_started':
      // Initialize conversation state
      await initCallSession(event.call_id);
      break;

    case 'transcript_update':
      // User spoke, generate response
      const response = await generateResponse(event);
      return NextResponse.json({
        response_text: response.text,
        end_call: response.shouldEndCall,
        transfer_number: response.transferTo,
      });

    case 'call_ended':
      // Log final transcript, update CRM
      await finalizeCall(event.call_id, event.transcript);
      break;
  }

  return NextResponse.json({ success: true });
}

async function generateResponse(event) {
  const message = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 300, // Short responses for voice
    temperature: 0.3,
    system: BELLABOT_SYSTEM_PROMPT_V3,
    messages: [
      {
        role: 'user',
        content: `Conversation so far:
${event.transcript}

User just said: "${event.user_message}"

What should you respond? Keep it conversational and under 50 words.`
      }
    ]
  });

  return {
    text: message.content[0].text,
    shouldEndCall: message.content[0].text.includes('[END CALL]'),
    transferTo: extractPhoneNumber(message.content[0].text),
  };
}

// BEFORE (3,200 tokens)
You are BellaBot, a professional and friendly call screening assistant...
[verbose instructions]

When a caller mentions they are interested in our services, you should...
[repetitive examples]

// AFTER (680 tokens)
You are BellaBot. Screen calls for VIXI.

Role: Greet → Qualify → Book/Transfer
Qualify = Budget $5k+, Timeline <90d, Service fit

Responses:
- Qualified: "Let's schedule! Thu 2PM or Fri 10AM?"
- Not qualified: "I'll email you details within 24h"
- Spam: "Not interested, thanks!" [END]

Never: Make up info, quote prices, collect payment

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: BELLABOT_SYSTEM_PROMPT_V3,
      cache_control: { type: 'ephemeral' } // Cache this!
    }
  ],
  messages: [{ role: 'user', content: userInput }]
});

// First call: Full cost (3,200 input tokens)
// Subsequent calls within 5 min: 90% cheaper (cached)

// Bad: Send entire 50-message conversation (10k+ tokens)
const messages = allMessages; // $$$$

// Good: Summarize + keep last 5 messages
const messages = [
  {
    role: 'user',
    content: `[Summary] Previous conversation: User is interested in n8n automation services. Budget confirmed at $12k. Needs timeline estimate.`
  },
  ...last5Messages // Only recent context
];

// Saves 8,000+ tokens per call

async function callAgentWithFallbacks(input: string) {
  // Try Claude Sonnet 4.6 first
  try {
    return await callClaude('claude-sonnet-4-20250514', input);
  } catch (error) {
    console.error('Sonnet 4.6 failed:', error);

    // Fallback 1: Try Haiku (faster, cheaper, less capable)
    try {
      return await callClaude('claude-haiku-20250303', input);
    } catch (error2) {
      console.error('Haiku failed:', error2);

      // Fallback 2: GPT-4o-mini
      try {
        return await callOpenAI('gpt-4o-mini', input);
      } catch (error3) {
        console.error('All models failed:', error3);

        // Fallback 3: Canned response
        return {
          response: "I'm experiencing technical difficulties. Please contact support@vixi.agency or call +1-555-0123.",
          intent: 'error',
          requiresHumanReview: true,
        };
      }
    }
  }
}

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 8000); // 8s max

try {
  const message = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{ role: 'user', content: input }],
  }, {
    signal: controller.signal, // Abort on timeout
  });

  clearTimeout(timeout);
  return message;

} catch (error) {
  if (error.name === 'AbortError') {
    // Model took too long, use cached response
    return getCachedResponse(input);
  }
  throw error;
}

system: `Rate your confidence on every response (0.0-1.0).
If confidence < 0.8, say "I'm not certain, let me get a human to help."`

// In your code
const { response, confidence } = await callAgent(input);

if (confidence < 0.8) {
  // Flag for human review
  await notifyHuman({
    input,
    agentResponse: response,
    confidence,
    priority: confidence < 0.5 ? 'high' : 'medium',
  });

  // Send safe fallback to user
  return "Great question—let me have a specialist reach out within 2 hours.";
}

n8n Workflow: "Lead Intelligence Pipeline"

[Webhook] New lead from website
    ↓
[Router Agent] Analyze lead source & completeness
    ↓
    ├─→ [Qualifier Agent] Score lead quality
    │       ↓
    │   [IF] Score > 7 → High Priority
    │       ↓
    │   [Researcher Agent] Enrich: LinkedIn + Website
    │       ↓
    │   [Outreach Agent] Generate personalized email
    │       ↓
    │   [Send Email] via SendGrid
    │
    └─→ [IF] Incomplete data → Request more info
            ↓
        [Send SMS] via Twilio

[ALL paths] → [Log to Supabase] → [Notify Slack]

# .env.production
ANTHROPIC_API_KEY=sk-ant-...
RETELL_API_KEY=retell_...
SUPABASE_URL=https://...
SUPABASE_KEY=eyJ...
REDIS_URL=redis://...

# Agent configuration
BELLABOT_PROMPT_VERSION=v3.2.1
QUALIFIER_CONFIDENCE_THRESHOLD=0.80
RESEARCHER_MAX_PARALLEL_CALLS=3

# Feature flags
ENABLE_VOICE_AGENTS=true
ENABLE_LEAD_SCORING=true
USE_PROMPT_CACHING=true