接口: ServerTool<TInput, TOutput, TName>

定义于: activities/chat/tools/tool-definition.ts:12

服务器端工具的标记类型

继承自

Tool<TInput, TOutput, TName>

类型参数

TInput

TInput extends SchemaInput = SchemaInput

TOutput

TOutput extends SchemaInput = SchemaInput

TName

TName extends string = string

属性

__toolSide

__toolSide: "server";

定义于: activities/chat/tools/tool-definition.ts:17

描述

description: string;

定义于: types.ts:383

清晰地描述工具的作用。

这至关重要 - 模型使用此信息来决定何时调用该工具。具体说明工具的作用、需要的参数以及返回的内容。

示例

"Get the current weather in a given location. Returns temperature, conditions, and forecast."

继承自

Tool.description

execute()?

optional execute: (args) => any;

定义于: types.ts:463

可选函数，在模型调用此工具时执行。

如果提供，SDK 将自动使用模型的参数执行该函数，并将结果反馈给模型。这实现了自主工具使用循环。

可以返回任何值 - 如果需要，将自动字符串化。

参数

any

从模型工具调用解析出的参数（根据 inputSchema 验证）

Returns (返回)

any

要发送回模型的結果（如果提供了 outputSchema，则进行验证）

示例

execute: async (args) => {
  const weather = await fetchWeather(args.location);
  return weather; // Can return object or string
}

继承自

Tool.execute

inputSchema?

optional inputSchema: TInput;

定义于: types.ts:423

描述工具输入参数的模式。

可以是任何符合标准 JSON Schema 规范的模式（Zod、ArkType、Valibot 等）或纯 JSON Schema 对象。定义工具接受的参数的结构和类型。模型将生成与此模式匹配的参数。符合标准 JSON Schema 规范的模式将转换为 JSON Schema 以供 LLM 提供程序使用。

参见

示例

// Using Zod v4+ schema (natively supports Standard JSON Schema)
import { z } from 'zod';
z.object({
  location: z.string().describe("City name or coordinates"),
  unit: z.enum(["celsius", "fahrenheit"]).optional()
})

// Using ArkType (natively supports Standard JSON Schema)
import { type } from 'arktype';
type({
  location: 'string',
  unit: "'celsius' | 'fahrenheit'"
})

// Using plain JSON Schema
{
  type: 'object',
  properties: {
    location: { type: 'string', description: 'City name or coordinates' },
    unit: { type: 'string', enum: ['celsius', 'fahrenheit'] }
  },
  required: ['location']
}

继承自

Tool.inputSchema

metadata?

optional metadata: Record<string, any>;

定义于: types.ts:469

用于适配器或自定义扩展的附加元数据

继承自

Tool.metadata

name

name: TName;

定义于: types.ts:373

工具的唯一名称（模型用于调用它）。

应具有描述性并遵循命名约定（例如，snake_case 或 camelCase）。必须在工具数组中是唯一的。

示例

"get_weather", "search_database", "sendEmail"

继承自

Tool.name

needsApproval?

optional needsApproval: boolean;

定义于: types.ts:466

如果为 true，则工具执行需要在运行前获得用户批准。适用于服务器和客户端工具。

继承自

Tool.needsApproval

outputSchema?

optional outputSchema: TOutput;

定义于: types.ts:444

用于验证工具输出的可选模式。

可以是任何符合标准 JSON Schema 规范的模式或纯 JSON Schema 对象。如果提供符合标准 Schema 规范的模式，则工具结果在发送回模型之前将根据此模式进行验证。这可以捕获工具实现中的错误，并确保输出格式一致。

注意：这仅是客户端验证 - 不发送给 LLM 提供程序。注意：纯 JSON Schema 输出验证在运行时不执行。

示例

// Using Zod
z.object({
  temperature: z.number(),
  conditions: z.string(),
  forecast: z.array(z.string()).optional()
})

继承自

Tool.outputSchema