AI Agent 工具调用工程：从 Function Calling 到自主工具编排的完整技术栈

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// 1. 定义工具 Schema
const tools: OpenAI.Chat.Completions.ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "获取指定城市的当前天气信息",
      parameters: {
        type: "object",
        properties: {
          city: {
            type: "string",
            description: "城市名称，例如：北京、上海",
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            description: "温度单位",
          },
        },
        required: ["city"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "search_flights",
      description: "搜索航班信息",
      parameters: {
        type: "object",
        properties: {
          from: { type: "string", description: "出发城市" },
          to: { type: "string", description: "到达城市" },
          date: { type: "string", description: "日期 YYYY-MM-DD" },
        },
        required: ["from", "to", "date"],
      },
    },
  },
];

// 2. 调用 LLM，传入工具定义
const response = await openai.chat.completions.create({
  model: "gpt-4-turbo",
  messages: [
    {
      role: "user",
      content: "北京今天天气怎么样？我想明天飞去上海。",
    },
  ],
  tools: tools,
  tool_choice: "auto", // LLM 自主决定是否调用工具
});

// 3. 处理工具调用请求
const message = response.choices[0].message;

if (message.tool_calls) {
  // LLM 请求调用工具
  for (const toolCall of message.tool_calls) {
    const functionName = toolCall.function.name;
    const functionArgs = JSON.parse(toolCall.function.arguments);
    
    // 4. 执行工具（这里调用真实的 API）
    const result = await executeTool(functionName, functionArgs);
    
    // 5. 将结果返回给 LLM
    const finalResponse = await openai.chat.completions.create({
      model: "gpt-4-turbo",
      messages: [
        ...messages,
        message,
        {
          role: "tool",
          tool_call_id: toolCall.id,
          content: JSON.stringify(result),
        },
      ],
      tools: tools,
    });
    
    console.log(finalResponse.choices[0].message.content);
  }
}

// 工具 Schema 定义最佳实践
const weatherToolSchema = {
  type: "function",
  function: {
    name: "get_weather",
    description: "获取指定城市的当前天气信息，包括温度、湿度、风速、天气状况。支持实时天气和未来 7 天预报。",
    parameters: {
      type: "object",
      properties: {
        city: {
          type: "string",
          description: "城市名称，支持中文和英文，例如：北京、Beijing、上海",
        },
        unit: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
          description: "温度单位：celsius（摄氏度）或 fahrenheit（华氏度），默认 celsius",
          default: "celsius",
        },
        forecast_days: {
          type: "integer",
          description: "预报天数，0 表示当前天气，1-7 表示未来天数",
          minimum: 0,
          maximum: 7,
          default: 0,
        },
      },
      required: ["city"],
      additionalProperties: false, // 禁止未定义参数
    },
  },
};

import { Server } from '@modelcontextprotocol/sdk/server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types';

// 创建 MCP Server
const server = new Server(
  {
    name: "weather-mcp-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {}, // 声明支持工具调用
    },
  }
);

// 注册可用工具列表
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_weather",
        description: "获取指定城市的当前天气信息",
        inputSchema: {
          type: "object",
          properties: {
            city: {
              type: "string",
              description: "城市名称",
            },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"],
              description: "温度单位",
            },
          },
          required: ["city"],
        },
      },
      {
        name: "get_forecast",
        description: "获取未来 7 天天气预报",
        inputSchema: {
          type: "object",
          properties: {
            city: { type: "string", description: "城市名称" },
            days: {
              type: "integer",
              description: "预报天数（1-7）",
              minimum: 1,
              maximum: 7,
            },
          },
          required: ["city"],
        },
      },
    ],
  };
});

// 处理工具调用请求
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === "get_weather") {
    // 调用真实的天气 API
    const weather = await fetchWeatherData(args.city, args.unit);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            city: args.city,
            temperature: weather.temp,
            humidity: weather.humidity,
            condition: weather.condition,
          }),
        },
      ],
    };
  }
  
  if (name === "get_forecast") {
    const forecast = await fetchForecast(args.city, args.days);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(forecast),
        },
      ],
    };
  }
  
  throw new Error(`Unknown tool: ${name}`);
});

// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server is running...");
}

main().catch(console.error);

// 多工具编排示例：旅行规划 Agent

interface ToolResult {
  success: boolean;
  data?: any;
  error?: string;
}

// 1. 串行编排：依次调用工具
async function sequentialOrchestration(
  tools: Array<{ name: string; args: any }>,
  executeTool: (name: string, args: any) => Promise<ToolResult>
): Promise<ToolResult[]> {
  const results: ToolResult[] = [];
  
  for (const tool of tools) {
    const result = await executeTool(tool.name, tool.args);
    results.push(result);
    
    if (!result.success) {
      // 如果某个工具失败，可以选择中断或继续
      break;
    }
  }
  
  return results;
}

// 2. 并行编排：同时调用多个工具
async function parallelOrchestration(
  tools: Array<{ name: string; args: any }>,
  executeTool: (name: string, args: any) => Promise<ToolResult>
): Promise<ToolResult[]> {
  const promises = tools.map(tool => executeTool(tool.name, tool.args));
  return await Promise.all(promises);
}

// 3. 条件分支编排：根据结果决定下一步
async function conditionalOrchestration(
  executeTool: (name: string, args: any) => Promise<ToolResult>
): Promise<ToolResult> {
  // 第一步：查询天气
  const weatherResult = await executeTool("get_weather", { city: "北京" });
  
  if (!weatherResult.success) {
    return weatherResult;
  }
  
  // 根据天气条件决定下一步
  if (weatherResult.data.condition === "rain") {
    // 如果下雨，查询室内景点
    return await executeTool("search_attractions", {
      city: "北京",
      type: "indoor",
    });
  } else {
    // 如果天气好，查询户外景点
    return await executeTool("search_attractions", {
      city: "北京",
      type: "outdoor",
    });
  }
}

