Tool Use / Function Calling — cách AI 'gọi function' thay vì chỉ trả text

const tool = {
  name: "get_order_status",
  description: `
    Get current status of a vietcodex.com order by order number.
    Use this when user asks about order delivery, status, or ETA.
    
    Examples of trigger queries:
      - "Đơn VC2026000001 đang ở đâu?"
      - "Khi nào nhận được hàng?"
      - "Status order #123?"
    
    DO NOT use for:
      - Refund requests (use 'refund_order' tool)
      - Order creation (use 'create_order' tool)
    
    Returns object with status, eta, tracking_url.
  `,
  input_schema: {
    type: "object",
    properties: {
      order_number: {
        type: "string",
        description: "Order number, format VC<year><6-digit>, e.g. VC2026000001",
        pattern: "^VC\\d{10}$"
      }
    },
    required: ["order_number"]
  }
};

✅ "get_order_status"
✅ "send_telegram_notification"
❌ "order"           // too vague
❌ "doStuff"         // useless

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
const TOOLS = [
  {
    name: "get_order_status",
    description: "...",
    input_schema: { ... }
  },
  {
    name: "send_email",
    description: "...",
    input_schema: { ... }
  },
  // ... more tools
];

async function chat(userMessage: string) {
  // Step 1: AI decide tool
  const response = await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    tools: TOOLS,
    messages: [{ role: "user", content: userMessage }]
  });
  
  // Step 2: Check if AI called tool
  if (response.stop_reason === "tool_use") {
    const toolUse = response.content.find(c => c.type === "tool_use");
    if (!toolUse) throw new Error("Expected tool_use");
    
    // Step 3: Execute tool
    const toolResult = await executeToolByName(toolUse.name, toolUse.input);
    
    // Step 4: Send result back to AI
    const final = await client.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 1024,
      tools: TOOLS,
      messages: [
        { role: "user", content: userMessage },
        { role: "assistant", content: response.content },
        { 
          role: "user", 
          content: [{ 
            type: "tool_result", 
            tool_use_id: toolUse.id,
            content: JSON.stringify(toolResult)
          }] 
        }
      ]
    });
    
    return final.content[0].type === "text" ? final.content[0].text : "";
  }
  
  // No tool needed, return AI text
  return response.content[0].type === "text" ? response.content[0].text : "";
}

async function agentLoop(userMessage: string, maxTurns = 10) {
  const messages: any[] = [{ role: "user", content: userMessage }];
  
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 4096,
      tools: TOOLS,
      messages
    });
    
    messages.push({ role: "assistant", content: response.content });
    
    if (response.stop_reason === "end_turn") {
      // AI finished, return final answer
      return extractText(response);
    }
    
    if (response.stop_reason === "tool_use") {
      // Execute all tool calls in parallel
      const toolUses = response.content.filter(c => c.type === "tool_use");
      const results = await Promise.all(
        toolUses.map(t => executeToolByName(t.name, t.input))
      );
      
      messages.push({
        role: "user",
        content: toolUses.map((t, i) => ({
          type: "tool_result",
          tool_use_id: t.id,
          content: JSON.stringify(results[i])
        }))
      });
      // Continue loop
    }
  }
  
  throw new Error("Max turns exceeded");
}

{ tool_choice: { type: "auto" } }

{ tool_choice: { type: "any" } }

{ tool_choice: { type: "tool", name: "get_order_status" } }

// User: "Thời tiết Hà Nội và Sài Gòn"
 
// AI generates 2 tool calls trong 1 response
{
  content: [
    { type: "tool_use", id: "1", name: "get_weather", input: { city: "Hanoi" } },
    { type: "tool_use", id: "2", name: "get_weather", input: { city: "HCMC" } }
  ]
}
 
// Execute parallel
const results = await Promise.all([
  getWeather("Hanoi"),
  getWeather("HCMC")
]);
 
// Result: 1s parallel vs 2s sequential

const getOrderStatus = {
  name: "get_order_status",
  description: "Read order status, no side effect",
  input_schema: { ... }
};
 
