Agents 智能体

智能体（Agent）将模型与工具结合，在循环中自主推理和行动，直到完成任务。

智能体是 deepseek-kit 中最强大的抽象。它将模型、工具和多步循环组合在一起——模型负责推理和决策，工具负责与外部世界交互，循环负责持续执行直到得出最终答案。这种模式被称为 ReAct（Reasoning + Acting），是构建 AI 应用的核心范式。

创建智能体

使用 createAgent() 创建智能体。你只需要提供一个模型实例，智能体就可以工作了：

import { createAgent, createModel } from 'deepseek-kit'

const model = createModel({ model: 'deepseek-v4-flash' })

const agent = createAgent({ model })

const result = await agent.generate({
  prompt: '你好！',
})

console.log(result.text)

但智能体的真正威力在于工具。为智能体配备工具后，它就能自主决定何时调用工具、如何处理结果，并持续推理直到完成任务：

import { createAgent, createModel, tool } from 'deepseek-kit'
import { z } from 'zod'

const model = createModel({ model: 'deepseek-v4-flash' })

const weatherTool = tool({
  name: 'getWeather',
  description: '查询城市的天气信息',
  schema: z.object({
    city: z.string().describe('城市名称'),
  }),
  execute: async (input) => {
    return `${input.city} 今日天气晴，温度22摄氏度，湿度60%。`
  },
})

const agent = createAgent({
  model,
  tools: [weatherTool],
})

const result = await agent.generate({
  prompt: '重庆今天天气怎么样？',
})

console.log(result.text)

智能体如何工作

智能体遵循 ReAct 循环运行：

  1. 推理 — 模型分析用户输入和当前上下文，决定下一步行动
  2. 行动 — 如果需要调用工具，模型生成工具调用；否则直接生成文本回复
  3. 观察 — 工具执行结果被添加到对话中，作为下一步的输入
  4. 循环 — 重复以上步骤，直到模型生成最终回复或达到最大步数
Rendering Chart

最大步数默认为 50，你可以通过 maxSteps 在创建智能体时进行控制：

const agent = createAgent({
  model,
  maxSteps: 10,
})

const result = await agent.generate({
  prompt: '复杂查询',
})

流式输出

使用 stream() 方法可以实时获取智能体的输出，包括文本增量和工具调用事件：

const stream = agent.stream({
  prompt: '重庆今天天气怎么样？',
})

for await (const event of stream) {
  switch (event.type) {
    case 'text-delta':
      process.stdout.write(event.textDelta)
      break
    case 'tool-call':
      console.log(`\n调用工具: ${event.toolCalls.map(t => t.function.name).join(', ')}`)
      break
    case 'finish':
      console.log('\n完成！')
      break
  }
}

系统提示词

通过 system 参数为智能体设定角色和行为准则，引导它以特定方式回应：

const agent = createAgent({
  model,
  tools: [searchTool],
  system: '你是一个研究助手。始终引用来源并提供详细的解释。',
})

Few-Shot 少样本

通过 fewShot 参数提供示例对话，引导模型的回复风格和格式。Few-shot 示例会被插入在系统提示词之后、实际对话之前，帮助模型从示范中学习期望的模式：

const agent = createAgent({
  model,
  system: '你是一个翻译助手。',
  fewShot: [
    { role: 'user', content: 'Hello' },
    { role: 'assistant', content: '你好' },
    { role: 'user', content: 'Goodbye' },
    { role: 'assistant', content: '再见' },
  ],
})

const result = await agent.generate({
  prompt: 'Thank you',
})

console.log(result.text) // 谢谢

最终对话中的消息顺序为：system → fewShot → messages → prompt。

结构化输出

智能体可以返回符合 Zod Schema 的结构化数据，而不仅仅是自由文本。这在需要将智能体的输出集成到其他系统时非常有用：

const agent = createAgent({
  model,
  tools: [weatherTool],
  output: {
    schema: z.object({
      city: z.string(),
      weather: z.string(),
      temperature: z.number(),
      recommendation: z.string(),
    }),
  },
})

const result = await agent.generate({
  prompt: '北京天气怎么样？需要带伞吗？',
})

console.log(result.output)
// { city: '北京', weather: '晴', temperature: 22, recommendation: '不需要带伞。' }

上下文压缩

当智能体运行多步并调用工具时，对话历史会持续增长，最终可能超出模型的上下文窗口。compact 选项会在上下文使用量接近限制时，自动摘要较旧的对话轮次，同时保留系统提示词、少样本示例和最近的对话轮次。

基本用法

使用默认设置启用压缩（阈值：上下文窗口的 85%，保留最近 3 轮，模型：deepseek-v4-flash）：

