Agent基本概念

// src/agent/tools.ts
import type { ToolDefinition } from './types'
 
export const tools: ToolDefinition[] = [
  {
    name: 'get_weather',
    description: '查询指定城市的当前天气信息，包括温度、空气质量',
    parameters: {
      type: 'object',
      properties: {
        city: {
          type: 'string',
          description: '城市名称，例如：北京、上海',
        },
      },
      required: ['city'],
    },
  },
  {
    name: 'send_reminder',
    description: '给用户发送一条提醒消息',
    parameters: {
      type: 'object',
      properties: {
        message: {
          type: 'string',
          description: '提醒内容',
        },
      },
      required: ['message'],
    },
  },
]

// src/agent/loop.ts
import type { Message, ToolCall, ToolResult } from './types'
import { callLLM } from './llm'
import { executeTool } from './executor'
 
const MAX_ITERATIONS = 10
 
export async function runAgent(
  userInput: string,
  systemPrompt: string,
): Promise<string> {
  // 初始化对话历史
  const messages: Message[] = [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: userInput },
  ]
 
  for (let i = 0; i < MAX_ITERATIONS; i++) {
    // 把对话历史发给 LLM，拿到回复
    const response = await callLLM(messages)
 
    // 如果 LLM 没有调用任何工具，说明它已经有了最终回复
    if (response.toolCalls.length === 0) {
      return response.text
    }
 
    // 把 LLM 的工具调用请求追加到对话历史
    messages.push({
      role: 'assistant',
      content: response.text,
      toolCalls: response.toolCalls,
    })
 
    // 逐个执行工具，把结果追加到对话历史
    for (const toolCall of response.toolCalls) {
      const result = await executeTool(toolCall)
      messages.push({
        role: 'tool',
        toolCallId: toolCall.id,
        content: JSON.stringify(result),
      })
    }
  }
 
  return 'Agent 已达到最大执行轮次，任务未能完成。'
}

// src/agent/executor.ts
import type { ToolCall, ToolResult } from './types'
 
export async function executeTool(toolCall: ToolCall): Promise<ToolResult> {
  const { name, arguments: args } = toolCall
 
  try {
    let result: unknown
 
    switch (name) {
      case 'get_weather':
        result = await fetchWeather(args.city)
        break
      case 'send_reminder':
        result = await sendNotification(args.message)
        break
      default:
        result = { error: `未知工具：${name}` }
    }
 
    return { toolCallId: toolCall.id, result }
  } catch (error) {
    // 工具执行失败时，把错误信息也返回给 LLM
    // LLM 可以据此决定重试还是换一种方式
    return {
      toolCallId: toolCall.id,
      result: { error: `工具执行失败：${error instanceof Error ? error.message : '未知错误'}` },
    }
  }
}

// src/routes/agent.ts
import { Hono } from 'hono'
import { runAgent } from '../agent/loop'
import type { AppEnv } from '../types'
 
const agentApp = new Hono<AppEnv>()
 
agentApp.post('/chat', async (c) => {
  const { message } = await c.req.json<{ message: string }>()
 
  if (!message) {
    return c.json({ error: 'message 不能为空' }, 400)
  }
 
  const systemPrompt = `你是一个智能助手，可以查询天气、发送提醒。
根据用户的需求，合理使用工具来完成任务。
如果用户的请求不需要工具，直接回复即可。`
 
  const reply = await runAgent(message, systemPrompt)
 
  return c.json({ reply })
})
 
export default agentApp

// src/index.ts
import { Hono } from 'hono'
import agentApp from './routes/agent'
 
const app = new Hono()
app.route('/api/agent', agentApp)
 
export default app

// src/agent/prompts.ts
 
// 反面：太模糊，Agent 容易乱调用工具
const badPrompt = '你是一个助手，帮用户做事。'
 
// 正面：明确了能力边界、决策规则、输出要求
const goodPrompt = `你是一个任务执行助手。
你可以使用以下工具：
- get_weather：查询天气，参数为城市名
- send_reminder：发送提醒消息，参数为提醒内容
 
决策规则：
1. 先理解用户意图，判断是否需要调用工具
2. 如果需要多个工具，按依赖顺序逐个调用
3. 工具返回错误时，尝试换一种方式；重试一次仍失败则告知用户
4. 所有任务完成后，用一句话总结结果
 
不要编造工具返回的数据，所有事实必须来自工具结果。`

// src/agent/actions.ts
import type { ToolCall, ToolResult } from './types'
 
type ActionHandler = (args: Record<string, unknown>) => Promise<unknown>
 
// 工具注册表：把所有 action 集中在一个地方管理
const actionRegistry = new Map<string, ActionHandler>()
 
actionRegistry.set('get_weather', async (args) => {
  const res = await fetch(`https://api.weather.com/v1/${args.city}`)
  return res.json()
})
 
// 统一的 action 执行入口
export async function executeAction(toolCall: ToolCall): Promise<ToolResult> {
  const handler = actionRegistry.get(toolCall.name)
  if (!handler) {
    return { toolCallId: toolCall.id, result: { error: `未知工具：${toolCall.name}` } }
  }
  const result = await handler(toolCall.arguments)
  return { toolCallId: toolCall.id, result }
}

// src/agent/memory.ts
import type { AppEnv } from '../types'
 
// 保存用户偏好到 KV
export async function saveUserPreference(
  env: AppEnv['Bindings'],
  userId: string,
  preference: Record<string, unknown>,
) {
  await env.AGENT_MEMORY.put(
    `user:${userId}:preference`,
    JSON.stringify(preference),
  )
}
 
// 从 KV 读取用户偏好
export async function loadUserPreference(
  env: AppEnv['Bindings'],
  userId: string,
): Promise<Record<string, unknown> | null> {
  const data = await env.AGENT_MEMORY.get(`user:${userId}:preference`)
  return data ? JSON.parse(data) : null
}