03. 自定义配置：打造专属代理

深入 createDeepAgent() 的九大配置项

引言

在上一篇文章中，我们用最简单的配置创建了第一个深度代理。但 createDeepAgent() 的能力远不止于此——它提供了九大配置项，让你能够精细控制代理的每一个方面。

typescript

const agent = createDeepAgent({
  name?: string,              // 代理名称
  model?: string | Model,     // 模型配置
  tools?: Tool[],             // 自定义工具
  systemPrompt?: string,      // 系统提示词
  middleware?: Middleware[],  // 中间件
  subagents?: SubAgent[],     // 子代理
  backend?: Backend,          // 文件系统后端
  interruptOn?: InterruptConfig, // 人机协作
  skills?: string[],          // 技能
  memory?: string[],          // 记忆文件
  responseFormat?: Schema,    // 结构化输出
});

本文将带你深入了解每一个配置项。

配置架构概览

┌─────────────────────────────────────────────────────────────────┐
│                     createDeepAgent()                           │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │    model    │  │    tools    │  │     systemPrompt        │ │
│  │  (大脑)     │  │   (双手)    │  │    (职业培训)           │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  middleware │  │  subagents  │  │       backend           │ │
│  │ (能力增强)  │  │  (助理团队) │  │     (档案系统)          │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ interruptOn │  │   skills    │  │        memory           │ │
│  │ (审批流程)  │  │ (专业技能)  │  │      (经验记忆)         │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

createDeepAgent() 九大配置项全景

1. model - 选择代理的"大脑"

模型提供商选择全景

默认模型

DeepAgents 默认使用 claude-sonnet-4-5-20250929（Anthropic 的 Claude Sonnet 模型）。

使用字符串标识符

最简单的方式是使用 provider:model 格式的字符串：

typescript

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "gpt-4.1",  // 使用 OpenAI GPT-4
});

const agent2 = createDeepAgent({
  model: "claude-sonnet-4-5-20250929",  // 使用 Anthropic Claude
});

const agent3 = createDeepAgent({
  model: "google-genai:gemini-2.5-flash-lite",  // 使用 Google Gemini
});

使用模型实例

如果需要更精细的控制，可以直接传入模型实例：

typescript

import { createDeepAgent } from "deepagents";
import { ChatOpenAI } from "@langchain/openai";
import { ChatAnthropic } from "@langchain/anthropic";

const agent = createDeepAgent({
  model: new ChatOpenAI({
    model: "gpt-4.1",
    apiKey: "your-api-key",
    temperature: 0,
    maxTokens: 4096,
  }),
});

const agent2 = createDeepAgent({
  model: new ChatAnthropic({
    model: "claude-sonnet-4-5-20250929",
    apiKey: "your-api-key",
    temperature: 0,
  }),
});

支持的模型提供商

提供商	安装包	字符串前缀
OpenAI	`@langchain/openai`	`openai:` 或直接使用模型名
Anthropic	`@langchain/anthropic`	`anthropic:` 或直接使用模型名
Google Gemini	`@langchain/google-genai`	`google-genai:`
Azure OpenAI	`@langchain/openai`	`azure_openai:`
AWS Bedrock	`@langchain/aws`	`bedrock:`

模型选择建议

场景	推荐模型	原因
复杂推理任务	Claude Sonnet / GPT-4	强大的推理能力
快速响应场景	GPT-4o-mini / Claude Haiku	低延迟
成本敏感场景	Gemini Flash	性价比高
企业合规需求	Azure OpenAI	数据驻留保障

2. tools - 赋予代理"双手"

内置工具与自定义工具

内置工具

DeepAgents 自带以下内置工具，无需额外配置：

工具	功能
`write_todos`	规划和跟踪任务
`ls`	列出目录内容
`read_file`	读取文件
`write_file`	写入文件
`edit_file`	编辑文件

添加自定义工具

typescript

import { tool } from "langchain";
import { createDeepAgent } from "deepagents";
import * as z from "zod";

