Agent components¶

この概要では、DataRobotのエージェントフレームワークを使用してエージェントを作成するために必要なコンポーネントについて詳しく説明します。エージェントのアーティファクトには、メタデータ、フック/関数、クラス、プロパティを含む複数の標準ファイルなどがあります。

セクション	説明
エージェントファイルの構造	DataRobotエージェントの重要なファイルとその構成について説明します。
関数とフック	エージェント操作に必要な必須関数と統合フックについて詳しく説明します。
エージェントクラスの実装	メインエージェントクラスの一般的な構造と、そのメソッドおよびプロパティについて詳しく説明します。
Tool integration	エージェントが`ToolClient`クラスとフレームワーク固有のツールAPIを介してツールを使用する方法を説明します。

エージェントファイルの構造¶

すべてのDataRobotエージェントは、custom_model/ディレクトリ内に特定のファイルセットを必要とします。これらのファイルは連携し、DataRobotによってデプロイおよび実行できる完全なエージェントを作成します。

custom_model/ directory

custom_model/
├── __init__.py           # Package initialization
├── agent.py              # Main agent implementation, including prompts
├── custom.py             # DataRobot integration hooks
├── config.py             # Configuration management
├── mcp_client.py         # MCP server integration (optional, for tool use)
└── model-metadata.yaml   # Agent metadata configuration

ファイル	説明
`__init__.py`	ディレクトリをPythonパッケージとして識別し、インポートを有効にします。
`model-metadata.yaml`	エージェントの設定、ランタイムパラメーター、デプロイ設定を定義します。
`custom.py`	エージェントを実行するためのDataRobot統合フック（`load_model`、`chat`）を実装します。
`agent.py`	ワークフローのコアロジックとフレームワーク固有の実装を持つ、メインの`MyAgent`クラスが含まれています。
`config.py`	Manages configuration loading from environment variables, runtime parameters, and DataRobot credentials.
`mcp_client.py`	Provides MCP server connection management for tool integration (optional, only needed when using MCP tools).

エージェントのメタデータ（`model-metadata.yaml`）¶

model-metadata.yamlファイルは、エージェントの設定およびデプロイ方法をDataRobotに指示します。エージェントのタイプ、名前、および必要なランタイムパラメーターを定義します。

model-metadata.yaml

---
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`	Defines optional runtime parameters for LLM configuration, MCP server connections, and other agent settings.

LLM Provider Configuration

Agents support multiple LLM provider configurations including:

LLM gateway direct: Use DataRobot's LLM Gateway directly
LLM blueprint with external LLMs: Connect to external providers (Azure OpenAI, Amazon Bedrock, Google Vertex AI, Anthropic, Cohere, TogetherAI)s
Deployed models: Use a DataRobot-deployed LLM via LLM_DEPLOYMENT_ID

関数とフック（`custom.py`）¶

エージェントは、「フック」と呼ばれる特定の関数シグネチャを使用してDataRobotと統合します。 custom.pyファイルには、DataRobotがエージェントを実行するために呼び出す必要のある関数が含まれています。これらの関数は、DataRobotとエージェントのロジックを接続します。詳細については、構造化モデルフックのドキュメントを参照してください。以下のDataRobotカスタムモデルフックが、custom.pyに実装されています。

コンポーネント	説明
`load_model()`	DataRobotがエージェントを起動するときに呼び出される1回限りの初期化関数。
`chat()`	各ユーザー操作やチャットメッセージごとに呼び出されるメインの実行関数。

DataRobotのその他のフック

score()およびscore_unstructured()関数は、特定のユースケースで必要な場合に実装できます。

`load_model()`フック¶

load_model()フックは、エージェントを初期化するために一度だけ呼び出されます。ここでは、1回限りの設定を定義できます。

custom.py

def load_model(code_dir: str) -> str:
    """The agent is instantiated in this function and returned.

    Args:
        code_dir: Path to the custom model directory

    Returns:
        str: "success" on successful initialization
    """
    _ = code_dir
    return "success"

`chat()`フック¶

エージェントの主なエントリーポイント。 DataRobotは、ユーザーがエージェントにメッセージを送信するたびに、この関数を呼び出します。

custom.py

def chat(
    completion_create_params: CompletionCreateParams,
    model: str,
) -> CustomModelChatResponse:
    """Main entry point for agent execution via chat endpoint.

    Args:
        completion_create_params: OpenAI-compatible completion parameters
        model: Model identifier

    Returns:
        CustomModelChatResponse: Formatted response with agent output
    """

エージェントクラスの実装（`agent.py`）¶

agent.pyファイルには、ワークフローのロジックを実装するためのMyAgentクラスが含まれています。ここでは、エージェントの動作、エージェントが使用するツール、およびエージェントが入力を処理する方法を定義します。

コンポーネント	説明
`init()`	資格情報、構成、およびフレームワーク固有の設定を使用してエージェントを初期化するメソッド。
`invoke()`	入力を処理し、フレームワーク固有の結果を返すメインの実行メソッド。
`llm`	エージェント操作用に設定されたLLMインスタンスを返すプロパティ。

どのエージェントもこの基本パターンに従いますが、具体的な実装はフレームワークによって異なります。

フレームワーク固有の実装

CrewAI、LangGraph、LlamaIndex、およびNAT（NVIDIA NeMo Agent Toolkit）のテンプレートには、フレームワーク固有のllmプロパティと戻り値の型が含まれています。 Generic Baseテンプレートは、どんなフレームワークでもカスタマイズできる最小限の実装を提供します。 NATのテンプレートでは、Pythonのllmプロパティではなくworkflow.yamlでLLMを設定します。

agent.py

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からの構成と資格情報、およびフレームワーク固有の設定を使用して、エージェントを初期化するメソッド。

agent.py

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がエージェントを実行するために呼び出すコア実行メソッドです。このメソッドの実装は必須であり、エージェントのメインワークフローロジックが含まれている必要があります。どのフレームワークでも、使われる戻り値の型のパターンは同じです。

agent.py

    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` property¶

