scenario-team-admin

シナリオチームの管理

概要

エンタープライズチームは、生成に使うエージェントから Scenario を管理できます。実行を許可するモデル、チームのメンバーと所属プロジェクト、各メンバーの利用上限、各ロールで使用できる API キーを設定できます。ここに記載するツールはすべてカタログ専用です。scenario_tools_search はスキーマとレーンを返し、scenario_tool_execute_read／write／delete は {name, parameters} でツールを実行します。スコープ ID は parameters 内に指定します（scenario スキルを参照）。引数を確認する前に、失敗の大半を左右する要素が 2 つあります。まず、呼び出し元の ID です。チームレベルの書き込みには OAuth 経由のチーム管理者が必要で、API キーは拒否されます。次に、チームで使用しているリストモードです。同じモデルアクセスの編集でも、ブロックリストモードと許可リストモードでは意味が逆になります。teams_list で両方を確認できます。各チームの行には modelsManagement、モデルリスト、plan、context.userRole が含まれています。1 つのチームと 1 つのプロジェクトに到達できる認証情報は、そのスコープ内です。複数に到達できる場合は操作を中止して一覧を表示します。これは scenario スキルに記載されています。ここで名前を挙げた関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマを確認して作業し、スキルがないことを明示してください。

クイックリファレンス

タスク	ツール	レーン	メモ
モデルアクセスの確認	model_access_get	読み取り	モードとチームの有効なリストを確認します。project_id を指定すると、そのプロジェクトのリストも併せて確認できます
モデルアクセスの変更	model_access_update	書き込み	level は team または project。add_models と remove_models のどちらか一方のみを指定します
チームのメンバー一覧	team_members_list	読み取り	メンバーと保留中の招待を確認します
招待	team_members_add	書き込み	emails を 1～32 件指定し、role と、任意で承諾時に追加する project_ids を指定します
ロールと利用上限	team_members_update	書き込み	member_ids を 1～32 件指定し、role および／または max_consumption を指定します
チームからの削除	team_members_remove	削除	招待も取り消され、アクセスは直ちに終了します
プロジェクトのメンバー一覧	project_members_list、_add、_update、_remove	読み取り、書き込み、削除	ロールは admin（オーナー）、editor（コントリビューター）、reader（閲覧者）
API キー	api_keys_list、api_key_get、api_key_update、api_key_delete	読み取り、書き込み、削除	プロジェクトスコープです。api_key_create はポータルへのリンクのみを返します
誰が何を使ったか	usage	読み取り（デフォルトのツール）	デフォルトのレスポンスには、ユーザー別およびモデル別の利用量が含まれます

モデルアクセス：編集前にモードを確認する

model_access_get は models_management と、そのモードで有効なリストのみを返します。非アクティブな保存済みリストは表示されません。デフォルトのブロックリストモードでは、チームまたはプロジェクトのブロックリストに登録されているモデルを除き、カタログ内のすべてのモデルを利用できます。2つのリストは和集合としてブロックします。許可リストモードでは、チームとプロジェクトの両方の許可リストに登録されている場合に限り、モデルを利用できます。プロジェクトの許可リストが空の場合はすべてのモデルが拒否され、許可リストが設定されていないプロジェクトではチームのリストが適用されます。

model_access_update は、そのモードで有効なリストを編集します。そのため、ブロックリストモードでは add_models はモデルをブロックし、許可リストモードでは許可します。毎回、最初にモードを確認してください。MCP からモードを切り替えることはできません。切り替えはウェブアプリのチーム設定で行うため、承認済みのモデルだけにチームを制限するには、まずユーザーがそこで許可リストモードに切り替える必要があります。ユーザーが操作できない場合、この切り替えは処理を停止して報告します。制限は切り替え待ちであることと、その後に実行する正確な呼び出しを記録し、ブロックリストで安全に実行できる部分（指定された不要モデルをプロジェクトレベルでブロックすること）を実施して、他のプロジェクトは引き続き制限されないことを伝えてください。認証情報で編集できるリストを、タスクで指定された対象セットに絞り込むことは許可されています。追加が成功した後に remove_models を実行するため、リストが空になることはありません。 level: "team" には OAuth 経由でのチーム管理者権限が必要です。このエンドポイントでは、サーバーは API キーを拒否します。level: "project" では、編集するプロジェクトを projects に指定し（1～200件）、そのすべてで管理者ロールが必要です。権限のないプロジェクトが1つでもあるとリクエスト全体が失敗し、何も更新されません。単一プロジェクト用のキーで編集できるのは、そのキーに対応するプロジェクトのリストだけです。呼び出し時の project_id は OAuth セッションのテナントコンテキストを示すもので、対象プロジェクトではありません。許可リストモードでは、プロジェクト管理者が追加できるのは、すでにチームの許可リストに登録されているモデルだけです（プロジェクトのリストはカタログを絞り込むもので、広げることはできません）。チームの許可リストからベースモデルを削除すると、そのモデルを基に作成された学習済みモデルも連鎖的に削除されます。また、チームレベルでの追加ではすべての ID が検証され、未知の ID が1つでもあると呼び出し全体が失敗します。updated: false は差分がなく、処理が不要だったことを意味し、エラーではありません。ブロックされたモデルはメンバーが実行できるモデルの一覧から消えます。そのモデルを実行しようとしたときにメンバーに表示されるエラーは、モデレーションではなく制限によるものです（scenario-moderation を参照）。

