From 11cc091768f57a4feecf5dfbc0ee8b5fea620d24 Mon Sep 17 00:00:00 2001 From: Michael Lugassy Date: Wed, 10 Jun 2026 11:58:38 +0300 Subject: [PATCH] feat: add Japanese translation of the guide under content/ja Full ja translation of all 32 content/*.md files (front matter + 5 modules). Proper nouns, protocol names, code, field names, paths and URLs kept verbatim; descriptive concepts, prose, guideline/module titles and section headers localized. Human-readable sample values (manifest/JSON-LD descriptions, FAQs, example utterances) localized; keys/enums/slugs/@types and the Acme placeholder kept. llms.txt example headers localized to Japanese per i18n convention. Validator scopes to top-level content/, so content/ja/ does not affect it. --- content/ja/00-toc.md | 55 +++++++++ content/ja/01-introduction.md | 56 +++++++++ content/ja/m1-0-module-discoverable.md | 24 ++++ content/ja/m1-1-discovery-files.md | 68 ++++++++++ content/ja/m1-2-well-known-agent-files.md | 96 +++++++++++++++ content/ja/m1-3-readable-without-js.md | 41 +++++++ content/ja/m1-4-topical-authority.md | 30 +++++ content/ja/m2-0-module-comprehensible.md | 20 +++ content/ja/m2-1-json-ld.md | 116 ++++++++++++++++++ content/ja/m2-2-llms-txt-content.md | 33 +++++ content/ja/m2-3-document-for-agents.md | 38 ++++++ content/ja/m2-4-competitive-positioning.md | 34 +++++ content/ja/m3-0-module-trustworthy.md | 18 +++ content/ja/m3-1-oauth-discovery.md | 45 +++++++ content/ja/m3-2-web-bot-auth.md | 48 ++++++++ content/ja/m3-3-self-serve-credentials.md | 40 ++++++ content/ja/m4-0-module-actionable.md | 18 +++ content/ja/m4-1-openapi-spec.md | 45 +++++++ content/ja/m4-10-nlweb.md | 46 +++++++ content/ja/m4-2-rate-limits-and-errors.md | 38 ++++++ content/ja/m4-3-streaming.md | 39 ++++++ content/ja/m4-4-mcp-server.md | 42 +++++++ content/ja/m4-5-webmcp.md | 58 +++++++++ content/ja/m4-6-agent-registries.md | 37 ++++++ content/ja/m4-7-sdks-and-cli.md | 41 +++++++ content/ja/m4-8-payment-protocols.md | 44 +++++++ content/ja/m4-9-commerce-protocols.md | 49 ++++++++ content/ja/m5-0-module-experiential.md | 24 ++++ content/ja/m5-1-verified-on-platforms.md | 41 +++++++ content/ja/m5-2-mcp-apps.md | 45 +++++++ content/ja/m5-3-cross-platform-consistency.md | 38 ++++++ content/ja/m5-4-end-to-end-flows.md | 40 ++++++ 32 files changed, 1407 insertions(+) create mode 100644 content/ja/00-toc.md create mode 100644 content/ja/01-introduction.md create mode 100644 content/ja/m1-0-module-discoverable.md create mode 100644 content/ja/m1-1-discovery-files.md create mode 100644 content/ja/m1-2-well-known-agent-files.md create mode 100644 content/ja/m1-3-readable-without-js.md create mode 100644 content/ja/m1-4-topical-authority.md create mode 100644 content/ja/m2-0-module-comprehensible.md create mode 100644 content/ja/m2-1-json-ld.md create mode 100644 content/ja/m2-2-llms-txt-content.md create mode 100644 content/ja/m2-3-document-for-agents.md create mode 100644 content/ja/m2-4-competitive-positioning.md create mode 100644 content/ja/m3-0-module-trustworthy.md create mode 100644 content/ja/m3-1-oauth-discovery.md create mode 100644 content/ja/m3-2-web-bot-auth.md create mode 100644 content/ja/m3-3-self-serve-credentials.md create mode 100644 content/ja/m4-0-module-actionable.md create mode 100644 content/ja/m4-1-openapi-spec.md create mode 100644 content/ja/m4-10-nlweb.md create mode 100644 content/ja/m4-2-rate-limits-and-errors.md create mode 100644 content/ja/m4-3-streaming.md create mode 100644 content/ja/m4-4-mcp-server.md create mode 100644 content/ja/m4-5-webmcp.md create mode 100644 content/ja/m4-6-agent-registries.md create mode 100644 content/ja/m4-7-sdks-and-cli.md create mode 100644 content/ja/m4-8-payment-protocols.md create mode 100644 content/ja/m4-9-commerce-protocols.md create mode 100644 content/ja/m5-0-module-experiential.md create mode 100644 content/ja/m5-1-verified-on-platforms.md create mode 100644 content/ja/m5-2-mcp-apps.md create mode 100644 content/ja/m5-3-cross-platform-consistency.md create mode 100644 content/ja/m5-4-end-to-end-flows.md diff --git a/content/ja/00-toc.md b/content/ja/00-toc.md new file mode 100644 index 0000000..4b1211b --- /dev/null +++ b/content/ja/00-toc.md @@ -0,0 +1,55 @@ +--- +id: toc +title: 目次 +kind: front-matter +--- + +# 目次 + +## 前付け +- まえがき - なぜエージェント対応が次の「モバイル対応」なのか + +## 第I部 - ライフサイクルという枠組み +- **第1章** はじめに: エージェントのライフサイクル、5つのモジュール、エージェントを意識したセキュリティ、本ガイドの読み方 + +## 第II部 - 5つのモジュール + +### モジュール1 - 発見可能であること +- 1.1 ディスカバリーファイルを公開する +- 1.2 well-known エージェントファイルを設置する ★ +- 1.3 JavaScript なしでコンテンツを読めるようにする +- 1.4 トピックの権威性とコーディングエージェント向けルールを構築する + +### モジュール2 - 理解可能であること +- 2.1 完全な JSON-LD 構造化データを公開する +- 2.2 有用な llms.txt を提供する +- 2.3 エージェント向けにドキュメントを整える +- 2.4 競合上のポジショニングを行う + +### モジュール3 - 信頼できること +- 3.1 OAuth を実装する ★ +- 3.2 ボットを暗号学的に検証する ★ +- 3.3 クレデンシャルをセルフサービス化する ★ + +### モジュール4 - 実行可能であること +- 4.1 OpenAPI 仕様を提供する ★ +- 4.2 レート制限とエラーを標準化する ★ +- 4.3 長時間実行の処理をストリーミングする ★ +- 4.4 MCP サーバーを運用する ★ +- 4.5 WebMCP でツールを公開する ★ +- 4.6 エージェントレジストリに登録する ★ +- 4.7 SDK と CLI を配布する ★ +- 4.8 エージェント決済プロトコルに対応する ★ +- 4.9 エージェンティックコマースプロトコルに対応する ★ +- 4.10 NLWeb エンドポイントを運用する ★ + +### モジュール5 - 体験を提供すること +- 5.1 AI プラットフォームで認証を受ける ★ +- 5.2 MCP Apps で UI を描画する ★ +- 5.3 サーフェス間で一貫性を保つ ★ +- 5.4 エンドツーエンドのエージェントフローを通過する ★ + +## チェックリスト +- 25 のジョブを一覧で + +★   *Forter による支援* diff --git a/content/ja/01-introduction.md b/content/ja/01-introduction.md new file mode 100644 index 0000000..b2bb765 --- /dev/null +++ b/content/ja/01-introduction.md @@ -0,0 +1,56 @@ +--- +id: introduction +title: はじめに +kind: chapter +--- + +# なぜエージェント対応が次の「モバイル対応」なのか + +2010年の問いは、あなたのサイトがスマートフォンで表示できるかどうかでした。2015年には、その答えはもはや選択肢ではなくなっていました。2026年の問いは、あなたのサイトが **エージェント対応 (agent-ready)** かどうかです。すなわち、自律型 AI - Claude、ChatGPT、Gemini - があなたの製品を発見し、それが何をするのかを理解し、あなたの API に認証し、ユーザーに代わって取引を行い、その結果を会話の中に返せるかどうか、ということです。 + +これは、見慣れた車輪がもう一度回り始めた瞬間でもあります。**SEO** はあなたのページを検索クローラー向けに調整しました。**AEO/GEO** - Answer / Generative Engine Optimization（回答エンジン最適化・生成エンジン最適化）- は、AI が生成するチャットの中で読まれ引用されるようにページを調整しました。エージェント対応はこの延長線上にあり - その過程で AEO/GEO の多くを吸収します - しかし対象とする相手が変わります。SEO、AEO、GEO は、結果を読む *人間* に向けて最適化します。エージェント対応は、人間に代わって発見・評価・行動する *自律エージェント* に向けて最適化します。エージェントは依然として人によって操作されているため、これらの分野は関連し続けます - しかしあなたはいまやソフトウェアに向けて書いているのであり、ソフトウェアは説得的なコピーよりも構造化データを、行動喚起 (call-to-action) よりも呼び出し可能な API を求めます。 + +今日のほとんどのサイトはエージェンティックではありません。第一段階 - 発見可能性 - は1〜2週間で完了しますが、完全なエージェント対応は別物です。OAuth、x402、ACP/UCP への対応には、集中したエンジニアリング作業がまとまって必要になります。ここにあるものは何ひとつ研究課題ではありません - すべてのプロトコルには、それに対して実装するための仕様があります。しかし、対応度のスケールで上を目指すほど、作業は現実味を帯びてきます。[**Forter エージェンティック・オーケストレーション・スイート**](https://www.forter.com/blog/agentic-orchestration/?utm_source=github&utm_medium=referral&utm_campaign=agentic-readiness-guide&utm_content=01-introduction) は、最も困難な層を吸収するために作られています - 私たちはそれを支援するためにここにいます。 + +> エージェント対応していないサイトは、見えない存在になりつつあります。第一段階は容易ですが、フルスタックには数か月かかることもあります。どちらも実現不可能な大事業ではありません - しかしフルスタックは現実の作業であり、スコアはその努力を反映します。 + +本ガイドは、自律エージェントから到達可能になりたいあらゆるウェブサイトに向けて書かれています - 最も具体的には、エージェントがタスクを完了する価値が直接的に表れる **e コマース、マーケットプレイス、トランザクション型サイト** を想定していますが、同じサーフェスは SaaS、コンテンツプラットフォーム、開発者向けツールにも等しく当てはまります。 + +## エージェント対応は、エージェントを意識したセキュリティでもある + +エージェント対応のもう一つの側面は、**エージェントが必ずしも計画どおりに動くとは限らない** という点です。エージェントはプロンプトインジェクションによって意図から逸脱することがあります。トークンが流出し、再利用 (リプレイ) されることがあります。API がスクレイピングされ、悪用されることがあります。悪質なボットが善良なボットになりすますことがあります。スコープが限定されていない MCP ツールは、現実の損害を与えかねません。 + +これらはいずれも目新しい問題ではなく、そのほとんどは本ガイドが扱うのと同じ標準で解決できます。すなわち、スコープを絞った OAuth、暗号学的なボット検証、構造化されたレート制限、ツール単位の認可、そして継続的なテストです。本ガイドでは、これらのリスクを文脈の中で随所に示し、Forter のアイデンティティ・リスクレイヤーがそれらの対処を容易にする箇所を指摘します。 + +## ライフサイクルという枠組み + +本ガイドは、エージェント対応サイトが行うべきすべてを、ひとつの問い - **エージェントは、あなたとのやり取りの各段階で何を必要とするのか?** - を中心に整理し、5つの連続したモジュールで答えます。各モジュールは前のモジュールの上に積み重なるため、その順序はそのまま、合理的な実装の手順にもなっています。 + +## 各ガイドラインに含まれるもの + +- **概要と理由** - その作業を平易な言葉で、1〜2文で +- **工数・インパクト・視覚的変化** - 工数とインパクトは 1〜5、視覚的変化は `なし` / `小` / `中` / `大` +- **手順** - パス、フォーマット、仕様参照を伴う、具体的で番号付きのアクション +- **参考資料** - 基盤となる RFC、スキーマ、標準へのリンク +- **Forter による支援** - Forter が本当に役立つガイドラインにのみ掲載 + +スコアリングは、エージェント対応度を測る2つの代表的なランカー - [isitagentready.com](https://isitagentready.com?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide)（Cloudflare）と [ora.ai](https://ora.ai?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide)（Ora）- を追跡します。これらを使って、自社のベースラインと進捗を把握してください。 + +**私たちはこれを机上の理論から書いたわけではありません。** 私たちは [forter.com](https://www.forter.com/) を [両方](https://isitagentready.com/www.forter.com) [のランカー](https://ora.ai/score/forter.com) にかけ、各ガイドラインが説明するエンジニアリングを実際に行い、何が本当にスコアを動かしたかを記録しました。その結果、私たちはいずれのランカーでも最高得点クラスのサイトに入りました - 作業をやり遂げる意志のあるチームなら、どこでもトップスコアに手が届くという証拠です。工数とインパクトの評価、実装の順序付け、そして *Forter による支援* の注記は、すべて本番稼働中のドメインに対して手を動かして行ったこの取り組みから得られたものです。 + +## Forter が支援できること + +[**Forter エージェンティック・オーケストレーション・スイート**](https://www.forter.com/blog/agentic-orchestration/?utm_source=github&utm_medium=referral&utm_campaign=agentic-readiness-guide&utm_content=01-introduction) は、OAuth、MCP / WebMCP / MCP Apps / UCP / ACP、OpenAPI（SDK と CLI のサポートを含む）、x402 / MPP などを横断的にカバーするホスト型のプロトコル横断プレーンであり、そのすべてが Forter Identity Network に接続されています。**マーチャントは、各層を自前で構築する代わりにここに向けるだけでよく**、あるいは既存の仕組みと並行して運用することもできます。 + +## 本ガイドの読み方 + +- **CTO・エンジニアリング責任者:** はじめに、5つのモジュール概要、そして各 *Forter が支援できること* のセクションを読んでください。 +- **アーキテクト・シニアエンジニア:** すべてのガイドラインを読んでください。手順はそのまま実装チェックリストになります。 +- **プロダクト・マーケティング:** モジュール2（理解可能）とモジュール5（体験）が、あなたのレバーがある場所です。 +- **セキュリティ・アイデンティティチーム:** モジュール3が、暗号技術のほとんどと脅威モデルの議論がある場所です。 + +## あなたのサイトをスコアリングする + +[Claude Code](https://docs.claude.com/claude-code?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) を使えば、本ガイドにあなたのサイトをスコアリングさせることができます。[github.com/forter/agentic-readiness-guide](https://github.com/forter/agentic-readiness-guide?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) のリポジトリには、すべてのガイドラインを読み込み、各項目に照らしてサイトをランク付けし、根拠を引用し、インパクト対工数の順に不合格項目を一覧化するスキルが含まれています。 + +それでは始めましょう。 diff --git a/content/ja/m1-0-module-discoverable.md b/content/ja/m1-0-module-discoverable.md new file mode 100644 index 0000000..90fbd8b --- /dev/null +++ b/content/ja/m1-0-module-discoverable.md @@ -0,0 +1,24 @@ +--- +id: module-discoverable +title: モジュール1 - 発見可能であること +kind: module-overview +moduleNumber: 1 +--- + +# モジュール1 - 発見可能であること +*「エージェントは、誰に教えられなくても、あなたの製品を見つけ出せる。」* + +## エージェントの問い +> _「ある買い物客から、防水のトレイルランニングシューズ、サイズ10、120ドル以下のものを探してほしいと頼まれた。どのサイトがそれを扱っているだろう?」_ + +## ファネルはすでに動き始めている + +業界イベントやアナリストのブリーフィングのたびに耳にする反論は、エージェントによる *取引* のボリュームはまだ小さい、というものです。それは今日においては事実であり - そして、すでに起きていることを見落としています。いま現に破壊されつつある部分は、検索と発見です。エージェントはあなたのサイトについて意見を形成し、あなたのカタログを読む（あるいは読めない）ことを通じて、どんな取引が俎上に載るよりもずっと前に、ユーザーの購買意図を形づくっているのです。 + +これらの段階は独立していません。エージェントが発見段階であなたを読めなければ、あなたは取引段階で競争の土俵にすら立てません - そこまで話が進まないからです。したがって、エージェント取引のボリュームが「無視できない規模」になるのを待ってから動くサイトは、トラフィックがすでに移ってしまっていることに気づくでしょう。エージェントはもっと早い段階で、そのとき読み取れた相手の中から候補リストを作っており、そのリストに載らなかったサイトが再検討されることは決してありません。これは、e コマースストアを運営していようと、SaaS プラットフォームであろうと、マーケットプレイスであろうと変わりません - 発見は、そのすべての前に立ちはだかる関門です。 + +発見可能性は、群を抜いて最も安価なモジュールです。作業のほとんどは、オリジンのルートや `/.well-known/` 配下に置く静的ファイル - 一度書けばあとは忘れていられるテキストと JSON - です。 + +## 3つの発見のレンズ + +エージェントは、それぞれ独自のファイルを持つ3つの並行するサーフェスを通じてあなたに到達します。**クラシックな検索**（Googlebot、Bingbot）、**AI 学習クローラー**（GPTBot、CCBot - 許可することも、制限することもできます）、そして **ライブのエージェントクローラー**（ChatGPT-User、ClaudeBot、Perplexity-User - ユーザーが質問した瞬間にあなたのサイトを取得します）です。実際に誰がノックしているのかを暗号学的に検証する方法は [3.2](./m3-2-web-bot-auth.md) に、ツール発見のためのレジストリ登録は（MCP サーバーが存在した後の）[4.6](./m4-6-agent-registries.md) にあります。 diff --git a/content/ja/m1-1-discovery-files.md b/content/ja/m1-1-discovery-files.md new file mode 100644 index 0000000..a54a467 --- /dev/null +++ b/content/ja/m1-1-discovery-files.md @@ -0,0 +1,68 @@ +--- +id: m1-1-discovery-files +module: discoverable +moduleNumber: 1 +guidelineNumber: 1 +title: ディスカバリーファイルを公開する +complexity: 1 +impact: 4 +visualChange: none +forterApplies: 'no' +--- + +# 1.1 ディスカバリーファイルを公開する + +## 概要と理由 +オリジンのルートに置く4つの小さな静的テキストファイルが、AI エコシステム全体に対して、あなたが何を持っていて、それで何ができるのかを伝えます。`sitemap.xml`、`robots.txt`、`llms.txt`、`index.md` の4つです。これらは書くのに半日もかからず、ライブのエージェントクローラー（収益につながる）を歓迎しつつ、学習クローラー（収益につながらない）を制限できます。5つ目のサーフェスはファイルですらありません。これらのリソースを広告する HTTP `Link:` レスポンスヘッダーで、これにより、エージェントは HTML を1行も解析することなく `HEAD` リクエストからリソースを解決できます。これは **ポリシー** の層であって、強制の層ではない点に注意してください - 行儀のよいボットだけがこれを尊重します。 + +## スコアリング +- **工数 1/5** - 半日でひと通り、ほとんどがテキストファイルです。最も難しいのは、CMS に `` を正しく出力させることです。 +- **インパクト 4/5** - 基盤となります。モジュール2〜5は、まずここであなたを見つけられないものからは評価すらされません。 +- **視覚的変化: なし** - 機械専用のパス（`/robots.txt`、`/llms.txt`、`/index.md`）に新しいファイルが増えるだけで、レンダリングされるページは変わりません。 + +## 手順 +1. **サイトマップ。** サイトマップは、クローラーがリンクから推測する代わりに、取得する価値のあるすべての URL を最速で知る手段です。`/sitemap.xml` を提供し、インデックス可能なすべての URL を、正確な `` ISO-8601 タイムスタンプとともに列挙してください - そのタイムスタンプこそ、ページが変更され再読み込みの価値があることをエージェントに伝えるシグナルです。各ファイルは 50 MB / 50,000 URL を上限とし、より大規模なサイトでは [サイトマップインデックス](https://www.sitemaps.org/protocol.html?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) を使ってください。`/sitemap.xml` はクローラーが最初に探るパスなので、もしサイトマップがすでに別の場所（`/sitemap_index.xml`、CMS が生成する URL）にあるなら、移動する必要はありません - `/sitemap.xml` から実際の場所への `301` リダイレクトを追加すれば、慣例的なパスが解決されます。 +2. **AI ポリシーを差別化した robots.txt。** `robots.txt` は、クローラーとの交戦規則を定める場所です - そして今日の有用なニュアンスは、すべての AI クローラーが同じではないということです。買い物客の質問に答えるためにページを取得するエージェントは、あなたに売上をもたらしうる一方、モデルを学習させるためにスクレイピングするクローラーは何も返してくれません。Cloudflare 発祥の慣例である [Content Signals](https://blog.cloudflare.com/content-signals-policy/?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) を使えば、どちらがどちらなのかを宣言できます。サイトマップを参照したうえで、3つのシグナルを設定してください。 + - `search` - このページを検索クエリ（クラシック検索と AI 駆動の検索の両方）に答えるためにインデックスしてよいか。 + - `ai-input` - このページをクエリ時点で取得し、AI の回答に投入してよいか（ライブ取得 / RAG）。 + - `ai-train` - このページを AI モデルの学習データとして使ってよいか。 + + `search=yes, ai-input=yes, ai-train=no` が、ほとんどのサイトが望む構成です - ライブのトラフィックを送ってくるエージェントを歓迎し、学習のためだけに収集するクローラーを断ります。これを明示したうえで、まだすべてのクローラーがシグナルを尊重するわけではないので、名指しした学習クローラーは正面からブロックしてください。 + ``` + Sitemap: https://example.com/sitemap.xml + + User-agent: * + Content-Signal: search=yes, ai-input=yes, ai-train=no + + User-agent: GPTBot + Disallow: / + + User-agent: CCBot + Disallow: / + ``` +3. **llms.txt。** あなたの HTML ホームページは人間向けに作られており - ナビゲーション、マーケティング、スクリプト - エージェントはわずかな事実を見つけるために、その全部をかき分ける必要があります。[`llms.txt`](https://llmstxt.org?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) は、代わりにモデル向けに書かれたプレーンな Markdown のブリーフィングです。あなたが何をするのか、誰に向けたものか、エージェントがあなたで何ができるのか、そして API やドキュメントへのリンクを、短く構造化して要約したものです。`/llms.txt` に公開し、製品概要、ユースケース、制約のセクションを設けてください。初日から完璧な文章である必要はありません - よく構造化されたスタブで始めるには十分で、内容の質は [2.2](./m2-2-llms-txt-content.md) で扱います。 +4. **モジュール化された llms.txt。** 単一のルート `llms.txt` は、長くならずにあらゆることを深掘りすることはできません。領域ごとのバリアント - `/docs/llms.txt`、`/api/llms.txt`、`/developers/llms.txt` - を追加して、特定のタスクに取り組むエージェントが必要なコンテキストのスライスだけを引けるようにしてください。各ファイルは焦点を保ち、あなたはモデルのアテンション予算の範囲内に収まります。 +5. **Markdown のホームページフォールバック。** 一部のエージェントは、HTML を解析する手間をかける前に `/index.md` - ホームページのクリーンな Markdown 版 - を探します。それを用意してあげてください（Content-Type `text/markdown`）。トップレベルの見出しと、ホームページの HTML が持つのと同じ中核的な価値提案テキストを含めます。マークアップを取り除く手間をエージェントから省く、2分でできるファイルです。 +6. **（任意）`Link` レスポンスヘッダー（[RFC 8288](https://datatracker.ietf.org/doc/html/rfc8288?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide)）。** 上記のすべては既知のパスに存在しますが、エージェントはそれを見つけるために各ファイルをリクエストしなければなりません。`Link:` レスポンスヘッダーを使えば、それらすべてを HTTP レスポンス自体の中で広告でき、エージェントは単一の `HEAD` リクエストからあなたのファイルセット全体を発見できます - HTML 解析は一切不要です。ここでは最も技術的な手順であると同時に最もインパクトが小さいので、4つのファイルが揃った後の「あると望ましい」項目として扱ってください。`Link: ; rel="sitemap"`、`Link: ; rel="describedby"`、`Link: ; rel="api-catalog"`、`Link: ; rel="service-desc"` を出力します。後ろの2つは [4.1](./m4-1-openapi-spec.md) がオンラインにするファイルを指しますが - パスは今日すでに確定しているので、設定した瞬間にヘッダーは正しく、4.1 が着地したときに解決され始めます。これらのヘッダーをすべてのページに追加して、どのページも一貫して広告するようにしてください。 + +**結果を検証する。** `curl -I` は HTTP `HEAD` リクエストを送り、ボディを一切表示せずにレスポンスヘッダーだけを出力します - これは、パスが存在し、`200` を返し、正しい `Content-Type` を持つことを確認する最速の方法です。公開した各ファイルに対して実行してください。 + +``` +curl -I https://example.com/llms.txt +``` + +健全なレスポンスは次のようになります。 + +``` +HTTP/2 200 +content-type: text/markdown; charset=utf-8 +content-length: 1843 +``` + +`/sitemap.xml`、`/robots.txt`、`/llms.txt`、`/index.md` を同じ方法でチェックしてください - それぞれで、`200` ステータスと妥当な `content-type` が得られることを確認します。手順6を完了したなら、ホームページに対する `curl -I https://example.com` にも `Link:` ヘッダーが一覧表示されるはずです。`-I` を外せば、ヘッダーと一緒にボディも取得できます。 + +## 参考資料 +- [sitemaps.org プロトコル](https://www.sitemaps.org/protocol.html?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) +- [Cloudflare Content Signals](https://blog.cloudflare.com/content-signals-policy/?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) +- [llms.txt 提案](https://llmstxt.org?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) +- [RFC 8288 - Web Linking](https://datatracker.ietf.org/doc/html/rfc8288?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) diff --git a/content/ja/m1-2-well-known-agent-files.md b/content/ja/m1-2-well-known-agent-files.md new file mode 100644 index 0000000..f03ad18 --- /dev/null +++ b/content/ja/m1-2-well-known-agent-files.md @@ -0,0 +1,96 @@ +--- +id: m1-2-well-known-agent-files +module: discoverable +moduleNumber: 1 +guidelineNumber: 2 +title: well-known エージェントファイルを設置する +complexity: 1 +impact: 3 +visualChange: none +forterApplies: 'partial' +--- + +# 1.2 well-known エージェントファイルを設置する + +## 概要と理由 +`/.well-known/` 配下に置く4つの小さな JSON ファイルが、4つの異なるエージェントエコシステムをカバーします。`ai-plugin.json`（OpenAI）、`agent.json`（汎用）、`agent-card.json`（Google A2A）、そして MCP ディスカバリードキュメントです。それぞれ30行未満です。いくつかは後のモジュールで初めてオンラインになるエンドポイントを参照しますが - すべてのパスは今日わかっているので、各ファイルを最終的な URL とともに一度だけ正しく書けば、二度と開く必要はありません。 + +## スコアリング +- **工数 1/5** - 4つの JSON ファイルと、一度きりのコピー方針の決定です。最も難しいのは、正式名称と説明文、スコープ、連絡先メールアドレスを確定させることです。 +- **インパクト 3/5** - すべてのエージェントがまだこれらを使うわけではないので 1.1 より低いですが、対応しているプラットフォームでは一級のプラグイン / カードのサーフェスを解放します。 +- **視覚的変化: なし** - `/.well-known/*` パスのファイルであり、サイト上でユーザーに見える変化はありません。 + +## 手順 +1. **まず正式コピーを確定する。** 名前と説明であふれた4つのマニフェストを書く前に、それらを一度だけ決めてください。短い製品名1つ（40文字以下）、モデル向けの説明1つ（120文字以下）、人間向けの段落1つ（400文字以下）です。これらを、リポジトリ内の唯一の信頼できる情報源 (single source of truth) となるファイル（例: `brand-copy.md`）にコミットしてください。ここから先、本ガイドが求めるすべての名前・説明フィールド - これらのマニフェスト、JSON-LD（[2.1](./m2-1-json-ld.md)）、`llms.txt`（[2.2](./m2-2-llms-txt-content.md)）、MCP ツール一覧（[4.4](./m4-4-mcp-server.md)）、meta タグや OG タグ - は、**このファイルからコピーするのであって、二度と即興で書き直さないでください**。この一つの規律こそ、[5.3](./m5-3-cross-platform-consistency.md) を書き直しではなく5分の検証作業に変えるものです。 +2. **`/.well-known/ai-plugin.json`** - OpenAI のプラグインマニフェスト、`application/json` として提供します。 + ```json + { + "schema_version": "v1", + "name_for_human": "Acme Returns", + "name_for_model": "acme_returns", + "description_for_human": "Acme のどの注文でも、注文状況の確認と返品の開始ができます。", + "description_for_model": "確認済みの顧客に代わって、Acme の注文状況を照会し、返品を開始します。", + "auth": { "type": "oauth", "authorization_url": "https://example.com/.well-known/oauth-authorization-server" }, + "api": { "type": "openapi", "url": "https://example.com/openapi.json" }, + "logo_url": "https://example.com/logo.png", + "contact_email": "agents@example.com", + "legal_info_url": "https://example.com/legal" + } + ``` + 上記のキー名はそのまま必須です。値はプレースホルダーなので - あなたの正式コピーと実際の URL に置き換えてください。`auth` は [3.1](./m3-1-oauth-discovery.md) の OAuth エンドポイントを、`api.url` は [4.1](./m4-1-openapi-spec.md) の `/openapi.json` を指します - いずれも後のモジュールで提供されるエンドポイントです。それらのパスはすでに決まっているので、**最終的な URL を今書いてください**。ファイルは保存した瞬間に正しく、それらのガイドラインが着地するにつれて単に解決され始めます。プレースホルダーも、二度目の訪問も不要です。 +3. **`/.well-known/agent.json`** - Claude 連携やいくつかの小規模レジストリで使われる汎用エージェントマニフェスト。ai-plugin の形を踏襲します。 + ```json + { + "name": "Acme Returns", + "description": "Acme のどの注文でも、注文状況の確認と返品の開始ができます。", + "version": "1.0.0", + "endpoints": { "openapi": "https://example.com/openapi.json" }, + "auth": { "type": "oauth", "authorization_url": "https://example.com/.well-known/oauth-authorization-server" }, + "capabilities": ["order-status", "returns"] + } + ``` + `description` はツールピッカーに表示される文言です - これはあなたの正式コピーからそのまま来ます。 +4. **`/.well-known/agent-card.json`** - Google の A2A（Agent-to-Agent）プロトコルカード。`skills` 配列が実質的な中身です。エージェントがあなたに委ねられるタスク1つにつき1エントリで、それぞれに例文 (example utterances) を添え、呼び出し側のエージェントがいつあなたにルーティングすべきかを判断できるようにします。 + ```json + { + "name": "Acme Returns", + "description": "Acme のどの注文でも、注文状況の確認と返品の開始ができます。", + "url": "https://example.com", + "version": "1.0.0", + "capabilities": { "streaming": false }, + "defaultInputModes": ["text/plain"], + "defaultOutputModes": ["text/plain"], + "skills": [ + { + "id": "order-status", + "name": "注文状況", + "description": "注文の現在の状況を照会します。", + "tags": ["orders", "tracking"], + "examples": ["注文番号1234はどこ?", "荷物はもう発送された?"] + } + ] + } + ``` +5. **MCP ディスカバリー。** `/.well-known/mcp.json` を公開するか、`/.well-known/mcp` からそのファイルへの `307` リダイレクトを設定します。 + ```json + { + "mcpServers": [ + { + "name": "acme", + "url": "https://mcp.example.com", + "transport": "streamable-http" + } + ] + } + ``` + MCP サーバーの正式 URL を今決めてください。[4.4](./m4-4-mcp-server.md) が後でエンドポイントをオンラインにしますが、ディスカバリーファイルは書いた瞬間に正しく、4.4 が着地したときに解決され始めます。プレースホルダーは不要です。 +6. **`curl` で検証する。** 4つの well-known ファイルはすべて、今日の時点で `200`、`Content-Type: application/json` を返し、問題なくパースできなければなりません - これらは今提供する静的ファイルです。それらが *指す* エンドポイント（OpenAPI、OAuth、MCP）は、モジュール3と4が着地するにつれて後で解決されます。CMS のデプロイがそれらをひそかに壊さないよう、4つのファイルを CI のスモークテストに追加してください。 + +## 参考資料 +- [OpenAI Plugin Manifest](https://openai.com/index/chatgpt-plugins/?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) +- [A2A (Agent2Agent) Agent Card 仕様](https://a2a-protocol.org/latest/specification/?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide)（[リポジトリ](https://github.com/a2aproject/A2A?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide)） +- [Model Context Protocol - discovery](https://modelcontextprotocol.io/specification?utm_source=forter&utm_medium=referral&utm_campaign=agentic-readiness-guide) + +## Forter による支援 + +[**Forter エージェンティック・オーケストレーション・スイート**](https://www.forter.com/blog/agentic-orchestration/?utm_source=github&utm_medium=referral&utm_campaign=agentic-readiness-guide&utm_content=m1-2-well-known-agent-files) のホスト型 MCP ゲートウェイを使う場合、Forter が MCP 関連の well-known ファイル（`/.well-known/mcp.json` と任意の MCP ディスカバリーリダイレクト）を公開・保守します - サーバー URL、トランスポート宣言、バージョン固定は、MCP 仕様が変化しても最新の状態に保たれます。これらのファイルはあなたのオリジンではなく Forter のインフラから提供されます。エージェントがすべてのディスカバリーファイルを一か所から取得できるよう、これらがあなた自身のドメイン配下でも解決されるリバースプロキシのルールを追加することを推奨します。 diff --git a/content/ja/m1-3-readable-without-js.md b/content/ja/m1-3-readable-without-js.md new file mode 100644 index 0000000..b286de9 --- /dev/null +++ b/content/ja/m1-3-readable-without-js.md @@ -0,0 +1,41 @@ +--- +id: m1-3-readable-without-js +module: discoverable +moduleNumber: 1 +guidelineNumber: 3 +title: JavaScript なしでコンテンツを描画する +complexity: 3 +impact: 4 +visualChange: low +forterApplies: 'no' +--- + +# 1.3 JavaScript なしでコンテンツを描画する + +## 概要と理由 +ライブのエージェントクローラーは、**ユーザーが質問した瞬間に** あなたのページを取得しますが、そのほとんどは JavaScript を実行しません。あなたのホームページがクライアントサイドでハイドレートする React のシェルだった場合、エージェントには空の `
` しか見えず、答えは競合に取られてしまいます。修正すべきサーフェスは、サーバーレンダリングされた HTML、すべてのビジュアルへの代替テキスト (alt)、ベクトルインデックスがチャンク化できる意味的構造、そして、クローラーがページを解決しページネーションできるようにする完全なドキュメント `` です。 + +## スコアリング +- **工数 3/5** - 本物のエンジニアリングですが、範囲は限られます。スタックがすでにサーバーサイドでレンダリングしているなら小さく、クライアント専用の React / SPA アプリならかなりの作業です。alt テキストの後埋めは機械的ですが時間がかかります。 +- **インパクト 4/5** - AI の回答に現れるか、まったく現れないかの違いです。 +- **視覚的変化: 小** - SSR レンダリングは目の見えるユーザーには不可視で、alt テキストはスクリーンリーダーに届き、意味的 HTML はピクセルを変えません。 + +## 手順 +1. **ホームページと主要な製品ページをサーバーレンダリングする。** これは今日の React や SPA ベースのサイトにおける最大の問題です。これらはほぼ空の HTML ドキュメントを送り、ブラウザでページを組み立てるため、JavaScript を実行しないエージェントには何も見えません。HTML には、単一の `

`、少なくとも500文字の意味のある本文、そして主要な CTA を実在する `` リンクとして含まなければなりません。サイトがクライアントサイドでレンダリングしているなら、マークアップがサーバーを離れる前に完成しているよう、主要ページをサーバーサイドレンダリング (SSR) に移してください。完全な SSR 移行が範囲外なら、既知のクローラー User-Agent に静的 HTML のスナップショットを返すプリレンダリング手順を追加します。`curl https://example.com | grep -c "` タグを数えて監査してください。製品画像は `{製品名} - {主要な属性} - {色/サイズ}` で後埋めし、装飾的な画像は `alt=""`（欠けているのではなく、意図的に空）にします。CMS レベルでは、今後の画像アップロード時に alt を必須フィールドにしてください。 +3. **div スープではなく意味的 HTML。** ページごとに `

` を1つ、`

`/`

` をドキュメント順に、そして `
` ではなく `