const calculator = tool(
  ({ expression }) => {
    try {
      return String(eval(expression));
    } catch {
      return "计算错误";
    }
  },
  {
    name: "calculator",
    description: "执行数学计算",
    schema: z.object({
      expression: z.string().describe("数学表达式，如 2 + 2"),
    }),
  }
);

const translator = tool(
  async ({ text, targetLang }) => {
    // 实际场景中调用翻译 API
    return `[翻译成${targetLang}]: ${text}`;
  },
  {
    name: "translator",
    description: "将文本翻译成目标语言",
    schema: z.object({
      text: z.string().describe("要翻译的文本"),
      targetLang: z.string().describe("目标语言，如 English, Japanese"),
    }),
  }
);

const agent = createDeepAgent({
  tools: [calculator, translator],
  systemPrompt: "你是一个多功能助手，可以进行计算和翻译。"
});

工具设计最佳实践

清晰的描述：description 要准确描述工具用途，LLM 靠它决定何时调用
完整的参数说明：每个参数都要有 .describe()
错误处理：工具内部要处理异常，返回友好的错误信息
单一职责：一个工具只做一件事

3. systemPrompt - 定义代理的"职业"

系统提示词决定了代理的角色定位和行为准则。

基础用法

typescript

const agent = createDeepAgent({
  systemPrompt: "你是一名专业的数据分析师。你擅长处理和分析数据，生成可视化报告。"
});

结构化提示词模板

typescript

const systemPrompt = `
# 角色定义
你是一名资深的 TypeScript 代码审查专家。

# 核心职责
1. 审查代码质量和最佳实践
2. 发现潜在的 bug 和安全问题
3. 提供改进建议

# 审查标准
- 类型安全性
- 错误处理完整性
- 代码可读性
- 性能考量

# 输出格式
对每个问题，请按以下格式输出：
- 🔴 严重问题：[描述]
- 🟡 建议改进：[描述]
- 🟢 优点：[描述]

# 注意事项
- 保持客观专业
- 解释问题原因，而不只是指出问题
- 提供可操作的修复建议
`;

const codeReviewer = createDeepAgent({
  systemPrompt,
  tools: [readFileTool, searchCodeTool],
});

提示词设计技巧

技巧	说明	示例
角色设定	明确代理的身份	"你是一名资深前端工程师"
行为准则	定义工作方式	"在修改代码前，先理解现有架构"
输出格式	规范响应结构	"使用 Markdown 表格展示对比"
边界限制	明确不做什么	"不要修改配置文件"

系统提示词四大设计技巧

4. middleware - 扩展代理能力

中间件是 DeepAgents 的"能力增强包"，可以在代理执行的各个阶段介入。

内置中间件

DeepAgents 默认启用以下中间件：

中间件	功能
`TodoListMiddleware`	任务规划和跟踪
`FilesystemMiddleware`	文件系统操作
`SubAgentMiddleware`	子代理管理
`SummarizationMiddleware`	长对话压缩
`AnthropicPromptCachingMiddleware`	Anthropic 模型缓存优化
`PatchToolCallsMiddleware`	工具调用修复

添加自定义中间件

typescript

import { createMiddleware, createDeepAgent } from "deepagents";

let callCount = 0;

const loggingMiddleware = createMiddleware({
  name: "LoggingMiddleware",
  
  wrapToolCall: async (request, handler) => {
    callCount += 1;
    const toolName = request.toolCall.name;
    
    console.log(`[${new Date().toISOString()}] 工具调用 #${callCount}: ${toolName}`);
    console.log(`  参数: ${JSON.stringify(request.toolCall.args)}`);
    
    const startTime = Date.now();
    const result = await handler(request);
    const duration = Date.now() - startTime;
    
    console.log(`  耗时: ${duration}ms`);
    console.log(`  结果: ${JSON.stringify(result).slice(0, 100)}...`);
    
    return result;
  },
});

const agent = createDeepAgent({
  middleware: [loggingMiddleware],
});

中间件执行时机

用户输入
    ↓
