AgentOS のセキュリティは階層構造で動作します。階層型セキュリティモデルを構築します: すべてのリクエストを認証し、ロール管理には RBAC を使用し、ユーザー間でデータとアクセスを分離します。

Agno 再入門 – 機能 : セキュリティ & 認証

作成 : クラスキャット・セールスインフォメーション
作成日時 : 06/11/2026
バージョン : v2.6.13

* 本記事は docs.agno.com の以下のページを参考にしています :

• Features : Security & Auth

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

 

 

Agno 再入門 – 機能 : セキュリティ & 認証

階層型セキュリティモデルを構築します: すべてのリクエストを認証し、ロール管理には RBAC を使用し、ユーザー間でデータとアクセスを分離します。

AgentOS のセキュリティは階層構造で動作します。各階層は、エッジでの認証されていないリクエストからデータベース内のユーザー間データアクセスまで、異なる種類の攻撃を阻止します。

レイヤー	What it stops	メカニズム
認証 (Authentication)	認証されていないリクエスト	ミドルウェアでの JWT 検証
認可 (権限付与, Authorization)	認証済みだがスコープ外のリクエスト	各エンドポイントでの RBAC スコープ
リクエスト分離	同時リクエストによる互いのデータ読み取り	リクエストごとに新しい、独立したオブジェクト
ユーザー分離	共有エンドポイントにおけるユーザー間のデータ漏洩	AuthorizationConfig(user_isolation=True) によるオプトイン

AgentOS give you good defaults at every layer

 

認証

本番環境の AgentOS は、JWT-検証ミドルウェアの背後で動作します。すべてのリクエストには、コントロールプレーン によって署名されたトークンが含まれています; サービスはそれを公開鍵で検証します。

from agno.os import AgentOS

agent_os = AgentOS(
    agents=[agent],
    db=db,
    authorization=True,  # reads JWT_VERIFICATION_KEY from env
)

`authorization=True` は、以下の両方のレイヤーを駆動します :

• 認証 (Authentication, このセクション) : すべてのリクエストで有効な JWT を必要とします。

• 認可 (Authorization, 下記) : エンドポイントごとにトークンのスコープを適用します。

以下の少数の公開ルートは、JWT の要件を免除されます: /, /health, /info, /docs, /redoc, /openapi.json, /docs/oauth2-redirect。

 

JWT_VERIFICATION_KEY の取得

1. JWT認証を切り替える

   os.agno.com を開く → `+ Connect AgentOS` → `Live` → URL の貼り付け。新しい AgentOS を接続する際、または後で OS 設定ページから JWT 認証を有効にします。

2. 公開キーのコピー

   モーダル (ウィンドウ) から、AgentOS の公開鍵をコピーします。

3. 検証キーの設定

   .env ファイルに JWT_VERIFICATION_KEY 環境変数として公開キーを設定するか、ターミナルで直接エクスポートします :

   export JWT_VERIFICATION_KEY="your-public-key"
   

   あるいは、JWKS ファイルを使用してキーを管理している場合は、AgentOS がそのファイルをポイントするようにします :

   export JWT_JWKS_FILE="/path/to/jwks.json"
   

   AgentOS コントロールプレーンがトークンを発行する場合、コントロールプレーンは秘密鍵を保持し、サービス側からは公開鍵のみが見えるようになります。詳しい手順については、Generate a Verification Key from the Control Plane を参照してください。

 

認可

