Overview

Overview

When using deployments, you:

Why use deployments?

Teams typically use deployments when they want:

• Non-technical users to make prompt and model changes without code deployments
• Faster feedback loops by avoiding engineering bottlenecks for prompt iterations
• Cost optimization by switching to newer, cheaper models without code changes
• Real-time improvements based on user feedback without redeploying code

Step-by-step guide

Let's walk through two common scenarios for setting up deployments.

Scenario 1: Data extraction agent (with input variables)

This example shows an agent that extracts event details from emails using input variables.

Step 1: Start with a basic agent

Here's our initial agent with a hardcoded prompt:

from pydantic import BaseModel

class EventDetails(BaseModel):
    event_name: str
    event_date: str
    event_location: str
    event_description: str

completion = client.beta.chat.completions.parse(
    model="llama4-maverick-instruct-fast",
    messages=[{
        "role": "user",
        "content": "Extract the event details from the following email: " + email_content
    }],
    response_format=EventDetails,
    metadata={
        "agent_id": "event-extractor"
    }
)

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

Step 2: Add input variables to your prompt

Replace the hardcoded parts of your prompt with input variables using {variable_name} syntax:

completion = client.beta.chat.completions.parse(
    model="llama4-maverick-instruct-fast",
    messages=[{
        "role": "user",
        "content": "Extract the event details from the following email: {{email}}"
    }],
    response_format=EventDetails,
    extra_body={ 
        "input": { 
            "email": email_content
        } 
    }, 
    metadata={
        "agent_id": "event-extractor"
    }
)

Step 3: Deploy the version and update code

After deploying in the WorkflowAI dashboard:

completion = client.beta.chat.completions.parse(
    model="#1/production", 
    messages=[],  # Empty because prompt is now stored in WorkflowAI #
    response_format=EventDetails,
    extra_body={ 
        "input": { 
            "email": email_content 
        } 
    }, 
    metadata={
        "agent_id": "event-extractor",
        "version": "#1/production"
    }
)

Scenario 2: Chatbot agent (no input variables needed)

This example shows a chatbot where all instructions are stored as the system message in WorkflowAI.

Step 1: Start with a basic chatbot

Here's a chatbot with hardcoded system instructions:

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "system", 
            "content": "You are a helpful customer support agent for TechCorp. Always be polite, provide accurate information about our products, and escalate complex issues to human agents."
        },
        {
            "role": "user", 
            "content": user_message
        }
    ],
    metadata={
        "agent_id": "customer-support-bot"
    }
)

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

Step 2: Deploy and update code

The system message becomes the "prompt" stored in WorkflowAI. After deploying:

completion = client.chat.completions.create(
    model="#1/production",
    messages=[ # system message is now stored in WorkflowAI
        {
            "role": "user", 
            "content": user_message
        }
    ],
    metadata={
        "agent_id": "customer-support-bot",
        "version": "#1/production"
    }
)

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

Key difference: No extra_body.input needed since there are no input variables. The user message is still provided normally in the messages array, but the system message (instructions) comes from the deployed prompt.

Deploying a version

Using the UI

For both scenarios, the deployment process is the same:

1. Go to the Deployments section in the WorkflowAI dashboard
2. Select your target environment: development, staging, or production
3. Click Deploy Version
4. Choose the version (prompt + model combination) you want to deploy
5. Click Deploy

The deployment will be associated with a schema number that defines:

• Input variables your code must provide (if any)
• Output format (response_format) your code expects (when using Structured Outputs)

You can view all schemas in the Schemas section of the WorkflowAI dashboard.

Additionally, if you're using the Playground to run your agent, you can deploy a version from the Playground directly:.

1. Select the Deploy button (circled arrow icon) in the output column:
   • Top of the column (next to model name)
   • Info section (below output)
2. Select the environment to deploy to from the options on the screen: development, staging, or production
3. If this is the first time you deploy a version of this agent, you will need to update your code. This can be done in two ways:
   • (Recommended) Use the WorkflowAI MCP in Cursor to automatically update your code to reflect the deployment.
   • Manually update your code by navigating to the Code page and copying the generated code.

TODO: add a video of this process

Using the API

TODO: @guillaume

Understanding the model parameter format

When using deployments, your model parameter follows this format: "agent-name/#schema-number/environment"

• agent-name = your agent name
• #schema-number = schema number (defines input/output contract)
• environment = development, staging, or production

Understanding schemas

Schemas define the "contract" between your code and the deployment. A schema includes:

• Input variables that must be provided in extra_body.input (if using input variables)
• Output format structure (your response_format, if using structured outputs)

Schemas are automatically created by WorkflowAI when you make changes to input variables or output formats. You don't manually create or manage schema numbers - WorkflowAI detects incompatible changes and assigns new schema numbers automatically.

When schema numbers are automatically incremented

WorkflowAI automatically creates a new schema number when you change:

• Input variable names, add new ones, or remove existing ones
• The structure of your response_format (add/remove fields, change types)

Schema migration workflow

When you need to change the schema:

1. Create a new version with updated input variables or output format in WorkflowAI
2. WorkflowAI automatically detects the changes and assigns a new schema number (like #2)
3. Deploy the new version to your target environment
4. Update your code to use the new schema number: "agent-name/#2/production"
5. Test thoroughly before deploying to production

This ensures backward compatibility - existing code using #1 continues working while new code uses #2.

You can view all automatically generated schemas in the Schemas section of the WorkflowAI dashboard.

Error handling

When there's a mismatch between your code and the deployed schema (missing input variables or incompatible response_format), the API will return an error.

Important notes

• Agent-specific: Deployments work with named agents only, not the default agent. Learn how to identify your agent.
• Environment isolation: Each environment (development/staging/production) has independent deployments.
• Schema independence: You can have different deployments for each schema without affecting each other.
• Input variables optional: Not all agents need input variables: simple chatbots can store all instructions in the deployed prompt.