// 4. 动态选择编排：由 LLM 自主决策
async function dynamicOrchestration(
  userRequest: string,
  availableTools: string[],
  llmDecide: (context: string, tools: string[]) => Promise<{
    tool: string;
    args: any;
    shouldContinue: boolean;
  }>,
  executeTool: (name: string, args: any) => Promise<ToolResult>
): Promise<ToolResult[]> {
  const results: ToolResult[] = [];
  let context = userRequest;
  let shouldContinue = true;
  
  while (shouldContinue) {
    // LLM 根据当前上下文决定下一步
    const decision = await llmDecide(context, availableTools);
    
    // 执行选定的工具
    const result = await executeTool(decision.tool, decision.args);
    results.push(result);
    
    // 更新上下文
    context += `\n工具 ${decision.tool} 执行结果: ${JSON.stringify(result)}`;
    shouldContinue = decision.shouldContinue;
  }
  
  return results;
}

import Anthropic from '@anthropic-ai/sdk';
import { z } from 'zod';

const anthropic = new Anthropic();

// 1. 定义工具 Schema
const tools = [
  {
    name: "get_weather",
    description: "查询指定城市的天气信息，包括温度、天气状况、未来 3 天预报。",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "城市名称" },
        date: { type: "string", description: "日期 YYYY-MM-DD，默认为今天" },
      },
      required: ["city"],
    },
  },
  {
    name: "search_flights",
    description: "搜索航班信息，返回价格和时刻表。",
    input_schema: {
      type: "object",
      properties: {
        from: { type: "string", description: "出发城市" },
        to: { type: "string", description: "到达城市" },
        date: { type: "string", description: "出发日期 YYYY-MM-DD" },
        budget: { type: "number", description: "预算上限（元）" },
      },
      required: ["from", "to", "date"],
    },
  },
  {
    name: "search_hotels",
    description: "搜索酒店信息，返回价格、评分、设施。",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "城市名称" },
        checkin: { type: "string", description: "入住日期 YYYY-MM-DD" },
        checkout: { type: "string", description: "退房日期 YYYY-MM-DD" },
        budget_per_night: { type: "number", description: "每晚预算上限（元）" },
      },
      required: ["city", "checkin", "checkout"],
    },
  },
  {
    name: "recommend_attractions",
    description: "推荐景点，支持按类型筛选（户外/室内/文化/美食）。",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "城市名称" },
        type: {
          type: "string",
          enum: ["outdoor", "indoor", "culture", "food"],
          description: "景点类型",
        },
        count: {
          type: "integer",
          description: "推荐数量，默认 5",
          default: 5,
        },
      },
      required: ["city"],
    },
  },
];

// 2. 工具执行引擎（带错误处理和重试）
async function executeTool(
  name: string,
  args: any,
  maxRetries = 3
): Promise<{ success: boolean; data?: any; error?: string }> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      // 根据工具名调用对应的 API
      switch (name) {
        case "get_weather":
          return await executeWeatherAPI(args);
        case "search_flights":
          return await executeFlightAPI(args);
        case "search_hotels":
          return await executeHotelAPI(args);
        case "recommend_attractions":
          return await executeAttractionAPI(args);
        default:
          return { success: false, error: `Unknown tool: ${name}` };
      }
    } catch (error: any) {
      console.error(`Tool ${name} failed (attempt ${attempt}): ${error.message}`);
      
      if (attempt === maxRetries) {
        return { success: false, error: `Tool ${name} failed after ${maxRetries} attempts: ${error.message}` };
      }
      
      // 指数退避重试
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1)));
    }
  }
  
  return { success: false, error: "Unexpected error" };
}

// 3. 主循环：Agent 推理与工具调用
async function travelAgent(userRequest: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    {
      role: "user",
      content: userRequest,
    },
  ];
  
  const maxIterations = 10; // 防止无限循环
  let iteration = 0;
  
  while (iteration < maxIterations) {
    iteration++;
    
    // 调用 Claude
    const response = await anthropic.messages.create({
      model: "claude-3-5-sonnet-20241022",
      max_tokens: 4096,
      tools: tools,
      messages: messages,
    });
    
    // 检查是否需要调用工具
    const toolUses = response.content.filter(
      (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
    );
    
    if (toolUses.length === 0) {
      // 没有工具调用，返回最终回复
      const textBlock = response.content.find(
        (block): block is Anthropic.TextBlock => block.type === "text"
      );
      return textBlock?.text || "Sorry, I couldn't generate a response.";
    }
    
    // 执行所有工具调用
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    
    for (const toolUse of toolUses) {
      console.log(`Calling tool: ${toolUse.name} with args:`, toolUse.input);
      
      const result = await executeTool(toolUse.name, toolUse.input);
      
      toolResults.push({
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: JSON.stringify(result),
      });
    }
    
    // 更新消息历史
    messages.push({
      role: "assistant",
      content: response.content,
    });
    
    messages.push({
      role: "user",
      content: toolResults,
    });
  }
  
  return "Sorry, I couldn't complete the task after multiple attempts.";
}

// 使用示例
async function main() {
  const userRequest = `
    我计划下周一从上海去北京出差 3 天。
    预算：机票 2000 元以内，酒店每晚 800 元以内。
    请帮我查一下北京天气，搜索航班和酒店，推荐一些适合的餐厅。
  `;
  
  const response = await travelAgent(userRequest);
  console.log(response);
}

main().catch(console.error);