エージェント認証¶
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が設定されていると、それらが自動的に使用されます。 これは、資格情報をコードに残さず、ToolClientクラスおよびMyAgentの初期化とシームレスに連携するため、推奨されるアプローチです。 どちらのパラメーターも、資格情報が明示的に指定されていない場合、自動的にこれらの環境変数にフォールバックします。
DATAROBOT_API_TOKEN=<your_api_key>
DATAROBOT_ENDPOINT=https://app.datarobot.com
ToolClientクラスはdatarobot-genaiパッケージで使用でき、DataRobotサービスへの認証をプログラムで実行する方法を提供します。 API資格情報は、ToolClientまたはMyAgentクラスを初期化するときに直接渡すことができます。 これは、環境変数をオーバーライドしたり、特定のインスタンスに対して異なる資格情報を使用したりする必要がある場合に便利です。 ToolClientクラスは、パラメーターが指定されていない場合でも環境変数にフォールバックします。
from datarobot_genai.core.chat.client import ToolClient
tool_client = ToolClient(
api_key="your_api_key",
base_url="https://app.datarobot.com"
)
外部APIの認証¶
外部APIへの認証が必要なカスタムツールを作成する場合は、ツールのrun()メソッド内で環境変数からAPIキーを取得します。 これにより、資格情報がソースコードに含まれず、エージェントテンプレート全体で使用されているのと同じセキュリティパターンに従います。 以下の例は、標準的なパターンを示しています。os.getenv()を使用してAPIキーを取得し、それを外部APIへのリクエストヘッダーに含めます。
import os
import requests
from crewai.tools import BaseTool
class ExternalAPITool(BaseTool):
def run(self, query: str) -> str:
api_key = os.getenv("EXTERNAL_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(
"https://api.external-service.com/data",
headers=headers,
params={"query": query}
)
return response.json()
認可コンテキスト¶
フレームワークは、認証情報を下流のツールやサービスに伝えるための認可コンテキストシステムを提供します。 これにより、手動で設定することなく、エージェントツール間でトークンと資格情報を自動的に受け渡すことができます。
datarobot-genaiパッケージのinitialize_authorization_context()を使用し、エージェントのchat()関数で認可コンテキストを初期化します。 その後、ツールはdatarobot SDKのget_authorization_context()を使用してコンテキストを取得できます。
from datarobot_genai.core.chat import initialize_authorization_context
from datarobot.models.genai.agent.auth import get_authorization_context
# In your chat() function
initialize_authorization_context(completion_create_params)
# In your tools
auth_context = get_authorization_context()
access_token = auth_context.get("access_token")
datarobot-genaiパッケージのToolClientクラスは、エージェントツールを呼び出す際に認可コンテキストを自動的に反映します。
from datarobot_genai.core.chat.client import ToolClient
tool_client = ToolClient()
result = tool_client.call(
deployment_id="your_deployment_id",
payload={"query": "your_query"}
)
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¶
このエラーは、ツールが初期化前の認可コンテキストにアクセスしようとすると発生します。
問題:エラー:ツールで認可コンテキストを使用できません
解決方法:initialize_authorization_context()がエージェントのchat()関数で呼び出されるようにします。
OAuthトークンの有効期限切れ¶
このエラーは、OAuthアクセストークンの有効期限が切れており、リフレッシュする必要がある場合に発生します。
問題:エラー:401 Unauthorized
解決方法:トークンリフレッシュロジックを実装するか、再認証します。
Debugging tips¶
認証の問題をデバッグするのに役立つテクニックを紹介します。
Enable verbose logging¶
認証操作に関する詳細情報を取得するには、詳細ログを有効にします。 そのためには、agent.pyに以下のコードを追加します。
from agent_generic_base.custom_model.agent import MyAgent
agent = MyAgent(verbose=True)
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}")