Create Agent

Create a new Agent or a new version of an existing Agent programmatically. This endpoint allows you to define the complete agent configuration including nodes, edges (conditional connections), input variables, and release labels. Please note that this feature was previously called “Workflows” and is now called “Agents”. Some references to “Workflows” remain in our SDK and will be updated before the feature exits beta.

HTTP Request

POST /rest/workflows

Request Body

The request body expects a JSON object with the following structure:

Schema

{
  "name": "string (optional, for new agents)",
  "workflow_id": "integer (optional, for new version of existing agent)",
  "workflow_name": "string (optional, for new version of existing agent)",
  "folder_id": "integer (optional)",
  "commit_message": "string (optional)",
  "nodes": [
    {
      "name": "string (required)",
      "node_type": "string (required)",
      "configuration": "object (required)",
      "dependencies": ["string"],
      "is_output_node": "boolean"
    }
  ],
  "required_input_variables": {
    "variable_name": "type"
  },
  "edges": [
    {
      "source_node_name": "string",
      "target_node_name": "string",
      "is_and": "boolean",
      "conditionals": [
        {
          "position": "integer",
          "operator": "string",
          "left_config": "object",
          "right_config": "object"
        }
      ]
    }
  ],
  "release_labels": ["string"]
}

Parameters

Agent Identification

name (string, optional): The name for a new agent. If not provided, a name will be auto-generated. Cannot be used with workflow_id or workflow_name.
workflow_id (integer, optional): The ID of an existing agent to create a new version for.
workflow_name (string, optional): The name of an existing agent to create a new version for.
folder_id (integer, optional): The folder ID to place the agent in.

Version Details

commit_message (string, optional): A message describing the changes in this version.

Nodes

Each node represents a step in the agent workflow:

name (string, required): Unique name for the node within this agent.
node_type (string, required): The type of node. See Node Types below.
configuration (object, required): Node-specific configuration.
dependencies (array of strings, optional): Names of nodes or input variables this node depends on.
is_output_node (boolean, required): Whether this node is an output node. At least one node must be an output node.

Input Variables

required_input_variables (object, optional): A mapping of variable names to their types (e.g., {"user_query": "string"}).

Edges (Conditional Connections)

Edges define conditional branching between nodes:

source_node_name (string, required): The source node name.
target_node_name (string, required): The target node name (must have source in its dependencies).
is_and (boolean, required): Whether multiple conditionals use AND logic (true) or OR logic (false).
conditionals (array, required): At least one conditional:
- position (integer): Order of evaluation.
- operator (string): One of =, !=, <, >, <=, >=, in, not_in, is_null, is_not_null.
- left_config (object): Left side of comparison.
- right_config (object): Right side of comparison.

Release Labels

release_labels (array of strings, optional): Labels to attach to this version (e.g., ["production", "staging"]).

Node Types

Agents use the same node types as evaluation pipelines. For the complete list of supported node types and their detailed configuration options, see the Node & Column Types documentation. Common node types include:

Node Type	Description
`VARIABLE`	Static value
`CODE_EXECUTION`	Run Python or JavaScript code
`PROMPT_TEMPLATE`	Call an LLM with a prompt template
`ENDPOINT`	Make an HTTP request
`COMPARE`	Compare two values
`CONTAINS`	Check if string contains value
`LLM_ASSERTION`	LLM-based evaluation
`AI_DATA_EXTRACTION`	Extract structured data
`CODING_AGENT`	Claude Code sandbox

Response

Status Code: 201 (Created)

{
  "success": true,
  "message": "Workflow created successfully",
  "workflow_id": 123,
  "workflow_name": "my-agent",
  "workflow_version_id": 456,
  "version_number": 1,
  "release_labels": ["production"],
  "nodes": [
    {
      "id": "uuid",
      "name": "output_node",
      "node_type": "VARIABLE",
      "is_output_node": true
    }
  ],
  "required_input_variables": {
    "user_input": "string"
  }
}

Examples

Create a Simple Agent

import requests

response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "name": "greeting-agent",
        "commit_message": "Initial version",
        "nodes": [
            {
                "name": "greeting",
                "node_type": "VARIABLE",
                "is_output_node": True,
                "configuration": {
                    "value": {"type": "string", "value": "Hello, World!"}
                },
                "dependencies": []
            }
        ],
        "release_labels": ["production"]
    }
)

Create an Agent with Multiple Nodes

response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "name": "classifier-agent",
        "nodes": [
            {
                "name": "classify",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": False,
                "configuration": {
                    "template": {
                        "prompt_name": "intent-classifier",
                        "label": "production"
                    }
                },
                "dependencies": ["user_message"]
            },
            {
                "name": "is_urgent",
                "node_type": "CONTAINS",
                "is_output_node": False,
                "configuration": {
                    "source": "classify",
                    "value": "urgent"
                },
                "dependencies": ["classify"]
            },
            {
                "name": "response",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": True,
                "configuration": {
                    "template": {
                        "prompt_name": "response-generator",
                        "label": "production"
                    }
                },
                "dependencies": ["classify", "is_urgent", "user_message"]
            }
        ],
        "required_input_variables": {
            "user_message": "string"
        }
    }
)

