The run_workflow() method initiates the execution of predefined Agents in PromptLayer, allowing you to start complex, multi-step sequences. For a comprehensive understanding of Agents, including their use cases, key concepts, and versioning, please refer to the Agents documentation.

​
Basic Usage

from promptlayer import PromptLayer

pl = PromptLayer(api_key="your_api_key")

response = pl.run_workflow(
    workflow_name="Your Agent Name",
    workflow_version=1
)

print(response)

​
Parameters

  • workflow_name / workflowName (str, required): The name of the Agent to run.
  • input_variables / inputVariables (Dict[str, Any], optional): Variables to be used in the Agent.
  • metadata (Dict[str, str], optional): Additional metadata for the Agent run.
  • workflow_label_name / workflowLabelName (str, optional): Label name for the Agent version.
  • workflow_version / workflowVersion (int, optional): Specific version number of the Agent to run.
  • return_all_outputs / returnAllOutputs (bool, optional): Whether to return all outputs from the Agent execution.

​
Return Value

By default, when return_all_outputs / returnAllOutputs is false, the method returns only the final node’s output as a single value; when set to true, it returns a dictionary (Python) or object (JavaScript) containing detailed outputs (including status) for each node in the agent.

​
When return_all_outputs / returnAllOutputs is False (default):

The method returns only the final node’s output as a single value. For example, if your output node produces False, the method simply returns:

Example response:

False

​
When return_all_outputs / returnAllOutputs is True:

You receive a dictionary (Python) or object (JavaScript) of all node outputs. Each key corresponds to a node in the workflow with details such as:

  • status (str): The execution status (e.g., "SUCCESS", "FAILED").
  • value (Any): The output (e.g., text, boolean).
  • error_message / raw_error_message: Error information, if any.
  • is_output_node (bool): Indicates whether this node is the designated “final output” node.

Example response:

{
  "Node 1": {
    "status": "SUCCESS",
    "value": "First node",
    "error_message": null,
    "raw_error_message": null,
    "is_output_node": false
  },
  "Node 2": {
    "status": "FAILED",
    "value": null,
    "error_message": "Code execution failed: Traceback...",
    "raw_error_message": {
      "raw": "Code execution failed: Traceback..."
    },
    "is_output_node": true
  }
}

​
Advanced Usage

​
Using Input Variables

response = pl.run_workflow(
    workflow_name="Data Analysis Agent",
    input_variables={"dataset_url": "https://example.com/data.csv"}
)

​
Adding Metadata

response = pl.run_workflow(
    workflow_name="Customer Service Agent",
    metadata={"customer_id": "12345"}
)

​
Using Agent Labels

response = pl.run_workflow(
    workflow_name="Marketing Campaign Agent",
    workflow_label_name="production"
)

​
Run Agents using the REST API

Step 1: Kick off the agent run

Start by making a request to “POST /workflows/agentName/run”.

This request requires:

  • input_variables – JSON object with the variables the agent needs
  • metadata – optional JSON for extra metadata
  • return_all_outputs – Set to true if you want to include all intermediate node results

The response will contain a workflow_version_execution_id that you’ll need for the next step.

Step 2: Poll until completion

After initiating the run, check for results using “GET /workflow-version-execution-results”.

Include these query parameters:

  • workflow_version_execution_id – The ID received from step 1
  • return_all_outputs – Same setting as in the first request

When polling (suggestion):

  • Check every 5000 ms
  • A 200 status code means the run is complete, while 202 indicates it’s still running
  • Consider timing out after about 10 minutes

Depending on if you set return_all_outputs or not, you will either return the output value or all node values on completion.