メンバーと利用上限

team_members_update は team_members_list の member_ids を受け取り、role（admin または member）、max_consumption、またはその両方を設定します。上限は現在の請求期間における Creative Units で指定します。 0 以上の値は上限を設定し、-1 は無制限、null はメンバーごとの上書きを解除して、 チーム全体のデフォルトを適用します。ロールは、OAuth を利用するチーム管理者、または team.members.manage スコープを持つチームスコープの API キーで設定できます。上限の設定には実際のチーム管理者が必要で、 キーで試みてもメンバーごとに拒否されます。最後の管理者を降格しようとすると、サーバー側で失敗します。メンバーの一括操作ツールは 1 行ずつ処理し、メンバーごとの結果を報告します。status: "partial" を含む応答の場合は、 remaining リストを指定して再度呼び出すと処理が完了します。

team_members_add は 1～32 件のメールアドレスを招待し、role（デフォルトは member）を設定します。招待の承諾後、 メンバーは project_ids で指定したプロジェクトに参加します。結果は理由（すでにメンバーである、すでに招待済み、 シート上限に達している）とともに invited、failed、skipped のいずれかになります。呼び出し時の project_id は 何も付与しません。ロールの変更と同様、招待には、OAuth を利用するチーム管理者、または team.members.manage スコープを持つチームスコープのキーが必要です。プロジェクトスコープのキーでは権限エラーになります。 保留中の招待にはメンバー ID がないため、上限は承諾されるまで適用されません。project_members_add は、すでにチームに所属しているユーザーを ユーザー ID またはメールアドレスで受け取ります（メールアドレスの解決には team_id が必要）。プロジェクトでのロールは必須です。

削除は即時に実行される退会操作です。team_members_remove はそのユーザーのすべてのアクセスを終了し、保留中の招待も取り消します。 project_members_remove ではチームへの所属や他のプロジェクトへのアクセスは変更されません。まず一覧を取得し、ユーザーに正確な名前を確認してから削除してください。 無人で実行する場合は、タスクの指示で指定されたメンバーのみを削除してください。

API キー

api_keys_list と api_key_get はプロジェクトスコープで、各キーの id、api_key_id、名前、 ステータス、スコープ、ロール、プロジェクト、作成日、および manage_keys_url を返します。チームスコープのキーはプロジェクトに紐づけられておらず、 ここには表示されず、ポータルにのみ表示されます。api_key_update はキーの role を admin、editor、reader、 または ; 区切りのカスタムスコープリスト（リファレンスの例は assets.read;models.run）に変更します。名前、ステータス、利用上限の設定はポータルでのみ行えます。 利用上限の設定には Enterprise プランと人間の管理者が必要です。キーの作成は意図的に MCP 操作として提供されていません。 api_key_create はポータルへのリンクを返します。シークレットはポータルで一度だけ表示され、会話を経由することはありません（シークレットに関する scenario スキルのルールがここでも適用されます）。api_key_delete はキーを key_id として受け取ります（一覧にある id または api_key_id のどちらでも指定できます）。 削除は取り消せず、プロジェクト管理者が必要です。また、現在のセッションの認証に使用しているキーは削除できません。まず一覧を取得し、ユーザーに正確なキーを確認してから削除してください。 無人で実行する場合は、タスクの指示で指定され、かつ一致するキーが 1 件だけの場合に限り、そのキーを削除してください。

誰がどれだけ使ったか

