# エージェント認証

> エージェント認証 - DataRobotのエージェントテンプレートに認証を実装する方法（APIトークン、認可コンテキスト、OAuth 2.0、セキュリティのベストプラクティスなど）について説明します。

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-07-15T05:55:44.561884+00:00` (UTC).

## Primary page

- [エージェント認証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [認証方法](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#authentication-methods): In-page section heading.
- [APIトークン認証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#api-token-authentication): In-page section heading.
- [DataRobot APIの認証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#datarobot-api-authentication): In-page section heading.
- [外部APIの認証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#external-api-authentication): In-page section heading.
- [MCPサーバー認証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#mcp-server-authentication): In-page section heading.
- [認可コンテキスト](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#authorization-context): In-page section heading.
- [OAuth 2.0認証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#oauth-2-0-authentication): In-page section heading.
- [セキュリティのベストプラクティス](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#security-best-practices): In-page section heading.
- [認証に関する問題のトラブルシューティング](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#troubleshooting-authentication-issues): In-page section heading.
- [よくある問題](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#common-issues): In-page section heading.
- [APIトークンがない](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#missing-api-token): In-page section heading.
- [無効なエンドポイント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#invalid-endpoint): In-page section heading.
- [認可コンテキストが設定されていない](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#authorization-context-not-set): In-page section heading.
- [OAuthトークンの有効期限切れ](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#oauth-token-expired): In-page section heading.
- [MCPサーバーの認証失敗](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#mcp-server-authentication-failure): In-page section heading.
- [デバッグのヒント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#debugging-tips): In-page section heading.
- [冗長ログを有効にする](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#enable-verbose-logging): In-page section heading.
- [環境変数のチェック](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#check-environment-variables): In-page section heading.
- [認証のテスト](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#test-authentication): In-page section heading.
- [認可コンテキストの検証](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-authentication.html.md#validate-authorization-context): In-page section heading.

## Documentation content

AIエージェントは、タスクを完了するために外部リソースへの認証を必要とすることがよくあります。 たとえば、デプロイされたエージェントは、データを取得したり操作を実行したりするために、外部API、データベース、またはクラウドサービスにアクセスする必要がある場合があります。

このドキュメントでは、DataRobot Agent Templatesでの認証の実装に関する包括的なガイダンスを提供します。これには、APIトークン、MCPサーバー認証、認可コンテキスト、OAuth 2.0、およびセキュリティのベストプラクティスが含まれます。

## 認証方法

このセクションでは、フレームワークで利用可能なさまざまな認証方式の概要を説明します。

| 方法 | 説明 | ユースケース |
| --- | --- | --- |
| APIトークン認証 | シンプルなトークンベースの認証 | 外部API、DataRobotのサービス。 |
| MCPサーバー認証 | MCPサーバーの自動トークンベース認証 | MCPツールの統合。 |
| OAuth 2.0 | 外部サービス向けの標準OAuth | サードパーティ製品との連携。 |

## APIトークン認証

APIトークン認証は、DataRobotのサービスや外部APIへの認証において最も一般的な方法です。 ヘッダーまたは環境変数で渡されるベアラートークンを使用します。

### DataRobot APIの認証

環境変数またはプログラムを使用してAPIトークンを設定します。 `DATAROBOT_API_TOKEN` は、 [アカウント設定の「APIのキーとツール」セクション](https://docs.datarobot.com/ja/docs/platform/acct-settings/api-key-mgmt.html.md) にあります。

**環境変数（推奨）:**
エージェントテンプレートでは、環境変数 `DATAROBOT_API_TOKEN` および `DATAROBOT_ENDPOINT` が設定されていると、それらが自動的に使用されます。 これは、資格情報をコードに残さず、 `MyAgent` の初期化とシームレスに連携するため、推奨されるアプローチです。 `MyAgent` クラスは、資格情報が明示的に指定されていない場合、自動的にこれらの環境変数にフォールバックします。 外部ツールとの連携にオプションの `ToolClient` クラスを使用する場合、デフォルトでこれらの環境変数も使用します。 MCPサーバーも、認証に `DATAROBOT_API_TOKEN` を自動的に使用します。

```
DATAROBOT_API_TOKEN=<your_api_key>
DATAROBOT_ENDPOINT=https://app.datarobot.com 
```

**プログラマチック:**
API資格情報は、 `MyAgent` クラスを初期化するときに直接渡すことができます。 これは、環境変数をオーバーライドしたり、特定のインスタンスに対して異なる資格情報を使用したりする必要がある場合に便利です。 `MyAgent` クラスは、パラメーターが指定されていない場合でも環境変数にフォールバックします。

```
from agent import MyAgent