エージェントが回答を生成するために使用する言語モデルを定義します。戻り値の型と実装は、フレームワークによって異なります。

The CrewAI, LangGraph, and LlamaIndex templates implement API base URL logic directly within their llm properties:

agent.py (CrewAI/LangGraph/LlamaIndex)

@property
def llm(self) -> LLM:  # Framework-specific type
    """Primary LLM instance for agent operations.

    Returns:
        Framework-specific LLM type:
        - CrewAI: LLM
        - LangGraph: ChatLiteLLM  
        - 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-4o-mini", api_base=api_base.geturl(), ...)

The Generic Base template implements the llm property as follows:

agent.py (Generic Base)

@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を使用しています。

workflow.yaml (NAT)

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によって定義されます。

workflow.yaml (NAT)

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プロバイダーの設定を参照してください。

Tool integration¶

エージェントはToolClientクラスを介して機能を拡張するツールを使用できます。これにより、エージェントはDataRobotツールのデプロイを呼び出すことができます。以前のバージョンにあったhelpers.pyの機能は、バージョン11.3.1において、エージェントをDataRobotのDRUMサーバーに接続するその他のアダプターコードとともに、datarobot-genaiパッケージへ移行されました。

ToolClientの使用に関する注意事項

ToolClientは、DataRobot内でユーザーがデプロイしたグローバルツールを呼び出すために特別に用意されたものです。このクライアントはそのような特殊なユースケースに対応するため、エージェントツールの実装の大半では必要ありません。

Framework-specific tools¶

Each framework provides its own native tool APIs for defining custom tools:

CrewAI：ツールは、toolsパラメーターを介してAgentインスタンスに渡されます。
LangGraph：ツールはグラフのノードとエッジの一部として定義されます。
LlamaIndex：ツールは関数として定義され、エージェントのコンストラクタに渡されます。
NAT：ツールはworkflow.yamlで関数として定義され、ワークフローのtool_listで参照されます（使用可能なツールタイプはnat_toolサブモジュールで定義されます）。

NATエージェントの設定

クエリーに応じてどのツールをどの順番で実行するかを決める柔軟なエージェントには、sequential_executorの代わりにreact_agentを使用します。

認可コンテキスト¶

The initialize_authorization_context() function from the datarobot-genai package is called in custom.py to automatically handle authentication for tools that require access tokens. This ensures tools can securely access external services using DataRobot's credential management system.

Agent components¶

エージェントファイルの構造¶

エージェントのメタデータ（model-metadata.yaml）¶

関数とフック（custom.py）¶

load_model()フック¶

chat()フック¶

エージェントクラスの実装（agent.py）¶

__init__()メソッド¶

invoke()メソッド¶

llm property¶

Tool integration¶

Framework-specific tools¶

認可コンテキスト¶

エージェントのメタデータ（`model-metadata.yaml`）¶

関数とフック（`custom.py`）¶

`load_model()`フック¶

`chat()`フック¶

エージェントクラスの実装（`agent.py`）¶

`init()`メソッド¶

`invoke()`メソッド¶

`llm` property¶