Quickstart¶

This guide covers creating, deploying, and testing an agentic workflow using DataRobot's pre-built templates, including setting up a development environment, configuring an agent framework, and deploying your workflow to interact with DataRobot's chat interface.

Prerequisites¶

Before proceeding, install the required components. If you experience issues while running this workflow, refer to the troubleshooting section.

Locate your DataRobot API key and endpoint¶

The section after this will require you to add your DataRobot API key and endpoint to your environment variables. Follow the steps below to locate them. For full details, see the DataRobot API keys documentation.

1. Log in to your DataRobot account.
2. Click the user icon in the top right of the UI and select API keys and tools.
3. Copy your DataRobot API endpoint and DataRobot API key and paste them into a temporary file.

Continue with the next section to configure your environment variables.

Configure environment variables¶

Create an .env file in the root directory before running any commands. To do this, copy and rename the provided sample environment file (.env.template) and provide the necessary environment variables in the file.

cp .env.template .env
# Previously, .env.template was .env.sample

Edit the file with your preferred text editor. Open the .env file and configure the required environment variables. The .env file must contain, at a minimum, the following variables, but it is recommended to set all variables to configure a complete environment:

nano .env  # or vim .env, code .env, etc.

Insert the DataRobot API key and endpoint into your .env file. Leave other variables at their default values during setup.

# Your DataRobot API token.
# Refer to https://docs.datarobot.com/en/docs/api/api-quickstart/index.html#configure-your-environment for help.
DATAROBOT_API_TOKEN=

# The URL of your DataRobot instance API.
DATAROBOT_ENDPOINT=https://app.datarobot.com/api/v2

If you aren't logged into Pulumi Cloud, define a PULUMI_CONFIG_PASSPHRASE. The passphrase can be any string.

# The Pulumi stack name to use for this project.
PULUMI_STACK_NAME=dev

# If empty, a blank passphrase will be used
PULUMI_CONFIG_PASSPHRASE=123

To define a DataRobot Use Case to link to the agent assets, provide a Use Case ID. If this field is empty, Pulumi creates a new Use Case.

# If empty, a new use case will be created
DATAROBOT_DEFAULT_USE_CASE=

Optionally, configure DATAROBOT_DEFAULT_EXECUTION_ENVIRONMENT. The default configuration selects the latest stable execution environment, using Pulumi to auto-select the most up-to-date environment by resolving the latest ID.

# If empty, a new execution environment will be created for each agent using the docker_context folder
DATAROBOT_DEFAULT_EXECUTION_ENVIRONMENT="[DataRobot] Python 3.11 GenAI Agents"

Select an agentic workflow¶

After defining the required environment variables, use task start to run the agent quickstart and select the type of agentic workflow you want to create.

task start

❯ 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 ‼️

❯ 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

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

To select a template, answer the prompt to choose your agent framework, enter one of the options below, and press Enter.

Then, press Y and then Enter to install prerequisites and set up environments for the selected agent.

Running these commands configures the environment for the selected template, removes all unnecessary files, and prepares the virtual environment (virtualenv or venv) to install the additional libraries required to run the selected agent template.

You can refresh the installed environment at any time by running:

task install

Customize and test an agentic workflow¶

Now you can customize the code of your agentic workflow in the {{ agent_name }}/custom_model folder. If you need to customize the execution environment with a custom Docker image, first create the docker context using task agent:create-docker-context, then modify the files in the {{ agent_name }}/docker_context directory.

To submit a test query to your agent, the development server must be running. Start it manually or use the auto-start option:

task agent:dev

task agent:cli -- execute --user_prompt 'Hi, how are you?'

task agent:cli -- execute --user_prompt '{"topic":"Generative AI"}'

task agent:cli START_DEV=1 -- execute --user_prompt 'Hi, how are you?'

task agent:cli START_DEV=1 -- execute --user_prompt '{"topic":"Generative AI"}'

Build and test an agentic workflow custom model¶

After testing, you can experiment with the agentic workflow in DataRobot.

task build

Pulumi lists the resources that it is going to create. When you are ready for the resources to be built, press Enter to continue.