Create an Agent with Conditional Edges

response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "name": "routing-agent",
        "nodes": [
            {
                "name": "router",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": False,
                "configuration": {"template": {"prompt_name": "router"}},
                "dependencies": ["query"]
            },
            {
                "name": "sales_handler",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": True,
                "configuration": {"template": {"prompt_name": "sales-response"}},
                "dependencies": ["router", "query"]
            },
            {
                "name": "support_handler",
                "node_type": "PROMPT_TEMPLATE",
                "is_output_node": True,
                "configuration": {"template": {"prompt_name": "support-response"}},
                "dependencies": ["router", "query"]
            }
        ],
        "required_input_variables": {"query": "string"},
        "edges": [
            {
                "source_node_name": "router",
                "target_node_name": "sales_handler",
                "is_and": True,
                "conditionals": [{
                    "position": 0,
                    "operator": "=",
                    "left_config": {"type": "source", "source": {"name": "router"}},
                    "right_config": {"type": "static_value", "static_value": "sales"}
                }]
            },
            {
                "source_node_name": "router",
                "target_node_name": "support_handler",
                "is_and": True,
                "conditionals": [{
                    "position": 0,
                    "operator": "=",
                    "left_config": {"type": "source", "source": {"name": "router"}},
                    "right_config": {"type": "static_value", "static_value": "support"}
                }]
            }
        ]
    }
)

Create a New Version of an Existing Agent

# By workflow ID
response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "workflow_id": 123,
        "commit_message": "Updated configuration",
        "nodes": [...],
        "release_labels": ["staging"]
    }
)

# By workflow name
response = requests.post(
    "https://api.promptlayer.com/rest/workflows",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "workflow_name": "my-agent",
        "commit_message": "v2 updates",
        "nodes": [...],
        "release_labels": ["production"]
    }
)

Error Responses

Status Code	Error
400	Invalid request body, duplicate name, validation errors
401	Missing or invalid API key
404	Workflow not found (when using workflow_id or workflow_name)

Headers

X-API-KEY

string

required

Your API key for authentication.

Body

application/json

Request body for creating a new workflow or workflow version.

nodes

object[]

required

The nodes in the workflow.

Show child attributes

name

string | null

The name for a new workflow. If not provided, a name will be auto-generated.

Required string length: 1 - 255

workflow_id

integer | null

The ID of an existing workflow to create a new version for.

workflow_name

string | null

The name of an existing workflow to create a new version for.

folder_id

integer | null

The folder ID to place the workflow in.

commit_message

string | null

A message describing the changes in this version.

required_input_variables

object

A mapping of variable names to their types.

Show child attributes

edges

object[] | null

Conditional edges between nodes.

Show child attributes

release_labels

string[] | null

Labels to attach to this version.

Response

Workflow created successfully

Response after creating or patching a workflow.

success

boolean

required

Indicates if the request was successful.

workflow_id

integer

required

The ID of the workflow.

workflow_name

string

required

The name of the workflow.

workflow_version_id

integer

required

The ID of the created workflow version.

version_number

integer

required

The version number.

base_version

integer | null

The base version this was created from (PATCH only).

release_labels

string[] | null

Labels attached to this version.

nodes

object[]

Summary of nodes in the workflow.

Show child attributes

required_input_variables

object

Required input variables for the workflow.

Show child attributes

Get Started

Languages & Environments

Usage Documentation

Why PromptLayer?

Reference

HTTP Request

Request Body

Schema

Parameters

Agent Identification

Version Details

Nodes

Input Variables

Edges (Conditional Connections)

Release Labels

Node Types

Response

Examples

Create a Simple Agent

Create an Agent with Multiple Nodes

Create an Agent with Conditional Edges

Create a New Version of an Existing Agent

Error Responses

Headers

Body

Response

Get Started

Languages & Environments

Usage Documentation

Why PromptLayer?

Reference

​HTTP Request

​Request Body

​Schema

​Parameters

​Agent Identification

​Version Details

​Nodes

​Input Variables

​Edges (Conditional Connections)

​Release Labels

​Node Types

​Response

​Examples

​Create a Simple Agent

​Create an Agent with Multiple Nodes

​Create an Agent with Conditional Edges

​Create a New Version of an Existing Agent

​Error Responses

Headers

Body

Response

HTTP Request

Request Body

Schema

Parameters

Agent Identification

Version Details

Nodes

Input Variables

Edges (Conditional Connections)

Release Labels

Node Types

Response

Examples

Create a Simple Agent

Create an Agent with Multiple Nodes

Create an Agent with Conditional Edges

Create a New Version of an Existing Agent

Error Responses