Executions - Julep

Overview

Executions in Julep represent instances of tasks that have been initiated with specific inputs. They embody the lifecycle of a task, managing its progression through various states from initiation to completion. Understanding executions is crucial for effectively managing and monitoring the behavior of your AI agents and their workflows.

Components

Executions are comprised of several key components that work together to manage and monitor the state of a task:

Execution ID: A unique identifier for each execution instance.
Task ID: The identifier of the task being executed.
Input: The inputs provided to the task at the time of execution.
Status: The current state of the execution (e.g., queued, running, succeeded).
Output: The result produced by the execution upon completion.
Transitions: The sequence of state changes that the execution undergoes.
Transition Count: The number of transitions that have occurred in this execution.

Execution Configuration options

Option	Type	Description	Default
`task_id`	`string`	The ID of the task to execute	Required
`input`	`object`	The input to the task	Required
`metadata`	`object`	Additional metadata for the execution instance	`null`
`transition_count`	`number`	The number of transitions in this execution	`null`

Lifecycle of an Execution

An execution follows a well-defined lifecycle, transitioning through various states from start to finish. Understanding these states helps in monitoring and managing task executions effectively.

Execution Statuses

Executions can exist in one of the following statuses:

Status	Description
`queued`	The execution is queued and waiting to start.
`starting`	The execution is starting.
`running`	The execution is currently running.
`awaiting_input`	The execution is suspended and awaiting user input to resume.
`succeeded`	The execution has completed successfully.
`failed`	The execution has failed due to an error.
`cancelled`	The execution has been cancelled by the user or system.

Execution State Machine

The state transitions of an execution are governed by a state machine that ensures proper progression and handling of different scenarios.

Execution State Transitions

Executions in Julep follow a specific state transition model. The transitions are governed by both the execution status and the transition type:

Init: The execution is initialized.
Start: The execution begins.
Step: A step within the execution is executed.
Wait: The execution is waiting for an external input.
Resume: The execution resumes after waiting.
Finish: The execution completes successfully.
Error: The execution encounters an error.
Cancel: The execution is cancelled.

Transition Types

Transition Type	Description
`init`	Initializes the execution.
`start`	Starts the execution process.
`step`	Executes a step within the task.
`wait`	Pauses execution waiting for external input.
`resume`	Resumes execution after a wait.
`finish`	Marks the execution as successfully completed.
`error`	Marks the execution as failed due to an error.
`cancel`	Cancels the execution.

Creating an Execution

To create an execution for a specific task, use the following method in the SDKs.

from julep import Julep
import yaml
client = Julep(api_key="YOUR_API_KEY")

# Execute the task (assuming the task is already created)
execution = client.executions.create(
    task_id="task_id",
    input={
        "parameter1": "value1",
        "parameter2": "value2"
    }
)

print(f"Execution ID: {execution.id}")

const { Julep } = require('@julep/sdk');
const client = new Julep({ apiKey: 'YOUR_API_KEY' });
// Execute the task (assuming the task is already created)
const execution = await client.executions.create({
    task_id: "task_id",
    input: {
        parameter1: 'value1',
        parameter2: 'value2'
    }
});

console.log("Execution ID:", execution.id);

