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

> エージェントコンポーネント - この概要では、DataRobotのエージェントフレームワークを使用してエージェントを作成するために必要なコンポーネントについて詳しく説明します。

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-07-15T05:55:44.565287+00:00` (UTC).

## Primary page

- [エージェントコンポーネント](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md): Full documentation for this topic (Markdown sidecar).

## Sections on this page

- [エージェントファイルの構造](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#agent-file-structure): In-page section heading.
- [エージェントのメタデータ（model-metadata.yaml）](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#agent-metadata-model-metadata-yaml): In-page section heading.
- [関数とフック（custom.py）](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#functions-and-hooks-custom-py): In-page section heading.
- [load_model()フック](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#load-model-hook): In-page section heading.
- [chat()フック](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#chat-hook): In-page section heading.
- [エージェントクラスの実装（myagent.py）](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#agent-class-implementation-myagent-py): In-page section heading.
- [__init__()メソッド](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#init-method): In-page section heading.
- [invoke()メソッド](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#invoke-method): In-page section heading.
- [llmプロパティ](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#llm-property): In-page section heading.
- [ツールの連携](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#tool-integration): In-page section heading.
- [フレームワーク固有のツール](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#framework-tools): In-page section heading.
- [認可コンテキスト](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-overview.html.md#authorization-context): In-page section heading.

## Documentation content

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

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

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

すべてのDataRobotエージェントは、 `agent/agent/` ディレクトリ内に特定のファイルセットを必要とします（例： [DataRobot Agentic Starterのテンプレート](https://github.com/datarobot-community/datarobot-agent-application) ）。 これらのファイルは連携し、DataRobotによってデプロイおよび実行できる完全なエージェントを作成します。

```
# agent/agent/ directory
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 
```

親ディレクトリ `agent/` には、 `custom.py` （DRUMフック）、 `dev.py` 、 `cli.py` 、およびその他のインフラストラクチャファイルも含まれています。

| ファイル | 説明 |
| --- | --- |
| __init__.py | ディレクトリをPythonパッケージとして識別し、インポートを有効にします。 |
| model-metadata.yaml | エージェントの設定、ランタイムパラメーター、デプロイ設定を定義します。 |
| custom.py（親agent/の下、1つ上のレベル） | エージェントを実行するためのDataRobot統合フック（load_model、chat）を実装します。 |
| myagent.py | 主要なエージェントのワークフローが含まれています。 フレームワークによっては、これはMyAgentクラスである場合もあれば、ファクトリー生成エージェントである場合もあります（たとえば、LangGraphではdatarobot_agent_class_from_langgraphが使用されます）。 |
| config.py | 環境変数、ランタイムパラメーター、およびDataRobotの資格情報からの設定読み込みを管理します。 |
| register.py | DRAgentのフロントサーバーをエージェント（LLMラッパー、MCPツール、およびオプションのワークフローツール）に接続します。 |
| workflow.yaml | DRAgentのワークフロータイプ、LLMコンポーネント、および関連設定を宣言します。 |

### エージェントのメタデータ（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サーバー接続、およびその他のエージェント設定のためのオプションのランタイムパラメーターを定義します。 |

> [!TIP] LLMプロバイダーの設定
> エージェントは、以下のような複数のLLMプロバイダー設定をサポートしています。
> 
> LLM Gatewayを直接使用
> ：DataRobotのLLM Gatewayを直接使用します。
> 外部LLMを使用したLLMブループリント
> ：外部プロバイダー（Azure OpenAI、Amazon Bedrock、Google Gemini Enterprise Agent Platform（以前の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とエージェントのロジックを接続します。 詳細については、 [構造化モデルフックのドキュメント](https://docs.datarobot.com/ja/docs/api/code-first-tools/drum/structured-custom-models.html.md) を参照してください。 以下のDataRobotカスタムモデルフックが、 `custom.py` に実装されています。

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

> [!TIP] 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
    """ 
```

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

`myagent.py` ファイルには、エージェントのワークフローロジックが含まれています。 多くのテンプレートでは、これは `MyAgent` クラスとなります。現在のLangGraph [Agentic Starter](https://github.com/datarobot-community/datarobot-agent-application) プロジェクトでは、 `MyAgent` は `graph_factory` とプロンプトテンプレートから `datarobot_agent_class_from_langgraph` によって生成されます。 ここでは、エージェントがどのように動作するか、どのツールを受け取るか、および入力をどのように処理するかを定義します。

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

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

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

```
# 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およびLlamaIndexのテンプレートは、APIのベースURLロジックをそれぞれの `llm` プロパティ内に直接実装しています。 通常、LangGraphのスターターテンプレートは、手動で作成したクラスの `llm` プロパティではなく、DRUM/DRAgentアダプターパスの `get_llm` などのヘルパーを通じてチャットモデルを取得します。

```
# myagent.py (CrewAI/LlamaIndex)
@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()` プロパティを以下のように実装しています。

```
# 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を使用できます。

> [!TIP] NATが提供するLLMインターフェイス
> LLM Gatewayの代わりに、 [NATが提供するLLMインターフェイス](https://docs.nvidia.com/nemo/agent-toolkit/latest/workflows/llms/index.html) を利用することもできます。 NAT LLMインターフェイスを利用するには、 `api_key` や `url` などの必要な設定パラメーターやプロバイダー固有のその他の設定を `workflow.yaml` ファイルに直接追加します。

NATのテンプレートとともにDataRobotのデプロイを使用する方法については、 [コードでのLLMプロバイダーの設定](https://docs.datarobot.com/ja/docs/agentic-ai/agentic-develop/agentic-llm-providers.html.md#datarobot-hosted-llm-deployments) を参照してください。

## ツールの連携

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

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

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

各フレームワークは、カスタムツールを定義するための独自のネイティブツールAPIを提供します。

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

> [!TIP] NATエージェントの設定
> クエリーに応じてどのツールをどの順番で実行するかを決める柔軟なエージェントには、 [sequential_executor](https://docs.nvidia.com/nemo/agent-toolkit/latest/workflows/about/sequential-executor.html) の代わりに [react_agent](https://docs.nvidia.com/nemo/agent-toolkit/latest/workflows/about/react-agent.html) を使用します。

### 認可コンテキスト

アクセストークンを必要とするツールの認証を自動的に処理するため、 `datarobot-genai` パッケージの `resolve_authorization_context()` 関数が `custom.py` で呼び出されます。 この関数は、 `completion_create_params["authorization_context"]` に割り当てられる認可コンテキストディクショナリを返します。 これにより、DataRobotの資格情報管理システムを使用して、ツールが安全に外部サービスにアクセスできるようになります。