自定义工具

除了内置工具，场景还可以定义自定义工具来扩展 AI 的能力。

声明式自定义工具

声明式场景通过 JSON 配置自定义工具，支持以下执行器：

执行器类型

执行器	说明	示例
web_search	搜索互联网，使用模板生成搜索词	搜索引擎查询
sql_query	执行 SQL 查询	数据库查询
run_command	执行命令	运行脚本
api_call	调用外部 API	REST API 请求

配置示例

{
  "capabilities": {
    "customTools": [
      {
        "name": "search_flights",
        "description": "Search for flights",
        "descriptionZh": "搜索航班信息",
        "parameters": {
          "origin": {
            "type": "string",
            "description": "Departure city",
            "required": true
          },
          "destination": {
            "type": "string",
            "description": "Arrival city",
            "required": true
          },
          "date": {
            "type": "string",
            "description": "Travel date YYYY-MM-DD"
          }
        },
        "executor": "web_search",
        "template": "flights from {origin} to {destination} on {date}"
      },
      {
        "name": "query_database",
        "description": "Query the scenario database",
        "descriptionZh": "查询场景数据库",
        "parameters": {
          "table": {
            "type": "string",
            "description": "Table name",
            "required": true
          },
          "limit": {
            "type": "number",
            "description": "Max results",
            "default": 10
          }
        },
        "executor": "sql_query",
        "template": "SELECT * FROM {table} LIMIT {limit}"
      },
      {
        "name": "get_weather",
        "description": "Get weather information",
        "descriptionZh": "获取天气信息",
        "parameters": {
          "city": {
            "type": "string",
            "description": "City name",
            "required": true
          }
        },
        "executor": "api_call",
        "url": "https://api.weather.com/v1/current",
        "method": "GET",
        "headers": {
          "X-API-Key": "{{env:WEATHER_API_KEY}}"
        },
        "queryParams": {
          "q": "{city}"
        }
      }
    ]
  }
}

参数定义

每个参数支持以下字段：

字段	类型	必填	说明
type	string	是	参数类型：string / number / boolean / array / object
description	string	是	参数描述
required	boolean	否	是否必填
default	any	否	默认值
enum	array	否	枚举值列表

模板语法

在 template 中使用 {参数名} 引用参数值：

search flights from {origin} to {destination} on {date}

执行时参数会被替换为实际值：

search flights from Beijing to Shanghai on 2025-06-15

编程式自定义工具

编程式场景通过 TypeScript 定义工具，完全控制执行逻辑。

工具定义

import type { ScenarioToolDefinition } from '@aweeclaw/scenario-sdk'

const tool: ScenarioToolDefinition = {
  name: 'analyze_code',
  definition: {
    name: 'analyze_code',
    description: '分析代码质量',
    descriptionZh: '分析代码质量并给出建议',
    parameters: {
      type: 'object',
      properties: {
        code: {
          type: 'string',
          description: '要分析的代码',
        },
        language: {
          type: 'string',
          description: '编程语言',
          enum: ['typescript', 'javascript', 'python', 'java', 'go'],
        },
        check_types: {
          type: 'array',
          description: '检查类型',
          items: {
            type: 'string',
            enum: ['security', 'performance', 'style', 'logic'],
          },
        },
      },
      required: ['code'],
    },
  },
  executor: async (args, context) => {
    const { code, language, check_types } = args

    // 执行分析逻辑
    const issues = analyzeCode(code, language, check_types)

    return {
      success: true,
      data: {
        issues,
        summary: `发现 ${issues.length} 个问题`,
      },
    }
  },
}

工具执行器

执行器接收两个参数：

type ToolExecutor = (
  args: Record<string, unknown>,
  context: ToolExecutionContext,
) => Promise<ToolExecutionResult>

args

用户传入的参数，由 JSON Schema 定义。

context

运行时上下文，提供：

interface ToolExecutionContext {
  scenarioId: string
  workspacePath: string
  logger: ScenarioLogger
  publishData: (channel: string, data: unknown) => void
  getSharedData: (key: string) => unknown
  querySql: (query: string) => Promise<ScenarioSqlResult>
}

返回值

interface ToolExecutionResult {
  success: boolean
  data?: unknown
  error?: string
}

错误处理

executor: async (args, context) => {
  try {
    const result = await performOperation(args)
    return { success: true, data: result }
  } catch (error) {
    context.logger.error('工具执行失败', error)
    return {
      success: false,
      error: error instanceof Error ? error.message : '未知错误',
    }
  }
}

最佳实践

1. 参数校验：在 executor 内部对参数进行校验
2. 错误处理：始终捕获异常并返回有意义的错误信息
3. 日志记录：使用 context.logger 记录关键操作
4. 超时控制：长时间操作应设置超时
5. 幂等性：尽量保证工具操作幂等