Vercel AI SDK Agent Loop 完全指南

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'openai/gpt-4o',
  prompt: '你好,请介绍一下自己。',
});

console.log(text);

import { generateText } from 'ai';

// 直接使用模型字符串 - AI Gateway 自动路由
const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: '分析这段代码的性能问题',
});

// 支持多种提供商
const providers = [
  'openai/gpt-4o',
  'anthropic/claude-sonnet-4.5',
  'google/gemini-2.5-pro',
  'xai/grok-3',
];

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const { text } = await generateText({
  model: anthropic('claude-sonnet-4.5'),
  prompt: '你好',
});

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

const weatherTool = tool({
  description: '获取指定城市的当前天气',
  inputSchema: z.object({
    city: z.string().describe('城市名称'),
    unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
  }),
  execute: async ({ city, unit }) => {
    // 调用真实的天气 API
    const response = await fetch(
      `https://api.weather.com/v1/current?city=${city}&unit=${unit}`
    );
    return response.json();
  },
});

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

const { text, toolCalls, toolResults } = await generateText({
  model: 'openai/gpt-4o',
  tools: {
    weather: tool({
      description: '获取天气信息',
      inputSchema: z.object({
        location: z.string().describe('城市名称'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 22,
        condition: '晴天',
      }),
    }),
  },
  prompt: '北京今天天气怎么样?',
});

console.log(text);
// 输出: 北京今天的天气是晴天,温度约为22度。

import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const { text, steps } = await generateText({
  model: 'openai/gpt-4o',
  stopWhen: stepCountIs(5), // 最多执行 5 步
  tools: {
    weather: tool({
      description: '获取天气信息',
      inputSchema: z.object({
        location: z.string(),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72 + Math.floor(Math.random() * 21) - 10,
      }),
    }),
    convertTemperature: tool({
      description: '将华氏度转换为摄氏度',
      inputSchema: z.object({
        fahrenheit: z.number(),
      }),
      execute: async ({ fahrenheit }) => ({
        celsius: Math.round((fahrenheit - 32) * (5 / 9)),
      }),
    }),
  },
  prompt: '旧金山的天气如何?请用摄氏度告诉我。',
});

// Agent 会:
// 1. 调用 weather 获取华氏温度
// 2. 调用 convertTemperature 转换为摄氏度
// 3. 生成最终回答
console.log(text);
console.log('执行步骤:', steps.length);

import { stepCountIs, hasToolCall } from 'ai';

// 1. 步数限制
stopWhen: stepCountIs(10)

// 2. 特定工具被调用时停止
stopWhen: hasToolCall('finish')

// 3. 组合多个条件（任一满足即停止）
stopWhen: [stepCountIs(10), hasToolCall('submitAnswer')]

import { generateText, StopCondition } from 'ai';

// 自定义停止条件：当获取到有效结果时停止
const hasValidResult: StopCondition = ({ steps }) => {
  const lastStep = steps[steps.length - 1];
  if (lastStep?.toolResults) {
    return lastStep.toolResults.some(
      result => result.result?.status === 'success'
    );
  }
  return false;
};

const { text } = await generateText({
  model: 'openai/gpt-4o',
  stopWhen: [stepCountIs(10), hasValidResult],
  tools: { /* ... */ },
  prompt: '查询订单状态',
});

import { ToolLoopAgent, stepCountIs, tool } from 'ai';
import { z } from 'zod';

const weatherAgent = new ToolLoopAgent({
  model: 'anthropic/claude-sonnet-4.5',
  instructions: '你是一个天气助手,帮助用户查询天气信息。',
  tools: {
    weather: tool({
      description: '获取天气信息',
      inputSchema: z.object({
        city: z.string(),
      }),
      execute: async ({ city }) => ({
        city,
        temperature: 25,
        condition: '多云',
      }),
    }),
  },
  stopWhen: stepCountIs(20), // 默认最多 20 步
});

const result = await weatherAgent.generate({
  prompt: '北京和上海今天天气如何?',
});

console.log(result.text);
console.log('执行步骤:', result.steps);

import { generateText, stepCountIs } from 'ai';

const { text } = await generateText({
  model: 'openai/gpt-4o',
  stopWhen: stepCountIs(10),
  tools: {
    search: searchTool,
    summarize: summarizeTool,
    calculate: calculateTool,
  },
  prepareStep: async ({ previousStep, stepCount }) => {
    // 根据步骤数调整可用工具
    if (stepCount > 5) {
      // 后期阶段禁用搜索，强制总结
      return {
        tools: { summarize: summarizeTool },
        toolChoice: 'required',
      };
    }

    // 根据上一步结果调整
    if (previousStep?.toolResults?.some(r => r.toolName === 'search')) {
      // 搜索后切换到更强的模型进行分析
      return {
        model: 'anthropic/claude-opus-4',
      };
    }

    return {}; // 使用默认配置
  },
  prompt: '研究人工智能的最新发展并总结',
});

import { generateText, stepCountIs } from 'ai';

const { text } = await generateText({
  model: 'openai/gpt-4o',
  stopWhen: stepCountIs(5),
  tools: { /* ... */ },
  onStepFinish: async ({ stepType, text, toolCalls, toolResults, usage }) => {
    console.log(`步骤类型: ${stepType}`);

    if (toolCalls?.length) {
      console.log('工具调用:', toolCalls.map(tc => tc.toolName));
    }

    if (toolResults?.length) {
      console.log('工具结果:', toolResults);
    }

    console.log('Token 使用:', usage);
  },
  prompt: '分析这个项目的代码质量',
});

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

// 始终需要审批
const deleteFileTool = tool({
  description: '删除文件',
  inputSchema: z.object({
    path: z.string().describe('文件路径'),
  }),
  needsApproval: true, // 始终需要用户批准
  execute: async ({ path }) => {
    // 删除逻辑
  },
});

// 条件性审批
const paymentTool = tool({
  description: '处理支付',
  inputSchema: z.object({
    amount: z.number(),
    recipient: z.string(),
  }),
  needsApproval: async ({ amount }) => {
    // 超过 1000 元需要审批
    return amount > 1000;
  },
  execute: async ({ amount, recipient }) => {
    return await processPayment(amount, recipient);
  },
});

import { generateText, tool, type ModelMessage, type ToolApprovalResponse } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import * as readline from 'readline/promises';

// 1. 定义需要审批的工具
const runCommand = tool({
  description: '执行 Shell 命令',
  inputSchema: z.object({
    command: z.string().describe('要执行的命令'),
  }),
  // 条件审批：危险命令需要审批，安全命令自动执行
  needsApproval: async ({ command }) => {
    const dangerousPatterns = ['rm', 'delete', 'drop', 'truncate', 'kill'];
    return dangerousPatterns.some(p => command.toLowerCase().includes(p));
  },
  execute: async ({ command }) => {
    // 实际执行逻辑（简化示例）
    return { stdout: `已执行: ${command}`, exitCode: 0 };
  },
});

// 2. 用户交互函数
async function askUserApproval(toolName: string, args: unknown): Promise<boolean> {
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const answer = await rl.question(
    `\n[审批请求] 工具: ${toolName}\n参数: ${JSON.stringify(args, null, 2)}\n是否批准? (y/n): `
  );
  rl.close();
  return answer.toLowerCase() === 'y';
}

// 3. 完整的审批循环
async function agentWithApproval(userPrompt: string) {
  const messages: ModelMessage[] = [
    { role: 'user', content: userPrompt },
  ];

  while (true) {
    const result = await generateText({
      model: openai('gpt-4o'),
      tools: { runCommand },
      messages,
    });

    // 将模型响应加入消息历史
    messages.push(...result.response.messages);

    // 检查是否有待审批的工具调用
    const approvalRequests = result.content.filter(
      part => part.type === 'tool-approval-request'
    );

    // 没有审批请求 -> Agent 完成
    if (approvalRequests.length === 0) {
      console.log('Agent 最终回复:', result.text);
      return result.text;
    }

    // 逐个处理审批请求
    const approvals: ToolApprovalResponse[] = [];

    for (const request of approvalRequests) {
      const approved = await askUserApproval(
        request.toolCall.toolName,
        request.toolCall.input,
      );

      approvals.push({
        type: 'tool-approval-response',
        approvalId: request.approvalId,
        approved,
        reason: approved ? '用户已确认' : '用户拒绝执行',
      });
    }

    // 将审批结果加入消息，继续循环
    messages.push({ role: 'tool', content: approvals });
    // 循环回到 generateText，模型会根据审批结果继续
  }
}

// 运行示例
agentWithApproval('帮我清理 /tmp 目录下的临时文件');

[审批请求] 工具: runCommand
参数: { "command": "rm -rf /tmp/temp_*" }
是否批准? (y/n): y

Agent 最终回复: 已成功清理 /tmp 目录下的临时文件。

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

const searchTool = tool({
  description: '搜索文档',
  inputSchema: z.object({
    query: z.string(),
  }),
  execute: async ({ query }) => {
    // 返回完整的搜索结果供应用使用
    const results = await searchDocuments(query);
    return {
      total: results.length,
      documents: results.map(doc => ({
        id: doc.id,
        title: doc.title,
        content: doc.content, // 可能很长
        metadata: doc.metadata,
      })),
    };
  },
  // 只将摘要发送给模型，节省 Token
  toModelOutput: ({ output }) => ({
    total: output.total,
    documents: output.documents.map(doc => ({
      id: doc.id,
      title: doc.title,
      snippet: doc.content.substring(0, 200) + '...',
    })),
  }),
});

import { generateText, Output, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const { output, steps } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  stopWhen: stepCountIs(10),
  tools: {
    fetchData: tool({
      description: '获取数据',
      inputSchema: z.object({ source: z.string() }),
      execute: async ({ source }) => {
        // 获取数据逻辑
        return { data: '...' };
      },
    }),
  },
  output: Output.object({
    schema: z.object({
      summary: z.string().describe('数据摘要'),
      insights: z.array(z.string()).describe('关键洞察'),
      recommendations: z.array(z.object({
        action: z.string(),
        priority: z.enum(['high', 'medium', 'low']),
      })),
    }),
  }),
  prompt: '分析销售数据并提供建议',
});

