概要
- poppy.json は、企業が AI エージェントに対して「自社サービスで提供可能な機能と接続方法」を宣言するための設定ファイルです。
- 特に重要なポイントは、auth.scopes と scope_hints(権限の単位と変更の性質)、連携経路(agent・web・apis)、tasks.endpoint、extensions の4つです。
- スコープ名は基本的に企業側で定義し、changes に未知の値が指定されている場合、エージェントは「取り消しできない変更」として安全側に扱います。
関連リンク:Poppy 1.0 仕様書 / Turkish Airlines の poppy.json(実物)
poppy.json は、企業が AI エージェントに向けて「自社サービスで何ができ、どのように連携すればよいか」を宣言するファイルです。配置場所は https://{ドメイン}/.well-known/poppy.json に固定されています。本記事では、Poppy 1.0 の仕様書に基づき、各フィールドの役割や意味を順を追って解説します(全6回シリーズの第2回)。
なお、本稿で取り扱うのは poppy.json の基本構造、スコープ、サインイン、セッション、拡張機能、企業からのガイダンスの各項目です。operations 拡張(操作ごとの個別の承認手続き)については対象外としています。
最小限の構成例
仕様書に記載されている例を、必須項目が分かるように簡略化したものが以下のコードです。
{
"protocol_version": "1.0",
"organization": { "name": "Example Company", "domain": "example.com" },
"auth": {
"scopes": { "orders:read": "See your orders, returns, and bookings." },
"scope_hints": { "orders:read": { "changes": "none", "personal_data": true } }
},
"agent": { "protocols": [ { "type": "poppy", "endpoint": "https://api.example.com/poppy/conversations" } ] },
"web": { "browser_session_endpoint": "https://example.com/poppy/browser-session" },
"apis": [ { "type": "openapi", "url": "https://api.example.com/openapi.json" } ]
}
フィールド一覧
| フィールド | 必須 | 内容 |
|---|---|---|
| protocol_version | 必須 | major.minor 形式の文字列。1.0 仕様では “1.0” と指定します。 |
| supported_versions | 任意 | 並行してサポートされている他バージョンの定義ファイル URL。 |
| organization | 必須 | name、domain(配信元ホスト名)、および任意で logo_uri を指定。 |
| auth | 任意 | issuer、disabled、scopes、scope_hints。認証方式やスコープを宣言します。 |
| agent.protocols[] | 条件付き必須(注参照) | 自社対話型エージェントに関する情報。type、endpoint、description、アクセス制御(session または signed_in)などを定義する。 |
| web | 条件付き必須(注参照) | browser_session_endpoint、disabled、unscoped など。Web サイト操作に関する設定。 |
| apis[] | 条件付き必須(注参照) | API 仕様。type(openapi、mcp など)、url、description を指定。 |
| tasks | 任意 | endpoint。対応不可タスク、公開スキル、フィードバック送信先などを返すエンドポイント。 |
| extensions | 任意 | 拡張機能名をキーとして、バージョンごとの設定を一覧で定義する。 |
※ 注:agent、web、apis のうち、少なくとも1つの定義が必要です。
連携経路の宣言(agent / web / apis)
企業は、エージェントからのアクセス方法として3つの経路を提供できます。自社の対話エージェントとやり取りする agent、ブラウザ操作を許可する web、直接 API を呼び出させる apis の3種類があり、これらは複数同時に指定できます。
agent と apis には description(説明文)を設定できます(web には description はありません)。仕様上、これは外部エージェントが「どの経路を使って処理すべきか」を判断するためのものです。なお、web の disabled フラグは「ブラウザ操作によるアクセスを推奨しない」という意図を示しますが、技術的な強制力はありません。
スコープ設計:auth.scopes と scope_hints
スコープは、ユーザーがエージェントに委任する権限の最小単位です。仕様上のポイントは以下のとおりです。
- スコープ名は、基本的に企業側が設計します(プロトコル自体が定義するスコープは poppy:browser-sign-in の1つだけです)。auth.scopes に名前と説明文のペアを記述します。なお、ここで定義した説明文は OpenAPI 仕様内の記述よりも優先して参照されます。
- scope_hints 内の changes は、操作に伴う変更の性質(none:変更なし、reversible:取り消し可能、irreversible:取り消し不可)を表します。未知の値が返された場合、エージェントは安全のため irreversible(取り消し不可)として扱います。
- scope_hints 内の personal_data は、そのスコープが個人情報へのアクセスを伴うかどうかを真偽値で示します。
- 企業側は、リクエストされていない余分なスコープを付与してはいけません(要求より少ない範囲で付与することは可能です)。存在しないスコープが要求された場合は invalid_scope エラーで拒否されます。
- 有効期限切れなどで追加権限が必要になった場合、エージェントはユーザーに再サインインを求め、不足しているスコープだけでなく、まだ必要な既存のスコープも含めて、1回で再要求する必要があります。
補足:一部の二次情報では poppy:read や poppy:write を標準スコープとして紹介している例もありますが、今回確認した公式仕様書内にその定義は見られませんでした。そのため、「スコープ名は各企業が定義する(プロトコル定義は poppy:browser-sign-in のみ)」という仕様書のルールを優先して解説しています。
2つのサインイン方式
- Direct Sign-In:ユーザーがブラウザ上で企業の認証ページに直接サインインし、要求されたスコープの承認・拒否を選択する方式。エージェント側の認可リクエストには、prompt=consent を含める必要があります(リダイレクトを、認証URLを開いた同じ端末だけで受け取る場合は例外です)。
- Device Sign-In:エージェントが認証用 URL とコードを表示し、ユーザーが別デバイスから承認を行う方式。仕様上、単に URL を開いただけで自動承認してはならないと定められています。
なお、個別の操作ごとに都度承認を挟む仕組みは、これら標準サインインフローの範囲外となります。これは Operations と呼ばれる拡張仕様にて規定されています。
セッション管理:リクエストごとの認証・検証
エージェントは、API や対話エンドポイントにリクエストを送信する際、必ず Poppy-Session ヘッダーを付与します。この中身は JWT で構成されており、主な仕様は以下のとおりです。
- ヘッダー構成:typ は poppy-session+jwt、alg は ES256、kid には委任鍵の JWK thumbprint を指定します。
- ペイロード(クレーム):iss(エージェントの client_id)、aud(企業の識別子)、sid(セッション ID)、sub(ユーザー ID)、htm、htu、iat、jti、および ath(アクセストークンがある場合のみ)を含めます。
- 委任(Delegation):エージェントの鍵で署名された短命の JWT です。typ は poppy-delegation+jwt、cnf.jwk に委任公開鍵を持ち、有効期間は iat から24時間以内に制限されます。
企業側は送られてきた委任と署名を検証し、aud、htm、htu、iat などを確認したうえで、client_id、sid、ユーザー ID をもとに該当セッションを特定します。また、バージョンは Poppy-Version ヘッダーで通知され、互換性がなければ version_unsupported(HTTP 400)エラーが返されます。単にセッションを終了する場合は、エージェント側が該当の sid を使用停止するだけで完結します。完全にサインアウトする場合はリフレッシュトークンを失効させますが、セッション自体は未サインイン状態のまま維持されます。
拡張機能(extensions):コア仕様を保った機能拡張
extensions フィールドには、拡張機能名をキーとして、対応するバージョンや設定情報を記述します。
"extensions": {
"example.com/gift-wrap": [ { "version": "2", "endpoint": "https://..." } ]
}
- ドメイン名を含まない標準的な名前は仕様側で予約されています。サードパーティが独自に拡張機能を作成する場合は、自社で管理するドメイン名を接頭辞として使用します。
- エージェントは、使用する拡張機能とそのバージョンを Poppy-Extensions ヘッダーで明示します。
- 未対応の拡張機能や未知のフィールドが存在する場合、双方はそれを無視して処理を継続します。ただし、特定の拡張機能が必須である場合、企業側は extension_required(HTTP 403)エラーを返し、レスポンス内で必要な拡張機能名を指定します。
- 仕様書では具体例として、Mediated Sign-In(トークンエンドポイントに新しいグラント種別を追加する拡張)や、個別の操作承認を扱う Operations などが挙げられています。
エージェント向け案内:tasks.endpoint
tasks.endpoint は、エージェントが実際の作業を開始する前に参照するガイドライン情報を取得するためのエンドポイントです。エージェントは Session ヘッダーを付与して GET リクエストを送信します(アクセストークンは付与しません)。正常時は HTTP 200 と JSON が返されます。なお、セッションごとに返却内容を動的に変える場合は、Cache-Control ヘッダーに private または no-store を指定する必要があります。レスポンスの基本構造は以下のとおりです。
{
"excluded_tasks": [
{ "task": "Send a wire transfer",
"alternative": {
"instructions": "Wire transfers can only be sent in the Example app, after the User verifies their identity.",
"references": [ { "type": "web", "url": "https://example.com/transfers/wire" } ]
} },
{ "task": "Close an account" }
],
"skill_index": { "$schema": "...", "skills": [ { "name": "manage-bookings", "type": "skill-md", "url": "...", "digest": "sha256:..." } ] },
"feedback": { "endpoint": "https://api.example.com/poppy/feedback" }
}
- excluded_tasks:自動化の対象外とするタスクのリスト。代替手順がある場合は alternative フィールドに案内を記載できます。
- skill_index:各種タスクの実行手順を定義した「スキル」の一覧。各項目には name、description、type(skill-md または archive)、url、digest(SHA-256 ハッシュ値)が含まれます。エージェントは digest の整合性を検証してからスキルを読み込みます。
- feedback:エージェント側から企業へフィードバックや意見を送信するためのエンドポイント情報。
※ スキルはあくまで手順の案内であり、アカウント権限や OAuth スコープを付与するものではありません。また、ユーザーによる承認手続きの代わりになるものでもない点に注意してください。
実際の定義ファイルを見る
実例として、Turkish Airlines が公開している poppy.json の具体的な解読を第3回で行います。
参考・出典
情報確認日:2026年11月18日
- Poppy 1.0 仕様書(※ operations 拡張のセクションを除く)
- Releasing Personal Agent Protocol 1.0(Sierra)
- Poppy Spec Status(独立トラッカー)