Skip to main content

​
什么是工具？

工具（Tools）允许 AI 模型调用外部功能来完成单纯文本生成无法完成的任务，如执行代码、查询数据库、生成特定格式的回复等。
关键特性：花卷智能体 API 采用服务端自动执行模式，一次请求即可完成工具调用和结果处理，无需客户端多轮交互。详见工具调用功能。

​
查看可用工具

使用 GET /api/v1/tools 端点查询当前可用的工具列表： 
curl -X GET https://huajune.duliday.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"
查看每个工具的 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 沙盒环境中运行，确保安全隔离。使用前需要：
  1. 创建 E2B 沙盒客户端
  2. 在 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": "蜀地源冒菜"
  }
}
详细的上下文配置请参考上下文管理文档。

​
上下文策略

使用 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"，用于调试工具配置问题。

​
工具对比

最佳实践：
  • ✅ 自动回复候选人咨询
  • ✅ 生成专业招聘话术
  • ✅ 根据品牌定制回复风格
  • ✅ 处理薪资、福利、工作时间等常见问题
限制：
  • 需要完整的 configData 和 replyPrompts 配置
  • 仅适用于 BOSS 直聘招聘场景
推荐使用场景：蓝领招聘自动化、候选人沟通
最佳实践：
  • ✅ 执行系统命令
  • ✅ 文件操作
  • ✅ 代码执行和测试
限制：
  • ❌ 需要 E2B 沙盒环境（额外配置）
  • ❌ 不适合业务逻辑处理
  • ❌ 安全风险需要隔离环境
推荐使用场景：开发测试、系统管理（需要沙盒）

​
执行模式

花卷智能体 API 采用服务端自动执行模式： 
用户 → API (一次请求)
    ↓
1. AI 决定需要调用工具
    ↓
2. 服务端自动执行工具
    ↓
3. AI 理解工具结果
    ↓
4. 生成最终回复
    ↓
API → 用户 (完整的对话历史)
优点：
  • ✅ 单次请求完成
  • ✅ 无需客户端处理工具执行
  • ✅ 自动重试和错误处理
  • ✅ 完整的执行历史

查看完整工作流程

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

​
下一步

工具调用实践

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

上下文管理

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

消息格式

了解工具调用的消息结构

API 端点详解

查看完整的 API 参数文档