Skip to content
For Self-Managed AI Platform users running v11.1, see the on-premise platform documentation
Agentic AI > Develop agentic workflows > Add Python packages

Add Python packages

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.

Fast iteration with runtime dependencies

For rapid development, you can add dependencies using runtime dependencies without rebuilding the Docker image. This is ideal for quick testing during development.

The typical workflow for adding packages is:

  1. Add the package: uv add <PACKAGE_NAME>
  2. Test locally: task dev (runs the development server)
  3. Build Docker image: task agent:build-docker-context (if using custom Docker image)
  4. Deploy: Use your deployment pipeline

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

  1. 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>

For example, to add the requests package:

uv add requests

You can also specify version constraints:

uv add "requests>=2.32.0"

  1. Create a custom execution environment to test your agent in the playground:

  2. Open the .env file.

  3. Set DATAROBOT_DEFAULT_EXECUTION_ENVIRONMENT= to empty or delete the line completely.

  4. 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.

You can manually test building your agent image by running the following command, ensuring the new dependency is defined successfully:

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. The task agent:build-docker-context command will then copy the updated pyproject.toml to the docker_context/ directory, build the Docker image with the new dependencies, and save the image as agent_generic_base:latest (or your chosen agent name, such as agent_nat:latest).

Don't remove requirements

Don't remove any packages from the pyproject.toml file unless you are certain they aren't needed. Removing packages may lead to unexpected behavior with playground or deployment interactions, even if the local execution environment works correctly.

Agent-specific considerations

Different agent types may have different dependency management approaches:

Agent Type Dependency Management Approach
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.

For all agent types, the recommended approach is to use uv add <PACKAGE_NAME> to modify the pyproject.toml file, which will automatically handle dependency resolution and version constraints.

The pyproject.toml file serves as the single source of truth for all dependencies, and the build process automatically handles the Docker environment setup.

Add runtime dependencies (Fast iteration)

For rapid development and testing, add dependencies at runtime without rebuilding the Docker image. Dependencies added to the extras group in your pyproject.toml file will be installed when the prompt is first executed in the Playground or when the deployment starts. Runtime dependencies are ideal for:

  • Quick iteration during development
  • Testing new packages without rebuilding images
  • Adding lightweight dependencies that don't require compilation

Use the task agent:add-dependency command to add a runtime dependency to your agent:

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

You can also add runtime dependencies directly using 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"

Use --no-upgrade flag

The --no-upgrade flag is crucial to minimize the time required to install extra dependencies. It ensures that only new dependencies are added without upgrading existing ones, which helps to keep the runtime installation fast and minimize differences from the execution environment.

Feature considerations

Runtime dependencies have several important limitations to consider:

  • Internet access required: Since extra dependencies are installed at runtime, internet access is required. In air-gapped environments, you must build custom execution environments to include custom dependencies.

  • Installation complexity: If a dependency has a sophisticated installation process (for example, compilation of C bindings, setting up cache, or custom build steps), the runtime installation may fail due to restrictions in the execution environment. In such cases, building a custom execution environment is the only option.

  • Security considerations: Using runtime dependencies makes it possible to quickly fix CVE issues in runtime by upgrading library versions directly in the agent. However, it's also possible to introduce vulnerabilities by downgrading libraries to vulnerable versions, even if the execution environment doesn't have those vulnerabilities. You must update both execution environments and pyproject.toml / uv.lock files in your agents to ensure vulnerabilities are properly fixed.

Consider the following best practices for using runtime dependencies:

  • Use runtime dependencies for development and testing.
  • For production deployments, consider building custom execution environments with all required dependencies installed.
  • Keep the pyproject.toml file synchronized with all dependencies to ensure consistency across environments.
  • Minimize upgrades by using the --no-upgrade flag to keep installation times fast.