エージェントコンポーネント¶
この概要では、DataRobotのエージェントフレームワークを使用してエージェントを作成するために必要なコンポーネントについて詳しく説明します。 エージェントのアーティファクトには、メタデータ、フック/関数、クラス、プロパティを含む複数の標準ファイルなどがあります。
| セクション | 説明 |
|---|---|
| エージェントファイルの構造 | DataRobotエージェントの重要なファイルとその構成について説明します。 |
| 関数とフック | エージェント操作に必要な必須関数と統合フックについて詳しく説明します。 |
| エージェントクラスの実装 | メインエージェントクラスの一般的な構造と、そのメソッドおよびプロパティについて詳しく説明します。 |
| ツールの連携 | エージェントがToolClientクラスとフレームワーク固有のツールAPIを介してツールを使用する方法を説明します。 |
エージェントファイルの構造¶
すべてのDataRobotエージェントは、agent/agent/ディレクトリ内に特定のファイルセットを必要とします（例：DataRobot Agentic Starterのテンプレート）。 これらのファイルは連携し、DataRobotによってデプロイおよび実行できる完全なエージェントを作成します。
agent/agent/
├── __init__.py # Package initialization
├── myagent.py # Main agent implementation, including prompts
├── config.py # Configuration management
├── register.py # DRAgent / NAT registration (framework-specific)
├── workflow.yaml # Declarative workflow config for DRAgent (framework-specific)
└── model-metadata.yaml # Agent metadata configuration
Parent directory agent/ also contains custom.py (DRUM hooks), dev.py, cli.py, and other infrastructure files.
| ファイル | 説明 |
|---|---|
__init__.py |
ディレクトリをPythonパッケージとして識別し、インポートを有効にします。 |
model-metadata.yaml |
エージェントの設定、ランタイムパラメーター、デプロイ設定を定義します。 |
custom.py (under the parent agent/, one level up) |
エージェントを実行するためのDataRobot統合フック（load_model、chat）を実装します。 |
myagent.py |
Contains the main agent workflow. Depending on the framework, this may be a MyAgent class or a factory-produced agent (for example, LangGraph uses datarobot_agent_class_from_langgraph). |
config.py |
環境変数、ランタイムパラメーター、およびDataRobotの資格情報からの設定読み込みを管理します。 |
register.py |
Connects the DRAgent front server to your agent: LLM wrappers, MCP tools, and optional workflow tools. |
workflow.yaml |
Declares workflow type, LLM component, and related settings for DRAgent. |
エージェントのメタデータ（model-metadata.yaml）¶
model-metadata.yamlファイルは、エージェントの設定およびデプロイ方法をDataRobotに指示します。 エージェントのタイプ、名前、および必要なランタイムパラメーターを定義します。
---
name: agent_name
type: inference
targetType: agenticworkflow
runtimeParameterDefinitions:
- fieldName: LLM_DEPLOYMENT_ID
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
- fieldName: LLM_DEFAULT_MODEL
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
- fieldName: LLM_DEFAULT_MODEL_FRIENDLY_NAME
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
- fieldName: USE_DATAROBOT_LLM_GATEWAY
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
- fieldName: MCP_DEPLOYMENT_ID
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
- fieldName: EXTERNAL_MCP_URL
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
- fieldName: SESSION_SECRET_KEY
defaultValue: SET_VIA_PULUMI_OR_MANUALLY
type: string
| フィールド | 説明 |
|---|---|
name |
DataRobotでのエージェントの表示名（識別とデプロイに使用されます）。 |
type |
エージェントのモデルタイプ。 すべてのDataRobotエージェントでinferenceである必要があります。 |
targetType |
エージェントのターゲットタイプ。 エージェントワークフローのデプロイでは、agenticworkflowである必要があります。 |
runtimeParameterDefinitions |
LLM設定、MCPサーバー接続、およびその他のエージェント設定のためのオプションのランタイムパラメーターを定義します。 |
LLMプロバイダーの設定
エージェントは、以下のような複数のLLMプロバイダー設定をサポートしています。
- LLM Gatewayを直接使用：DataRobotのLLM Gatewayを直接使用します。
- LLM blueprint with external LLMs: Connect to external providers (Azure OpenAI, Amazon Bedrock, Google Vertex AI, Anthropic, Cohere, TogetherAI)
- デプロイされたモデル：
LLM_DEPLOYMENT_IDを使用して、DataRobotにデプロイされたLLMを使用します。
When you use the DataRobot Deployed LLM option, USE_DATAROBOT_LLM_GATEWAY is automatically set to 0 so the workflow targets your deployment instead of the gateway.
関数とフック（custom.py）¶
エージェントは、「フック」と呼ばれる特定の関数シグネチャを使用してDataRobotと統合します。 custom.pyファイルには、DataRobotがエージェントを実行するために呼び出す必要のある関数が含まれています。 これらの関数は、DataRobotとエージェントのロジックを接続します。 詳細については、構造化モデルフックのドキュメントを参照してください。 以下のDataRobotカスタムモデルフックが、custom.pyに実装されています。
| コンポーネント | 説明 |
|---|---|
load_model() |
DataRobotがエージェントを起動するときに呼び出される1回限りの初期化関数。 |
chat() |
各ユーザー操作やチャットメッセージごとに呼び出されるメインの実行関数。 |
DataRobotのその他のフック
score()およびscore_unstructured()関数は、特定のユースケースで必要な場合に実装できます。
load_model()フック¶
load_model()フックは、エージェントを初期化するために一度だけ呼び出されます。 ここでは、1回限りの設定を定義できます。
def load_model(code_dir: str) -> tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop]:
"""The agent is instantiated in this function and returned.
Args:
code_dir: Path to the agentic workflow directory
Returns:
tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop]: Thread pool executor and event loop for async operations
"""
thread_pool_executor = ThreadPoolExecutor(1)
event_loop = asyncio.new_event_loop()
thread_pool_executor.submit(asyncio.set_event_loop, event_loop).result()
return (thread_pool_executor, event_loop)
chat()フック¶
エージェントの主なエントリーポイント。 DataRobotは、ユーザーがエージェントにメッセージを送信するたびに、この関数を呼び出します。
def chat(
completion_create_params: CompletionCreateParams
| CompletionCreateParamsNonStreaming
| CompletionCreateParamsStreaming,
load_model_result: tuple[ThreadPoolExecutor, asyncio.AbstractEventLoop],
**kwargs: Any,
) -> Union[CustomModelChatResponse, Iterator[CustomModelStreamingResponse]]:
"""Main entry point for agent execution via chat endpoint.
Args:
completion_create_params: OpenAI-compatible completion parameters
load_model_result: Result from load_model() function
**kwargs: Additional keyword arguments (e.g., headers)
Returns:
Union[CustomModelChatResponse, Iterator[CustomModelStreamingResponse]]: Formatted response with agent output
"""
エージェントクラスの実装（myagent.py）¶
The myagent.py file contains the workflow logic for your agent. In many templates this is a MyAgent class; in current LangGraph Agentic Starter projects, MyAgent is produced by datarobot_agent_class_from_langgraph from a graph_factory and prompt template. This is where you define how the agent behaves, which tools it receives, and how it processes inputs.
| コンポーネント | 説明 |
|---|---|
init() |
資格情報、構成、およびフレームワーク固有の設定を使用してエージェントを初期化するメソッド。 |
invoke() |
入力を処理し、フレームワーク固有の結果を返すメインの実行メソッド。 |
llm or llm() |
エージェント操作用に設定されたLLMインスタンスを返すプロパティまたはメソッド（フレームワークのテンプレートによって異なります）。 |
どのエージェントもこの基本パターンに従いますが、具体的な実装はフレームワークによって異なります。
フレームワーク固有の実装
CrewAI、LangGraph、LlamaIndex、およびNAT（NVIDIA NeMo Agent Toolkit）のテンプレートには、フレームワーク固有のllmまたはllm()の実装と戻り値の型が含まれています。 Generic Baseテンプレートは、どんなフレームワークでもカスタマイズできる最小限の実装を提供します。 NATのテンプレートでは、Pythonのllm設定ではなくworkflow.yamlでLLMを設定します。
class MyAgent:
"""Agent implementation following DataRobot patterns."""
def __init__(
self,
api_key: Optional[str] = None,
api_base: Optional[str] = None,
model: Optional[str] = None,
verbose: Optional[Union[bool, str]] = True,
timeout: Optional[int] = 90,
**kwargs: Any,
):
"""Initialize agent with credentials and configuration."""
self.api_key = api_key or os.environ.get("DATAROBOT_API_TOKEN")
self.api_base = api_base or os.environ.get("DATAROBOT_ENDPOINT")
self.model = model
self.timeout = timeout
# ... other initialization
@property
def llm(self) -> LLM: # Framework-specific type
"""Primary LLM configuration."""
if os.environ.get("LLM_DEPLOYMENT_ID"):
return self.llm_with_datarobot_deployment
else:
return self.llm_with_datarobot_llm_gateway
def invoke(self, completion_create_params: CompletionCreateParams) -> Union[
Generator[tuple[str, Any | None, dict[str, int]], None, None],
tuple[str, Any | None, dict[str, int]],
]:
"""Main execution method - REQUIRED."""
# Extract inputs
inputs = create_inputs_from_completion_params(completion_create_params)
# Execute agent workflow
# Return results
return response_text, pipeline_interactions, usage_metrics
__init__()メソッド¶
DataRobotからの構成と資格情報、およびフレームワーク固有の設定を使用して、エージェントを初期化するメソッド。
class MyAgent:
def __init__(self, api_key: Optional[str] = None,
api_base: Optional[str] = None,
model: Optional[str] = None,
verbose: Optional[Union[bool, str]] = True,
timeout: Optional[int] = 90,
**kwargs: Any):
"""Initialize agent with DataRobot credentials and configuration."""
invoke()メソッド¶
DataRobotがエージェントを実行するために呼び出すコア実行メソッドです。 このメソッドの実装は必須であり、エージェントのメインワークフローロジックが含まれている必要があります。 どのフレームワークでも、使われる戻り値の型のパターンは同じです。
def invoke(self, completion_create_params: CompletionCreateParams) -> Union[
Generator[tuple[str, Any | None, dict[str, int]], None, None],
tuple[str, Any | None, dict[str, int]],
]:
"""Main execution method - REQUIRED for DataRobot integration.
Args:
completion_create_params: Input parameters from DataRobot
Returns:
Union of generator (for streaming) or tuple (for non-streaming):
- response_text: str - The agent's response
- pipeline_interactions: Any | None - Event tracking data
- usage_metrics: dict[str, int] - Token usage statistics
"""
llmプロパティ¶
エージェントが回答を生成するために使用する言語モデルを定義します。 戻り値の型と実装は、フレームワークによって異なります。
The CrewAI and LlamaIndex templates implement API base URL logic directly within their llm properties. LangGraph starter templates typically obtain the chat model through helpers such as get_llm in the DRUM/DRAgent adaptor path rather than an llm property on a handwritten class.
@property
def llm(self) -> LLM: # Framework-specific type
"""Primary LLM instance for agent operations.
Returns:
Framework-specific LLM type:
- CrewAI: LLM
- LlamaIndex: DataRobotLiteLLM
"""
api_base = urlparse(self.api_base)
if os.environ.get("LLM_DEPLOYMENT_ID"):
# Handle deployment-specific URL construction
# ... implementation details ...
return LLM(model="openai/gpt-4o-mini", api_base=deployment_url, ...)
else:
# Handle LLM gateway URL construction
# ... implementation details ...
return LLM(model="datarobot/azure/gpt-5-mini-2025-08-07", api_base=api_base.geturl(), ...)
Generic Baseテンプレートはllm()プロパティを以下のように実装しています。
@property
def llm(self) -> Any:
"""Primary LLM instance for agent operations.
Returns:
Any: Minimal implementation for custom frameworks
"""
if os.environ.get("LLM_DEPLOYMENT_ID"):
return self.llm_with_datarobot_deployment
else:
return self.llm_with_datarobot_llm_gateway
NATのテンプレートでは、Pythonのプロパティではなくworkflow.yamlでLLMを設定します。 DataRobot LLM Gateway（_type: datarobot-llm-gateway）、DataRobotのデプロイ（_type: datarobot-llm-deployment）、またはDataRobotのNIMデプロイ（_type: datarobot-nim）を使用できます。 以下の例では、DataRobot LLM Gatewayを使用しています。
llms:
datarobot_llm:
_type: datarobot-llm-gateway
model_name: azure/gpt-4o-mini # Define the model name you want to use
temperature: 0.0
特定のエージェントが使用するLLMは、functionsセクション内のそのエージェントの定義でllm_nameによって定義されます。
functions:
planner:
_type: chat_completion
llm_name: datarobot_llm # Reference the LLM defined above
system_prompt: |
You are a content planner...
llmsセクションに複数のLLMが定義されている場合、各functionsはタスクに合わせて異なるLLMを使用できます。
NATが提供するLLMインターフェイス
LLM Gatewayの代わりに、NATが提供するLLMインターフェイスを利用することもできます。 NAT LLMインターフェイスを利用するには、api_keyやurlなどの必要な設定パラメーターやプロバイダー固有のその他の設定をworkflow.yamlファイルに直接追加します。
NATのテンプレートとともにDataRobotのデプロイを使用する方法については、コードでのLLMプロバイダーの設定を参照してください。
ツールの連携¶
エージェントはToolClientクラスを介して機能を拡張するツールを使用できます。これにより、エージェントはDataRobotツールのデプロイを呼び出すことができます。 以前のバージョンにあったhelpers.pyの機能は、バージョン11.3.1において、エージェントをDataRobotのDRUMサーバーに接続するその他のアダプターコードとともに、datarobot-genaiパッケージへ移行されました。
ToolClientの使用に関する注意事項
ToolClientは、DataRobot内でユーザーがデプロイしたグローバルツールを呼び出すために特別に用意されたものです。 このクライアントはそのような特殊なユースケースに対応するため、エージェントツールの実装の大半では必要ありません。
フレームワーク固有のツール¶
各フレームワークは、カスタムツールを定義するための独自のネイティブツールAPIを提供します。
- CrewAI：ツールは、
toolsパラメーターを介してAgentインスタンスに渡されます。 - LangGraph：ツールはグラフのノードとエッジの一部として定義されます。
- LlamaIndex：ツールは関数として定義され、エージェントのコンストラクタに渡されます。
- NAT：ツールは
workflow.yamlで関数として定義され、ワークフローのtool_listで参照されます（使用可能なツールタイプはnat_toolサブモジュールで定義されます）。
NATエージェントの設定
クエリーに応じてどのツールをどの順番で実行するかを決める柔軟なエージェントには、sequential_executorの代わりにreact_agentを使用します。
認可コンテキスト¶
アクセストークンを必要とするツールの認証を自動的に処理するため、datarobot-genaiパッケージのresolve_authorization_context()関数がcustom.pyで呼び出されます。 この関数は、completion_create_params["authorization_context"]に割り当てられる認可コンテキストディクショナリを返します。 これにより、DataRobotの資格情報管理システムを使用して、ツールが安全に外部サービスにアクセスできるようになります。