Allow time for Pulumi to create an execution environment (~5 minutes). Once created, Pulumi reports a custom model ID and a chat interface endpoint for the agentic workflow.

Agent Chat Completion Endpoint [agent_generic_base]: "https://app.datarobot.com/api/v2/genai/agents/fromCustomModel/683ed1fcd767c535b580bc1da/chat/"

Test this chat completion endpoint with the following command, replacing <CUSTOM_MODEL_ID> with the ID returned above (for example, 683ed1fcd767c535b580bc1da):

task agent:cli execute-custom-model --user_prompt '{"topic":"Generative AI"}' --custom_model_id <CUSTOM_MODEL_ID>

Experimentation mode does not require you to redeploy a custom model to see changes when you interact with the /chat interface. It will sync file changes in the running session.

Deploy an agentic workflow¶

When you have finished experimenting, you can deploy the agentic workflow.

task deploy

Check that the agentic workflow works correctly by running the following command to receive an agentic workflow response:

task agent:cli -- execute-deployment --deployment_id %your_id% --user_prompt 'Hi, how are you?'

Make predictions with a deployed agentic workflow¶

After the agentic workflow is deployed, access real-time prediction snippets from the deployment's Predictions > Prediction API tab. For more information on deployment predictions, see the Prediction API snippets documentation.

Alternatively, you can modify the script below to make predictions with the deployed agentic workflow, replacing the placeholders for the API_KEY, DEPLOYMENT_ID, and CHAT_API_URL variables.

import sys
import logging
import time
import os

from openai import OpenAI

API_KEY = '<API_KEY>' # Your API Key
DEPLOYMENT_ID = '<DEPLYMENT_ID>' # The agentic workflow deployment ID
CHAT_API_URL = '<CHAT_API_URL>' # The chat API URL for the agentic workflow deployment
# For example, 'https://app.datarobot.com/api/v2/deployments/68824e9aa1946013exfc3415/'

logging.basicConfig(
    level=logging.INFO,
    stream=sys.stdout,
    format='%(asctime)s %(filename)s:%(lineno)d %(levelname)s %(message)s',
)
logger = logging.getLogger(__name__)


def main():
    openai_client = OpenAI(
        base_url=CHAT_API_URL,
        api_key=API_KEY,
        _strict_response_validation=False
    )

    prompt = "What would it take to colonize Mars?"
    logging.info(f"Trying Simple prompt first: \"{prompt}\"")
    completion = openai_client.chat.completions.create(
        model="datarobot-deployed-llm",
        messages=[
            {"role": "system", "content": "Explain your thoughts using at least 100 words."},
            {"role": "user", "content": prompt},
        ],
        max_tokens=512,  # omit if you want to use the model's default max
    )

    print(completion.choices[0].message.content)

    return 0

if __name__ == '__main__':
    sys.exit(main())

Specify association ID and report custom metrics¶

When making a chat request to a DataRobot-deployed text generation or agentic workflow custom model, an association ID can be optionally specified and values can be reported for custom metrics defined for the deployment by setting certain fields in the optional extra_body field of the chat request.

If the field datarobot_association_id is found in extra_body, DataRobot uses that value instead of the automatically generated one. If the field datarobot_metrics is found in extra_body, DataRobot reports a custom metric for all the name:value pairs found inside. A matching custom metric for each name must already be defined for the deployment. If the reported value is a string, the custom metric must be the multiclass type, with the reported value matching one of the classes.

extra_body = {
    # These values pass through to the LLM
    "llm_id": "azure-gpt-6",
    # If set here, replaces the auto-generated association ID
    "datarobot_association_id": "my_association_id_0001",
    # DataRobot captures these for custom metrics
    "datarobot_metrics": {
        "field1": 24,
        "field2": "example"
    }
}
completion = openai_client.chat.completions.create(
    model="datarobot-deployed-llm",
    messages=[
        {"role": "system", "content": "Explain your thoughts using at least 100 words."},
        {"role": "user", "content": prompt},
    ],
    max_tokens=512,
    extra_body=extra_body
)

print(completion.choices[0].message.content)