agent = MyAgent(
    api_key="your_api_key",
    api_base="https://app.datarobot.com"
) 
```

> [!NOTE] 外部ツール用のToolClientおよびMCPツール
> `datarobot-genai` パッケージの `ToolClient` クラスを使用して外部ツールを統合している場合は、プログラムで資格情報を渡すこともできます。 For MCP server-based tool integration, authentication is handled automatically via `DATAROBOT_API_TOKEN`. 詳細については、 [ツール統合のドキュメント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html.md) および [MCPツールのドキュメント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html.md) を参照してください。


### 外部APIの認証

外部APIへの認証が必要なカスタムツールを作成する場合は、ツールの `run()` メソッド内で環境変数またはランタイムパラメーターからAPIキーを取得します。 これにより、資格情報がソースコードに含まれず、エージェントテンプレート全体で使用されているのと同じセキュリティパターンに従います。

ローカルで開発する場合は、環境変数を使用します。 デプロイされたエージェントの場合は、 `model-metadata.yaml` でランタイムパラメーターを定義し、 `datarobot_drum` から `RuntimeParameters.get()` を使って取得します。 以下の例に示すように、まず `os.environ.get()` を試し（ローカル開発の場合）、その後、 `RuntimeParameters.get()` にフォールバックします（デプロイされたエージェントの場合）。

```
# custom-tool-example.py
import os
import requests
from crewai.tools import BaseTool
from datarobot_drum import RuntimeParameters

class ExternalAPITool(BaseTool):
    def run(self, query: str) -> str:
        api_key = os.environ.get("EXTERNAL_API_KEY")
        if not api_key:
            api_key = RuntimeParameters.get("EXTERNAL_API_KEY")["apiToken"]

        headers = {"Authorization": f"Bearer {api_key}"}
        response = requests.get(
            "https://api.external-service.com/data",
            headers=headers,
            params={"query": query}
        )
        return response.json() 
```

> [!NOTE] デプロイにランタイムパラメーターを定義する
> デプロイされたエージェントでランタイムパラメーターを使用するには、 `model-metadata.yaml` ファイルで定義します。 資格情報タイプのパラメーター（APIキーなど）には、 `type: credential` を使用します。
> 
> ```
> runtimeParameterDefinitions:
>   - fieldName: EXTERNAL_API_KEY
>     type: credential
>     credentialType: api_token
>     description: API key for external service authentication 
> ```
> 
> 設定オプションの詳細については、 [ランタイムパラメーターのドキュメント](https://docs.datarobot.com/ja/docs/api/code-first-tools/drum/custom-model-runtime-parameters.html.md) を参照してください。
> 
> `api_token` は単一フィールド資格情報タイプであるため、プラットフォームは、 `EXTERNAL_API_KEY_API_TOKEN` ではなく、 `fieldName` とまったく同じ名前の環境変数（例： `EXTERNAL_API_KEY` ）にトークンを挿入します。 上記のサンプルコードは、デプロイでの実行時に `os.environ.get("EXTERNAL_API_KEY")` を使用します。 複数フィールド資格情報タイプについては、 [ランタイムパラメーター](https://docs.datarobot.com/ja/docs/api/code-first-tools/drum/custom-model-runtime-parameters.html.md) を参照してください。

### MCPサーバー認証

When using MCP (Model Context Protocol) servers to provide tools to your agents, authentication is handled automatically using the `DATAROBOT_API_TOKEN` environment variable. エージェントテンプレートのMCPクライアントは、MCPサーバーへの認証済みリクエストにこのトークンを自動的に使用します。

設定 ：

```
# .env
DATAROBOT_API_TOKEN=<your_api_key>
DATAROBOT_ENDPOINT=https://app.datarobot.com 
```

MCPクライアントは、MCPサーバーにリクエストを送信する際、 `DATAROBOT_API_TOKEN` を自動的に使用します。 これらの環境変数を設定する以外に、追加の設定は不要です。

> [!NOTE] MCPとToolClientの認証
> MCPツールは、サーバー認証に `DATAROBOT_API_TOKEN` を直接使用しますが、 `ToolClient` （直接のツールデプロイに使用）は、APIトークンと認可コンテキストの両方を使用できます。 MCPツールの統合に関する詳細については、 [MCPサーバーを使用してツールを統合する](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html.md) を参照してください。

## 認可コンテキスト

フレームワークは、認証情報を下流のツールやサービスに伝えるための認可コンテキストシステムを提供します。 これにより、手動で設定することなく、エージェントツール間でトークンと資格情報を自動的に受け渡すことができます。

`datarobot-genai` パッケージの `resolve_authorization_context()` を使用し、エージェントの `chat()` 関数で認可コンテキストを初期化します。 この関数は認可コンテキストディクショナリを返します。これは、 `completion_create_params["authorization_context"]` に割り当てる必要があります。 その後、ツールは `datarobot` SDKの `get_authorization_context()` を使用してコンテキストを取得できます。

```
# custom.py
from datarobot_genai.core.chat import resolve_authorization_context
from datarobot.models.genai.agent.auth import get_authorization_context

