Run Agent
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
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:
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:
Advanced Usage
Using Input Variables
Adding Metadata
Using Agent Labels
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 needsmetadata
– optional JSON for extra metadatareturn_all_outputs
– Set totrue
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 1return_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.