Skip to content
バージョン11.0を実行しているセルフマネージドAIプラットフォームのユーザーは、オンプレミスプラットフォームのドキュメントを参照してください

Use the agent CLI

The repository uses Task as the command interface for development operations, working together with uv for package management and Pulumi for infrastructure management. Task provides commands for building, deploying, and managing your agent infrastructure—all accessible through the task command. Additionally, the agent:cli command provides a dedicated CLI for testing your agentic workflows during development.

Agentic workflow templates use three key tools for development and deployment: uv, Task, and Pulumi. For more information on these tools, review the FAQ's below.

What is uv?

uv is a Python package and project management solution, combining the features of poetry and pipx. Rustで記述されたuvは、パフォーマンスを大幅に向上させます。 Some benchmarks estimate that it is 10x-100x faster than pip or poetry. これらのメリットにより、エージェントテンプレートでのパッケージ管理に推奨されるソリューションとなっています。

There are 3 virtual environments used in the templates, each scoped to a folder:

  1. Root folder environment used for template management commands.
  2. Agent folder environment used to run agent locally.
  3. infra folder environment used for Pulumi commands.

They are defined in pyproject.toml in each folder. You don't need to worry about using the right environment: just run python commands using uv run prefix, and uv will select the right context for you.

By default, uv will use the latest python version available on your machine which satisfies requirements set in pyproject.toml. It will download and manage a version, if there is no suitable version installed. You can see all python versions installed with uv python list.

What is Task?

Task is a generic build tool, suitable for any project, and inspired by GNU make. It is cross-platform, allowing for easy installation in MacOS, Linux, or Windows.

Compared to the Makefile syntax used by GNU make, the Taskfile.yaml syntax used by task is more verbose and readable. In DataRobot agentic templates, Task serves as the entry point to standard operations, such as installing dependencies, building agents for experimentation, and deploying agents to production.

The primary benefits of Task are:

  • Concise commands: Because tasks are predefined, instead of typing multiple, verbose commands, you can instead type task infra:build or task infra:deploy to initiate an automated workflow.

  • Environment management: Because Task loads environment variables defined in a .env file, you don't need to load these variables manually for every command.

What is Pulumi?

Pulumi is Infrastructure-as-Code (IaC) in Python (or any other programming language). Terraform has a steep learning curve, so Pulumi is implemented to abstract away some of the complexity. To do this, the pulumi-datarobot Python package is generated directly from the Terraform provider. This package remains up-to-date with any changes to the API. In addition, the datarobot-pulumi-utils Python package provides a set of helper modules to simplify complex operations.

Terraform is the industry standard for Infrastructure-as-Code (IaC): a way to define, deploy, and manage resources for any SaaS product using code. IaC automates the provisioning and updating of these required resources. The primary use-case for Terraform is provisioning cloud resources, such as EC2 or S3 in AWS; however, it is applicable to most stateful APIs. IaC is also one of the pillars of GitOps: a methodology applying application development processes to the management of cloud resources. DataRobot has a Terraform provider, enabling the creation of experiments, datasets, deployments, and other assets.

In agentic templates, Pulumi manages the state of all DataRobot assets associated with your agent: custom models, execution environments, and deployments. At each step, it tracks when changes are needed, and which entities must be updated. As a result, when you update your agent code and use task infra:build or task infra:deploy, a Pulumi command included in the task generates a plan to update the related remote assets, requests user approval, and then executes the plan.

You can also use Pulumi to provide other resources to your use case—for example, credentials, datasets, vector databases, tools, machine learning models, and applications. For more information, review the following documentation:

Changes made to an agentic workflow in the DataRobot UI (via codespace or workshop) cannot be synced with changes made locally and managed by Pulumi. Be careful when modifying agentic workflow code in both locations. If you experiment and change agent code in the DataRobot UI, ensure you port it back to your local codebase.

Taskfile CLI commands

The task command lists all available tasks in the current workspace. It shows the main tasks you can run from the current location and with the current workspace configuration. Use task --list-all to include hidden tasks. This is useful for discovering available commands after setup or when switching between agent frameworks.

task

Before running task start, this command displays the following list:

❯ task   
task: Available tasks for this project:
* default:       ℹ️ Show all available tasks (run `task --list-all` to see hidden tasks)
* install:       Install dependencies for all agent components and infra      (aliases: req, install-all)
* start:         ‼️ Quickstart for DataRobot Agent Templates ‼️

Prepare for local development

The task start command prepares agentic workflow templates for use and local development. This command runs the quickstart script to initialize the DataRobot Agent Templates workspace. It prompts you to choose an agentic framework (CrewAI, Generic Base, LangGraph, or LlamaIndex), verifies prerequisites (.env file, uv, task, and Pulumi), removes unused framework templates, and sets up a project-specific Taskfile. Optionally, this script also installs Python dependencies. Run this first to prepare the workspace for local development.

