​
Create and Execute a Julep Task

This guide will walk you through the process of creating a Julep task and executing it.
This guide is based on the Trip Planning task. For a detailed explanation of the task’s workflow, please check out the corresponding Trip Planning tutorial.

​
Step 1: Initialize the Julep Client

First, you need to initialize the Julep client with your API key. 
from julep import Julep

# Initialize the Julep client
julep = Julep(api_key="your_api_key")

​
Step 2: Create a Julep Agent

Create an agent to associate the task with. In Julep, tasks are scoped to agents, and agents take on the responsibility of executing tasks. 
# Create an agent
agent = julep.agents.create(
    name="Task Agent",
    model="gpt-4o"
)

​
Step 3: Create a Julep Task

In this step, you will define the task that the Julep agent will execute. This involves specifying the task’s name, description, input schema, tools, and the main workflow. The task definition is written in YAML format and includes details about the integrations and the logic for processing the input data. 
import yaml

task_def = yaml.safe_load("""
# yaml-language-server: $schema=https://raw.githubusercontent.com/julep-ai/julep/refs/heads/dev/src/schemas/create_task_request.json
name: Julep Trip Planning Task
description: A Julep agent that can generate a detailed itinerary for visiting tourist attractions in some locations, considering the current weather conditions.


input_schema:
  type: object
  properties:
    locations:
      type: array
      items:
        type: string
      description: The locations to search for.


tools:
- name: wikipedia
  type: integration
  integration:
    provider: wikipedia

- name: weather
  type: integration
  integration:
    provider: weather
    setup:
      openweathermap_api_key: "YOUR_OPENWEATHERMAP_API_KEY"

- name: internet_search
  type: integration
  integration:
    provider: brave
    setup:
      brave_api_key: "YOUR_BRAVE_API_KEY"


main:
- over: $ steps[0].input.locations
map:
  tool: weather
  arguments:
    location: $ _

- over: $ steps[0].input.locations
map:
  tool: internet_search
  arguments:
    query: $ 'tourist attractions in ' + _

# Zip locations, weather, and attractions into a list of tuples [(location, weather, attractions)]
- evaluate:
  zipped: |-
    $ list(
      zip(
        steps[0].input.locations,
        [output['result'] for output in steps[0].output],
        steps[1].output
      )
    )


- over: $ _['zipped']
parallelism: 3
# Inside the map step, each `_` represents the current element in the list
# which is a tuple of (location, weather, attractions)
map:
  prompt:
  - role: system
    content: >-
      $ f'''You are {agent.name}. Your task is to create a detailed itinerary
      for visiting tourist attractions in some locations.
      The user will give you the following information for each location:

      - The location
      - The current weather condition
      - The top tourist attractions'''
  - role: user
    content: >-
      $ f'''Location: "{_[0]}"
      Weather: "{_[1]}"
      Attractions: "{_[2]}"'''
  unwrap: true

- evaluate:
  final_plan: |-
    $ '\\n---------------\\n'.join(activity for activity in _)
""")


# Create a task
task = julep.tasks.create(
    agent_id=agent.id,
    **task_def
)

​
Step 4: Execute the Julep Task

Once the task is created, you can execute it by providing the necessary input that matches the task’s input schema. This step involves calling the execute method on the task, which will start the task execution process. 
# Execute the task with specific input that matches the task's input schema
execution = julep.tasks.execute(
    task_id=task.id,
    input={"locations": ["New York", "Paris", "Tokyo"]}
)

​
Step 5: Get the Task Execution Result

After executing the task, you can retrieve the results by checking the execution status and output. This step involves polling the execution status until it reaches a terminal state (succeeded, failed, or cancelled) and printing the current output. Alternatively, you can fetch the execution transitions for a more detailed view of the task’s progress, which is useful for debugging.

​
Fetching the Execution Status & Current Output

import time

# Fetch the execution status & current output
execution = julep.executions.get(execution_id=execution.id)

while execution.status not in ["succeeded", "failed", "cancelled"]:
    execution = julep.executions.get(execution_id=execution.id)
    print(f"Execution status: {execution.status}")
    print(f"Execution output: {execution.output}")
    print("************************************************")

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