def chat(completion_create_params, load_model_result, **kwargs):
    # Initialize the authorization context for downstream agents and tools
    completion_create_params["authorization_context"] = resolve_authorization_context(
        completion_create_params, **kwargs
    )
    # ... rest of chat function

# In your tools
auth_context = get_authorization_context()
access_token = auth_context.get("access_token") 
```

> [!NOTE] ToolClientおよび認可コンテキストを使用するMCPツール
> 外部ツールの統合に `datarobot-genai` パッケージのオプションクラス `ToolClient` を使用すると、エージェントツールを呼び出す際に認可コンテキストを自動的に反映します。 MCPツールは、認証に `DATAROBOT_API_TOKEN` を直接使用し、認可コンテキストの伝播を必要としません。 詳細については、 [ツール統合のドキュメント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html.md) および [MCPツールのドキュメント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html.md) を参照してください。

## OAuth 2.0認証

OAuth 2.0をサポートする外部サービスの場合は、ツールにOAuthフローを実装します。 サービスの開発者コンソールでOAuthアプリケーションを作成し、環境変数を設定します。

```
# .env
OAUTH_CLIENT_ID=<your_client_id>
OAUTH_CLIENT_SECRET=<your_client_secret>
OAUTH_REDIRECT_URI=<your_redirect_uri>
OAUTH_SCOPE=<required_scopes> 
```

次に、OAuthの実装でそれらの環境変数を使用します。 この例は、CrewAIツール向けの完全なOAuth 2.0認可コードフローを示しています。 このツールは `crewai.tools.BaseTool` （CrewAIエージェントテンプレートのツールの標準基本クラス）を継承し、インメモリーキャッシュを使用して独自のトークンライフサイクルを管理し、環境変数から資格情報を取得するリポジトリのパターンに従います。

> [!NOTE] 実装例
> これは、基本的なOAuth認証パターンを示すCrewAI固有のフレームワークの例です。 `run()` メソッドはトークンの使用方法を示すためのプレースホルダーAPI呼び出しを行いますが、実際のツールロジックは、具体的なユースケースに基づいて実装する必要があります。

```
# custom-tool-example.py
import os
import time
import requests
from urllib.parse import urlencode
from crewai.tools import BaseTool

class ExampleToolWithOAuth(BaseTool):
    def __init__(self):
        super().__init__()
        self.client_id = os.getenv("OAUTH_CLIENT_ID")
        self.client_secret = os.getenv("OAUTH_CLIENT_SECRET")
        self.redirect_uri = os.getenv("OAUTH_REDIRECT_URI")
        self._access_token = None
        self._token_expires_at = None

    def get_authorization_url(self) -> str:
        params = {
            "client_id": self.client_id,
            "redirect_uri": self.redirect_uri,
            "response_type": "code",
            "scope": "read:data"
        }
        return f"https://oauth.provider.com/authorize?{urlencode(params)}"

    def exchange_code_for_token(self, code: str) -> dict:
        response = requests.post(
            "https://oauth.provider.com/token",
            data={
                "grant_type": "authorization_code",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
                "code": code,
                "redirect_uri": self.redirect_uri
            }
        )
        token_data = response.json()
        self._access_token = token_data.get("access_token")
        expires_in = token_data.get("expires_in", 3600)
        self._token_expires_at = time.time() + expires_in
        return token_data

    def get_cached_access_token(self) -> str:
        if self._access_token and self._token_expires_at and time.time() < self._token_expires_at:
            return self._access_token
        # Token expired or not set - refresh or re-authenticate
        # In production, implement token refresh logic here
        raise ValueError("Access token expired. Re-authenticate to get a new token.")

    def run(self, query: str) -> str:
        access_token = self.get_cached_access_token()
        response = requests.get(
            "https://api.provider.com/data",
            headers={"Authorization": f"Bearer {access_token}"},
            params={"query": query}
        )
        return response.json() 
