Overview
Atlas エージェント ポリシー エンジン は、組織管理者にエージェントの実行に対するランタイム制御を付与します。管理者は、組織スコープ、プロジェクトポリシー スコープ、またはその両方内で作成します。コントロール プレーンはプロジェクトに適用されるポリシーを単一の効果的な構成にマージし、オーケストレーション エンジン（UE）は実行ごとにその構成を強制します。
ポリシーは、呼び出されるツールとモデルや 1 回の実行で実行される作業量など、エージェントが実行するアクションを制御します。ポリシーは、次の 2 つのカテゴリに分類されます。
許可リストは、エージェントが呼び出すことができるツールとモデルを制限します。
実行予算は、ツール呼び出しの数、大規模言語モデル（LVM）の呼び出しの数、実行期間など、1 回の実行が消費するリソースを制限します。
エージェントを通過するコンテンツを制御するには、「 コンテンツ 保護の使用 」を参照してください。
ポリシー タイプ
各ポリシー タイプには、ポリシーの値の形状を記述する種類があります。この種類は、ポリシー エンジンが組織とプロジェクトのポリシーをマージする方法を決定します。次のポリシー タイプを使用できます。
ポリシー タイプ | Kind | 説明 |
|---|---|---|
| 許可リスト | エージェントが呼び出すことができるツールのセット。 UE は、ツールを呼び出すたびにこのポリシーを評価します。リストが省略するツールをエージェントが呼び出すと、UE は実行を停止し、 ポリシー拒否エラーを返します。 |
| 許可リスト | エージェントが呼び出すことができるモデルのセット。プライマリは、各 LM を呼び出す前にこのポリシーを評価します。リストが省略するモデルをエージェントが呼び出すと、OA は実行を停止し、ポリシー拒否エラーを返します。 |
| Numeric cap | エージェントが1 回の実行で行うことができるツール呼び出しの最大数。実行が上限に達した後にエージェントがツール呼び出しを試みると、OA は実行を停止し、 ポリシー拒否エラーを返します。 |
| Numeric cap | エージェントが1 回の実行で行うことができる LM 呼び出しの最大数。実行が上限に達した後にエージェントがLM 呼び出しを試行すると、OA は実行を停止し、ポリシー拒否エラーを返します。 |
| Numeric cap | 1 回の実行の最大経過時間（ミリ秒単位）。 OA は、各ツール呼び出しと LM 呼び出しの前に経過時間をチェックします。実行が制限に達した場合、OA は実行を停止し、拒否のエラーを返します。 OA はすでに進行中の呼び出しを停止しません。 |
| Numeric cap | 1 回の実行で消費できる LM トークンの最大数。実行が上限に達した後にエージェントがLM 呼び出しを試行すると、OA は実行を停止し、ポリシー拒否エラーを返します。 |
| Numeric cap | 1 つのセッションが、そのセッション内のすべての実行で消費できる LM トークンの最大数。セッションが上限に達した後にエージェントがLM 呼び出しを試行すると、OA は実行を停止し、ポリシー拒否エラーを返します。 |
ポリシー拒否エラーの詳細については、 強制 を参照してください。
トークン合計は、LM 呼び出しの前ではなく、各モデル応答の後に蓄積されます。詳細については、「 制限 」を参照してください。
エージェントが子エージェントにタスクを委任した場合、子は親のルート セッションを継承するため、両方のエージェントが同じセッションで実行されます。合計されたトークンは、エージェントごとに個別の合計ではなく、1MAX_TOKENS_PER_SESSION つの 合計にカウントされます。エージェント間の削除の詳細については、「 エージェント間通信の使用 」を参照してください。
ツールとカタログの一致
AUTHORIZED_TOOLS 許可リスト エントリは、ツールの名前または、ツールを公開するカタログの識別子（stripe/payments など）のいずれかと一致します。カタログ識別子は、カタログが後で追加するツールを含め、カタログが公開するすべてのツールを許可リストに登録します。
カスタム ツールを含む、カタログ識別子を持たないツールは、ツール名のみと一致します。これらのツールの 1 つを許可するには、その名前を許可リストに追加します。
ポリシーの範囲と継承
組織スコープまたはプロジェクトスコープ内でポリシーを作成できます。組織ポリシーは、組織内のすべてのプロジェクトに適用されます。すべてのプロジェクトポリシーは、少なくとも同じ種類の組織ポリシーと同等の制限的である必要があります。 2 つのスコープが同じポリシー タイプを定義する場合、ポリシー エンジンはそれらをプロジェクトの 1 つの有効な値にマージします。
マージ ルールは、ポリシーの種類によって異なります。次の表は、各ポリシーの種類とそれに対応するマージルールを示しています。
ポリシーの種類 | マージ ルール | プロジェクトの制約 |
|---|---|---|
許可リスト | 有効な値は、組織許可リストとプロジェクト許可リストの共通部分です。 | プロジェクトでは、組織の許可リストが省略する値を追加することはできません。 |
Numeric cap | 有効な値は、組織上限とプロジェクト上限のうち低い方です。 | プロジェクトは、組織の上限よりも高い上限を設定できません。 |
同じ種類の組織ポリシーよりも制限が低いプロジェクトポリシーを保存すると、Atlas Agent Engine はリクエストを拒否します。プロジェクトの制限を引き上げたり、許可リストを拡大したりするには、まず組織管理者が組織ポリシーを変更する必要があります。
施行
UE は、実行ごとに特定のチェックポイントで有効なポリシーを評価します。
チェックポイント | 評価されたポリシー |
|---|---|
ツール呼び出し前 |
|
事前 LMM- 呼び出し |
|
ポリシー チェックに失敗すると、UE は実行を停止し、呼び出し元にポリシー拒否エラーを返します。エラーには、policy_denied の error_code と、拒否の理由を特定する Policy denied: <reason> 形式のメッセージが含まれます。
注意
特定のタイプのポリシーが実行に適用されない場合、OE は対応するアクションを制限しません。有効なポリシーがないプロジェクトは、ポリシー制限なしで実行されます。
ポリシー伝達
ポリシーを作成、更新、または削除すると、Atlas Agent Engine は約 1 分以内に変更を適用します。 Atlas Agent Engine は、まず、影響を受けるプロジェクトごとに効果的な構成を再構築し、次にその構成をプロジェクトのエージェントを実行する OA に渡します。
各実行は開始時に有効なポリシーのスナップショットを取得し、そのスナップショットを有効期間全体で使用します。ポリシーの変更は、変更が伝達された後に開始される実行にのみ適用されます。ポリシーの変更は、実行中の実行には影響しません。
Atlas Agent Engine が変更を提供できない場合でも、UE は最後に受信した構成を強制します。変更を受信していないプロジェクトを確認するには、「 組織ポリシーのロールアウトの確認 」を参照してください。
ポリシーの作成と編集
ポリシーは、プラットフォームUIまたはREST APIから作成および編集できます。
プロジェクトポリシーを管理するには、Manage > に移動します。プロジェクトの Policies 。組織ポリシーを管理するには、組織設定の Policies に移動します。どちらのページから、各ポリシー タイプのポリシーを作成、読み取り、更新、および削除することができます。プロジェクトポリシーは、プロジェクトPolicies ページから有効または無効にできます。プラットフォームUI、組織ポリシーの有効化または無効化はサポートされていません。
注意
カスタマー向けREST API はポリシー操作を公開します。リクエストには、操作に必要なロール を持つユーザーによるベアラ認証が必要です。 Atlas Agent Engine でユーザー ロールの詳細については、「 組織、プロジェクト、ワークスペースの管理 」と「 組織の表示 」を参照してください。
次の表は、使用可能なプロジェクトエンドポイントを示しています。
方式 | エンドポイント | 必要なロール | 参照 |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
次の表には、利用可能な組織エンドポイントをまとめています。
方式 | エンドポイント | 必要なロール | 参照 |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
組織の許可リストをプレビューする
許可リストは交差するものとしてマージされるため、組織の許可リストから値を削除すると、許可された値のないプロジェクトが残ります。組織ポリシーへの変更を保存する前に、ORG_OWNER ロールを持つ次のエンドポイントを呼び出します。
POST /api/v1/organizations/{orgId}/policies/preview
APIレスポンスは、有効な許可リストが空になった各プロジェクトを名前付けし、プロジェクトが現在強制している許可リストを表示します。詳細については、「 影響を受けるプロジェクトのプレビュー 」を参照してください。
ポリシーの有効化と無効化
Atlas Agent エンジンは、有効な構成を構築するときに無効になっているポリシーをスキップします。組織ポリシーとプロジェクトポリシーの両方にenabled フラグがあります。ポリシーを有効または無効にするには、ポリシーのスコープに対してPUT APIエンドポイントを呼び出し、enabled フラグを設定します。プラットフォームUIからプロジェクトポリシーを有効または無効にすることもできます。詳しくは、「 ポリシーの作成と編集 」を参照してください。
ポリシーを無効にすると、Atlas Agent Engine はポリシーの構成と履歴を保持します。ポリシーを再度有効にすると、Atlas Agent Engine は同じ構成を復元します。
効果的なポリシーの表示
効果的なビューは、組織とプロジェクトのスコープがプロジェクトのどのように解決されるかを示します。有効なビューを取得するには、プロジェクト読み取りロールを持つ次のプロジェクトエンドポイントを使用します。
GET /api/v1/projects/{projectId}/policies/effective
API応答には、すべてのポリシー タイプ、OA が強制するマージされた有効値、各スコープが定義する値、および強制されているスコープが一覧表示されます。 Atlas Agent Engine はユーザーに代わって組織値を読み取るため、組織ロールを保持しなくても継承されたベースラインを確認できます。詳しくは、「 有効なポリシーを一覧表示する 」を参照してください。
組織ポリシーのロールアウトを確認
Atlas Agent Engineでは、プロジェクトはまとめてではなく、一度に 1 つずつポリシー変更を受け取ります。組織ポリシーのロールアウトが進行中、一部のプロジェクトは新しいポリシーを適用し、他のプロジェクトは引き続き前のポリシーを適用します。組織ポリシーのロールアウトの進行状況を確認するには、ORG_OWNER または ORG_READ_ONLY ロールを持つ次のエンドポイントを使用します。
GET /api/v1/organizations/{orgId}/policies/rollout
このAPI応答は、遅延した各プロジェクト、プロジェクトが再ビルドされなかった、または有効な構成を受信しなかった理由、および Atlas Agent Engine が有効な構成を再ビルドまたは受信するために実行した試行回数を識別します。 API応答では、Atlas Agent Engine がログに記録する基になるエラーテキストは省略されます。詳細については、 「 組織ポリシーのロールアウト ステータス 」を参照してください。
保存されたポリシーがプロジェクトで受信されない場合、Atlas Agent Engine はそのプロジェクトへのポリシーの提供を再試行し、変更をすでに受信したプロジェクトはそのままにします。無効なポリシー値など、ビルドを再試行することで障害を解決できない場合、Atlas Agent Engine はそのプロジェクトのビルド試行をすぐに停止します。到達不能なプロジェクトなど、障害が一時的な場合、Atlas Agent Engine はプロジェクトの構築を再試行し、試行間の遅延を増加させます。 Atlas Agent Engine は、10 の試行が失敗した後にプロジェクトの再試行を停止します。
試行回数は、ユーザーが次にポリシーを編集するときにリセットされます。 Atlas Agent Engine がプロジェクトの再試行を停止 した場合は、ポリシーを修正して再度保存し、プロジェクトをロールアウト キューに戻します。
ポリシー拒否の監視
プラットフォームUI は、組織とプロジェクト内の呼び出しを拒否する頻度を報告します。プラットフォームUIメトリクスの読み取り方法については、「 ポリシー拒否の表示 」を参照してください。
制限
ポリシー エンジンには、次の制限があります。
新しいまたは更新されたポリシーが有効になるまでに最大 1 分かかります。ポリシーは、伝達後に開始される実行にのみ適用されます。文字列はすぐに有効化されます。
OA は 1 回の呼び出しで上限を超えることができます。 UE は、各呼び出しの前に期間とトークンの使用状況をチェックします。呼び出しが
MAX_EXECUTION_DURATION_MSまたはMAX_TOKENS_PER_EXECUTIONの制限に達していない場合は、呼び出しがこれらの制限を超えても、次の呼び出しが行われます。OA は、複数の呼び出しでセッション トークンの上限を超えることができます。 1 つのセッションが同時に複数の実行を実行します。 Atlas Agent Engine は、実行中の呼び出しがすべて完了した後にのみセッション 上限をチェックします。
MAX_TOKENS_PER_SESSIONの値は、それらの呼び出しの合計トークンによって構成された最大値を超える可能性があります。トークン 上限はメモリ抽出を除外します。メモリ抽出で消費されるトークンは、
MAX_TOKENS_PER_EXECUTIONまたはMAX_TOKENS_PER_SESSION値にはカウントされません。カタログのないツールは名前のみ一致します。カスタムツールなど、カタログ識別子を持たないツールは、ツール名のみで
AUTHORIZED_TOOLSポリシータイプのエントリと一致します。詳しくは、「 ツールとカタログの一致 」を参照してください。ネットワーク出力は個別に管理されます。ポリシー エンジンはネットワーク出力を制御しません。ネットワーク Egress 制限の設定方法については、「 ネットワーク Egress ポリシーの管理 」を参照してください。