Executions

​

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

​

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:

​

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

​

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}")

​

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

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)

​

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)

​

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"
    }
)

​

Best Practices

​

Next Steps

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