エージェント認証¶
AIエージェントは、タスクを完了するために外部リソースへの認証を必要とすることがよくあります。 たとえば、デプロイされたエージェントは、データを取得したり操作を実行したりするために、外部API、データベース、またはクラウドサービスにアクセスする必要がある場合があります。
このドキュメントでは、DataRobotのエージェントテンプレートに認証を実装するための包括的なガイダンスを提供し、APIトークン、認可コンテキスト、OAuth 2.0、セキュリティのベストプラクティスについて説明します。
認証方法¶
このセクションでは、フレームワークで利用可能なさまざまな認証方式の概要を説明します。
| 方法 | 説明 | ユースケース |
|---|---|---|
| APIトークン認証 | シンプルなトークンベースの認証 | 外部API、DataRobotのサービス。 |
| OAuth 2.0 | 外部サービス向けの標準OAuth | サードパーティ製品との連携。 |
APIトークン認証¶
APIトークン認証は、DataRobotのサービスや外部APIへの認証において最も一般的な方法です。 ヘッダーまたは環境変数で渡されるベアラートークンを使用します。
DataRobot APIの認証¶
環境変数またはプログラムを使用してAPIトークンを設定します。 DATAROBOT_API_TOKENは、アカウント設定の「APIのキーとツール」セクションにあります。
エージェントテンプレートでは、環境変数DATAROBOT_API_TOKENおよびDATAROBOT_ENDPOINTが設定されていると、それらが自動的に使用されます。 これは、資格情報をコードに残さず、MyAgentの初期化とシームレスに連携するため、推奨されるアプローチです。 MyAgentクラスは、資格情報が明示的に指定されていない場合、自動的にこれらの環境変数にフォールバックします。 外部ツールとの連携にオプションのToolClientクラスを使用する場合、デフォルトでこれらの環境変数も使用します。
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"
)
外部ツール用ToolClient
datarobot-genaiパッケージのToolClientクラスを使用して外部ツールを統合している場合は、プログラムで資格情報を渡すこともできます。 詳細については、ツール連携のドキュメントを参照してください。
外部APIの認証¶
When creating custom tools that need to authenticate with external APIs, retrieve API keys from environment variables or runtime parameters within your tool's run() method. これにより、資格情報がソースコードに含まれず、エージェントテンプレート全体で使用されているのと同じセキュリティパターンに従います。
For local development, use environment variables. For deployed agents, define runtime parameters in model-metadata.yaml and retrieve them using RuntimeParameters.get() from datarobot_drum. Try os.environ.get() first (for local development), then fall back to RuntimeParameters.get() for deployed agents., as shown in the example below:
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()
Define runtime parameters for deployment
To use runtime parameters in deployed agents, define them in your model-metadata.yaml file. For credential-type parameters (like API keys), use type: credential:
runtimeParameterDefinitions:
- fieldName: EXTERNAL_API_KEY
type: credential
credentialType: api_token
description: API key for external service authentication
See the runtime parameters documentation for more details on configuration options.
認可コンテキスト¶
フレームワークは、認証情報を下流のツールやサービスに伝えるための認可コンテキストシステムを提供します。 これにより、手動で設定することなく、エージェントツール間でトークンと資格情報を自動的に受け渡すことができます。
datarobot-genaiパッケージのresolve_authorization_context()を使用し、エージェントのchat()関数で認可コンテキストを初期化します。 この関数は認可コンテキストディクショナリを返します。これは、completion_create_params["authorization_context"]に割り当てる必要があります。 その後、ツールはdatarobot SDKのget_authorization_context()を使用してコンテキストを取得できます。
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")
ToolClientと認可コンテキスト
外部ツールの統合にdatarobot-genaiパッケージのオプションクラスToolClientを使用すると、エージェントツールを呼び出す際に認可コンテキストを自動的に反映します。 詳細については、ツール連携のドキュメントを参照してください。
OAuth 2.0認証¶
OAuth 2.0をサポートする外部サービスの場合は、ツールにOAuthフローを実装します。 サービスの開発者コンソールでOAuthアプリケーションを作成し、環境変数を設定します。
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エージェントテンプレートのツールの標準基本クラス)を継承し、インメモリーキャッシュを使用して独自のトークンライフサイクルを管理し、環境変数から資格情報を取得するリポジトリのパターンに従います。
実装例
これは、基本的なOAuth認証パターンを示すCrewAI固有のフレームワークの例です。 run()メソッドはトークンの使用方法を示すためのプレースホルダーAPI呼び出しを行いますが、実際のツールロジックは、具体的なユースケースに基づいて実装する必要があります。
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()
Security best practices¶
本番環境で認証を処理する場合、セキュリティのベストプラクティスに従うことが不可欠です。 以下のガイドラインに従ってください。
- APIトークン認証
- トークンは環境変数に保管します。ソースコードにシークレットを直接記述することは絶対に避けてください。
- 本番環境ではセキュアなトークン保管ソリューションを利用します。
- トークンのローテーションを実施し、トークンの有効期限ポリシーを適用します。
- 認可コンテキストは、検証してからツールで使用します。
- 最小権限の原則に従います。
- 監査目的で認証イベントをログに記録します。
- OAuth 2.0
- すべてのOAuth通信にHTTPSを使用します。
- CSRF攻撃を防ぐために
stateパラメーターを検証します。 - リフレッシュトークンをセキュアに保管します。
- トークンの有効期限とリフレッシュのロジックを確実に処理します。
- 認可コンテキストは、検証してから使用します。
- セキュリティ全般
- 開発と運用に別々の環境を使用します。
- 強固なシークレット管理プラクティスを実施します。
- コンテナセキュリティのベストプラクティスに従います。
- 定期的なセキュリティ監査を実施し、更新プログラムを適用します。
認証に関する問題のトラブルシューティング¶
このセクションでは、エージェントの開発またはデプロイ時に発生する一般的な認証の問題を診断し、解決する方法について説明します。
よくある問題¶
以下のセクションでは、一般的な認証エラーとその解決方法について説明します。
APIトークンがない¶
このエラーは、DataRobot APIトークンが設定されていない場合に発生します。
問題:エラー:DataRobot APIトークンがありません。 DATAROBOT_API_TOKEN環境変数を設定してください
解決方法:DataRobot APIキーを使用するようにDATAROBOT_API_TOKEN環境変数を設定します。
無効なエンドポイント¶
このエラーは、DataRobotのエンドポイントがないか、正しく設定されていない場合に発生します。
問題:エラー:DataRobotのエンドポイントがありません。 DATAROBOT_ENDPOINT環境変数を設定してください
解決方法:DATAROBOT_ENDPOINT環境変数を正しく設定します。
Authorization context not set¶
このエラーは、ツールが初期化前の認可コンテキストにアクセスしようとすると発生します。
問題:エラー:ツールで認可コンテキストを使用できません
解決方法:resolve_authorization_context()がエージェントのchat()関数で呼び出され、その結果がcompletion_create_params["authorization_context"]に割り当てられるようにします。
OAuthトークンの有効期限切れ¶
このエラーは、OAuthアクセストークンの有効期限が切れており、リフレッシュする必要がある場合に発生します。
問題:エラー:401 Unauthorized
解決方法:トークンリフレッシュロジックを実装するか、再認証します。
Debugging tips¶
認証の問題をデバッグするのに役立つテクニックを紹介します。
Enable verbose logging¶
認証操作に関する詳細情報を取得するには、詳細ログを有効にします。 そのためには、custom.pyでMyAgentがインスタンス化されている場所を探し、verbose=Trueを設定します。
from agent import MyAgent
# ...
agent = MyAgent(verbose=True, **completion_create_params)
Check environment variables¶
必要な環境変数が正しく設定されていることを確認します。
import os
print(f"API Token: {os.getenv('DATAROBOT_API_TOKEN')}")
print(f"Endpoint: {os.getenv('DATAROBOT_ENDPOINT')}")
Test authentication¶
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()を使用して、認可コンテキストを確認します。
from datarobot.models.genai.agent.auth import get_authorization_context
auth_context = get_authorization_context()
print(f"Authorization context: {auth_context}")