ard-registry-builder

ARD Registry Builder

Agentic Resource Discovery（ARD）を使うと、AI クライアントはエージェント、MCP サーバー、スキル、API をハードコードする代わりに、検索によって実行時に発見できます。公開者は静的な ai-catalog.json ケイパビリティマニフェストでリソースを記述し、動的なエージェントレジストリがそれらのマニフェストをインデックス化して POST /search に応答します。このスキルは、両方を設計するのに役立ちます。作成、検証、テスト、保守を行い、適合性を満たして実際に発見されるようにします。

2 つのアーティファクトを 1 つの考え方で捉えます — 識別情報と場所：

• マニフェスト（ai-catalog.json、静的）はエントリーを列挙します。各エントリーの identifier は永続的な urn:air: URN（識別情報）であり、url／data は移動可能なエンドポイント（場所）です。
• レジストリ（REST API、動的）は、インデックス化されたエントリーを検索するサービスです。

ホスト名を URN に埋め込んではいけません。URL を識別情報として扱ってはいけません。ARD で起こる誤りのほとんどは、この 2 つを混同することに起因します。

同梱ツール（これらを使い、独自に作り直さないでください）

すべてのスクリプトは標準ライブラリのみを使用する Python 3.8 以降対応です。validate_catalog.py は jsonschema ライブラリがある場合に使用し（推奨：pip install jsonschema）、ない場合は組み込みのチェッカーにフォールバックします。