task start 

graph LR
    A((task start)) --> B[uv run quickstart.py]
    B --> C[/User selects agent type/]
    C --> D[Template prepared]

    classDef circleStyle fill:#c8e6c9,stroke:#4caf50,stroke-width:3px
    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px,stroke-width:3px
    classDef parallelStyle fill:#fff9c4,stroke:#ffc107,stroke-width:3px
    classDef diamondStyle fill:#ffe0b2,stroke:#ff9800,stroke-width:3px

    class A circleStyle
    class B,D squareStyle
    class C parallelStyle
| Start | Process | Input | Decision |

Review agent development commands

After running task start, the task command displays a list of available commands (the prefix will change based on the agent framework you selected).

❯ task
task: Available tasks for this project:
* default:                           ℹ️ Show all available tasks (run `task --list-all` to see hidden tasks)
* install:                           🛠️ Install all dependencies for agent and infra
* agent:install:                     🛠️ [agent_crewai] Install agent uv dependencies      (aliases: agent:req)
* agent:add-dependency:              🛠️ [agent_crewai] Add provided packages as a new dependency to an agent
* agent:cli:                         🖥️ [agent_crewai] Run the CLI with provided arguments
* agent:dev:                         🔨 [agent_crewai] Run the development server
* agent:dev-stop:                    🛑 [agent_crewai] Stop the development server
* agent:chainlit:                    🛝 Run the Chainlit playground
* agent:create-docker-context:       🐳 [agent_crewai] Create the template for a local docker_context image
* agent:build-docker-context:        🐳 [agent_crewai] Build the Docker image
* infra:install:                     🛠️ [infra] Install infra uv dependencies
* infra:build:                       🔵 Deploy only playground testing resources with pulumi
* infra:deploy:                      🟢 Deploy all resources with pulumi
* infra:refresh:                     ⚪️ Refresh and sync local pulumi state
* infra:destroy:                     🔴 Teardown all deployed resources with pulumi

For more information on the infra commands, see Use Pulumi to manage agent infrastructure.

Task command variants

You can also run task commands from various directories. The task command may change based on the agent framework you selected and the current directory you are in. You may also need to source the .env file to ensure that environment variables are set correctly if you are running commands outside the agent directory.

Use Pulumi to manage agent infrastructure

The repository uses Pulumi to manage infrastructure as code. The following commands are available to manage your infrastructure through task commands.

infra:build