// output 是类型安全的
console.log(output.summary);
console.log(output.insights);
console.log(output.recommendations);

import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const { text, steps } = await generateText({
  model: 'openai/gpt-4o',
  stopWhen: stepCountIs(5),
  tools: {
    riskyTool: tool({
      description: '可能失败的工具',
      inputSchema: z.object({ input: z.string() }),
      execute: async ({ input }) => {
        if (Math.random() > 0.5) {
          throw new Error('工具执行失败');
        }
        return { result: 'success' };
      },
    }),
  },
  prompt: '执行风险操作',
});

// 检查工具错误
for (const step of steps) {
  const errors = step.content?.filter(
    part => part.type === 'tool-error'
  );

  if (errors?.length) {
    console.log('工具执行错误：', errors);
  }
}

import { generateText, RetryError } from 'ai';

try {
  const { text } = await generateText({
    model: 'openai/gpt-4o',
    prompt: '你好',
  });
} catch (error) {
  if (RetryError.isInstance(error)) {
    console.log('重试失败：', error.reason);
    console.log('最后一个错误：', error.lastError);
    console.log('所有错误：', error.errors);
  } else {
    console.log('其他错误：', error);
  }
}

import { streamText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const result = streamText({
  model: 'openai/gpt-4o',
  stopWhen: stepCountIs(5),
  tools: {
    weather: tool({
      description: '获取天气',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, temp: 25 }),
    }),
  },
  onStepFinish: ({ stepType, toolCalls }) => {
    if (toolCalls?.length) {
      console.log('正在调用工具：', toolCalls.map(t => t.toolName));
    }
  },
  prompt: '北京天气如何?',
});

