developing-genkit-tooling

Genkit ツールの開発

命名規則

命名に一貫性を持たせると、ユーザーやエージェントがツールを見つけやすくなります。

CLI コマンド

サブコマンドには、コロンで区切った ケバブケース を使用します。

• 形式：noun:verb または category:action
• 例：flow:run、eval:run、init
• 引数：コードではキャメルケース（flowName）、ヘルプテキストでは標準形式（<flowName>）を使用します。

MCP ツール

MCP の標準に合わせ、ツール名には スネークケース を使用します。

• 形式：verb_noun
• 例：list_flows、run_flow、list_genkit_docs、read_genkit_docs

CLI コマンドのアーキテクチャ

コマンドは commander を使用して cli/src/commands/ に実装します。

ランタイムとの連携

ほとんどのコマンドでは、ユーザーのプロジェクトのランタイムとの連携が必要です。runWithManager ユーティリティを使用して、ランタイムプロセスのライフサイクルを管理します。

import { runWithManager } from '../utils/manager-utils';

// ... command definition ...
.action(async (arg, options) => {
  await runWithManager(await findProjectRoot(), async (manager) => {
    // Interact with manager here
    const result = await manager.runAction({ key: arg });
  });
});

出力形式

• ログ出力：@genkit-ai/tools-common/utils の logger を使用します。
• 機械可読形式：コマンドがデータを生成する場合は、JSON 出力またはファイルへの書き込みオプションを用意します。
• ストリーミング：操作がストリーミング（flow:run など）に対応している場合は、--stream フラグを用意し、出力を stdout にパイプします。

MCP ツールのアーキテクチャ

cli/src/mcp/ の MCP ツールは、静的 と ランタイム の 2 種類のパターンに従います。

静的ツール（ドキュメントなど）

これらのツールは、Genkit プロジェクトの実行中のコンテキストを必要としません。

• 登録：defineDocsTool(server: McpServer)
• 依存関係：server インスタンスのみです。
• 用途：ドキュメント、使用ガイド、グローバル設定。

ランタイムツール（フロー、ランタイム制御など）

これらのツールは、特定の Genkit プロジェクトのランタイムと連携します。

• 登録：defineRuntimeTools(server: McpServer, options: McpToolOptions)
• 依存関係：manager（プロセスマネージャー）と projectRoot を含む options が必要です。
• スキーマ：ツールが必要に応じて（複数プロジェクト環境など）projectRoot 引数を受け取れるよう、getCommonSchema(options.explicitProjectRoot, ...) を必ず使用します。

// Runtime tool definition pattern
server.registerTool(
  'my_runtime_tool',
  {
    inputSchema: getCommonSchema(options.explicitProjectRoot, {
      myArg: z.string(),
    }),
  },
  async (opts) => {
    // Resolve project root before action
    const rootOrError = resolveProjectRoot(
      options.explicitProjectRoot,
      opts,
      options.projectRoot
    );
    if (typeof rootOrError !== 'string') return rootOrError;

    // access manager via options.manager
  }
);

エラー処理

MCP ツールでは通常、エラーを例外としてスローするのではなく捕捉し、isError: true を指定したコンテンツブロックとして返します。これにより、クライアントは構造化されたエラーレスポンスを受け取れます。

try {
  // operation
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  return {
    isError: true,
    content: [{ type: 'text', text: `Error: ${message}` }],
  };
}