Creates or updates the resources required in DataRobot to begin or continue experimentation with an agentic workflow:

  1. ユースケース
  2. Custom execution environment (if a pre-built environment isn't defined)
  3. カスタムモデル
# Update the custom model in DataRobot with your latest code changes
task infra:build

The base process is the same for task infra:build and task infra:deploy.

graph LR
    A((task infra:build)) --> B[pulumi up]
    B --> C{Pulumi stack exists?}
    C -- No --> D[/User enters stack name/]
    C -- Yes --> E
    D --> E[Compare local and remote state]
    E --> F{States differ?}
    F -- Yes --> G[Show proposed changes]
    G --> H[/User confirms build/]

    classDef circleStyle fill:#c8e6c9,stroke:#4caf50,stroke-width:3px
    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px,stroke-width:3px
    classDef parallelStyle fill:#fff9c4,stroke:#ffc107,stroke-width:3px
    classDef diamondStyle fill:#ffe0b2,stroke:#ff9800,stroke-width:3px

    class A circleStyle
    class B,E,G squareStyle
    class D,H parallelStyle
    class C,F diamondStyle
| Start | Process | Input |

The difference is within the Pulumi program's logic. task infra:build does not include the steps necessary to prepare your agent for production usage, making it much faster to execute.

graph LR
    A((pulumi up)) --> B{Execution environment missing or changed?}
    B -- Yes --> C[Create or update execution environment]
    B -- No --> D
    C --> D{Custom model exists?}
    D -- No --> E[Create custom model and version]
    D -- Yes --> F
    E --> F{Custom model changed?}
    F -- Yes --> G[Create new custom model version]

    classDef circleStyle fill:#c8e6c9,stroke:#4caf50,stroke-width:3px
    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px,stroke-width:3px
    classDef diamondStyle fill:#ffe0b2,stroke:#ff9800,stroke-width:3px

    class A circleStyle
    class C,E,G squareStyle
    class B,D,F diamondStyle
| Start | Process | Decision |

infra:deploy

Initially follows the same process as task infra:build, but proceeds to the steps to prepare an agent for production usage, such as creating a Deployment.

Verify agent functionality before deployment

Launching a deployment takes time, so ensure that you properly test the agentic workflow before running this command.

# Deploy your agent with your latest code changes (this includes all build steps)
task infra:deploy

The base process is the same for task infra:build and task infra:deploy.

graph LR
    A((task infra:deploy)) --> B[pulumi up]
    B --> C{Pulumi stack exists?}
    C -- No --> D[/User enters stack name/]
    C -- Yes --> E
    D --> E[Compare local and remote state]
    E --> F{States differ?}
    F -- Yes --> G[Show proposed changes]
    G --> H[/User confirms deployment/]

    classDef circleStyle fill:#c8e6c9,stroke:#4caf50,stroke-width:3px
    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px,stroke-width:3px
    classDef parallelStyle fill:#fff9c4,stroke:#ffc107,stroke-width:3px
    classDef diamondStyle fill:#ffe0b2,stroke:#ff9800,stroke-width:3px

    class A circleStyle
    class B,E,G squareStyle
    class D,H parallelStyle
    class C,F diamondStyle
| Start | Process | Input | Decision |

The difference is within the Pulumi program's logic. task infra:deploy includes the steps necessary to prepare your agent for production usage, making it slower to execute.

graph LR
    A((pulumi up)) --> B{Execution environment missing or changed?}
    B -- Yes --> C[Create or update execution environment]
    B -- No --> D
    C --> D{Custom model exists?}
    D -- No --> E[Create custom model and version]
    D -- Yes --> F
    E --> F{Custom model changed?}
    F -- Yes --> G[Create new custom model version]
    G --> H[Deploy steps]

    classDef circleStyle fill:#c8e6c9,stroke:#4caf50,stroke-width:3px
    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px,stroke-width:3px
    classDef diamondStyle fill:#ffe0b2,stroke:#ff9800,stroke-width:3px

    class A circleStyle
    class C,E,G,H squareStyle
    class B,D,F diamondStyle
| Start | Process | Decision |

The task infra:deploy steps are expanded below:

graph LR
    subgraph deploy [Deploy steps]
        direction LR
        A[Create or update prediction environment]
        B[Create or update registered model]
        C[Create or update deployment]
        A --> B
        B --> C
    end

    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px

    class A,B,C squareStyle
Pulumi dependency tracking

Pulumi tracks dependencies between entities; therefore, if you change an entity upstream, the entities downstream are updated or recreated. This means that if you change a custom model in DataRobot, you must create a new registered model and a new deployment from that registered model. Below is a diagram of these dependencies:

graph LR
    Deployment -- "depends on" --> Registered_model
    Registered_model -- "depends on" --> Custom_model
    Custom_model -- "depends on" --> Execution_environment
    Deployment -- "depends on" --> Prediction_environment

    Prediction_environment[Prediction environment]
    Execution_environment[Execution environment]
    Custom_model[Custom model]
    Registered_model[Registered model]
    Deployment[Deployment]

    classDef squareStyle fill:#b3e5fc,stroke:#2196f3,stroke-width:3px

    class Prediction_environment,Execution_environment,Custom_model,Registered_model,Deployment squareStyle

infra:destroy

The task infra:destroy command tears down all deployed infrastructure resources using Pulumi. Running pulumi destroy to remove all resources in the current stack, effectively deleting the infrastructure.

# Tear down all the deployed infrastructure related to your agent
task infra:destroy

infra:refresh

The task infra:refresh command refreshes and syncs the local Pulumi state file with the deployed infrastructure. Runs pulumi refresh to reconcile state when out of sync, updating state to match the actual cloud resources without making changes.

# Refresh the Pulumi state file if it is out of sync with the deployed infrastructure
task infra:refresh

実行時依存関係の追加

agent:add-dependencyコマンドを使うと、Dockerイメージを再構築することなく、エージェントに実行時依存関係をすばやく追加できます。 これは、開発時に迅速なイテレーションを行う場合に最適です。

# Add a runtime dependency
task agent:add-dependency -- "chromadb>=1.1.1"

たとえば、複数の依存関係を追加するには：

# Add a specific version
task agent:add-dependency -- "chromadb>=1.1.1"

# Add another dependency
task agent:add-dependency -- "requests>=2.32.0"

実行時依存関係

実行時依存関係は、エージェントがプレイグラウンドで最初に実行されたとき、またはデプロイが開始されたときにインストールされます。 これにより、Dockerイメージを再構築することなく、新しいパッケージをすばやくテストできます。 詳細については、Pythonパッケージの追加に関するドキュメントを参照してください。

agent:add-dependencyで追加された依存関係は実行時にインストールされます。つまり、インターネットアクセスが必要です。 インストールプロセスが複雑な依存関係（Cの拡張機能など）は、実行時にインストールに失敗する可能性があります。 制限事項やベストプラクティスの詳細については、Pythonパッケージの追加に関するドキュメントを参照してください。

Use the agent CLI

The agent:cli command provides a convenient interface for testing your agent. This allows you to quickly execute the entire LLM agent workflow from the command line without having to write any additional code. Run this command from the root directory.

# Root directory
task agent:cli

This displays CLI usage information.

❯ task agent:cli
Running CLI 

Usage: cli.py [OPTIONS] COMMAND [ARGS]...

  A CLI for interacting with and executing agent custom models using the chat endpoint
  and OpenAI completions.

  For more information on the main CLI commands and all available options, run
  the help command: > task agent:cli -- execute --help > task agent:cli -- execute-
  deployment --help

  Common examples:

  # Run the agent with a string user prompt > task agent:cli -- execute
  --user_prompt "Artificial Intelligence"

  # Run the agent with a JSON user prompt > task agent:cli -- execute --user_prompt
  '{"topic": "Artificial Intelligence"}'

  # Run the agent with a JSON file containing the full chat completion json >
  task agent:cli -- execute --completion_json "example-completion.json"

  # Run the deployed agent with a string user prompt [Other prompt methods are
  also supported similar to execute] > task agent:cli -- execute-deployment
  --user_prompt "Artificial Intelligence" --deployment_id 680a77a9a3