┌─────────────────┐
│  beforeAgent()  │  ← 代理开始前
└─────────────────┘
    ↓
┌─────────────────┐
│   LLM 调用      │
└─────────────────┘
    ↓
┌─────────────────┐
│ wrapToolCall()  │  ← 每次工具调用前后
└─────────────────┘
    ↓
┌─────────────────┐
│  afterAgent()   │  ← 代理完成后
└─────────────────┘
    ↓
最终响应

中间件执行生命周期

5. subagents - 组建"助理团队"

子代理允许主代理将特定任务委托给专门的"助理"。

基础用法

typescript

import { createDeepAgent } from "deepagents";

const researchAgent = {
  name: "researcher",
  description: "专门负责信息搜索和资料整理",
  systemPrompt: "你是一名研究专家，擅长从互联网收集和整理信息。",
  tools: [internetSearchTool],
  model: "gpt-4o-mini",  // 可以使用更便宜的模型
};

const writerAgent = {
  name: "writer",
  description: "专门负责撰写和润色文章",
  systemPrompt: "你是一名专业作家，擅长将信息整理成流畅的文章。",
  tools: [],
  model: "claude-sonnet-4-5-20250929",  // 写作用更强的模型
};

const mainAgent = createDeepAgent({
  subagents: [researchAgent, writerAgent],
  systemPrompt: `你是一个项目经理。
    - 需要搜索信息时，委托给 researcher
    - 需要撰写文章时，委托给 writer
    - 你负责协调整体流程和最终审核`
});

子代理配置项

配置项	类型	说明
`name`	string	子代理名称（主代理通过此名称委托任务）
`description`	string	描述子代理的能力（帮助主代理决定何时委托）
`systemPrompt`	string	子代理的角色定义
`tools`	Tool[]	子代理可用的工具
`model`	string	子代理使用的模型（可选，默认继承主代理）
`middleware`	Middleware[]	子代理的中间件（可选）
`interruptOn`	object	子代理的人机协作配置（可选）
`skills`	string[]	子代理的技能（可选）

子代理 vs 工具

特性	工具	子代理
复杂度	单一功能	可以有自己的规划和工具
上下文	共享主代理上下文	独立的上下文空间
适用场景	API 调用、计算	复杂子任务
返回值	直接返回结果	返回摘要

主代理与子代理协作关系

6. backend - 配置"档案系统"

后端决定了代理的文件系统工具如何存储数据。

StateBackend（默认）

临时存储，数据存在 LangGraph 状态中：

typescript

import { createDeepAgent } from "deepagents";
import { StateBackend } from "deepagents/backends";

const agent = createDeepAgent({
  backend: (rt) => new StateBackend(rt),
});

特点：

✅ 无需额外配置
✅ 适合单次会话任务
❌ 数据不跨会话持久化

FilesystemBackend

本地磁盘读写：

typescript

import { FilesystemBackend } from "deepagents/backends";

const agent = createDeepAgent({
  backend: (rt) => new FilesystemBackend(rt, {
    workingDirectory: "/path/to/project",
  }),
});

特点：

✅ 直接操作本地文件
✅ 适合开发和调试
⚠️ 需要谨慎授权

StoreBackend

跨线程持久化存储：

typescript

import { StoreBackend } from "deepagents/backends";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  backend: (rt) => new StoreBackend(rt),
  store: store,
});

特点：

✅ 数据跨会话持久化
✅ 适合长期记忆
✅ 部署到 LangSmith 时自动配置

CompositeBackend

多后端路由——不同路径使用不同存储：

typescript

import { CompositeBackend, StateBackend, StoreBackend } from "deepagents/backends";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = createDeepAgent({
  backend: (rt) => new CompositeBackend(
    new StateBackend(rt),  // 默认后端
    {
      "/memories/": new StoreBackend(rt),   // 记忆路径 → 持久化
      "/workspace/": new FilesystemBackend(rt, { workingDirectory: "." }),
    }
  ),
  store: store,
});

路由规则：

