工具系统

什么是工具？

工具（Tools）允许 AI 模型调用外部功能来完成单纯文本生成无法完成的任务，如执行代码、查询数据库、生成特定格式的回复等。

关键特性：花卷智能体 API 采用服务端自动执行模式，一次请求即可完成工具调用和结果处理，无需客户端多轮交互。详见工具调用功能。

查看可用工具

使用 GET /api/v1/tools 端点查询当前可用的工具列表：

curl -X GET https://huajune.duliday.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "bash",
        "requiresSandbox": true,
        "requiredContext": ["sandboxId"]
      },
      {
        "name": "zhipin_reply_generator",
        "requiresSandbox": false,
        "requiredContext": ["configData", "replyPrompts"]
      }
    ]
  }
}

查看每个工具的 requiredContext 字段，了解调用该工具需要提供哪些上下文数据。

内置工具

zhipin_reply_generator

用途：生成 BOSS 直聘专业招聘回复，用于自动化候选人沟通。 所需上下文：

configData: 品牌配置数据（包含公司信息、岗位模板等）
replyPrompts: 回复提示词配置（不同场景的回复策略）

典型场景：

回答候选人关于薪资、福利、工作时间等问题
自动生成专业、友好的招聘沟通话术
根据品牌配置定制回复内容

示例：

基础配置

{
  "allowedTools": ["zhipin_reply_generator"],
  "context": {
    "preferredBrand": "蜀地源冒菜",
    "configData": {
      "city": "上海",
      "brands": {
        "蜀地源冒菜": {
          "templates": { /* 岗位模板 */ }
        }
      }
    },
    "replyPrompts": {
      "general_chat": "礼貌、专业地回复候选人"
    }
  }
}

查看完整示例

在工具调用功能文档中查看详细的配置示例和代码

bash

用途：执行 Bash 命令，适用于文件操作、系统命令、代码执行等场景。 所需上下文：

sandboxId: E2B 沙盒环境 ID（必需）

重要：bash 工具需要在 E2B 沙盒环境中运行，确保安全隔离。使用前需要：

创建 E2B 沙盒客户端
在 context.sandboxId 中提供沙盒 ID

如果没有沙盒环境，工具将无法工作。

示例：

bash 工具配置

{
  "allowedTools": ["bash"],
  "context": {
    "sandboxId": "your_e2b_sandbox_id"
  }
}

推荐：对于招聘业务场景，建议使用 zhipin_reply_generator 等业务工具，而非 bash 工具。

工具配置要素

启用工具

通过 allowedTools 数组指定要启用的工具：

启用单个工具

{
  "allowedTools": ["zhipin_reply_generator"]
}

启用多个工具

{
  "allowedTools": ["bash", "zhipin_reply_generator"]
}

如果不指定 allowedTools 或传入空数组，则不启用任何工具（纯文本对话模式）。

工具上下文

某些工具需要额外的上下文信息才能正常工作。通过 context 字段提供：

全局上下文
工具级上下文

使用 context 提供所有工具共享的上下文：

全局配置

{
  "context": {
    "configData": { /* 品牌配置 */ },
    "replyPrompts": { /* 回复策略 */ },
    "preferredBrand": "蜀地源冒菜"
  }
}

使用 toolContext 为特定工具提供上下文，会覆盖全局 context：

工具级配置

{
  "context": {
    "replyPrompts": { "default": "默认策略" }
  },
  "toolContext": {
    "zhipin_reply_generator": {
      "replyPrompts": { "custom": "自定义策略" }  // 优先使用
    }
  }
}

详细的上下文配置请参考上下文管理文档。

上下文策略

使用 contextStrategy 参数控制缺失必需上下文时的行为：

策略	行为	适用场景
`error`（默认）	返回 400 错误，列出缺失字段	确保工具配置正确
`skip`	跳过无法实例化的工具，继续执行	可选工具，部分失败不影响主流程
`report`	仅返回验证报告，不执行请求	预检工具配置

策略使用示例

skip 策略示例

{
  "allowedTools": ["bash", "zhipin_reply_generator"],
  "contextStrategy": "skip"  // 跳过无法初始化的工具
}

report 策略示例

{
  "allowedTools": ["zhipin_reply_generator"],
  "contextStrategy": "report"  // 仅验证，不执行
}

验证模式

使用 validateOnly: true 进行”干跑”，检查工具配置是否正确，而不实际执行对话：

验证配置

{
  "model": "anthropic/claude-3-7-sonnet-20250219",
  "messages": [...],
  "allowedTools": ["zhipin_reply_generator"],
  "context": { ... },
  "validateOnly": true  // 仅验证，不执行
}

验证模式等价于 contextStrategy: "report"，用于调试工具配置问题。

工具对比

zhipin_reply_generator - 招聘回复生成

最佳实践：

✅ 自动回复候选人咨询
✅ 生成专业招聘话术
✅ 根据品牌定制回复风格
✅ 处理薪资、福利、工作时间等常见问题

限制：

需要完整的 configData 和 replyPrompts 配置
仅适用于 BOSS 直聘招聘场景

推荐使用场景：蓝领招聘自动化、候选人沟通

bash - 命令执行

最佳实践：

✅ 执行系统命令
✅ 文件操作
✅ 代码执行和测试

限制：

❌ 需要 E2B 沙盒环境（额外配置）
❌ 不适合业务逻辑处理
❌ 安全风险需要隔离环境

推荐使用场景：开发测试、系统管理（需要沙盒）

执行模式

花卷智能体 API 采用服务端自动执行模式：

用户 → API (一次请求)
    ↓
1. AI 决定需要调用工具
    ↓
2. 服务端自动执行工具
    ↓
3. AI 理解工具结果
    ↓
4. 生成最终回复
    ↓
API → 用户 (完整的对话历史)

优点：

✅ 单次请求完成
✅ 无需客户端处理工具执行
✅ 自动重试和错误处理
✅ 完整的执行历史

查看完整工作流程

了解服务端自动执行的详细流程和响应结构

下一步

工具调用实践

查看完整的工具调用示例和代码

上下文管理

深入了解上下文配置和验证

消息格式

了解工具调用的消息结构

API 端点详解

查看完整的 API 参数文档

快速开始

核心概念

功能指南

最佳实践

什么是工具？

查看可用工具

内置工具

zhipin_reply_generator

查看完整示例

bash

工具配置要素

启用工具

工具上下文

上下文策略

验证模式

工具对比

执行模式

查看完整工作流程

下一步

工具调用实践

上下文管理

消息格式

API 端点详解

​什么是工具？

​查看可用工具

​内置工具

​zhipin_reply_generator

查看完整示例

​bash

​工具配置要素

​启用工具

​工具上下文

​上下文策略

​验证模式

​工具对比

​执行模式

查看完整工作流程

​下一步

工具调用实践

上下文管理

消息格式

API 端点详解

什么是工具？

查看可用工具

内置工具

zhipin_reply_generator

bash

工具配置要素

启用工具

工具上下文

上下文策略

验证模式

工具对比

执行模式

下一步