YepAPI/skills

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 個以上的工具