ツール	目的
scripts/validate_catalog.py <path-or-url> [--json] [--strict]	マニフェストを検証します。JSON Schema および ARD の意味規則を検査します。エラーがある場合は終了コード 1 を返します。
scripts/test_registry.py <base-url> [--query T] [--json]	稼働中のレジストリの /search（必須）、/agents、/explore を調査し、適合性を確認します。
scripts/new_catalog.py --template minimal|enterprise|local-dev [--publisher D] [--host N] --out F	初期マニフェストのひな形を作成します。
assets/ai-catalog.schema.json	ai-catalog.json マニフェスト形式の JSON Schema（Draft 2020-12）。オフライン検証用に同梱されています。
assets/ard-entry.schema.json	単独の ARD エントリーと ArdManifest（v0.91 の ard.json 形式）用の JSON Schema。エントリー単体、または entries のみのマニフェストを検証する際に使用します。
assets/templates/*.json	有効な開始用テンプレート：minimal、enterprise（信頼情報とレジストリーエントリーを含む）、local-dev。

編集のたびに必ず検証し、公開後はローカルファイルだけでなく、公開中の URL も検証してください。

ユーザーのニーズを見極める

• 「カタログを作成／ひな形を作成／始めたい」 → ワークフロー 1。
• 「検証／チェック／これは有効か／適合性を満たせないのはなぜか／このマニフェストを修正したい」 → ワークフロー 2（何かを読む前に、まず validate_catalog.py を実行します）。
• 「レジストリをテスト／調査したい／/search は動作するか／API は ARD に準拠しているか」 → ワークフロー 3。
• 「エージェントを追加／バージョンを上げる／エンドポイントを変更／保守したい」 → ワークフロー 4。
• 「X の仕組みを知りたい」（データモデル、API、信頼、公開） → 以下の該当するリファレンスを読みます。

ワークフロー 1 — マニフェストを作成する

1. 最も近いテンプレートを選び、ひな形を作成します： python scripts/new_catalog.py --template enterprise --publisher mycorp.com --host "MyCorp AI" --out ./ard.json。 （ひな形を作成しない場合は、assets/templates/ のファイルをコピーします。）
2. 各リソースについて、identifier（urn:air:<publisher>:<namespace?>:<name>）、 displayName、type（アーティファクトのメディアタイプ）、および url か data のどちらか一方のみを設定します。
3. description、tags、capabilities、特に representativeQueries（自然言語のクエリを 2～5 件）を追加します。これはセマンティック検索で発見される可能性を高める、最も効果の大きい要素です。 これがない場合、v0.91 では適合性に関する警告が出ます。存在していても、引き続き強く推奨されます。
4. 実際の本人確認情報や証明がある場合に限り trustManifest を追加します。シンプルなエントリーは簡潔に保ちます。
5. デプロイ環境に合った公開者ドメインを選びます（エンタープライズ FQDN、github.com:you のようなパブリック名前空間、またはローカル専用の agent.localhost／example.com）。references/data-model.md を参照してください。
6. 検証します：python scripts/validate_catalog.py ./ard.json。合格するまで修正します。

ワークフロー 2 — マニフェストを検証／デバッグする

1. ファイルを手作業で読む前に、まずバリデーターを実行します。問題をすばやく特定できます： python scripts/validate_catalog.py <path-or-url>.
2. 指摘事項を重大度ごとに確認します。ERROR は必ず修正し、WARN も修正するのが望ましいです（CI で強制するには --strict を使用します）。 INFO は参考情報です。各指摘事項には JSON パスと安定した code が記載されています。
3. code を references/validation-rules.md で確認し、修正方法を特定します。特に頻度の高いもの：
   • urn-wrong-nid → urn:ai: を urn:air: に変更します。
   • value-or-reference → url と data のどちらか一方だけを指定します。
   • schema（oneOf/required/pattern/minItems）→ メッセージで示された構造を修正します。
   • urn-localhost / urn-publisher-fqdn → 検証可能なドメイン、または予約済みのプレースホルダードメインを使用します。
   • trust-domain-mismatch → trustManifest.identity のドメインを URN の発行者と一致させます。
4. 問題がなくなるまで再実行します。CI では --json（機械可読な出力）および／または --strict（警告がある場合に失敗）を使用します。

ワークフロー 3 — 稼働中のレジストリ API をテストする

1. 接続を確認します：python scripts/test_registry.py https://registry.example.com/api/v1。 テスターは実際の POST /search を送信し、results エンベロープ（各項目は score が 0～100 のカタログエントリーで、source を含みます）を検証します。また、不正なリクエストが 400 + errorCode + message で拒否されることを確認し、オプションの /agents と /explore も確認します（サーバーが 404／501 を返す場合は失敗ではなくスキップされます）。
2. 必須チェックに失敗する場合、そのサーバーは必須の最低要件（/search）において ARD に準拠していません。references/registry-api.md を参照し、エンベロープ／ステータスを修正します。
3. 探索的な呼び出しについては、curl でエンドポイントに直接アクセスします（references/registry-api.md を参照）。

ワークフロー 4 — 更新／保守する

1. エントリーを編集します。identifier URN は安定した状態に保ちます。これは永続的な契約です。エンドポイントを移動する場合は、URN ではなく url（または data）を変更します。
2. アーティファクトが変更されたら、エントリーの version を上げ、updatedAt（ISO 8601）を更新します。
3. リソースを追加する場合は、エントリーを追加し、identifier が一意であることを確認します（重複はバリデーターが検出します）。
4. ファイルを再検証します。すでに公開済みの場合は、ライブ URL も検証し、レジストリがあれば再度プローブします。「検証に合格すること」を完了の定義とします。

基本原則（チェックを行う理由）

• URN はアイデンティティ、url/data は場所です。 安定した URN により、インフラストラクチャが移動しても検索インデックス、クライアント参照、オーケストレーションを維持できます。
• 発行者セグメントは検証可能な FQDN である必要があります。 レジストリはこれを抽出し、trustManifest.identity に紐付けて名前空間の不正占有を防ぎます。localhost や一般的な単語では機能しません。
• url または data のどちらか一方だけを指定します。 エンタープライズパイプラインで予測可能な解析を行うには、これが必要です。
• score は関連性を示すものであり、信頼性を示すものではありません。 検索スコアを安全性の判断基準にしてはいけません。trustManifest は個別に検証してください。
• 早めに、頻繁に、ライブ URL を検証します。 「インデックスに登録されない」問題の多くはスキーマまたはホスティングの問題であり、1 秒で終わるバリデーターの実行で見つけられます。

リファレンスファイル

タスクに合ったファイルを参照してください。各ファイルには目次があります。

• references/data-model.md — マニフェスト／エントリーのフィールド、URN 形式、メディアタイプ、値と参照の指定方法、トラストマニフェスト、JSON-LD コンテキストの拡張、urn:air: と urn:ai: に関する既知のドキュメント間の不整合。
• references/registry-api.md — /search、/explore、/agents、クエリ／フィルターモデル、フェデレーションモード、エラーコード。
• references/validation-rules.md — バリデーターが実行するすべてのチェックと、その code および重大度。
• references/publishing.md — well-known URI（ard.json）、CORS、DNS 検出、テスト対象となる公開リファレンスレジストリ。

評価

evals/evals.json には、skill-creator の評価ループに使用する現実的なタスクプロンプトが含まれています。このスキルの変更をベンチマークまたは回帰テストするために使用します。