# SDK App の作成と管理 SDK App は、自社のアプリケーションが接続する [Agent Channel](/ja/products/ai-studio/agent-channels) です。SDK App を作成すると、その共有作業フォルダが Treasure AI Studio の外部から到達できるようになります。そのためウィザードが尋ねるのは、どのフォルダを参照するか、誰の権限で動くか、の2点だけです。このページでは、その判断、生成される資格情報の保管、そしてその後の運用 — 停止と再開、実行者の引き継ぎ、削除 — を扱います。 自社でホストするアプリケーションがチャットを開始する必要が出てきたら設定してください。SDK App は一度作り、そのトークンをサーバーのシークレットマネージャーに保存すれば、以降はアプリケーションがそれを使い続けます。 ## 前提条件 - 自分が **manage 権限**を持つ[共有作業フォルダ](/ja/products/ai-studio/shared-folders/)。ウィザードに表示されるのは manage 権限を含むワークモードを持っているフォルダだけで、アーカイブ済みのフォルダは選べません。 - チャネルを作成する権限。共有フォルダの manage 権限は常に必要で、アカウントの作成ポリシーによっては、さらにアカウント管理者である必要があります。作成ポリシーは Agent Channels ページの **作成できるユーザー** に表示されます（[Agent Channels を作成できるユーザーを設定する](#agent-channels-%E3%82%92%E4%BD%9C%E6%88%90%E3%81%A7%E3%81%8D%E3%82%8B%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC%E3%82%92%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B)を参照）。**アカウント管理者のみ** になっていて自分が管理者でない場合、**新規 SDK App** は押せません。 - Agent Channels の作成と管理は **Web 版または Desktop 版**の Treasure AI Studio で行います。Mobile アプリからは設定できません。 - 受け取ったトークンを置く場所。テキストファイルではなくシークレットマネージャーを用意してください。表示は一度だけです。 始める前に、誰が実行者になるべきかを決めておいてください。作成者が実行者になり、そのチャネルが作るすべてのチャットはその人の権限・コネクション・クレジットで動きます。チャネル単位の設定ではなくこの選択がチャネルの範囲を決める理由は、[Agent Channel のチャットが到達できる範囲](/ja/products/ai-studio/agent-channels/channel-chats#%E5%88%B6%E9%99%90%E3%81%95%E3%82%8C%E3%81%A6%E3%81%84%E3%81%AA%E3%81%84%E3%82%82%E3%81%AE)で説明しています。 ## SDK App を作成する 1. **設定 → エージェントチャネル**を開きます。**SDK Apps** の見出しの下に、アカウントのチャネルが一覧表示されます。最初の SDK App を作成するまでは、一覧の代わりに **アプリケーションを接続** の案内が表示されます。 SDK App がまだない状態の Agent Channels 設定ページ。作成できるユーザーが「すべてのユーザー」の行、新規 SDK App ボタン付きの SDK Apps 見出し、3 ステップの接続案内が並んでいる 1. **新規 SDK App** を選択します。ウィザードが「ステップ 1/2」で開き、最初に利用できる共有フォルダを確認します。manage 権限を持つフォルダが1つもない場合は、入力欄の代わりに *「SDK App の作成には、少なくとも 1 つの共有フォルダの manage 権限が必要です。フォルダの管理者に manage 権限を依頼してください。」* と表示されます。使えない名前を入力してしまうことはありません。 新規 SDK App ウィザードのステップ 1/2。入力欄の代わりに、SDK App の作成には少なくとも 1 つの共有フォルダの manage 権限が必要だという案内が表示されている 1. **名前** に名前を入力します。たとえば *「マーケティングサイトのキャンペーンアシスタント」* のような形です。フォルダ名ではなくアプリケーションの名前を使ってください — これが一覧と後の監査でチャネルを識別する手掛かりになります。255文字まで。 2. 必要に応じて、同僚向けの**コメント**を追加します。管理しているチームや連絡先などです。1,000文字まで。チャネルの停止や実行者の引き継ぎの際のメモもここに残るため、共有のメモとして扱い、恒久的な記録として当てにしないでください。 3. ブラウザからメッセージング API を直接呼べるようにする場合は、**詳細設定**を展開して **エンドユーザーのブラウザからのチャット操作を許可** を選択します。チャットごとのトークンをブラウザに渡す構成でない限りオフのままにしてください — オフなら、ゲートウェイは `Origin` ヘッダーを伴う呼び出しをすべて拒否するので、ページ上で動くスクリプトがサーバーを迂回できません。オンにする前に[ブラウザアクセス](/ja/products/ai-studio/agent-channels/tokens#%E3%83%96%E3%83%A9%E3%82%A6%E3%82%B6%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9)を読んでください。この設定は後から変更できます。 新規 SDK App ウィザードのステップ 1/2。名前とコメントが入力され、詳細設定を展開してブラウザからのチャット操作を許可するチェックボックス (オフ) が表示されている 1. **次へ** を選択し、チャネルのチャットが参照する**共有フォルダ**を選びます。入力すると絞り込まれ、manage 権限を持つフォルダだけが表示されます。 2. フォルダの下に表示される同意文を読みます。自分が何を許可しているのかがそこに書かれています。アプリケーションのエンドユーザーがそのフォルダを読み取り専用で参照するチャットを作成し、それが自分の権限とコストで動き、各チャットの作業領域はチャット終了時に破棄される、という内容です。**実行者**は自分として表示され、ここで他人に設定することはできません — 同じフォルダの別の管理者が、後から実行者を引き継げます。 ウィザードのステップ 2/2。共有フォルダが選ばれ、実行者として自分が表示され、そのフォルダについての同意文と、有効期限 90 日とその日の終わりの日時が表示されている 1. 最初のトークンの**有効期限**を選びます。**7 日**、**30 日**、**90 日**（既定）、カスタム日付、または**無期限**です。確定した日付は、個人タイムゾーンでのその日の終わりとしてフィールドの下に表示され、そこにタイムゾーン名も併記されます。有効期限はトークン発行時に確定し、後から変更できません。別の期限にしたい場合は、新しいトークンを発行して古いものを無効化します。 2. **App を作成してトークンを発行** を選択します。チャネルの作成と最初の Gateway Token の発行が1回で行われ、完了画面が表示されます。 App は作成されたがトークンが発行されなかった場合 この2つは別のリクエストなので、後半だけが失敗することがあります。その場合ウィザードは最初からやり直させるのではなく **App を作成しました — トークンは未発行です** と表示します。SDK App 自体は存在しています。**トークンの発行を再試行** を選ぶか、**後で App ページから発行する** を選んで、準備ができたときにチャネルの詳細ページから発行してください。 ## 接続情報を保管する 完了画面は **サーバーを接続** という見出しで、アプリケーションに必要な2つの値を環境変数の形で表示します。 ```bash AGENT_GATEWAY_URL=<アカウントの Agent Gateway URL> GATEWAY_TOKEN=tasgwt_<シークレット> ``` 完了画面「サーバーを接続」。AGENT_GATEWAY_URL と GATEWAY_TOKEN の 2 行とすべてコピーボタン、トークンは二度と表示されないという警告、統合ガイドへのリンク、値を保存しましたのチェックボックス、押せない状態の完了ボタンが並んでいる トークンが表示されるのはこの一度だけです このシークレットは二度と表示されず、Treasure AI Studio 側で復元することもできません。ページを離れる前に、両方の値をサーバーのシークレットマネージャーにコピーしてください。トークンを紛失した場合の復旧手段は、それを無効化して新しく発行することであり、参照することではありません。 1. **すべてコピー** を選択し、シークレットマネージャーに貼り付けます。 2. **値を保存しました** を選択します。これを選ぶまで **完了** ボタンは押せません。 3. **完了** を選択します。 チェックを入れずにページを離れようとすると *「トークンをまだ保存していません」* と表示され、**戻る** が提示されます。本当に保存済みでない限り、戻ってください。 ゲートウェイの URL はサイトごとに決まっていて変わりません。後から必要になった場合は、チャネルの詳細ページに **Agent Gateway URL** として表示されます。 これで接続情報が揃いました。次は実装です。[Vercel AI SDK でチャットアプリを作る](/ja/products/ai-studio/agent-channels/building-an-app)に進んでください。 ## Agent Channels ページの読み方 **設定 → エージェントチャネル**の一覧は、アカウントの外部入口を点検する場所です。SDK App は1行として表示されます。 | 列 | 意味 | | --- | --- | | **名前** | チャネルの名前。コメントが設定されていれば、その下に表示されます | | **フォルダ** | このチャネルのチャットが参照する唯一の共有作業フォルダ | | **実行者** | チャットがその権限とクレジットで動くユーザー。メールアドレスで表示されます。**実行者なし** が警告色で表示されている場合は実行者が空席で、チャネルは動作しません | | **ステータス** | チャネルの現在の状態（後述）。無効なチャネルには *「接続は停止中」* が併記されます | | **目のアイコン**（見出しのない最後の列） | チャネルの詳細ページを開きます | 同じ共有作業フォルダに対する 3 つの SDK App の一覧。実行者なしで「停止中 — 実行者が必要です」のもの、有効なもの、無効でステータスの下に「接続は停止中」と出ているものが並んでいる アカウントのすべてのメンバーがすべての行を見られます。チャネルが存在すること自体はアクセス権にならないためです。そのフォルダを管理しているか、実行者であるか、アカウント管理者である場合を除き、**フォルダ**と**実行者**のセルには「—」と鍵アイコンだけが表示されます。マウスを重ねると *「アクセス権のあるメンバーにのみ表示されます」* と表示されます。 アカウント管理者でないメンバーから見た Agent Channels ページ。作成できるユーザーはアカウント管理者のみでトグルはなく、新規 SDK App は押せず、すべての行のフォルダと実行者のセルが「—」と鍵アイコンになっている 詳細ページにも同じマスクが適用されます。名前とステータスに加えて、*「この SDK App の存在は確認できますが、フォルダ、実行者、接続設定、トークンはアクセス権のあるメンバーにのみ表示されます。」* という案内だけが表示されます。 マスクされた SDK App の詳細ページ。名前、有効のステータス、フォルダ・実行者・接続設定・トークンはアクセス権のあるメンバーにのみ表示されるという鍵付きの案内だけが表示されている ## Agent Channels を作成できるユーザーを設定する Agent Channels ページの上部には、アカウントの作成ポリシーが **作成できるユーザー** として表示されます。値は **すべてのユーザー** か **アカウント管理者のみ** のどちらかで、アカウントのすべてのメンバーが確認できます。既定は **すべてのユーザー** で、アカウント単位の制限はかかりません。ただし、どちらの場合も共有フォルダの manage 権限は必要です。 アカウント管理者には、値の横にトグルも表示されます。**すべてのユーザーに Agent Channels の作成を許可** をオフにすると作成できるのはアカウント管理者だけになり、オンに戻すと再びすべてのユーザーが作成できます。変更が適用されるのは、それ以降に作成するチャネルだけです。既存のチャネルとトークンはそのまま動き、既存のチャネルで新しいトークンを発行することも制限されません。 Agent Channels ページの作成できるユーザーの行。アカウント管理者のみに設定され、トグルはオフになっている ## チャネルのステータス | ステータス | 意味 | 解除の方法 | | --- | --- | --- | | **有効** | チャネルは接続を受け付けています | — | | **無効** | 誰かがチャネルをオフにしました。配下のすべてのトークンによる認証が直ちに停止しますが、トークン自体は無効化されていません | トグルを再びオンにする | | **停止中 — 実行者が必要です** | 実行者が降りたため空席になっています。何も動かず、空席の間はチャネルを有効にできません。トークンは保持されます | フォルダの管理者が **実行者を引き受ける** を選び、その後チャネルを有効にする | 実行者がそのフォルダのワークモードを失った場合も、ステータスは変わらないままチャネルは接続を受け付けなくなります。権限はチャネルの保存時ではなく、リクエストごとに評価されます。フォルダの管理者がフォルダそのものを削除すると、そのフォルダのチャネルも一緒に削除されます。[チャネルを削除する](#%E3%83%81%E3%83%A3%E3%83%8D%E3%83%AB%E3%82%92%E5%89%8A%E9%99%A4%E3%81%99%E3%82%8B)を参照してください。 ## チャネルを管理する 一覧からチャネルを開きます。そこで何ができるかは自分のロールによって決まります。**実行者**と**そのチャネルのフォルダの管理者**は、編集・トークンの発行と無効化・削除ができます。**アカウント管理者**はチャネルの停止と再開だけです。実行者でないフォルダの管理者は、実行者を引き継げます。降りられるのは実行者本人だけです。 有効な SDK App の詳細ページ。有効 / 無効のトグル、同意内容の要約、フォルダ・実行者・作成者の概要、Agent Gateway URL・ブラウザアクセス・2 つのチャットトークン期限の接続設定、トークンの発行ボタン付きのトークン一覧、実行者から降りるボタン、危険な操作の SDK App を削除が並んでいる 止め方は2種類あり、取り消せるかどうかが違います。混同すると戻せない操作を選んでしまうため、先に区別しておいてください。 | 操作 | 対象と効果 | | --- | --- | | **チャネルの停止** | チャネル全体を止めます。トグルを **無効** に切り替えるだけで、トークンは1本も失われません。**取り消せます** — トグルを戻せば元の構成のまま再開します | | **トークンの無効化** | トークン1本だけを恒久的に使えなくします。チャネルと他のトークンはそのまま動き続けます。**取り消せません** — 必要になったら新しいトークンを発行します | ### チャネルの停止と再開 ヘッダーの **有効 / 無効** のトグルを使うと、何も壊さずにチャネルを止められます。オフにする際に任意のコメントを求められます。理由を書いてください — 次にこれを見た人が、再開してよいかを判断する材料はそのメモだけです。配下のすべてのトークンによる認証が直ちに止まり、トグルを戻せば以前とまったく同じ構成が復元されます。 インシデント対応にはこれが適した手段です。直ちに効き、取り消せて、しかもアカウント管理者が取れる唯一のチャネル操作です。これは意図的な設計です。管理者は問題をいったん止められますが、取り消せない操作は行えません。 SDK App を無効にするかを確認するダイアログ。配下のすべてのトークンの認証が直ちに止まることの説明、任意のコメント欄、無効化ボタンがある ### チャネルの設定を変更する 詳細ページの **編集** から、チャネルの名前、コメント、ブラウザアクセスの可否、そして Chat Access Token の2つの有効期間を変更できます。フォルダと実行者は含まれません。この2つはチャネルが同意を得た前提そのもので、変えれば別の取り決めになるためです。 有効期間は **アイドル期限 (秒)** と **最大期限 (秒)** として秒単位で入力します。空欄にすると既定値 (アイドル 24 時間、最大 30 日) が使われます。入力する場合は秒数を正の整数で指定し、アイドル期限を最大期限以下にしてください。 SDK App の編集ダイアログ。名前、コメント、ブラウザアクセスのチェックボックス、空欄のアイドル期限と最大期限 (秒) があり、空欄なら 24 時間と 30 日が使われると書かれている ### 実行者を引き継ぐ / 降りる 実行者の交代には本人の同意が必要なため、降りる人と引き受ける人がそれぞれ自分で操作する形でしか行えません。 - **降りる場合**は **実行者から降りる** を選択します。同じ操作で実行者が空席になり、チャネルが停止します。既存のトークンは保持されますが動作しなくなります。何が起きたのかがフォルダの管理者に伝わるよう、コメントを添えてください。 - **引き継ぐ場合**は、チャネルを開いて **実行者を引き受ける** を選択します。そのチャネルのフォルダを管理している必要があり、現在の実行者がいるかどうかに関係なく引き継げます。引き受けても停止中のチャネルは再開しません — その後で有効にしてください。そこが「自分の権限とコストで動かす」ことに同意する時点になります。 「停止中 — 実行者が必要です」となった SDK App の詳細ページ上部。トグルはオフで、実行者を引き受けるボタン付きのバナーに、既存のトークンは保持され、有効にすると自分の権限とコストで動くことが書かれている 他人を実行者に任命する方法はありません。引き継ぎは任命ではなく、引き受けです。 ### トークンの発行と無効化 **トークン** セクションには、そのチャネルでこれまでに発行したすべてのトークンが、現在有効なものもそうでないものも一緒に並びます。ローテーションが古い行と新しい行の並びとして読めるようにするためです。各行にはトークンのヒント、状態、発行日と発行者、有効期限、最終使用が表示されます。 発行と無効化は、実行者とそのチャネルのフォルダの管理者が行えます。ローテーションと、無効化が何を止めるのかは [Gateway Token と Chat Access Token](/ja/products/ai-studio/agent-channels/tokens)で扱います。 ### チャネルを削除する 詳細ページ下部の**危険な操作**にある **SDK App を削除** は、チャネルを恒久的に削除します。配下のすべてのトークンも二度と使えなくなります。確認のためチャネル名の入力を求められます。フォルダの管理者が共有作業フォルダを削除した場合も、そのフォルダのチャネルはすべて同じように削除されます。 削除してもそのチャネルが作ったチャットは削除されません。実行者のチャット一覧に残り、アカウントの通常の保持ポリシーの対象になります。また使う可能性があるなら、削除ではなくチャネルの停止を選んでください。削除は取り消せず、チャネルを作り直すとトークンが変わってアプリケーションの再デプロイが必要になります。 ## トラブルシューティング | 症状 | 原因と対処 | | --- | --- | | ウィザードに入力欄が出ず、*「SDK App の作成には、少なくとも 1 つの共有フォルダの manage 権限が必要です」* と表示される | manage 権限を含むワークモードをどの共有作業フォルダでも持っていません。対象フォルダの管理者に付与を依頼するか、チャネルの作成を依頼してください | | **新規 SDK App** が押せない、またはウィザードに「Agent Channels を作成できるのはアカウント管理者だけ」と表示される | **作成できるユーザー** が **アカウント管理者のみ** になっていて、自分はアカウント管理者ではありません。アカウント管理者にチャネルの作成を依頼するか、すべてのユーザーへの許可を依頼してください | | チャネルが **停止中 — 実行者が必要です** になっている | 実行者が降りました。フォルダの管理者が **実行者を引き受ける** を選び、その後チャネルを有効にしてください | | **有効 / 無効** のトグルがオンにできない | 実行者が空席です。フォルダの管理者が **実行者を引き受ける** を選ぶと、トグルをオンにできるようになります | | アプリケーションがゲートウェイから毎回 `401` を受け取る | トークンが無効化済みか期限切れ、チャネルが停止中、実行者のフォルダへのアクセスが失われている、またはチャネルかそのフォルダが削除されています。まずチャネルのステータスとトークンの行を確認してください | | ブラウザに関するメッセージとともに `403` が返る | ブラウザアクセスがオフの状態で、呼び出しに `Origin` ヘッダーが付いていました。中継サーバーがブラウザの `Origin` ヘッダーを転送してしまっている（転送してはいけません）か、ブラウザが直接ゲートウェイを呼んでいます。[ブラウザアクセス](/ja/products/ai-studio/agent-channels/tokens#%E3%83%96%E3%83%A9%E3%82%A6%E3%82%B6%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9)を参照してください | | トークンを紛失した | 復元できません。そのトークンを無効化して、新しいトークンを発行してください | ## 次のステップ - [Gateway Token と Chat Access Token](/ja/products/ai-studio/agent-channels/tokens) — ローテーション、無効化、チャットごとの資格情報 - [Vercel AI SDK でチャットアプリを作る](/ja/products/ai-studio/agent-channels/building-an-app) — アプリケーション側の実装 - [Agent Channel のチャットが到達できる範囲](/ja/products/ai-studio/agent-channels/channel-chats) — チャネルのチャットができること・できないこと - [共有作業フォルダ](/ja/products/ai-studio/shared-folders/) — ワークモードと、フォルダを管理するのは誰か