エージェント型AI > 構築 > エージェントコンポーネント

エージェントコンポーネント¶

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

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

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

Every DataRobot agent requires a specific set of files in the agent/agent/ directory (for example, in the DataRobot Agentic Starter template). これらのファイルは連携し、DataRobotによってデプロイおよび実行できる完全なエージェントを作成します。

agent/agent/ directory

agent/agent/
├── __init__.py           # Package initialization
├── myagent.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`）を実装します。
`myagent.py`	ワークフローのコアロジックとフレームワーク固有の実装を持つ、メインの`MyAgent`クラスが含まれています。
`config.py`	環境変数、ランタイムパラメーター、およびDataRobotの資格情報からの設定読み込みを管理します。
`mcp_client.py`	ツール連携のためのMCPサーバー接続管理を提供します（オプション。MCPツールを使用する場合にのみ必要です）。

エージェントのメタデータ（`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`	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回限りの設定を定義できます。

custom.py

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は、ユーザーがエージェントにメッセージを送信するたびに、この関数を呼び出します。

custom.py

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
    """

Agent class implementation (`myagent.py`)¶

The myagent.py file contains the MyAgent class to implement the workflow logic. ここでは、エージェントの動作、エージェントが使用するツール、およびエージェントが入力を処理する方法を定義します。

コンポーネント	説明
`init()`	資格情報、構成、およびフレームワーク固有の設定を使用してエージェントを初期化するメソッド。
`invoke()`	入力を処理し、フレームワーク固有の結果を返すメインの実行メソッド。
`llm` or `llm()`	Property or method (depending on framework template) that returns the configured LLM instance for agent operations.

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

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

CrewAI, LangGraph, LlamaIndex, and NAT (NVIDIA NeMo Agent Toolkit) templates include framework-specific llm or llm() implementations and return types. Generic Baseテンプレートは、どんなフレームワークでもカスタマイズできる最小限の実装を提供します。 NAT templates configure LLMs in workflow.yaml rather than through Python llm configuration.

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

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

myagent.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`プロパティ¶

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

CrewAI、LangGraph、LlamaIndexの各テンプレートは、APIのベースURLロジックをllmプロパティ内に直接実装しています。

myagent.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-5-mini-2025-08-07", api_base=api_base.geturl(), ...)

Generic Baseテンプレートはllm()プロパティを以下のように実装しています。

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

ツールの連携¶

エージェントは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の資格情報管理システムを使用して、ツールが安全に外部サービスにアクセスできるようになります。

エージェントコンポーネント¶

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

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

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

load_model()フック¶

chat()フック¶

Agent class implementation (myagent.py)¶

__init__()メソッド¶

invoke()メソッド¶

llmプロパティ¶

ツールの連携¶

フレームワーク固有のツール¶

認可コンテキスト¶

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

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

`load_model()`フック¶

`chat()`フック¶

Agent class implementation (`myagent.py`)¶

`init()`メソッド¶

`invoke()`メソッド¶

`llm`プロパティ¶