YepAPI/技能

AI 智能体

规则

• 将工具定义为带描述的具有类型注解的函数 —— 模型自行选择调用哪个工具
• 工具模式：{ name, description, parameters: zodSchema, execute: async (args) => result }
• 多步循环：发送消息 → 模型返回工具调用 → 执行工具 → 将结果反馈回去 → 重复直到完成
• maxSteps 限制以防止无限循环 —— 默认 5-10 步，具体取决于复杂度
• 使用 Zod 进行结构化输出：generateObject({ schema: z.object({...}) }) 保证输出形状
• 重试逻辑：用 try/catch 包裹工具执行，对临时失败重试 2-3 次，使用指数退避
• 智能体编排：将复杂任务分解为具有聚焦工具集的子智能体，由协调智能体进行委托
• 始终在将工具结果反馈给模型之前进行验证 —— 对不可信数据进行清理
• 使用 streamText 配合 onToolCall 获取智能体推理的实时可见性

模式

// 工具定义
const tools = {
  searchDatabase: tool({
    description: "搜索产品数据库",
    parameters: z.object({ query: z.string(), limit: z.number().default(10) }),
    execute: async ({ query, limit }) => db.products.search(query, limit),
  }),
};

// 智能体循环
const result = await generateText({
  model,
  tools,
  maxSteps: 10,
  messages,
});

应避免的问题

• 给予智能体不受限制的工具访问权限 —— 将工具范围限定到当前任务
• 缺少 maxSteps —— 智能体会无限循环
• 信任未经验证的工具输出 —— 在根据结果采取行动之前务必检查
• 使用单体智能体 —— 优先使用聚焦的子智能体，而不是一个拥有 20 多个工具的单个智能体