すべての JWT には、呼び出し元の権限 (デフォルトのスコープ; プロバイダが WorkOS のパーミッションなど別の名称を使用している場合は、scopes_claimで設定可能）をリスティングしたクレームが含まれています。エンドポイントは、これらのスコープに基づいてアクセスが制限されます。

• (スコープ – 権限 (Grants))

• agents:read – エージェントのリスティングとそれらの設定の読み取り

• agents:<id>:run -特定のエージェントの実行

• agents:*:run – 任意のエージェントの実行 (チーム、ワークフローでも同じパターン)

• agent_os:admin – セッション、メモリ、トレース・クエリを含むフルアクセス

AgentOS コントロールプレーンは、適切なスコープを持つそれぞれのトークンを新規発行します。スコープはロールに束ねられ、コントロールプレーン内でユーザーに割り当てられます: AgentOS コントロールプレーンには、デフォルトで 3 つのロール (オーナー、管理者、メンバー) が用意されており、Enterprise ではカスタムロールも利用可能です。セルフホスティングを行うユーザー (Self-hosters) は、ID プロバイダーまたはバックエンドでロールを定義します。スコープの全リストについては スコープリファレンス、各ロールが付与する権限については デフォルトロール、独自のロールを構成するには カスタムロール を参照してください。

 

リクエストの分離

すべてのリクエストは、アクセス先のエージェント、チーム、またはワークフローの最新コピーを取得します。AgentOS はリクエストごとに登録済みコンポーネントに対して deep_copy()を呼び出すため、可変状態（セッションスコープ変数、ツール実行コンテキスト、実行メタデータ）は同時実行される呼び出し間で状態が混在しないようにします。

負荷の高いリソース（DB接続、モデルクライアント、MCP ツールハンドル）は参照により共有されます; 分離されるのは実行ごとの可変状態のみです。これにより、同じインメモリ・エージェントインスタンス上で競合する、2つのリクエストの自爆 (footgun) を回避し、低コストで並行処理を実現できます。

この機能はすべての実行エンドポイントでデフォルトで有効になっています。設定は不要です。

 

ユーザー分離

ユーザーごとのデータ分離はオプトイン方式です。この設定がなくても認可 (authorization) は有効であり続けますが、ルーティングはスコープなしのデータベース上で動作します。`agents:my-agent:run` を持つ呼び出し元は、ID を知っていれば他のユーザーのセッションを読み取ることができます。マルチテナント・デプロイでは、この機能を有効にしてください :

from agno.os.config import AuthorizationConfig

agent_os = AgentOS(
    agents=[agent],
    db=db,
    authorization=True,
    authorization_config=AuthorizationConfig(
        verification_keys=[public_key],
        user_isolation=True,   # requires authorization=True; the user_id comes from the JWT sub
    ),
)

`user_isolation=True` を有効にすると、管理者以外のすべての呼び出し元に対して、次の保証が提供されます :

• (保証 (Guarantee) – 仕組み)

• ユーザー間の読み取り不可 – ユーザースコープの読み取り (セッション、メモリ、トレース）では、JWT の sub(ject) が user_id として伝播します。呼び出し元は自身の行しか参照できません。

• ユーザー間の書き込み不可 – すべての書き込み時に user_id が強制設定されるため、管理者以外のユーザーは、別ユーザーの属性となるセッション、メモリ、トレースを永続化できません。

• 実行の所有権 – キャンセル、再開、継続ルートでは session_id を要求し、その実行が呼び出し元のセッションに属していることを検証します。

• WebSocket 再接続 – ワークフロー実行への再接続では session_id と workflow_id を要求し、呼び出し元がその実行の所有者であることを検証します。

管理者呼び出し元（設定された admin_scope を持つユーザー、デフォルトは agent_os:admin）は、上記すべてをバイパスして、スコープなしの完全なビュー: サービスアカウント、内部ツール、コントロールプレーンにアクセスできます。

ユーザーごとの分離には、user_id を記録するデータベースが必要です (本番環境では PostgreSQL 推奨)。

 

デフォルト

• (Concern – デフォルトの動作)

• 認証 – `authorization=False`. 本番環境では `authorization=True` と JWT_VERIFICATION_KEY を設定して有効にしてください。

• リクエスト分離 – 有効。実行エンドポイントごとにコンポーネントがディープコピーされます。

• ユーザー分離 – 無効。マルチテナント環境では `AuthorizationConfig(user_isolation=True)` で有効にしてください。

See the AuthorizationConfig reference for all configuration options and their defaults.

以上