DeepSeek Harness 最初のツールを開発する:defineTool
ツールとは、Agent が作業を実行するための関数であり、モデルはツール定義を見て呼び出しを決定します。
この章では、defineTool を使って最初のツール greet を作成し、モデルに実際に呼び出させます。
ツールとは
ツール(tool)は、名前、説明、パラメータ、出力形式を含む、明確に記述された関数です。
モデルは応答を生成する際に、この情報に基づいて呼び出しを実行できます。
dsh では、ツールは ctx.tools.register を通じてツールレジストリに登録されます。
defineTool の完全な構造
defineTool はツールを定義する DSL であり、ツールのすべての情報を記述するオブジェクトを受け取ります。
| フィールド | 役割 | 説明 |
|---|---|---|
| name | ツール名 | モデルがこれを使って呼び出しを実行する |
| description | ツールの説明 | モデルにこのツールが何をするかを伝える |
| parameters | 入力パラメータ schema | 型定義であり、defineTool はこれに基づいて args を推論・検証する |
| output.schema | 戻り値 schema | execute が返す canonical value の型を宣言する |
| output.render | 結果のフォーマット | canonical value をモデル向けのコンテンツに変換する |
| execute | ツールの実装 | 実際にロジックを実行し、canonical value を返す |
greet ツールを作成する
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: 'Greet someone by name.',
// 入力パラメータ schema:defineTool が args を推論・検証する
parameters: {
name: { type: 'string', required: true, description: 'The name to greet' },
},
// 出力定義
output: {
// canonical value の型:execute の戻り値
schema: { type: 'string' },
// render:canonical value をモデル向けのコンテンツに変換する
render: (_args, value) => [{ type: 'text', text: value }],
},
// ツールの実装:実際にロジックを実行する
async execute(args) {
// canonical value を返す。ここでは文字列
return `Hello, ${args.name}!`
},
}))
}
inject により、Cordis はツールレジストリの準備ができるまで待機します。
defineTool は parameters に基づいて args を推論・検証します。
execute は output.schema で宣言された canonical value を返します。
output.render が canonical value をモデル向けのコンテンツに変換します。

実行と呼び出し
開発コマンドが実行されていない場合は、再起動してください:
pnpm dsh web --patch ./scratch-plugin/cordis.yml
http://127.0.0.1:3080 を開き、次のように入力します:
Use the greet tool to greet サンプル.

モデルは greet を呼び出し、ツール結果として Hello, サンプル! を受け取ります。
重要ポイント:schema が自動的にプロンプトに流れ込む
ツールの name、description、parameters、output は自動的にモデルのプロンプトに組み込まれます。
モデルはそのようなツールが存在することを「認識」し、適切なタイミングで呼び出します。
モデルに関数シグネチャを手書きで渡す必要はありません。schema がモデルが見るインターフェースです。
canonical value(canonical value)は execute が返し、output.schema で宣言された値です。
これは「モデル向けのコンテンツ」と疎結合です。同じ canonical value は異なる render によって異なる形式に変換できます。
ヒント:より複雑なツールの書き方(ネストされた schema、バックグラウンド処理、ポリシーフック)については、公式のツール作成リファレンスを参照してください。
まとめと自己テスト
defineTool は schema でツールを記述し、ctx.tools.register で登録します。モデルは schema を見て直接呼び出します。
その他の拡張1. defineTool の execute は何を返しますか?
2. output.render の役割は何ですか?
3. モデルはどうやって greet を呼び出すことを知るのですか?