DeepSeek Harness 最初のツールを開発する:defineTool

ツールとは、Agent が作業を実行するための関数であり、モデルはツール定義を見て呼び出しを決定します。

この章では、defineTool を使って最初のツール greet を作成し、モデルに実際に呼び出させます。


ツールとは

ツール(tool)は、名前、説明、パラメータ、出力形式を含む、明確に記述された関数です。

モデルは応答を生成する際に、この情報に基づいて呼び出しを実行できます。

dsh では、ツールは ctx.tools.register を通じてツールレジストリに登録されます。


defineTool の完全な構造

defineTool はツールを定義する DSL であり、ツールのすべての情報を記述するオブジェクトを受け取ります。

フィールド役割説明
nameツール名モデルがこれを使って呼び出しを実行する
descriptionツールの説明モデルにこのツールが何をするかを伝える
parameters入力パラメータ schema型定義であり、defineTool はこれに基づいて args を推論・検証する
output.schema戻り値 schemaexecute が返す canonical value の型を宣言する
output.render結果のフォーマットcanonical value をモデル向けのコンテンツに変換する
executeツールの実装実際にロジックを実行し、canonical value を返す

greet ツールを作成する

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: '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 を呼び出すことを知るのですか?

その他の拡張