const agent = createAgent({
  model,
  tools: [searchTool, readFileTool],
  compact: true,
})

自定义配置

传入对象来自定义压缩行为：

const agent = createAgent({
  model,
  tools: [searchTool, readFileTool],
  compact: {
    threshold: 0.9,
    keepRecentRounds: 5,
    model: 'deepseek-v4-flash',
    contextWindowSize: 1_000_000,
  },
})
  • threshold（number，默认 0.85）— 触发压缩的上下文使用比例。当 prompt_tokens >= contextWindowSize * threshold 时，历史对话会被摘要。
  • keepRecentRounds（number，默认 3）— 保留不压缩的最近对话轮数。
  • model（Model，默认 'deepseek-v4-flash'）— 用于生成摘要的 LLM。
  • contextWindowSize（number，默认 1,000,000）— 模型的上下文窗口大小（token 数）。

工作原理

  1. 每一步开始时，智能体检查上一步的 prompt_tokens 是否超过阈值
  2. 如果触发，较旧的对话轮次会通过 LLM 被摘要为一条消息
  3. 系统提示词、少样本示例和最近的对话轮次始终保留
  4. 摘要以 user 消息的形式插入，name 为 'compact-summary'

生命周期 Hook

智能体支持三个生命周期 Hook，让你可以在每个步骤前后插入自定义逻辑——用于日志记录、动态修改消息、调整配置和处理错误：

const agent = createAgent({
  model,
  tools: [weatherTool],
  hooks: {
    beforeStep: (context, hookCtx) => {
      console.log(`步骤 ${context.step} 开始，${context.messages.length} 条消息`)
    },
    afterStep: (step, hookCtx) => {
      console.log(`步骤 ${step.step} 完成: ${step.type}`)
      if (step.toolCalls) {
        console.log(`  调用工具: ${step.toolCalls.map(t => t.function.name).join(', ')}`)
      }
    },
    onError: (error, hookCtx) => {
      console.error(`步骤出错: ${error.type} - ${error.message}`)
    },
  },
})

你还可以通过 hookCtx.stop() 提前终止循环：

beforeStep: (context, hookCtx) => {
  if (context.step > 5) {
    hookCtx.stop()
  }
}

也可以在 beforeStep 中通过返回配置来修改当前步骤的配置：

beforeStep: (context, hookCtx) => {
  if (context.step > 5) {
    return {
      config: {
        model: 'deepseek-v4-pro',
      },
    }
  }
}

这将导致智能体在第 6 步后切换到 Pro 模型。

API 参考

参数

modelrequiredDeepSeekModel
模型实例，作为智能体的推理引擎。
toolsTool[]
可用工具列表。智能体会根据用户输入自主决定调用哪些工具。
systemstring
系统提示词，用于设定智能体的角色和行为准则。
fewShotChatMessage[]
Few-shot 示例消息，插入在系统提示词之后、对话之前。用于通过示范引导模型的回复风格和格式。
output{ schema: ZodSchema }
结构化输出 Schema。指定后，智能体将返回符合 Schema 的结构化数据。
compactboolean | AgentCompactConfig
启用上下文压缩。设为 true 时，当上下文使用量接近限制时，较旧的对话轮次会自动被摘要。传入对象 { threshold?: number, keepRecentRounds?: number, model?: Model, contextWindowSize?: number } 可自定义设置。
hooksGenerateTextHooks
生命周期 Hook，包含 beforeStep、afterStep 和 onError。
maxStepsnumber
50
最大执行步数。达到此限制后循环终止。
signalAbortSignal
中止信号，用于取消正在执行的智能体请求。

方法

generate(params)Promise<GenerateTextResult>
执行智能体并返回完整结果。params 包含 prompt 或 messages。
stream(params)AsyncGenerator<StreamEvent>
流式执行智能体，按事件返回。事件类型包括 text-delta、reasoning-delta、tool-call、step 和 finish。

StreamEvent 类型

text-deltaTextDeltaStreamEvent
文本增量事件，包含 textDelta 字段。
reasoning-deltaReasoningDeltaStreamEvent
推理增量事件，包含 reasoningDelta 字段（思考模式启用时可用）。
tool-callToolCallStreamEvent
工具调用事件，包含 step 和 toolCalls 字段。
stepStepStreamEvent
步骤开始事件，包含 step 字段。
finishFinishStreamEvent
完成事件，包含 text 和 usage 字段。
Messages 消息
消息（Message）是智能体与模型交互的基本单元——包含角色、内容和元数据，构成完整的对话上下文。
概述
工具（Tool）让模型能够与外部世界交互——查询数据库、调用 API、执行计算，从而突破训练数据的局限。