写入 /memories/notes.md → 使用 StoreBackend（持久化）
写入 /workspace/code.ts → 使用 FilesystemBackend（本地）
写入 /temp/data.json → 使用 StateBackend（临时）

四种后端与 CompositeBackend 路由

7. interruptOn - 设置"审批流程"

某些敏感操作需要人类确认才能执行。

基础用法

typescript

import { createDeepAgent } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

const agent = createDeepAgent({
  tools: [deleteFileTool, sendEmailTool, readFileTool],
  interruptOn: {
    delete_file: true,  // 删除文件需要审批
    send_email: { allowedDecisions: ["approve", "reject"] },  // 发邮件需要审批，但不允许编辑
    read_file: false,   // 读文件不需要审批
  },
  checkpointer,  // 必须提供！
});

决策类型

决策	说明
`approve`	批准执行
`edit`	修改参数后批准
`reject`	拒绝执行

处理中断

typescript

const result = await agent.invoke({
  messages: [{ role: "user", content: "删除 temp.txt" }],
}, { configurable: { thread_id: "thread-1" } });

if (result.interrupted) {
  console.log("需要审批:", result.pendingToolCalls);
  
  // 用户批准后继续
  const continued = await agent.invoke(
    { decision: "approve" },
    { configurable: { thread_id: "thread-1" } }
  );
}

人机协作审批流程

8. skills - 加载"专业技能"

技能是可按需加载的专业能力模块。

技能文件格式（SKILL.md）

markdown

---
name: react-component-generator
description: 生成 React 组件的技能
compatibility:
  - React
  - TypeScript
allowed-tools:
  - write_file
  - read_file
---

# React 组件生成技能

## 使用方法

当用户要求创建 React 组件时，遵循以下步骤：

1. 确认组件类型（函数组件/类组件）
2. 确认是否需要 TypeScript
3. 生成组件代码

## 代码模板

### 函数组件模板

```tsx
interface ${ComponentName}Props {
  // props
}

export const ${ComponentName}: React.FC<${ComponentName}Props> = (props) => {
  return (
    <div>
      {/* content */}
    </div>
  );
};


### 加载技能

```typescript
import { createDeepAgent } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

const agent = createDeepAgent({
  skills: ["/skills/"],  // 技能目录路径
  checkpointer,
});

// 调用时传入技能文件
const result = await agent.invoke({
  messages: [{ role: "user", content: "创建一个 Button 组件" }],
  files: {
    "/skills/react-generator/SKILL.md": skillFileData,
  },
}, { configurable: { thread_id: "thread-1" } });

技能 vs 记忆

特性	技能 (Skills)	记忆 (Memory)
内容类型	公共知识、模板、指南	用户偏好、历史经验
来源	开发者预定义	代理在使用中学习
加载时机	按需加载（渐进式披露）	每次对话开始时加载
可修改性	通常只读	可读写

9. responseFormat - 结构化输出

让代理返回符合特定结构的数据。

typescript

import { createDeepAgent } from "deepagents";
import { z } from "zod";

const weatherReportSchema = z.object({
  location: z.string().describe("地点"),
  temperature: z.number().describe("温度（摄氏度）"),
  condition: z.string().describe("天气状况"),
  humidity: z.number().describe("湿度百分比"),
  forecast: z.string().describe("未来 24 小时预报"),
});

const agent = createDeepAgent({
  tools: [weatherTool],
  responseFormat: weatherReportSchema,
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "查询北京天气" }],
});

console.log(result.structuredResponse);
// {
//   location: "北京",
//   temperature: 25,
//   condition: "晴",
//   humidity: 45,
//   forecast: "明天多云，气温略降"
// }

完整配置示例

typescript

import { createDeepAgent } from "deepagents";
import { CompositeBackend, StateBackend, StoreBackend } from "deepagents/backends";
import { MemorySaver, InMemoryStore } from "@langchain/langgraph";

const checkpointer = new MemorySaver();
const store = new InMemoryStore();