Check out the API reference here or SDK reference (Python here or JavaScript here for more details on different operations you can perform on executions.

Monitoring an Execution

After initiating an execution, it’s essential to monitor its progress and handle its completion or failure appropriately.

import time
from julep import Julep

client = Julep(api_key="YOUR_API_KEY")
execution_id = "YOUR_EXECUTION_ID"

while True:
    result = client.executions.get(execution_id)
    print(f"Status: {result.status}")
    print(f"Current output: {result.output}")

    if result.status in ["succeeded", "failed", "cancelled"]:
        if result.status == "succeeded":
            print("Execution succeeded with output:", result.output)
        else:
            print("Execution ended with status:", result.status)
        break

    time.sleep(5)  # Wait for 5 seconds before polling again

const { Julep } = require('@julep/sdk');

const client = new Julep({ apiKey: 'YOUR_API_KEY' });
const executionId = 'YOUR_EXECUTION_ID';

while (true) {
    const result = await client.executions.get(executionId);
    console.log(`Status: ${result.status}`);
    console.log(`Current output: ${result.output}`);
    if (["succeeded", "failed", "cancelled"].includes(result.status)) {
        if (result.status === "succeeded") {
            console.log("Execution succeeded with output:", result.output);
        } else {
            console.log("Execution ended with status:", result.status);
        }
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait for 5 seconds before polling again
}

To view more details about the status of the execution and how it is transitioning between states, you can use list the transitions of an execution. Example:

from julep import Julep

client = Julep(api_key="YOUR_API_KEY")
execution_id = "YOUR_EXECUTION_ID"

transitions = client.executions.transitions.list(execution_id)
print(transitions.items)

const { Julep } = require('@julep/sdk');

const client = new Julep({ apiKey: 'YOUR_API_KEY' });
const executionId = 'YOUR_EXECUTION_ID';

const transitions = await client.executions.transitions.list(executionId);
console.log(transitions.items);

Check out the API reference here or SDK reference (Python here or JavaScript here for more details on different operations you can perform on executions.

Streaming Execution Status Updates

Using the raw SSE endpoint

You can subscribe to real-time status updates using the Server-Sent Events (SSE) endpoint. Each event conforms to the ExecutionStatusEvent schema and includes the following fields:

execution_id: The UUID of the execution.
status: The current execution status.
updated_at: ISO 8601 timestamp of the update.
error: Error message if the execution failed.
transition_count: Number of transitions that have occurred.
metadata: Arbitrary metadata for the event.

curl -X GET 'https://api.julep.ai/api/executions/{execution_id}/status.stream' \
  -H 'Authorization: Bearer $JULEP_API_KEY'

You’ll be getting events that look like this:

data: {"execution_id":"068306ff-e0f3-7fe9-8000-0013626a759a","status":"starting","updated_at":"2025-05-23T12:54:24.565424Z","error":null,"transition_count":1,"metadata":{}}
data: {"execution_id":"068306ff-e0f3-7fe9-8000-0013626a759a","status":"running","updated_at":"2025-05-23T12:54:30.903484Z","error":null,"transition_count":2,"metadata":{}}
data: {"execution_id":"068306ff-e0f3-7fe9-8000-0013626a759a","status":"succeeded","updated_at":"2025-05-23T12:56:12.054067Z","error":null,"transition_count":3,"metadata":{}}

Using the Python SDK `AsyncClient`

from julep import AsyncClient

client = AsyncClient(api_key="YOUR_API_KEY")
execution_id = "YOUR_EXECUTION_ID"

# Subscribe to the live status stream (async generator)
status_stream = await client.executions.status.stream(execution_id=execution_id)

# Consume events in real-time using async for
async for event in status_stream:
    print("Execution status:", event.status, "updated at", event.updated_at)

This approach relies on Python’s async / await syntax. Make sure to:

Use AsyncClient not Client.
await client.executions.status.stream(...) to obtain the async generator.
Iterate with async for to consume events.

Updating/Cancelling an Execution

To update or cancel an execution, you can use the change_status method in the SDKs. Example:

from julep import Julep

client = Julep(api_key="YOUR_API_KEY")
execution_id = "YOUR_EXECUTION_ID"

# To cancel an execution
client.executions.change_status(execution_id=execution_id, status="cancelled")
# To resume an execution with specific input
client.executions.change_status(
    execution_id=execution_id,
    status="running",
    input={
        "parameter1": "value1",
        "parameter2": "value2"
    }
)

const { Julep } = require('@julep/sdk');

const client = new Julep({ apiKey: 'YOUR_API_KEY' });
const executionId = 'YOUR_EXECUTION_ID';

// To cancel an execution
await client.executions.changeStatus(executionId, 'cancelled');
// To resume an execution with specific input
await client.executions.changeStatus(
    executionId,
    'running',
    {
        input: {
            "parameter1": "value1",
            "parameter2": "value2"
        }
    }
);

Check out the API reference here or SDK reference (Python here or JavaScript here for more details on different operations you can perform on executions.

Best Practices

Handle All Statuses

1. Execution Statuses: Ensure your application gracefully handles all possible execution statuses, including failed and cancelled.

Polling Interval

1. Polling Interval: Choose an appropriate polling interval to balance responsiveness and API usage.

Logging

1. Logging: Maintain detailed logs of execution statuses and outputs for auditing and debugging purposes.

Next Steps

Checkout the Tutorial - Learn how to use executions in a tutorial
Checkout the Execution Lifecycle - Learn more about the execution lifecycle

​Overview

​Components

​Execution Configuration options

​Lifecycle of an Execution

​Execution Statuses

​Execution State Machine

​Execution State Transitions

​Transition Types

​Creating an Execution

​Monitoring an Execution

​Streaming Execution Status Updates

​Using the raw SSE endpoint

​Using the Python SDK AsyncClient

​Updating/Cancelling an Execution

​Best Practices

Handle All Statuses

Polling Interval

Logging

​Next Steps

Overview

Components

Execution Configuration options

Lifecycle of an Execution

Execution Statuses

Execution State Machine

Execution State Transitions

Transition Types

Creating an Execution

Monitoring an Execution

Streaming Execution Status Updates

Using the raw SSE endpoint

Using the Python SDK `AsyncClient`

Updating/Cancelling an Execution

Best Practices

Next Steps