ratel-integrate

/ratel-integrate — Ratel 経由でエージェントのツールとスキルを読み込む

既存のエージェントリポジトリを、動作する Ratel インテグレーションに変換します。まずエージェントと、すでに備えている機能を把握します。次に、フレームワークに適した最小限の変更で、同じツールとスキルを Ratel 経由で接続します。

成果物は、ユーザーのリポジトリに加えるコード、依存関係、テストの変更です。ユーザーから明示的に求められない限り、.ratel/ratel-integrate.md の計画は作成しないでください。

対象範囲

このインテグレーションの範囲は、意図的に限定してください。

• エージェント、ツール、スキル、および現在の所有範囲を特定します。
• 実行可能なツールとスキルの本文を Ratel に登録します。
• 各エージェントに Ratel の安定した機能ツールを提供し、ホストアダプターがサポートしている場合はターンごとのリコールも提供します。
• Vercel AI SDK のエージェントには @ratel-ai/vercel-ai-sdk を、Mastra のエージェントには @ratel-ai/mastra を使用します。
• その他のサポート対象ホストにはコア SDK を直接使用し、アダプターパッケージを新たに作らないでください。
• 小規模な接続変更が必要な場合を除き、プロンプト、モデル、実行器、スキーマ、ミドルウェア、メモリ、リクエストコンテキストを維持します。
• テレメトリ、実験、フィーチャーフラグ、パイロット向けのロジック、ダッシュボード、A/B テスト、ロールアウト用の仕組みは追加しないでください。

可観測性は前提条件ではありません。ユーザーが Ratel のインテグレーションを明示的に希望している場合、ツールカタログが小規模でも、スキルのみを持つエージェントでも問題ありません。

原則

1. 接続の前に構成を把握します。 パッケージの存在だけではエージェントの構成はわかりません。実際のエージェント構築箇所、モデル呼び出し、ツールレジストリ、スキルのソース、履歴のライフサイクルを調べます。
2. 機能の境界を維持します。 1 つの ratel() インスタンスは、共有ツールカタログとスキルカタログを所有します。同じ機能を意図的に共有するエージェント間でのみ共有し、それ以外の場合はインスタンスを分けます。統合カタログは認可上の問題につながる可能性があります。
3. ホストアダプターを優先します。 AI SDK アダプターと Mastra アダプターは、ネイティブスキーマ、実行コンテキスト、パススルーツール、リコールのメッセージ形式を維持します。手書きの変換は、すでに解決済みのエッジケースを再実装することになります。
4. 構成の起点で統合します。 既存のツール定義とスキル定義を再利用します。Ratel に対応させるためだけに個々の実装を書き換えることは避けてください。
5. モデルに公開するツールを安定させます。 パススルーツールを登録した後、エージェントごとに modelTools() を一度だけ呼び出して再利用します。ライブカタログには、通常の実行可能ツールやスキルを後から追加できます。

ワークフロー

ステップ 1 — リポジトリを安全に調査する

変更を加える前に、リポジトリの指示を読み、ワークツリーの状態を確認します。ロックファイルとマニフェストから、パッケージマネージャーとワークスペースを特定します。

rg を使って、以下を検索します。

• エージェントのコンストラクター、ファクトリー、スーパーバイザー、サブエージェント、モデル呼び出し、ツールループのエントリーポイント。
• generateText、streamText、ToolLoopAgent などの Vercel AI SDK のインポート。
• Mastra の Agent の構築箇所と createTool の定義。
• 独自の TypeScript／Python モデルループとフレームワークラッパー。
• 静的なツールオブジェクト、動的レジストリ、ツールファクトリー、ディスパッチャー、MCP クライアント。
• ランタイムのスキル登録と、.agents/skills、.claude/skills、.codex/skills、またはリポジトリ固有のディレクトリにあるプロジェクトスコープの SKILL.md ファイル。
• 既存の Ratel 依存関係と、部分的なインテグレーションコード。

リポジトリが明示的に読み込む場合を除き、ベンダー依存関係、生成された出力、ビルド成果物、ユーザーグローバルのスキルディレクトリは対象外とします。

ステップ 2 — エージェントごとの機能マップを作成する

モデルとやり取りする各エージェントについて、次の項目を記録します。