// 流式输出文本
for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

// 获取最终结果
const finalResult = await result;
console.log('\n步骤数：', finalResult.steps.length);

import { ToolLoopAgent, tool, stepCountIs } from 'ai';
import { z } from 'zod';
import { readFile } from 'fs/promises';
import { glob } from 'glob';

const codeAnalyzer = new ToolLoopAgent({
  model: 'anthropic/claude-sonnet-4.5',
  instructions: `你是一个代码分析专家。分析代码时请：
1. 首先了解项目结构
2. 阅读关键文件
3. 识别潜在问题
4. 提供具体改进建议`,

  tools: {
    listFiles: tool({
      description: '列出匹配模式的文件',
      inputSchema: z.object({
        pattern: z.string().describe('Glob 模式，如 "src/**/*.ts"'),
      }),
      execute: async ({ pattern }) => {
        const files = await glob(pattern);
        return { files: files.slice(0, 50) }; // 限制数量
      },
    }),

    readFile: tool({
      description: '读取文件内容',
      inputSchema: z.object({
        path: z.string().describe('文件路径'),
      }),
      execute: async ({ path }) => {
        const content = await readFile(path, 'utf-8');
        return { path, content };
      },
      toModelOutput: ({ output }) => ({
        path: output.path,
        // 限制发送给模型的内容长度
        content: output.content.length > 5000
          ? output.content.substring(0, 5000) + '\n... (truncated)'
          : output.content,
      }),
    }),

    searchCode: tool({
      description: '在代码中搜索关键词',
      inputSchema: z.object({
        keyword: z.string(),
        filePattern: z.string().default('**/*.ts'),
      }),
      execute: async ({ keyword, filePattern }) => {
        // 实现搜索逻辑
        return { matches: [] };
      },
    }),
  },

  stopWhen: stepCountIs(15),
});

// 使用 Agent
const result = await codeAnalyzer.generate({
  prompt: '分析 src 目录下的 TypeScript 代码，找出潜在的性能问题和改进建议',
});

console.log(result.text);

import { generateText, stepCountIs } from 'ai';

interface ContextStrategy {
  systemPrompt: string;      // 始终保留
  summary: string;           // 历史摘要（每 3-5 轮更新）
  recentMessages: Message[]; // 最近 5-7 轮完整对话
  entities: Entity[];        // 关键实体（跨会话保持）
}

