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 следующим содержимым.
Пример
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?