{
  "name": "create_task",
  "description": "在项目管理系统中创建一个新任务。仅当用户明确要求创建、添加或记录待办事项时使用。",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "任务的简短标题，例如：‘撰写下周周报’"
      },
      "priority": {
        "type": "string",
        "enum": ["high", "medium", "low"],
        "description": "任务紧急程度，默认为 medium"
      },
      "due_date": {
        "type": "string",
        "format": "date",
        "description": "截止日期，格式必须为 YYYY-MM-DD"
      }
    },
    "required": ["title"]
  }
}

用户: "帮我建一个明天截止的写代码任务"
       │
       ▼
[应用层] 发送用户 Prompt + 工具 Schema
       │
       ▼ (网络请求)
[模型] 分析语义，匹配 Schema，输出 tool_call 请求：
       { name: "create_task", arguments: { title: "写代码", due_date: "2026-05-29" } }
       │
       ▼ (网络响应挂起)
[应用层] 拦截到 tool_call -> 执行参数校验 -> 执行本地代码（写入数据库）-> 拿到 result: { success: true, task_id: 1024 }
       │
       ▼ (新网络请求)
[应用层] 将工具执行结果 `{ role: "tool", tool_call_id: "...", content: "{...}" }` 回传给模型
       │
       ▼
[模型] 阅读执行结果，生成最终人类语言：“我已经为您创建好了任务，ID是1024。”

import { z } from 'zod';
import { tool } from 'ai';

// 模拟的外部系统接口
const db = {
  async createTask(title: string, priority: string, dueDate?: string) {
    return { id: Math.floor(Math.random() * 10000), title, priority, dueDate, status: 'created' };
  },
  async searchWiki(query: string) {
    if (query.includes('AI')) {
      return { content: 'AI应用开发中，Tool Calling 是实现 Agent 架构的核心。' };
    }
    return { content: '未找到相关资料。' };
  }
};

export const tools = {
  // 工具一：查询资料
  searchWiki: tool({
    description: '查询内部 Wiki 知识库，获取相关开发规范与背景资料。',
    parameters: z.object({
      query: z.string().describe('检索关键词，如 "AI 开发规范"')
    }),
    execute: async ({ query }) => {
      console.log(`[工具执行] 正在检索 Wiki: "${query}"`);
      const result = await db.searchWiki(query);
      return result;
    }
  }),

  // 工具二：创建任务
  createTask: tool({
    description: '在项目管理系统中创建一个新任务。',
    parameters: z.object({
      title: z.string().describe('任务标题'),
      priority: z.enum(['high', 'medium', 'low']).default('medium').describe('紧急程度'),
      dueDate: z.string().optional().describe('截止日期，格式为 YYYY-MM-DD')
    }),
    execute: async ({ title, priority, dueDate }) => {
      console.log(`[工具执行] 正在创建任务: "${title}", 优先级: ${priority}`);
      const result = await db.createTask(title, priority, dueDate);
      return result;
    }
  })
};

import { generateText, ToolExecutionValidationError } from 'ai';
import { openai } from '@ai-sdk/openai'; // 需要提前配置好 OPENAI_API_KEY

async function runAgentWithRetry(prompt: string, maxRetries = 2) {
  let currentPrompt = prompt;
  let attempts = 0;

  while (attempts <= maxRetries) {
    try {
      const response = await generateText({
        model: openai('gpt-4o'),
        tools: tools,
        prompt: currentPrompt,
        maxSteps: 5, // 允许自动进行多轮工具调用循环
      });

      return response;
    } catch (error) {
      attempts++;
      if (error instanceof Error && error.name === 'ZodError') {
        // 捕捉到本地 Zod 校验失败
        console.warn(`[参数校验失败] 第 ${attempts} 次尝试失败，正在反馈给模型进行纠错。`);
        currentPrompt = `${currentPrompt}\n\n【系统提示】上一次工具调用参数未通过校验，错误信息为："${error.message}"。请重新检查你的参数格式并再次调用。`;
      } else {
        // 遇到不可恢复的其他错误（如网络中断、API 凭证失效），不再重试，直接抛出
        throw error;
      }
    }
  }
  throw new Error('达到最大重试次数，模型未能成功纠正其生成的工具参数。');
}