const researchSubAgent = {
  name: "researcher",
  description: "负责信息搜索",
  systemPrompt: "你是研究专家",
  tools: [searchTool],
};

const agent = createDeepAgent({
  name: "ProjectManager",
  model: "claude-sonnet-4-5-20250929",
  tools: [calculatorTool, translatorTool],
  systemPrompt: `你是一个项目经理，负责协调研究和报告撰写工作。`,
  middleware: [loggingMiddleware],
  subagents: [researchSubAgent],
  backend: (rt) => new CompositeBackend(
    new StateBackend(rt),
    { "/memories/": new StoreBackend(rt) }
  ),
  interruptOn: {
    send_email: true,
  },
  skills: ["/skills/"],
  memory: ["/AGENTS.md"],
  store,
  checkpointer,
});

小结

九大配置项总览

本文详细介绍了 createDeepAgent() 的九大配置项：

配置项	用途	类比
model	选择 LLM	大脑
tools	添加能力	双手
systemPrompt	定义角色	职业培训
middleware	扩展功能	能力增强
subagents	任务委托	助理团队
backend	数据存储	档案系统
interruptOn	人机协作	审批流程
skills	专业知识	技能证书
memory	经验记忆	个人日记

掌握这些配置，你就能打造出适应各种场景的专属代理。

下一步

在后续文章中，我们将深入探索：

后端系统的详细配置
子代理的高级用法
人机协作的完整流程
技能系统的开发指南

实践任务

创建一个使用 GPT-4 的代理，对比它与默认 Claude 的表现
为代理添加一个自定义的"翻译"工具
配置 CompositeBackend，实现临时文件和持久记忆的分离
尝试设置 interruptOn，体验人机协作流程

03. 自定义配置：打造专属代理 ​

引言 ​

配置架构概览 ​

1. model - 选择代理的"大脑" ​

默认模型 ​

使用字符串标识符 ​

使用模型实例 ​

支持的模型提供商 ​

模型选择建议 ​

2. tools - 赋予代理"双手" ​

内置工具 ​

添加自定义工具 ​

工具设计最佳实践 ​

3. systemPrompt - 定义代理的"职业" ​

基础用法 ​

结构化提示词模板 ​

提示词设计技巧 ​

4. middleware - 扩展代理能力 ​

内置中间件 ​

添加自定义中间件 ​

中间件执行时机 ​

5. subagents - 组建"助理团队" ​

基础用法 ​

子代理配置项 ​

子代理 vs 工具 ​

6. backend - 配置"档案系统" ​

StateBackend（默认） ​

FilesystemBackend ​

StoreBackend ​

CompositeBackend ​

7. interruptOn - 设置"审批流程" ​

基础用法 ​

决策类型 ​

处理中断 ​

8. skills - 加载"专业技能" ​

技能文件格式（SKILL.md） ​

技能 vs 记忆 ​

9. responseFormat - 结构化输出 ​

完整配置示例 ​

小结 ​

下一步 ​

实践任务 ​

参考资源 ​

03. 自定义配置：打造专属代理

引言

配置架构概览

1. model - 选择代理的"大脑"

默认模型

使用字符串标识符

使用模型实例

支持的模型提供商

模型选择建议

2. tools - 赋予代理"双手"

内置工具

添加自定义工具

工具设计最佳实践

3. systemPrompt - 定义代理的"职业"

基础用法

结构化提示词模板

提示词设计技巧

4. middleware - 扩展代理能力

内置中间件

添加自定义中间件

中间件执行时机

5. subagents - 组建"助理团队"

基础用法

子代理配置项

子代理 vs 工具

6. backend - 配置"档案系统"

StateBackend（默认）

FilesystemBackend

StoreBackend

CompositeBackend

7. interruptOn - 设置"审批流程"

基础用法

决策类型

处理中断

8. skills - 加载"专业技能"

技能文件格式（SKILL.md）

技能 vs 记忆

9. responseFormat - 结构化输出

完整配置示例

小结

下一步

实践任务

参考资源