ツールの追加

ツールは、JSON-Schema パラメーターを持つ型付き TypeScript 関数です。apps/agent/src/tools/<name>.ts に配置し、ToolEntry[] を返すファクトリ関数をエクスポートします。

最小構成の例

apps/agent/src/tools/my-provider.ts を作成します。

import { PermissionTier, type ToolEntry } from "../core/tool-registry.js";
import { ok, err, errFromThrow } from "./_shared/result.js";

export function createMyProviderTools(): ToolEntry[] {
  const apiKey = process.env.MY_PROVIDER_API_KEY;
  if (!apiKey) return []; // feature-gate: registry hides missing tools

  return [
    {
      name: "my_provider_search",
      toolSet: "research",
      permissionTier: PermissionTier.READ_ONLY,
      isAsync: true,
      description: "Search My Provider for a query",
      schema: {
        name: "my_provider_search",
        description: "Search My Provider for a query",
        parameters: {
          type: "object",
          properties: {
            query: { type: "string", description: "The search query" },
            limit: { type: "number", description: "Max results", default: 10 },
          },
          required: ["query"],
        },
      },
      handler: async ({ query, limit }) => {
        try {
          const res = await fetch(
            `https://api.myprovider.com/search?q=${encodeURIComponent(query)}&limit=${limit ?? 10}`,
            { headers: { Authorization: `Bearer ${apiKey}` } },
          );
          if (!res.ok) return err(`HTTP ${res.status}`);
          return ok(await res.json());
        } catch (e) {
          return errFromThrow(e);
        }
      },
    },
  ];
}

最も近い機能のそばでファクトリを登録します。配線ドメインに属するツールは、apps/agent/src/app/ の対応する Builder、たとえば messaging.ts、institution.ts、artifacts.ts に置きます。対応する Builder がない場合は、apps/agent/src/app.ts の関連する登録の近くに置きます。

import { createMyProviderTools } from "./tools/my-provider.js";
// ...
for (const tool of createMyProviderTools()) toolRegistry.register(tool);

さらに apps/agent/src/core/tool-registry.ts 内の BUILTIN_TOOL_SETS に、ツールセットのエントリーを追加します。

research: {
  description: "Market and social research tools",
  tools: [
    // ... existing
    "my_provider_search",
  ],
},

Agent がスキルを通してツールを発見する場合は、正確な名前をそのスキルの metadata.minara.tool_names に追加します。遅延ツールは tool_search から探されるため、説明は具体的で衝突のない内容にしてください。

パーミッションティア

パーミッションティア（Permission tier）は apps/agent/src/core/tool-registry.ts で定義されています。

ティア	名前	使用する場面
1	`READ_ONLY`	価格取得・残高照会・検索・`read_file`
2	`CONFIRM_ONCE`	分析・リサーチ・少額スワップ
3	`ALWAYS_CONFIRM`	`write_file`・`patch`・資金移動・ドキュメント生成
4	`MANUAL_ONLY`	出金・外部アドレスへの送金・緊急停止

迷った場合は、既存の最も近いツールに合わせてください。資金を動かすツールは isFundMoving: true と controlPolicy.confirm も宣言します。共通の権限ゲートがプレビューを表示し、ハンドラ実行前に正確な要求を確認します。

pnpm --filter @minara/agent exec vitest run tests/unit/tools/my-provider.test.ts
pnpm --filter @minara/agent typecheck
pnpm --filter @minara/docs generate

公開フローが変わる場合は、手書き文書を四言語で更新します。生成されるツールリファレンスは BUILTIN_TOOL_SETS がソースです。直接編集しないでください。

最小構成の例

パーミッションティア

結果エンベロープ

サンドボックスに限定したファイルツール

検証して文書化する

目次