import { tool } from 'ai';
import { z } from 'zod';

// 模拟挂起和等待外部确认的信号器
const pendingApprovals = new Map<string, (approved: boolean) => void>();

export const secureTransferTool = tool({
  description: '将资金转入指定的银行账户。此操作敏感，必须经过人工审核。',
  parameters: z.object({
    amount: z.number().positive().describe('转账金额'),
    accountNumber: z.string().describe('目标账户')
  }),
  execute: async ({ amount, accountNumber }) => {
    const approvalId = `req_${Math.random().toString(36).substr(2, 9)}`;
    console.log(`\n⚠️ [高危操作拦截] 检测到转账请求！`);
    console.log(`- 目标账户: ${accountNumber}`);
    console.log(`- 转账金额: ¥${amount}`);
    console.log(`- 审批 ID : ${approvalId}`);
    console.log(`[系统提示] 请在控制台中输入 "yes" 同意转账，或输入 "no" 拒绝：`);

    // 挂起 execute 的异步流程，等待外部输入信号
    const approved = await new Promise<boolean>((resolve) => {
      pendingApprovals.set(approvalId, resolve);
      
      // 在控制台中模拟人工交互输入
      process.stdin.once('data', (data) => {
        const input = data.toString().trim().toLowerCase();
        if (input === 'yes' || input === 'y') {
          resolve(true);
        } else {
          resolve(false);
        }
      });
    });

    pendingApprovals.delete(approvalId);

    if (!approved) {
      throw new Error('用户拒绝了该转账操作，转账已被安全拦截。');
    }

    // 只有在获批后，才会真正调用底层写库/转账接口
    return { status: 'success', transactionId: `tx_${Date.now()}`, message: '转账成功' };
  }
});

{
  "name": "tool-calling-demo",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@ai-sdk/openai": "^1.0.0",
    "ai": "^3.0.0",
    "zod": "^3.22.0"
  }
}

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { tools } from './tools.js'; // 导入我们前面写好的 tools 定义

async function main() {
  // 模拟输入：一句话同时触发 Wiki 检索和任务创建
  const userInput = "根据 Wiki 里关于 AI 的开发规范，帮我建一个今天截止的‘编写 AI 模块代码’任务，优先级定为高。";

  console.log(`[User]: ${userInput}\n`);
  console.log(`--- [开始执行可观测 Trace] ---`);

  const response = await generateText({
    model: openai('gpt-4o'), // 确保已在环境变量中注入了 OPENAI_API_KEY
    tools: tools,
    prompt: userInput,
    maxSteps: 5, // 开启多步调用，允许模型先查 Wiki，拿到结果后再建任务
    onStepFinish({ text, toolCalls, toolResults, finishReason }) {
      // 每一步推理/执行结束时的钩子，这是可观测性的关键
      console.log(`\n[Step Finish Log]`);
      if (text) { 
        console.log(`> 模型输出: "${text}"`); 
      }
      if (toolCalls && toolCalls.length > 0) {
        console.log(`> 模型提议调用工具:`);
        toolCalls.forEach(call => {
          console.log(`  - 工具名: ${call.toolName}`);
          console.log(`  - 提取参数: ${JSON.stringify(call.args)}`);
        });
      }
      if (toolResults && toolResults.length > 0) {
        console.log(`> 应用程序执行工具结果:`);
        toolResults.forEach(res => {
          console.log(`  - 工具: ${res.toolName}`);
          console.log(`  - 结果: ${JSON.stringify(res.result)}`);
        });
      }
      console.log(`> 终止状态: ${finishReason}`);
    }
  });

  console.log(`\n--- [Trace 结束] ---`);
  console.log(`\n[AI 最终答复]: ${response.text}`);
}

main().catch(console.error);