```

## セキュリティのベストプラクティス

本番環境で認証を処理する場合、セキュリティのベストプラクティスに従うことが不可欠です。 以下のガイドラインに従ってください。

- APIトークン認証
- トークンは環境変数に保管します。ソースコードにシークレットを直接記述することは絶対に避けてください。
- 本番環境ではセキュアなトークン保管ソリューションを利用します。
- トークンのローテーションを実施し、トークンの有効期限ポリシーを適用します。
- 認可コンテキストは、検証してからツールで使用します。
- 最小権限の原則に従います。
- 監査目的で認証イベントをログに記録します。
- OAuth 2.0
- すべてのOAuth通信にHTTPSを使用します。
- CSRF攻撃を防ぐために state パラメーターを検証します。
- リフレッシュトークンをセキュアに保管します。
- トークンの有効期限とリフレッシュのロジックを確実に処理します。
- 認可コンテキストは、検証してから使用します。
- セキュリティ全般
- 開発と運用に別々の環境を使用します。
- 強固なシークレット管理プラクティスを実施します。
- コンテナセキュリティのベストプラクティスに従います。
- 定期的なセキュリティ監査を実施し、更新プログラムを適用します。

## 認証に関する問題のトラブルシューティング

このセクションでは、エージェントの開発またはデプロイ時に発生する一般的な認証の問題を診断し、解決する方法について説明します。

### よくある問題

以下のセクションでは、一般的な認証エラーとその解決方法について説明します。

#### APIトークンがない

このエラーは、DataRobot APIトークンが設定されていない場合に発生します。

問題 ： `エラー：DataRobot APIトークンがありません。 DATAROBOT_API_TOKEN環境変数を設定してください`

解決方法 ： [DataRobot APIキー](https://docs.datarobot.com/ja/docs/platform/acct-settings/api-key-mgmt.html.md) を使用するように `DATAROBOT_API_TOKEN` 環境変数を設定します。

#### 無効なエンドポイント

このエラーは、DataRobotのエンドポイントがないか、正しく設定されていない場合に発生します。

問題 ： `エラー：DataRobotのエンドポイントがありません。 DATAROBOT_ENDPOINT環境変数を設定してください`

解決方法 ： `DATAROBOT_ENDPOINT` 環境変数を正しく設定します。

#### 認可コンテキストが設定されていない

このエラーは、ツールが初期化前の認可コンテキストにアクセスしようとすると発生します。

問題 ： `エラー：ツールで認可コンテキストを使用できません`

解決方法 ： `resolve_authorization_context()` がエージェントの `chat()` 関数で呼び出され、その結果が `completion_create_params["authorization_context"]` に割り当てられるようにします。

#### OAuthトークンの有効期限切れ

このエラーは、OAuthアクセストークンの有効期限が切れており、リフレッシュする必要がある場合に発生します。

問題 ： `エラー：401 Unauthorized`

解決方法 ：トークンリフレッシュロジックを実装するか、再認証します。

#### MCPサーバーの認証失敗

このエラーは、MCPサーバーがエージェントのリクエストを認証できない場合に発生します。

問題 ： `Error: 401 Unauthorized` または `MCP接続の失敗`

解決方法 ：

1. APIトークンの確認 ：環境で DATAROBOT_API_TOKEN が正しく設定されていることを確認してください
2. トークン権限の確認 ：MCPサーバーへのアクセスに必要な権限がトークンにあることを確認してください
3. MCPサーバーエンドポイントの確認 ：MCPサーバーエンドポイントが正しいことを確認してください
4. ローカル開発の場合 ：MCPサーバーが実行中でアクセス可能であることを確認してください
5. MCP設定の確認 ：詳細については、 MCPツールのトラブルシューティング を参照してください

### デバッグのヒント

認証の問題をデバッグするのに役立つテクニックを紹介します。

#### 冗長ログを有効にする

認証操作に関する詳細情報を取得するには、詳細ログを有効にします。 そのためには、 `custom.py` で `MyAgent` がインスタンス化されている場所を探し、 `verbose=True` を設定します。

```
# custom.py
from agent import MyAgent

# ...

agent = MyAgent(verbose=True, **completion_create_params) 
```

#### 環境変数のチェック

必要な環境変数が正しく設定されていることを確認します。

```
import os
print(f"API Token: {os.getenv('DATAROBOT_API_TOKEN')}")
print(f"Endpoint: {os.getenv('DATAROBOT_ENDPOINT')}") 
```

#### 認証のテスト

`datarobot_genai.core.cli` の `AgentEnvironment` クラスを使用して認証をテストします。

```
from datarobot_genai.core.cli import AgentEnvironment

try:
    env = AgentEnvironment()
    print("Authentication successful")
except ValueError as e:
    print(f"Authentication failed: {e}") 
```

#### 認可コンテキストの検証

`datarobot.models.genai.agent.auth` の `get_authorization_context()` を使用して、認可コンテキストを確認します。

```
# custom-tool-example.py
from datarobot.models.genai.agent.auth import get_authorization_context

auth_context = get_authorization_context()
print(f"Authorization context: {auth_context}") 
```