// Implementation
async function executeGetOrderStatus(input: { order_number: string }) {
  return await db.query.orders.findFirst({
    where: eq(orders.orderNumber, input.order_number)
  });
}

const sendEmail = {
  name: "send_email_to_customer",
  description: "Send email. CRITICAL: User must confirm before send.",
  input_schema: { ... }
};
 
// Implementation requires human approval
async function executeSendEmail(input: EmailParams) {
  // Queue for human approval
  await queue.add("pending-email", input);
  return { status: "pending_human_approval", queue_id: ... };
}

const runPython = {
  name: "run_python_code",
  description: "Execute Python in isolated sandbox. No network, readonly fs.",
  input_schema: {
    type: "object",
    properties: {
      code: { type: "string", description: "Python code" }
    },
    required: ["code"]
  }
};
 
async function executeRunPython(input: { code: string }) {
  return await sandbox.execute("python3", input.code, {
    timeout: 5000,
    network: false,
    filesystem: "readonly"
  });
}

// User: "Tìm 3 customer cao nhất + gửi email upgrade offer"
 
// AI auto chains:
// 1. query_top_customers({ limit: 3 })
// 2. For each customer:
//    a. get_customer_email({ customer_id })
//    b. send_email({ to: email, template: "upgrade_offer" })

❌ description: "Get data"
✅ description: "Get customer order history. Use when user asks 'my orders', 'past purchases', etc."

// BAD
async function executeRunSQL({ query }) {
  return db.execute(query);  // SQL injection paradise
}
 
// GOOD
async function executeRunSQL({ query }) {
  if (!query.match(/^SELECT/i)) throw new Error("Only SELECT allowed");
  if (query.includes(";")) throw new Error("Single statement only");
  return db.execute(query);
}

// BAD: 30s tool blocking AI response
async function executeProcessVideo({ url }) {
  return await processVideo(url);  // 30s
}
 
// GOOD: queue + return job_id
async function executeProcessVideo({ url }) {
  const jobId = await queue.add("video", { url });
  return { status: "queued", job_id: jobId, check_after: "30s" };
}

// BAD: tool throw → AI confused
async function execute(input) {
  return await fragileAPI(input);  // throws on 500
}
 
// GOOD: graceful error
async function execute(input) {
  try {
    return { success: true, data: await fragileAPI(input) };
  } catch (e) {
    return { success: false, error: e.message, retry_after: 60 };
  }
}

const SUPPORT_TOOLS = [
  // Read-only knowledge
  { name: "search_wiki", description: "Search wiki.vietcodex.com docs" },
  { name: "get_service_pricing", description: "Get pricing for service" },
  { name: "get_order_status", description: "Get order status by number" },
  
  // Customer-specific (need auth)
  { name: "get_my_orders", description: "Get my orders (auto-scoped to user)" },
  { name: "get_my_subscription", description: "Get my subscription detail" },
  
  // Actions (need confirmation)
  { name: "create_support_ticket", description: "Create ticket" },
  { name: "schedule_call", description: "Book discovery call with team" },
  
  // Escalation
  { name: "escalate_to_human", description: "Transfer to human support" }
];
 
// Agent loop
async function supportAgent(userMessage: string, userId: string) {
  const messages = [
    { role: "user", content: userMessage }
  ];
  
  for (let turn = 0; turn < 5; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-5",
      system: SUPPORT_SYSTEM_PROMPT,
      tools: SUPPORT_TOOLS,
      messages
    });
    
    if (response.stop_reason === "end_turn") {
      return extractText(response);
    }
    
    if (response.stop_reason === "tool_use") {
      const toolUses = response.content.filter(c => c.type === "tool_use");
      const results = await Promise.all(
        toolUses.map(t => executeWithAuth(t, userId))
      );
      
      messages.push({ role: "assistant", content: response.content });
      messages.push({
        role: "user",
        content: toolUses.map((t, i) => ({
          type: "tool_result",
          tool_use_id: t.id,
          content: JSON.stringify(results[i])
        }))
      });
    }
  }
}