DeepSeek Harness: Разработка первого инструмента: defineTool

Инструменты — это функции, которые Агент использует для выполнения задач. После того как модель увидит определение инструмента, она решает, вызывать ли его.

В этой главе мы с помощью defineTool напишем наш первый инструмент, greet, и заставим модель действительно вызвать его.


Что такое инструмент?

Инструмент — это чётко описанная функция, которая включает имя, описание, параметры и формат вывода.

При генерации ответа модель может выполнять вызовы на основе этой информации.

В dsh инструменты регистрируются в реестре инструментов через ctx.tools.register.


Полная структура defineTool

defineTool — это DSL для определения инструментов. Он принимает объект, описывающий всю информацию об инструменте.

FieldsФункцияОписание
nameНазвание инструментаМодель использует его для инициирования вызовов.
descriptionОписание инструментаСообщает модели, что делает этот инструмент.
parametersсхема входных параметровТипизированное определение: defineTool выводит и валидирует args из него.
output.schemaСхема возвращаемого значенияОбъявляет канонический тип значения, возвращаемого execute.
output.renderФорматирование результатаПреобразует канонические значения в содержимое, ориентированное на модель.
executeРеализация инструментаФактически выполняет логику и возвращает канонические значения.

Создайте инструмент приветствия.

Замените scratch-plugin/src/my-plugin.ts следующим содержимым.

Пример

// Путь к файлу: scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
// Требуется сервис tools: предварительное условие для регистрации инструментов.
export const inject = ['tools']

export function apply(ctx: Context) {
  // Зарегистрировать инструмент с именем greet
  ctx.tools.register(defineTool({
    // Имя инструмента: модель будет вызывать инструмент по этому имени
    name: 'greet',
    // Описание инструмента: подскажите модели, когда его использовать
    description: 'Поприветствовать кого-либо по имени.',
    // Схема входных параметров: defineTool выведет и проверит аргументы
    parameters: {
      name: { type: 'string', required: true, description: 'Имя для приветствия' },
    },
    // Определение вывода
    output: {
      // Нормализовать тип значения: возвращаемое значение execute
      schema: { type: 'string' },
      // render: преобразовать канонические значения в содержимое, ориентированное на модель
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    // Реализация инструмента: фактическое выполнение логики
    async execute(args) {
      // Возвращает каноническое значение; здесь это строка
      return `Hello, ${args.name}!`
    },
  }))
}

inject заставляет Cordis ждать, пока реестр инструментов будет готов.

defineTool выводит и проверяет args на основе parameters.

execute возвращает каноническое значение, объявленное в output.schema.

output.render затем преобразует каноническое значение в контент, предназначенный для модели.


Запуск и вызов

Если команда разработки не запущена, перезапустите её:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

Откройте http://127.0.0.1:3080, введите:

Use the greet tool to greet EXAMPLE.

Модель может вызвать greet и получить результат работы инструмента Hello, EXAMPLE!.

工具注册到执行的完整流程


Ключевой момент: схема автоматически попадает в промпт.

Имя инструмента, описание, параметры и вывод автоматически собираются в промпт модели.

Модель «знает», что такой инструмент существует, и вызовет его в нужный момент.

Вам не нужно вручную писать сигнатуры функций для модели. Схема — это интерфейс, который видит модель.

Каноническое значение(каноническое значение) — это значение, возвращаемое execute и объявленное в output.schema.

Оно отделено от «контента, предназначенного для модели»: одно и то же каноническое значение можно преобразовать в разные форматы с помощью разных render-функций.

Совет: чтобы увидеть более сложные примеры инструментов (вложенные схемы, фоновая работа, хуки политик), обратитесь к официальному руководству по написанию инструментов.


Итог и самопроверка

defineTool описывает инструмент с помощью схемы, ctx.tools.register регистрирует его, а модель вызывает его напрямую, увидев схему.

1. Что возвращает execute у defineTool?

2. Каково назначение output.render?

3. Как модель узнаёт, что нужно вызвать greet?

Другие расширения