usage はデフォルトのツールセットに含まれ、デフォルトでは概要を返します。内容は、合計 CU の概要、ユーザーごとの消費量、 モデルごとの CU とジョブ数（降順）、アセット種別ごとの件数で、start_date と end_date（ISO 日付）で期間を指定します。 project_id を指定すると数値が絞り込まれるため、単一プロジェクトの認証情報ではチーム全体ではなく、そのプロジェクト内の利用額が順位付けされます。 日付を指定しない呼び出しではプロジェクトの全期間の数値が返されるため、必ず期間を指定してください。totals とユーザーごとの consumption 行 （userId、total）は start_date と end_date に従います。メンバーの順位はこれらの行から取得します。 日ごとの系列（利用タイプごとの include: ["usages.daily"]、モデルごとの ["modelUsages.daily"]）にはユーザーの情報はありません。 nsfwUsages はモデレーションの合計を、activity は生のイベントログを追加します。自分自身の呼び出しを合計して利用額を割り出してはいけません。 上限を設定する前に消費量を確認してください。どちらも請求期間中の CU であり、メンバーがすでに使った量より低い上限を設定すると、 そのメンバーは直ちに利用できなくなります。

作業例：プロジェクトで承認済みモデルのみを許可し、業務委託者の上限を設定する

1. scenario_tools_search で query="model access"、続けて query="team members" を指定します。以下の呼び出しに必要なスキーマとレーンを確認します。
2. scenario_tool_execute_read で name: "model_access_get"、parameters: {"team_id", "project_id"} を指定します。チームはブロックリストモードのため、「この3つのモデルのみ」は指定できません。ユーザーには、Web アプリのチーム設定でチームを許可リストに切り替えてから再読み込みするよう伝えます。無人で実行する場合は、以下の呼び出しでこの問題を記録し、停止します。その間、タスクで不要と指定されたモデルは、プロジェクトレベルでブロックします。
3. 許可リストモードでは、まずチームリストを更新します。scenario_tool_execute_write で name: "model_access_update"、parameters: {"team_id", "project_id", "level": "team", "add_models": [<the three ids>]} を指定します。この呼び出しには、OAuth 経由でチーム管理者である呼び出し元が必要です（teams_list の行にある context.userRole で確認できます）。次にプロジェクトを更新します。level: "project"、projects: [<project id>]、同じ add_models を指定します。チームリストにモデルが追加済みの場合に限り、成功します。
4. scenario_tool_execute_read で name: "team_members_list" を指定し、2人の業務委託者のメンバー ID を取得します。scenario_tool_execute_write で name: "team_members_update"、parameters: {"team_id", "project_id", "member_ids": [<two ids>], "max_consumption": 2000} を指定します。status: "partial" の場合は、remaining を指定して再度呼び出します。
5. プロジェクトを対象に、scenario_tool_execute_read で name: "api_keys_list" を指定します。admin として実行されているレンダーファーム用キーは、api_key_update で role: "assets.read;models.run" に権限を絞ります。所有者が確認できないキーは、ユーザーが名前を確認した後に限り削除します。
6. 確認します。model_access_get に project_id を指定し、プロジェクトリストの configured に3つの ID が表示されることを確認します。期間経過後に、日付範囲と include: ["usages.daily"] を指定した usage を実行し、業務委託者の消費量が上限内であることを確認します。

よくある間違い

• models_management を読み込まずにモデルアクセスを編集すること：add_models は、一方のモードではブロックされ、もう一方のモードでは許可されます。
• ブロックリストモードのまま、チームを短いリストに固定しようとすること：これは許可リストで行う設定であり、モードの切り替えは Web アプリの設定で行います。
• API キーでチームレベルの書き込みを行うこと：設計上拒否されます。呼び出し元は OAuth 経由のチーム管理者である必要があります。
• 実行ツールで parameters ではなく arguments を指定すること：無視され、スコープエラーとして表示されます（scenario を参照）。
• team.members.manage キーで上限を設定すること：変更できるのはロールであり、上限ではありません。
• 日付を指定していない usage の呼び出しを、期間内の支出として扱うこと：その数値はプロジェクトの全期間の値です。start_date と end_date を渡し、日付付きの consumption 行からメンバーを順位付けします。日ごとの系列にはユーザーの情報がないため、期間合計との照合にのみ使用します。
• api_keys_list にチームスコープのキーが表示されると期待すること：それらのキーはポータルにのみ存在します。
• プロジェクトへのアクセス権付与に team_members_add へ project_id を渡すこと：アクセス権の付与には project_ids を使用します。project_id はテナントのコンテキストです。
• 最初に一覧表示して確認せずに、キーを削除したりメンバーを削除したりすること：削除レーンは取り消しできず、api_key_delete はセッション自身のキーを拒否します。