AI Agent 与工具调用

// lib/ai-tools.ts
import { tool } from 'ai'
import { z } from 'zod'
 
export const weatherTool = tool({
  description: '查询指定城市的天气信息',
  parameters: z.object({
    city: z.string().describe('城市名称，如"上海"、"北京"'),
  }),
  execute: async ({ city }) => {
    const response = await fetch(
      `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${city}`,
    )
    const data = await response.json()
    return {
      city,
      temperature: data.current.temp_c,
      condition: data.current.condition.text,
      humidity: data.current.humidity,
    }
  },
})

// app/api/chat/route.ts
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { weatherTool } from '@/lib/ai-tools'
 
export async function POST(request: Request) {
  const { messages } = await request.json()
 
  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    tools: {
      getWeather: weatherTool,
    },
    maxSteps: 5,  // 允许最多 5 轮工具调用
  })
 
  return result.toDataStreamResponse()
}

import { tool } from 'ai'
import { z } from 'zod'
 
// 搜索知识库
const searchKnowledge = tool({
  description: '在知识库中搜索相关文档，当用户问到公司内部信息时使用',
  parameters: z.object({
    query: z.string().describe('搜索关键词'),
  }),
  execute: async ({ query }) => {
    const chunks = await searchSimilarChunks(query, workspaceId)
    return chunks.map((c) => ({ content: c.content, source: c.documentName }))
  },
})
 
// 查询数据库
const queryDatabase = tool({
  description: '查询业务数据，如用户数、收入、Token 用量等统计信息',
  parameters: z.object({
    metric: z.enum(['user_count', 'revenue', 'token_usage', 'active_users']),
    timeRange: z.enum(['today', 'this_week', 'this_month', 'this_year']),
  }),
  execute: async ({ metric, timeRange }) => {
    const result = await getMetric(metric, timeRange)
    return { metric, timeRange, value: result.value, unit: result.unit }
  },
})
 
// 发送邮件
const sendEmail = tool({
  description: '发送邮件给团队成员',
  parameters: z.object({
    to: z.string().email().describe('收件人邮箱'),
    subject: z.string().describe('邮件主题'),
    body: z.string().describe('邮件正文'),
  }),
  execute: async ({ to, subject, body }) => {
    await resend.emails.send({ from: '[email protected]', to, subject, html: body })
    return { success: true, message: `邮件已发送给 ${to}` }
  },
})
 
// 在 API 中使用
const result = streamText({
  model: openai('gpt-4o'),
  messages,
  tools: { searchKnowledge, queryDatabase, sendEmail },
  maxSteps: 5,
})

// ❌ 差的描述 — AI 不知道什么时候用
tool({ description: '搜索', ... })
 
// ✅ 好的描述 — AI 明确知道使用场景
tool({ description: '在知识库中搜索公司内部文档和产品文档，当用户提问与公司产品、政策、流程相关的问题时使用', ... })

parameters: z.object({
  // ❌ AI 不知道格式
  date: z.string(),
 
  // ✅ AI 知道该传什么格式
  date: z.string().describe('日期，格式为 YYYY-MM-DD，如 2024-03-15'),
})

parameters: z.object({
  // ❌ AI 可能传入任意字符串
  priority: z.string(),
 
  // ✅ 限定取值范围
  priority: z.enum(['low', 'medium', 'high', 'urgent']).describe('任务优先级'),
})

const result = streamText({
  model: openai('gpt-4o'),
  messages,
  tools: { searchKnowledge, queryDatabase, createChart },
  maxSteps: 10,  // 允许最多 10 轮推理
})

// lib/agents/research-agent.ts
import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
 