// 实现上下文压缩的 prepareStep
const { text } = await generateText({
  model: 'openai/gpt-4o',
  stopWhen: stepCountIs(20),
  tools: { /* ... */ },
  prepareStep: async ({ messages, stepCount }) => {
    // 每 5 步检查是否需要压缩
    if (stepCount > 0 && stepCount % 5 === 0) {
      const compressedMessages = await compressContext(messages);
      return { messages: compressedMessages };
    }
    return {};
  },
  prompt: '执行复杂任务...',
});

async function compressContext(messages: Message[]): Promise<Message[]> {
  const KEEP_RECENT = 6; // 保留最近 6 条

  if (messages.length <= KEEP_RECENT + 1) {
    return messages; // 无需压缩
  }

  const systemMessage = messages[0];
  const oldMessages = messages.slice(1, -KEEP_RECENT);
  const recentMessages = messages.slice(-KEEP_RECENT);

  // 使用小模型生成摘要
  const { text: summary } = await generateText({
    model: 'openai/gpt-4o-mini',
    prompt: `请简洁总结以下对话的关键信息：\n${JSON.stringify(oldMessages)}`,
  });

  return [
    systemMessage,
    { role: 'system', content: `[历史摘要]：${summary}` },
    ...recentMessages,
  ];
}

import { generateText, tool, stepCountIs } from 'ai';
import { MemoryClient } from 'mem0ai';
import { z } from 'zod';

const memory = new MemoryClient({ apiKey: process.env.MEM0_API_KEY });

const memoryTools = {
  saveMemory: tool({
    description: '保存重要信息到长期记忆',
    inputSchema: z.object({
      content: z.string().describe('要记住的信息'),
      tags: z.array(z.string()).optional(),
    }),
    execute: async ({ content, tags }) => {
      await memory.add(content, {
        user_id: 'user_123',
        metadata: { tags },
      });
      return { success: true };
    },
  }),

  recallMemory: tool({
    description: '从长期记忆中检索相关信息',
    inputSchema: z.object({
      query: z.string().describe('检索查询'),
    }),
    execute: async ({ query }) => {
      const memories = await memory.search(query, {
        user_id: 'user_123',
        limit: 5,
      });
      return { memories };
    },
  }),
};

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  stopWhen: stepCountIs(10),
  tools: {
    ...memoryTools,
    // 其他业务工具...
  },
  system: `你是一个有记忆能力的助手。
在对话开始时，先用 recallMemory 检索相关历史。
当用户提供重要信息时，用 saveMemory 保存。`,
  prompt: userMessage,
});

import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

// 定义子代理工具
const subagentTools = {
  researcher: tool({
    description: '研究专家 - 搜索和分析信息',
    inputSchema: z.object({
      task: z.string().describe('研究任务'),
      sources: z.array(z.string()).optional(),
    }),
    execute: async ({ task, sources }) => {
      // 启动研究子代理
      const { text } = await generateText({
        model: 'openai/gpt-4o-mini', // 使用较小模型
        stopWhen: stepCountIs(5),
        tools: {
          webSearch: webSearchTool,
          readDocument: readDocumentTool,
        },
        system: '你是一个研究专家，专注于查找和验证信息。',
        prompt: task,
      });
      return { findings: text };
    },
  }),

  coder: tool({
    description: '编程专家 - 编写和分析代码',
    inputSchema: z.object({
      task: z.string().describe('编程任务'),
      language: z.string().default('typescript'),
    }),
    execute: async ({ task, language }) => {
      const { text } = await generateText({
        model: 'anthropic/claude-sonnet-4.5',
        stopWhen: stepCountIs(8),
        tools: {
          readFile: readFileTool,
          writeFile: writeFileTool,
          runTests: runTestsTool,
        },
        system: `你是一个 ${language} 专家，专注于编写高质量代码。`,
        prompt: task,
      });
      return { result: text };
    },
  }),

  reviewer: tool({
    description: '审查专家 - 代码和文档审查',
    inputSchema: z.object({
      content: z.string().describe('待审查内容'),
      type: z.enum(['code', 'document']),
    }),
    execute: async ({ content, type }) => {
      const { text } = await generateText({
        model: 'openai/gpt-4o-mini',
        system: `你是一个${type === 'code' ? '代码' : '文档'}审查专家。
提供具体、可操作的反馈。`,
        prompt: `请审查以下内容：\n\n${content}`,
      });
      return { review: text };
    },
  }),
};

// 主 Agent 协调子代理
const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  stopWhen: stepCountIs(15),
  tools: subagentTools,
  system: `你是一个项目经理，协调研究员、程序员和审查员完成任务。
根据任务性质选择合适的专家，并整合他们的工作成果。`,
  prompt: '帮我研究 React Server Components 的最佳实践，然后写一个示例组件',
});