Options:
  --api_token TEXT  API token for authentication.
  --base_url TEXT   Base URL for the API.
  --help            Show this message and exit.

Commands:
  execute               Execute agent code locally using OpenAI completions.
  execute-custom-model  Query a custom model using the command line for...
  execute-deployment    Query a deployed model using the command line for...

Test a local agent

The following are common examples of how to use the CLI to test your agent on your local environment.

Development server mode

You can use development server execution for faster iteration. Set START_DEV=1 when running the CLI to automatically start and stop a development server:

# Use development server mode for faster iteration
task agent:cli START_DEV=1 -- execute --user_prompt "Artificial Intelligence"

Development server mode uses the legacy development server flow and can be useful for rapid testing during development. あるいは、1つのターミナルでtask agent:devを実行し（task agent:devは継続的に実行され、そのターミナルをブロック）、続いて別のターミナルで以下のコマンド例を実行します。

# Run the agent with a string sent as the user prompt
task agent:cli -- execute --user_prompt "Artificial Intelligence" 

# Run the agent with a JSON sent as the user prompt
task agent:cli -- execute --user_prompt '{"topic": "Artificial Intelligence"}' 

# Run the agent with a JSON file containing the full chat completion json
task agent:cli -- execute --completion_json example-completion.json

If you are using the completion_json option, the JSON file should contain a full chat completion request. An example JSON is provided in the example-completion.json file. The JSON structure is shown below. You can pass additional parameters as needed using the extra_body field.

{
  "model": "datarobot-deployed-llm",
  "messages": [
    {
      "content": "You are a helpful assistant",
      "role": "system"
    },
    {
      "content": "Artificial Intelligence",
      "role": "user"
    }
  ],
  "n": 1,
  "temperature": 0.01,
  "extra_body": {
    "api_key": "DATAROBOT_API_KEY",
    "api_base": "https://app.datarobot.com",
    "verbose": true
  }
}

Test a deployed agent

Once you have deployed your agent to DataRobot, you can use the CLI to test your deployed agent. You will need the deployment ID, which is shown after the deployment process is complete. You can find the deployment ID in the terminal output or in the DataRobot Console.

If you have not already done so, you will need to deploy your agent using the task infra:deploy command.

# Run the deployed agent with a string sent as the user prompt
task agent:cli -- execute-deployment --user_prompt "Artificial Intelligence" --deployment_id 680a77a9a3 

# Run the deployed agent with a JSON sent as the user prompt
task agent:cli -- execute-deployment --user_prompt '{"topic": "Artificial Intelligence"}' --deployment_id 680a77a9a3 

# Run the deployed agent with a JSON file containing the full chat completion json
task agent:cli -- execute-deployment --completion_json example-completion.json --deployment_id 680a77a9a3

If you are using the completion_json option, the JSON file should contain a full chat completion request, the same as when testing locally. An example JSON is provided in the example-completion.json file.

Test an agent in the DataRobot playground

You can also test your agent using the DataRobot playground. This allows you to interactively examine queries and traces sent to your agent. To use the playground, you will need to deploy your agent using the task infra:build command. Because the playground is a text-based interface, your agent will only respond to text-based prompts in this environment.

After running the task infra:build command, your custom model will be available to use in the DataRobot playground. You can find the custom model ID in the terminal output (or in workshop).

# Run the agent with a string sent as the user prompt
task agent:cli -- execute-custom-model --user_prompt "Artificial Intelligence" --custom_model_id <model_id>