export async function runResearchAgent(topic: string) {
  const { text, steps } = await generateText({
    model: openai('gpt-4o'),
    system: `你是一个研究助手。使用提供的工具收集信息，然后写一份简洁的研究报告。`,
    prompt: `研究主题：${topic}`,
    tools: {
      webSearch: tool({
        description: '搜索互联网获取最新信息',
        parameters: z.object({ query: z.string() }),
        execute: async ({ query }) => {
          // 调用搜索 API
          return await searchWeb(query)
        },
      }),
      readUrl: tool({
        description: '读取网页内容',
        parameters: z.object({ url: z.string().url() }),
        execute: async ({ url }) => {
          const response = await fetch(url)
          const html = await response.text()
          return extractMainContent(html)
        },
      }),
    },
    maxSteps: 10,
  })
 
  // steps 包含完整的推理过程
  console.log(`Agent 完成，共 ${steps.length} 步`)
  return text
}

// 服务端：定义工具但不自动执行
const deleteUser = tool({
  description: '删除用户账号（需要用户确认）',
  parameters: z.object({
    userId: z.string(),
    reason: z.string(),
  }),
  // 不提供 execute — 这是一个"确认型工具"
})
 
// 服务端 API
const result = streamText({
  model: openai('gpt-4o'),
  messages,
  tools: { deleteUser },
})

// 客户端：拦截工具调用，展示确认对话框
'use client'
 
import { useChat } from 'ai/react'
 
export function ChatWithConfirmation() {
  const { messages, ... } = useChat({
    api: '/api/chat',
    onToolCall: async ({ toolCall }) => {
      if (toolCall.toolName === 'deleteUser') {
        // 展示确认对话框
        const confirmed = await showConfirmDialog(
          `确认删除用户 ${toolCall.args.userId}？原因：${toolCall.args.reason}`,
        )
 
        if (confirmed) {
          // 用户确认 → 执行操作
          await deleteUserAction(toolCall.args.userId)
          return { success: true }
        } else {
          return { success: false, message: '用户取消了操作' }
        }
      }
    },
  })
}

// 消息渲染：检测工具调用并展示特殊 UI
{messages.map((msg) => (
  <div key={msg.id}>
    {msg.content && <Markdown content={msg.content} />}
 
    {/* 渲染工具调用结果 */}
    {msg.toolInvocations?.map((invocation) => {
      if (invocation.state === 'result') {
        switch (invocation.toolName) {
          case 'getWeather':
            return <WeatherCard key={invocation.toolCallId} data={invocation.result} />
          case 'queryDatabase':
            return <MetricCard key={invocation.toolCallId} data={invocation.result} />
          default:
            return <pre key={invocation.toolCallId}>{JSON.stringify(invocation.result, null, 2)}</pre>
        }
      }
      // 工具正在执行
      return <div key={invocation.toolCallId} className="animate-pulse">正在查询...</div>
    })}
  </div>
))}

function getToolsForUser(role: 'admin' | 'member' | 'viewer') {
  const baseTools = { searchKnowledge, getWeather }
 
  if (role === 'admin') {
    return { ...baseTools, queryDatabase, sendEmail, deleteUser }
  }
  if (role === 'member') {
    return { ...baseTools, queryDatabase }
  }
  return baseTools // viewer 只有基础工具
}
 
// API 中
const result = streamText({
  model: openai('gpt-4o'),
  messages,
  tools: getToolsForUser(session.user.role),
  maxSteps: 5,
})

const result = streamText({
  model: openai('gpt-4o'),
  messages,
  tools,
  maxSteps: 5,          // 限制最大步数
  toolChoice: 'auto',   // 'auto' | 'required' | 'none' | { type: 'tool', toolName: '...' }
})

execute: async ({ userId }) => {
  // 验证 userId 格式
  if (!isValidUUID(userId)) {
    return { error: '无效的用户 ID' }
  }
 
  // 验证权限
  const hasPermission = await checkPermission(currentUser, 'delete', userId)
  if (!hasPermission) {
    return { error: '没有权限执行此操作' }
  }
 
  // 执行操作
  await deleteUser(userId)
  return { success: true }
}