項目	特定する内容
エージェント	安定した名前、コンストラクターのファイル、呼び出し元のファイル
ホスト	AI SDK、Mastra、カスタム TypeScript、Python、またはその他のフレームワーク
ツール	定義元、レジストリの形式、ディスパッチャー、正確に割り当てられた ID
スキル	定義元／ファイルシステム上の場所、ローダー、正確に割り当てられた ID
スコープ	共有、エージェント固有、テナント固有、またはリクエスト固有
履歴	ステートレス、一時的なツールループ、または永続的な複数ターンのメッセージ
検証	最も関連性の高いユニットテスト／統合テストとビルドコマンド

命名規則ではなく、データフローを追ってください。ai への依存があっても、アプリケーションが Vercel AI SDK を直接使用しているとは限りません。依存関係として Mastra が取り込んでいる可能性があります。Markdown ファイルが自動的にエージェントスキルになるわけでもありません。

機能の所有権がセキュリティ上重要で、コードや設定から特定できない場合は、カタログを統合する前に、焦点を絞った質問を 1 つしてください。回答を待つ間も、曖昧さのないエージェントの作業は続けてください。

ステップ 3 — 現在の SDK の仕様を確認する

Ratel は頻繁に更新されます。編集前にドキュメントを確認してください。

1. Context7 が利用可能な場合は、ratel-ai/ratel を解決します。
2. マニフェストとロックファイルに固定されているバージョンを確認し、インストール済みパッケージの README があれば読みます。
3. 新規インストールや main で追加された API については、ratel-ai/ratel の公式 SDK とアダプターの README を読みます。

安定版パッケージのバージョン、非同期登録 API、スキルのデータモデル、アダプターの互換性、想起のイディオムを確認します。安定版リリースを優先し、ユーザーから依頼がない限り、プレリリース版や実験的なパッケージは選択しないでください。

Context7 の情報は、最近のアダプターの変更に追いついていないことがあります。リリース済みパッケージの README や現在の公式ソースと食い違う場合は、リポジトリが実際にインストールするバージョンの情報を優先します。アダプターの選択とコード例については references/integration-patterns.md を読み、最新のドキュメントと照合してください。

ステップ 4 — エージェントごとにサポートされている方法を選ぶ

検出したホスト	統合方法
互換性のある Vercel AI SDK API を直接インポートする TypeScript	@ratel-ai/sdk + @ratel-ai/vercel-ai-sdk；ratel(...).adaptTo(aiSdk())
互換性のある Mastra リリースを使用する TypeScript	@ratel-ai/sdk + @ratel-ai/mastra；ratel(...).adaptTo(mastra())
カスタム、またはその他の TypeScript ホスト	@ratel-ai/sdk；既存のモデル境界でのみネイティブの機能ツールに適応させます
Python ホスト	ratel-ai；コア機能ツールをフレームワークのドキュメントに記載されたツール形式でラップします
サポートされていない言語／フレームワーク	現在の SDK の形式に適合する場合は、ドキュメントに記載された薄いラッパーを使用します。適合しない場合は、具体的な阻害要因を報告します

アダプターを選ぶ前に、現在の peer と Node.js のバージョン範囲を確認してください。フレームワークやランタイムのアップグレードが必要になる場合は、作業範囲を黙って広げないでください。セマンティクスを維持できる場合に限り、ドキュメントに記載されたコアの方法を使用し、それ以外の場合は阻害要因を報告します。存在しないアダプターを推奨したり、プロセス内統合を Ratel Local や MCP ゲートウェイに置き換えたりしないでください。

ステップ 5 — ケイパビリティの読み込みを実装する

リポジトリのパッケージマネージャーを使い、エージェントを所有するパッケージに依存関係をインストールします。

ケイパビリティの境界ごとに、次の作業を行います。

