Pythonパッケージの追加¶

To add additional Python packages to your agent environment, add them to your pyproject.toml file using uv, a modern Python package and environment manager.

Keep existing packages

We recommend keeping existing packages in pyproject.toml to ensure consistent behavior across playground and deployment environments.

実行時依存関係を用いた高速イテレーション

開発を迅速に行うために、Dockerイメージを再構築せずに、実行時依存関係を使って依存関係を追加できます。これは、開発時の簡単なテストに最適です。

パッケージを追加するための一般的なワークフローは次のとおりです。

パッケージを追加する：uv add <PACKAGE_NAME>
ローカルでテストする：task dev（開発サーバーを実行）
Build Docker image: task agent:build-docker-context (if using custom Docker image)
デプロイする：デプロイパイプラインを使用

Automatic synchronization

During a task deploy or task build, the pyproject.toml file is automatically synchronized with the agentic workflow code. Package installation is auto-synchronized with uv by default. You don't need to manually update the pyproject.toml file in these directories.

Add packages to your agent¶

Navigate to your agent directory and use uv to add the new package:

   cd agent_generic_base  # Or your chosen agent directory (agent_crewai, agent_langgraph, agent_llamaindex, agent_nat)
   uv add <PACKAGE_NAME>

たとえば、requestsパッケージを追加するには、次のようにします。

   uv add requests

バージョンの制約も指定できます。

   uv add "requests>=2.32.0"

Create a custom execution environment to test your agent in the playground:
Open the .env file.
Set DATAROBOT_DEFAULT_EXECUTION_ENVIRONMENT= to empty or delete the line completely.
Optional: If you need to test with a custom Docker image, first create the docker context:

   # Create docker_context directory if needed
   task agent:create-docker-context

   # Then build and test the Docker image
   cd agent_generic_base/docker_context  # or your chosen agent directory (agent_crewai, agent_langgraph, agent_llamaindex, agent_nat)
   docker build -f Dockerfile . -t docker_context_test

After completing these steps, when you run task build or task deploy, the new environment will be automatically built the first time. Subsequent builds will use the cached environment if the requirements have not changed. The new environment will be automatically linked and used for all your agent components, models, and deployments.

以下のコマンドを実行してエージェントイメージの構築を手動でテストし、新しい依存関係が正常に定義されていることを確認できます。

task agent:build-docker-context

docker_context is optional

The docker_context directory is no longer included by default. If you need to build a custom Docker image, first create the docker context using task agent:create-docker-context. This command downloads the necessary Docker files and creates the docker_context directory in your agent folder. 次にtask agent:build-docker-contextコマンドを実行すると、更新されたpyproject.tomlがdocker_context/ディレクトリにコピーされ、新しい依存関係を持つDockerイメージが構築されて、そのイメージがagent_generic_base:latest（または選択したエージェント名（agent_nat:latestなど））として保存されます。

設定ファイルを削除しないようにしてください

pyproject.tomlファイルからのパッケージの削除は、それが不要であることを確認してから行ってください。パッケージを削除すると、ローカルの実行環境が正常に動作していても、プレイグラウンドやデプロイの操作で予期しない動作が発生する可能性があります。

エージェント特有の注意事項¶

エージェントのタイプによって依存関係の管理方法が異なる場合があります。

エージェントのタイプ	依存関係の管理方法
agent_generic_base	Uses `pyproject.toml`.
agent_llamaindex	Uses `pyproject.toml` with auto-generated `requirements.in` and `requirements.txt` files.
agent_crewai	Uses `pyproject.toml`.
agent_langgraph	Uses `pyproject.toml`.
agent_nat	Uses `pyproject.toml`.

すべてのエージェントタイプで推奨される方法は、uv add <PACKAGE_NAME>を使用してpyproject.tomlファイルを修正することです。これにより、依存関係の解決とバージョンの制約が自動的に処理されます。

pyproject.tomlファイルは、すべての依存関係の唯一の情報源として機能し、ビルドプロセスはDocker環境のセットアップを自動的に処理します。

実行時依存関係の追加（高速イテレーション）¶

開発とテストを迅速に行うには、Dockerイメージを再構築せずに、実行時の依存関係を追加します。 pyproject.tomlファイルのextrasグループに追加された依存関係は、プレイグラウンドでプロンプトが最初に実行されたとき、またはデプロイが開始されたときにインストールされます。実行時依存関係は、次の場合に最適です。

開発中の簡単なイテレーション
イメージを再構築せずに新しいパッケージをテストする
コンパイルを必要としない軽量な依存関係を追加する

Taskを使用して実行時依存関係を追加するuvを使用して実行時依存関係を追加する

エージェントに実行時の依存関係を追加するには、task agent:add-dependencyコマンドを使用します。

task agent:add-dependency -- "chromadb>=1.1.1"

また、uv を使って実行時依存関係を直接追加することもできます。

cd agent_generic_base  # Or your chosen agent directory (agent_crewai, agent_langgraph, agent_llamaindex, agent_nat)
uv add --active --no-upgrade --group extras "chromadb>=1.1.1"

--no-upgradeフラグの使用

--no-upgradeフラグは、追加の依存関係のインストールに必要な時間を最小限に抑えるために重要です。このフラグにより、既存の依存関係をアップグレードせずに新しい依存関係のみが追加されるため、ランタイムのインストールを高速に保ち、実行環境との違いを最小限に抑えることができます。

機能に関する注意事項¶

実行時依存関係には、注意すべき重要な制限がいくつかあります。

インターネットアクセスが必要：追加の依存関係が実行時にインストールされるため、インターネットアクセスが必要です。エアギャップ環境では、カスタム実行環境を構築して、カスタム依存関係を含める必要があります。
インストールの複雑さ：依存関係に高度なインストールプロセス（Cバインディングのコンパイル、キャッシュの設定、カスタムビルド手順など）がある場合、実行環境の制限によりランタイムインストールが失敗することがあります。このような場合、カスタム実行環境を構築する以外に方法はありません。
セキュリティに関する注意事項：実行時依存関係を使用すると、エージェントで直接ライブラリバージョンをアップグレードすることで、実行時のCVEの問題を迅速に修正できます。ただし、実行環境にそのような脆弱性がない場合でも、ライブラリを脆弱性のあるバージョンにダウングレードすることで脆弱性が発生する可能性があります。脆弱性が適切に修正されるように、実行環境とエージェントのpyproject.toml/uv.lockファイルの両方を更新する必要があります。

実行時依存関係を使用する際には、以下のベストプラクティスを検討してください。

開発とテストに実行時依存関係を使用します。
本番環境にデプロイする場合は、必要な依存関係をすべてインストールしたカスタム実行環境の構築を検討してください。
pyproject.tomlファイルとすべての依存関係を同期させて、環境間の一貫性を確保します。
--no-upgradeフラグを使用してアップグレードを最小限に抑え、インストール時間を短縮します。