agent-friendly-design

エージェントフレンドリーな設計

AI エージェントが実際に使えるサイトやアプリの作り方。

このガイドの目的

デザインに関するガイダンスの多くは、エージェントが UI を 構築する 方法を扱っています。このスキルでは、エージェントが UI を 利用する 方法を扱います。サイトの利用者は、もはや人間だけではありません。2024 年には自動トラフィックが人間のトラフィックを上回り、ウェブ上のやり取り全体の 51％を占めました。エージェントはユーザーに代わって、サイトを閲覧し、比較し、購入し、調査し、操作します。

サイトがエージェントから見えなければ、増え続けるウェブの大多数から見えないのと同じです。

核心となる考え方

もともとはスクリーンリーダー向けに作られたアクセシビリティツリーが、AI エージェントとウェブサイトをつなぐ主要なインターフェースになりつつあります。OpenAI の Atlas は、ページ構造の解釈に ARIA タグを明示的に使用しています。Microsoft の Playwright MCP が提供するのは、スクリーンショットではなくアクセシビリティスナップショットです。視覚を優先するエージェント（Anthropic Computer Use、Google Mariner）でさえ、信頼性を高めるためにアクセシビリティデータを取り入れています。

**エージェント向けの構築とアクセシビリティ向上は、同じ取り組みです。**一方のために行った改善は、もう一方にも効果があります。

チェックリスト

1. セマンティック HTML（必須）

エージェントはレイアウトを「見る」ことができません。読み取るのは構造です。div だらけのマークアップは認識されません。

• ネイティブ要素を使用します：<button>、<nav>、<main>、<article>、<section>、<header>、<footer>、<aside>
• 見出し階層を適切に設定します：<h1> から <h6> まで、レベルを飛ばさないでください
• <label> 要素をフォーム入力に明示的に関連付けます（for 属性を使用）
• 表形式のデータには <thead>、<th>、scope 属性を含む <table> を使用します
• リンクには <a> 要素、ボタンには <button> 要素を使用します。<div onclick> は使わないでください
• フォームには <form> を使用し、グループには <fieldset> と <legend> を使います
• 意味のある <img alt> テキストを指定します（「image1.png」のようなテキストは避けてください）

テスト： CSS を無効にしても、ページの内容を理解できますか？理解できるなら、エージェントにも理解できます。

2. ARIA：便利ですが、万能ではありません

ARIA はセマンティック HTML を補完するものであり、置き換えるものではありません。ネイティブ要素では操作を表現できない場合に使用します。

• 表示テキストのないボタンやリンク（アイコンボタン、閉じるボタン）に aria-label を指定します
• トグル、ドロップダウン、アコーディオンに aria-expanded を指定します
• エージェントに認識させる必要がある動的コンテンツ（ステータスメッセージ、通知）には aria-live 領域を使用します
• ネイティブ要素が存在しない場合に限り、role 属性を使用します（例：role="tablist"、role="dialog"）
• 追加のコンテキストが必要な複雑なフォームフィールドには aria-describedby を使用します
• エージェントが無視すべき装飾要素には aria-hidden="true" を指定します

避けること： あらゆる要素に ARIA を付けないでください。ラベルを付けすぎるとノイズになります。ネイティブ要素で役割がすでに伝わる場合は、ARIA を省略します。

3. 機械可読な状態

エージェントは視覚的な手がかりを解釈できません。ボタンが灰色でも、disabled が設定されていなければ何の意味もありません。

• 無効なコントロールには disabled 属性を使用します
• トグルの状態には aria-selected、aria-checked、aria-pressed を使用します
• 読み込み状態：コンテンツを更新しているコンテナーに aria-busy="true" を指定します
• エラー状態：検証エラーのあるフィールドに aria-invalid="true" を指定し、aria-errormessage でエラーテキストに関連付けます
• 空の状態：実際の DOM コンテンツをレンダリングします（CSS の ::after 疑似要素だけにしないでください）
• ページネーション：現在のページに aria-current="page" を指定します

ルール： 人間が見て状態を判断できるなら、エージェントも DOM を読んで状態を判断できるようにします。

4. 構造化データ（JSON-LD + Schema.org）

コンテンツがどのような構造かだけでなく、何であるかをエージェントが理解するのに役立ちます。

• 適切に Organization、Product、Article、BreadcrumbList、FAQPage、HowTo のスキーマを使用します
• マイクロデータや RDFa よりも、<script type="application/ld+json"> 内の JSON-LD を推奨します
• 構造化データを表示コンテンツと同期させます。キーワードを詰め込まないでください
• エージェントが情報の新しさを把握できるよう、dateModified と datePublished を含めます
• 商品ページ：価格、在庫状況、レビュー、SKU
• 記事：著者、datePublished、見出し、説明

5. llms.txt

/llms.txt に配置する、サイトの概要を簡潔に LLM に伝える Markdown ファイルです。robots.txt の言語モデル版です。

# Your Project Name

> Brief description of what this site/product does.

## Docs