1. エージェントのコンポジションルートで、不変の認可セットごとに Ratel コアを 1 つ構築するか、キャッシュします。テナント単位またはリクエスト単位のケイパビリティには、リクエストごとのコア、またはスコープを厳密に一致させたキャッシュを使用します。リクエスト固有のツールをプロセス全体のコアに登録してはいけません。リポジトリに明示的な検索設定がすでにある場合を除き、BM25 と小さな再呼び出し予算をデフォルトにします。
2. エージェントの既存のフレームワークネイティブなツールを、アダプター経由のビューから登録します。ID、説明、スキーマ、実行関数、承認動作、実行時のコンテキストを維持します。
3. そのエージェントがすでに上流の MCP を利用している場合に限り、既存の上流 MCP ツールを同じカタログに取り込みます。MCP へのアクセス範囲を広げてはいけません。
4. 割り当てられたスキルを r.skills に一括登録します。Ratel はディレクトリをスキャンしません。既存のローダーを再利用するか、承認済みのプロジェクトスキルを { id, name, description, tags?, tools?, metadata?, body? } に変換する最小限のローダーを追加します。
5. 各スキルの tools フィールドを、正確に登録されたツール ID と一致させます。リポジトリ内の任意の Markdown や、ユーザー共通のスキルを登録してはいけません。
6. モデルに渡す、実行可能な全ツールカタログを r.modelTools() に置き換え、アダプターのパススルーを維持します。
7. ホストがサポートする再呼び出し／検出経路を追加します。
   • AI SDK：ステートレスな呼び出しやドロップイン呼び出しには prepareStep を使用します。アプリケーションが複数ターンにわたる応答メッセージを永続化する場合は appendRecall を使用します。
   • Mastra：既存の入力プロセッサーに r.recallProcessor() を追加します。
   • カスタム TypeScript：ホストに明確なメッセージ注入境界がある場合に限り、コアの r.recall(query) を使用します。
   • Python およびその他のホスト：ケイパビリティツールをフレームワークのネイティブ形式で公開します。現在の公式サンプルにその方法が記載されている場合に限り、Top-K フィルタリングまたはメッセージ注入を追加します。

リポジトリにすでに Ratel がある場合は、2 つ目のカタログを作成せず、既存の統合を拡張または移行します。このスキルをもう一度実行しても、追加の変更が発生しない状態にします。

ステップ 6 — 動作を検証する

新しいローダーやケイパビリティのマッピングロジックを追加する場合は、まず対象を絞った失敗テストを作成します。その後、次の項目を検証します。

• 各エージェントが search_capabilities、invoke_tool、get_skill_content と、正当なパススルーツールのみを公開している。
• 代表的なクエリで、Ratel を介して割り当て済みのツールを検出し、呼び出せる。
• 代表的なクエリで、割り当て済みのスキルを検出し、その全文を読み込める。
• スキルで宣言されたツール ID が、同じカタログで解決できる。
• ケイパビリティのスコープが異なるエージェント同士で、互いのツールやスキルを検出できない。
• 選択したアダプターが再呼び出しを提供している場合、アダプターによる再呼び出しがユーザーターンごとに 1 回注入され、既存の会話の永続化も引き続き機能する。

まず対象を絞ったテストを実行し、その後、利用可能な範囲で影響を受けるパッケージの型チェック、テストスイート、Lint、ビルドを実行します。無関係な既存の失敗は修正せず、別途報告します。

ステップ 7 — 統合の完了を報告する

次の項目を要約します。

1. 見つかったエージェントと、それぞれに使用した Ratel の経路。
2. 各エージェントに接続したツールとスキルのソース。
3. 変更した依存関係とファイル。
4. 検証コマンドと結果。
5. サポート対象外、または意図的に変更しなかった箇所。

展開指標や、将来のテレメトリ計画は含めないでください。

誠実に作業を止める場合

• エージェントの経路がない場合： モデルに公開されるエージェントや、ツール／スキルの読み込み経路が存在しない場合は、Ratel をインストールしないでください。確認した場所を報告し、標準とは異なる配置場所を尋ねます。
• ケイパビリティがない場合： エージェントにツールもスキルもない場合は、変更せず、その理由を伝えます。
• 所有権の境界が安全に判断できない場合： カタログを統合するとエージェントのアクセス範囲が広がる可能性がある場合は、統合しないでください。不足している境界の判断を尋ねます。
• 未対応のアダプターの場合： パッケージを捏造したり、フレームワークの動作を気付かれない形で弱めたりしてはいけません。現在ドキュメントに記載されているラッパー経路を使用するか、安全に統合できない理由を説明します。

リファレンス

• references/integration-patterns.md — 現在安定している TypeScript アダプターの形式、フレームワークに依存しない代替手段、スキルの登録、マルチエージェントの境界