retrieving-developer-knowledge

Google Developer Knowledge

Developer Knowledge スキルは、Developer Knowledge MCP サーバーまたは REST API のフォールバックを通じて、Google Cloud、AI/ML（ai.google.dev、ADK、TensorFlow）、Android、Chrome、Web、Flutter、Go、Firebase、その他の Google 開発者向けプラットフォームに関する公式ドキュメントにアクセスできます。

ワークフロー

1. 直接取得：技術的な質問に回答する際は、現在の会話コンテキスト内でドキュメントを一度だけ直接検索します（取得をサブエージェントに委任しないでください）。
   • 環境に MCP ツールがある場合：answer_query（概念的なガイドやワークフロー向け）または search_documents（CLI のフラグや構文向け）を呼び出します。
   • 環境に MCP ツールがない場合：curl を使って https://developerknowledge.googleapis.com/v1 に REST API リクエストを実行します。
   • サーバーが宣言されていても、常に接続されているとは限りません。 一部のクライアントはこのサーバーとの MCP ハンドシェイクを完了できず、プラグインでサーバーが宣言されているにもかかわらず、answer_query、search_documents、get_documents のいずれのツールも公開しないことがあります。これは通常の状態として扱い、以下の REST フォールバックを使用してください。
2. 取得した情報を使う前に、検索の成功を確認する：応答が届いたからといって、自動的に回答が得られたことにはなりません。PERMISSION_DENIED、UNAUTHENTICATED、HTTP 401 または 403、結果が空の場合、あるいはエラーペイロードが含まれる場合は、ツール自体がエラーを報告していなくても検索失敗です。検索に失敗した場合、成功したかのように回答してはいけません。
   • レート制限（HTTP 429／クォータ超過）：answer_query または REST の :answerQuery エンドポイントが HTTP 429（RESOURCE_EXHAUSTED／クォータ超過エラー）を返した場合、これはサーバー側の生成 QA クォータが枯渇したことを示します。回復不能な失敗と見なしたり、根拠のない記憶に頼ったりせず、ただちに検索エンドポイントを使って再試行してください（MCP の場合は search_documents、REST の場合は documents:searchDocumentChunks）。クエリから絞り込んだ 2～5 個のキーワードを使用してください。
   • 失敗が続く場合：もう一方の通信手段を一度試し、それも失敗した場合は、Developer Knowledge にアクセスできなかったため、それを参照せずに回答していることをユーザーにはっきり伝えてください。取得した結果であるかのように、記憶しているドキュメントの内容を提示するのは最悪の対応です。実際の検索結果ではないことが、回答から判別できなくなるためです。
3. ただちに完全な解決策を出力する：ドキュメントの応答を受け取ったらすぐに、完全で自己完結した、実行可能な技術的解決策（必須のフラグやプレースホルダーを含むコマンド、YAML／JSON 設定、またはコードスニペット）を回答本文に直接出力します。

ツールの選択と使用方法

実行環境で利用できるツールに応じて、適切なツールを選択してください。

1. Developer Knowledge MCP ツール（推奨）

有効なツール定義に MCP ツールがある場合：

• answer_query(query="...")：概念的なガイド、アーキテクチャの比較、製品選択の概要、複数ステップのワークフローに使用します。このツールのクォータには制限があります。クォータ超過エラーである 429 が発生した場合は、代わりに search_documents を使用してください。
• search_documents(query="...")：詳細な CLI フラグ、正確な構文、パラメーター名、IAM 権限（service.resource.verb）に使用します。会話形式の文章全体ではなく、cloud run filestore nfs mount gcloud のように、絞り込んだ 2～5 個のキーワードを使用してください。
• get_documents(names=["documents/{uri_without_scheme}"])：リソース名を指定して、ドキュメントページ全体を取得します（例：names: ["documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run"]）。

2. REST API のフォールバック

MCP ツールがない場合は、curl を使って Developer Knowledge REST API （https://developerknowledge.googleapis.com/v1）にクエリを送信します。使用できる認証情報は 2 種類あり、以下の順序で試してください。

既存の Google 認証情報（推奨）。 gcloud で認証済みの場合は、ベアラートークンと割り当て先プロジェクトを渡します。インストールや設定は必要ありません。

curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: $(gcloud config get-value project 2>/dev/null)" \
  -H "Content-Type: application/json" \
  -d "{\"query\": \"How do I configure public read access on Cloud Storage?\"}"

認証に失敗した場合、つまり 401、403、またはその他の認証情報エラーが返された場合、そのアカウントのトークンは API で受け付けられません。上記のコマンドで gcloud auth print-access-token を gcloud auth application-default print-access-token に置き換えて、もう一度試してください。API が受け付ける認証情報は環境の認証方法によって異なるため、ここで認証エラーが発生した場合は、検索失敗と判断するのではなく、アプリケーションのデフォルト認証情報を試してください。

API キー（設定されている場合）。 環境に DEVELOPERKNOWLEDGE_API_KEY が設定されている場合は、Authorization ヘッダーではなく、key クエリパラメーターとして渡してください。どちらの認証情報も使用できない場合、このクライアントでサポートされている方法は API キーです。Developer Knowledge のクイックスタートに従って API を有効にし、API キーを作成してから、DEVELOPERKNOWLEDGE_API_KEY としてエクスポートしてください。検索せずに回答するのではなく、認証情報が必要であることを伝えてください。このセクションの残りの例では、この方法を使用します。

• クエリへの回答：

  curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery?key=${DEVELOPERKNOWLEDGE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"query": "How do I configure public read access on Cloud Storage?"}'
  

  このエンドポイントの割り当て量には上限があります。割り当て量超過エラーとして 429 が返された場合は、代わりに documents:searchDocumentChunks を使用してください。
• ドキュメントチャンクの検索（焦点を絞ったキーワードを 2～5 個使用）：

  curl -s "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=gcloud+logging+metrics+create&key=${DEVELOPERKNOWLEDGE_API_KEY}"
  

• ドキュメントの取得：

  curl -s "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key=${DEVELOPERKNOWLEDGE_API_KEY}"
  

• ドキュメントの一括取得（GET を使用し、ドキュメントごとに names パラメーターを 1 つ指定します。リクエストボディは不要です。1 回の呼び出しで最大 20 件）：

  curl -s -G "https://developerknowledge.googleapis.com/v1/documents:batchGet" \
    --data-urlencode "names=documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run" \
    --data-urlencode "names=documents/docs.cloud.google.com/storage/docs/creating-buckets" \
    --data-urlencode "key=${DEVELOPERKNOWLEDGE_API_KEY}"
  

統合と出力のガイドライン

1. 公式ドキュメントに基づくこと：すべてのソリューションは、取得したドキュメントに直接基づいてください。公式ドキュメントの規則は、記憶しているデフォルト設定よりも常に優先されます。
2. パラメーターを正確に記述すること：CLI フラグ、複合キー（例：location=IP:PATH）、IAM 権限文字列は、公式の Google 仕様に従って記述してください。
3. 最終回答に完全なソリューションを含めること：内部での計画時にすでに触れている場合でも、明確で一般的なプレースホルダー（例：PROJECT_ID、SERVICE_NAME、REGION）を含む、完全で自己完結した実行可能な技術ソリューション（コマンド、設定、またはコードスニペット）を必ず最終回答に記載してください。

参考資料

• MCP の使用方法とツールの詳細
• REST API のフォールバックガイド
• サポート対象のドメインとスコープ設定