- [Getting Started](https://yoursite.com/docs/getting-started): How to set up...
- [API Reference](https://yoursite.com/docs/api): Full API documentation...

## Optional

- [Changelog](https://yoursite.com/changelog): Recent updates...

• すばやくコンテキストを読み込めるよう、2000 トークン未満に抑えます
• 重要なページの詳細な Markdown 版へのリンクを記載します（可能であれば URL に .md を追加します）
• コンテンツが変更されたら更新します。古い llms.txt は、ない場合よりも好ましくありません
• 仕様：https://llmstxt.org

6. クロール可能性とレンダリング

エージェントがすべて JavaScript を実行できるわけではありません。多くのエージェントは生の HTML を利用します。

• 重要なコンテンツは、サーバーサイドレンダリング（SSR）または事前レンダリングを行います
• クライアント側のみで実行される JavaScript の背後に、重要な情報を隠さないでください
• robots.txt を更新し、既知の AI ユーザーエージェント（ChatGPT-User、OAI-SearchBot、Googlebot など）を許可します
• sitemap.xml を最新の状態に保ちます
• 応答時間を短くします（エージェントは 10～30 秒でタイムアウトする場合があります）
• 重要なコンテンツは HTML ソースの上部に配置します（エージェントはスクロールしない場合があります）

7. 予測可能なインタラクション

エージェントはパターンを見つけて自動化します。一貫性がないと、その動作が妨げられます。

• 命名を統一します。あるページのボタンのテキストが「カートに追加」なら、別のページで「今すぐ購入」にしないでください
• 標準的な HTML フォームコントロールを使用します（入力欄のように見えても実際にはそうではない、カスタム JavaScript ウィジェットは使用しないでください）
• 類似したページ間で、ID とクラス名に一貫性を持たせます
• 複雑な閉じる操作が必要なモーダル、ポップアップ、インタースティシャルは避けます
• 閲覧時のログイン制限を最小限に抑えます（可能な場合はゲストチェックアウトを許可します）
• 重要ではないフローで CAPTCHA を避けます。CAPTCHA はエージェントの動作を完全に妨げます

8. API ファーストのパターン

エージェントが HTML をスクレイピングせずにデータを取得できれば、すべての人にメリットがあります。

• コアデータ（製品、コンテンツ、ステータス）用の REST または GraphQL エンドポイント
• 公開され、llms.txt からリンクされた OpenAPI 仕様
• MCP（Model Context Protocol）サーバーによる直接的なツールアクセス。エージェントはブラウザー自動化を使わず、MCP 経由で API を呼び出せます
• データに対する自然言語クエリ向けの NLWeb 統合
• エージェントが操作するネイティブインターフェイス向けの A2UI（Google のオープンプロジェクト。エージェントがホストアプリのスタイルを継承するコンポーネントの設計図を送信します）
• エージェントが反応する必要のある状態変更用の Webhook

9. 人だけでなくエージェント向けのコンテンツ

• 明確で説明的なページタイトルを付けます（エージェントは <title> を重視します）
• ページの内容を正確に説明するメタディスクリプションを設定します
• 「こちらをクリック」のような一般的なリンクテキストではなく、「料金の詳細を見る」のような説明的なリンクテキストを使用します
• 長いコンテンツは見出しを使ってセクションに分けます
• 内容が密なページには、概要や TL;DR を用意します
• 情報の伝達を画像だけに頼らず、必ずテキストによる代替情報を用意します

10. エージェントでテストする

• ブラウザーの開発者ツールを使ってアクセシビリティツリーを確認します（Chrome：Elements の Accessibility ペイン）
• AI ブラウザーエージェント（ChatGPT Atlas、Playwright MCP）で重要なフローをテストします
• Lighthouse のアクセシビリティ監査を実行します。検出される問題の多くは、エージェントにも影響します
• フォームをプログラムから入力できることを確認します
• 動的コンテンツの更新が、見た目だけでなく DOM にも反映されることを確認します

デュアルインターフェイスの考え方

1 つのページに 2 つのインターフェイスを構築しています。

人間向けインターフェイス： 視覚的な階層、色、タイポグラフィ、余白、動き、楽しさ エージェント向けインターフェイス： セマンティック構造、ARIA ロール、JSON-LD、予測可能なコントロール、API エンドポイント

両者は競合しません。適切に構造化されたセマンティックなページは、人にもエージェントにも使いやすくなります。デュアルインターフェイスはトレードオフではなく、機能の追加です。

適用範囲

• すべての Web プロジェクト： 項目 1～3（セマンティック HTML、ARIA、機械可読な状態）は必須です
• 一般公開サイト： 項目 4～6（構造化データ、llms.txt、クロール可能性）を追加します
• 製品／eコマース／SaaS： 項目 7～9（予測可能なインタラクション、API ファースト、コンテンツの最適化）を追加します
• 完全なエージェント対応： 10 項目すべて

注目すべき新興プロトコル

プロトコル	機能	状況
llms.txt	LLM 向けの Markdown サイト概要	多くのサイトで採用されており、実装も簡単
MCP	エージェントがツールに直接アクセスできます（ブラウザーは不要です）	急速に普及中、Anthropic 主導
NLWeb	データに対する自然言語クエリ	Microsoft のオープンソースプロジェクト、初期段階
A2UI	エージェント主導のネイティブ UI コンポーネント	Google による初期仕様
AGENTS.md	プロジェクト単位のエージェント向け指示	コミュニティでの採用が拡大中

蓄積

エージェントにとって使いやすいサイトを構築または監査した後は、次のことを行います。

• エージェントが苦労したパターンを記録し、このスキルのチェックリストに追加します
• 最も大きな違いをもたらした ARIA パターンを記録し、チームで共有します
• アナリティクスでエージェントのトラフィック（ユーザーエージェント文字列）を追跡し、実際の利用状況を把握します
• 新しいプロトコルが成熟するにつれてテストし（MCP、A2UI）、このガイドを更新します

ウェブはページ主導からアクション主導へと移行しています。エージェント向けの設計は将来への備えではなく、今日のトラフィックに対応するためのものです。