​
Fetching the Execution Transitions

import time

# Fetch the execution transitions
transitions = julep.executions.transitions.list(execution_id=execution.id)

# Wait until the execution is either finished, errored, or canceled
while transitions[0].items.type not in ["finish", "error", "canceled"]:
    transitions = julep.executions.transitions.list(execution_id=execution.id)

    # Transitions are ordered from the latest to the oldest
    for transition in reversed(transitions.items):
        print(f"Transition type: {transition.type}")
        print(f"Transition output: {transition.output}")
        print("************************************************")
    
    # Wait for 5 seconds before fetching the next set of transitions
    time.sleep(5)

​
Full Example

from julep import Julep
import yaml
import time

# Initialize the Julep client
julep = Julep(api_key="your_api_key")

# Create an agent
agent = julep.agents.create(
    name="Task Agent",
    model="gpt-4o"
)

task_def = yaml.safe_load("""
# yaml-language-server: $schema=https://raw.githubusercontent.com/julep-ai/julep/refs/heads/dev/src/schemas/create_task_request.json
name: Julep Trip Planning Task
description: A Julep agent that can generate a detailed itinerary for visiting tourist attractions in some locations, considering the current weather conditions.


input_schema:
  type: object
  properties:
    locations:
      type: array
      items:
        type: string
      description: The locations to search for.


tools:
- name: wikipedia
  type: integration
  integration:
    provider: wikipedia

- name: weather
  type: integration
  integration:
    provider: weather
    setup:
      openweathermap_api_key: "YOUR_OPENWEATHERMAP_API_KEY"

- name: internet_search
  type: integration
  integration:
    provider: brave
    setup:
      brave_api_key: "YOUR_BRAVE_API_KEY"


main:
- over: $ steps[0].input.locations
map:
  tool: weather
  arguments:
    location: $ _

- over: $ steps[0].input.locations
map:
  tool: internet_search
  arguments:
    query: $ 'tourist attractions in ' + _

# Zip locations, weather, and attractions into a list of tuples [(location, weather, attractions)]
- evaluate:
  zipped: |-
    $ list(
      zip(
        steps[0].input.locations,
        [output['result'] for output in steps[0].output],
        steps[1].output
      )
    )


- over: $ _['zipped']
parallelism: 3
# Inside the map step, each `_` represents the current element in the list
# which is a tuple of (location, weather, attractions)
map:
  prompt:
  - role: system
    content: >-
      $ f'''You are {agent.name}. Your task is to create a detailed itinerary
      for visiting tourist attractions in some locations.
      The user will give you the following information for each location:

      - The location
      - The current weather condition
      - The top tourist attractions'''
  - role: user
    content: >-
      $ f'''Location: "{_[0]}"
      Weather: "{_[1]}"
      Attractions: "{_[2]}"'''
  unwrap: true

- evaluate:
  final_plan: |-
    $ '\\n---------------\\n'.join(activity for activity in _)
""")


# Create a task
task = julep.tasks.create(
    agent_id=agent.id,
    **task_def
)

# Execute the task with specific input that matches the task's input schema
execution = julep.tasks.execute(
    task_id=task.id,
    input={"locations": ["New York", "Paris", "Tokyo"]}
)

# Fetch the execution status & current output
execution = julep.executions.get(execution_id=execution.id)

while execution.status not in ["succeeded", "failed", "cancelled"]:
    execution = julep.executions.get(execution_id=execution.id)
    print(f"Execution status: {execution.status}")
    print(f"Execution output: {execution.output}")
    print("************************************************")

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

​
Conclusion

This guide provided a comprehensive overview of how to create and execute a Julep task. It covered the necessary steps, including initializing the Julep client, creating an agent, defining the task, executing it, and retrieving the results. By following these steps, you can effectively use Julep’s capabilities to automate complex workflows and achieve your goals.

​
Next Steps

  • Tasks - Learn about Julep tasks in more details and see other tasks steps.
  • Tutorials - Check out other tutorials to see more real-world examples of Julep in action.
  • Cookbooks - Easy to run Jupyter notebooks to execute Julep tasks.