​
Overview

Tasks are GitHub Actions-style workflows that define multi-step actions in Julep. Think of them as recipes that tell an agent exactly how to accomplish a goal. For example, a task might outline the steps to “Summarize a Research Paper” or “Debug a Code Issue”.

Here are some of the key features of tasks:

  • Connect multiple AI operations seamlessly
  • Make decisions based on intermediate results
  • Run operations in parallel for efficiency
  • Integrate with external tools and APIs
  • Maintain state throughout execution

​
Components

A task consists of several key components which can be broadly classified into:

​
Input Schema

YAML
name: Summarize Document
description: Create a concise summary of any document
input_schema:
  type: object
  properties:
    document_text:
      type: string
      description: The text to summarize

​
Tools

Tools are functions that can be used by an agent to perform tasks. Julep supports:

Learn more about tools here.

YAML
tools:
- name: internet_search
  description: Performs an internet search using Brave
  type: integration
  integration:
    provider: brave
    method: search
    setup:
      api_key: <BRAVE_API_KEY>

​
Sub-Workflows

A task can be made up of multiple sub-workflows. These sub-workflows can be named and can be used to break down complex tasks into smaller, more manageable pieces.

YAML
name: Summarize Document
description: Create a concise summary of any document

sample_sub_workflow:
- prompt: |-
    $ f'Tell me a joke about {steps[0].input.topic}:'

main:
- workflow: sample_sub_workflow
  arguments:
    topic: AI

You can learn more about sub-workflows here.

​
Steps

We use tasks and workflows interchangeably. They are the same except Julep’s branding reflects tasks.

Below is a table of all the steps that can be used in a task.

NameDescription
Tool CallExecute tools defined in the task
PromptSend messages to the AI model
EvaluatePerform calculations or data manipulation
Wait for InputPause workflow for user input
SubworkflowExecute a subworkflow
SetStore values for later use
GetRetrieve values from storage
ForeachIterate over a collection
Map-reduceProcess collections in parallel
SwitchMultiple condition handling
If-elseConditional execution
SleepPause execution
ReturnReturn values from workflow
YieldExecute subworkflows
LogLog messages or specific values
ErrorHandle errors by specifying an error message

You can learn more about workflow steps as to how they work in the Workflow Steps section.

​
Context Variables

Tasks have access to three types of context:

​
Input Variables

Access input parameters:

YAML
- prompt: $ f'Hello {steps[0].input.user_name}'

​
Step Results

Use outputs from previous steps:

YAML
- evaluate: $ len(_.search_results)
- if: $ _.count > 0

To learn more about how to use the $ variable and new syntax, please refer to the New Syntax section.

​
Environment Context

Access agent and session data:

YAML
- prompt: $ f'Agent {agent.name} is helping you'

Input schemas help catch errors early by validating all inputs before execution starts.

Here’s how these components work together:

YAML
name: Process Customer Feedback
description: Analyze and categorize customer feedback
input_schema:
  type: object
  required: ["feedback_text"]
  properties:
    feedback_text:
      type: string
    sentiment_analysis:
      type: boolean
      default: true

tools:
- name: get_weather_info
  type: integration  
  integration:
    provider: weather
    setup:
      api_key: OPENWEATHERMAP_API_KEY

main:
- tool: get_weather_info
  arguments:
    location: $ steps[0].input.location

- prompt: |-
    $ f"""The weather in {steps[0].output.location} is the following:
    {steps[0].output.weather}
    
    <task>
    Analyze the weather and provide a summary of the weather in the location. Include some recommendations on what to wear based on the weather.
    </task>
    """

Learn more about tools here.

​
Metadata

Metadata is a key-value pair that can be used to categorize and filter tasks.

​
How to Use Tasks ?

​
Creating a Task

Here’s a simple task that summarizes a document and checks if the summary is too long. We first define the task in a YAML file and then create it using the Julep SDK.

name: Summarize Document
description: Create a concise summary of any document
input_schema:
  type: object
  properties:
    document_text:
      type: string
      description: The text to summarize

main:
  - prompt: |-
      $ f'''Analyze the following text and create a summary:
      {steps[0].input.document_text}'''
    unwrap: true
  - evaluate:
      too_long: $ len(_) > 500
  - if: $ _.too_long
    then:
      prompt: |-
        $ f'''Make the summary more concise:
        {steps[0].output}'''
      unwrap: true
    else: 
      evaluate:
        content: $ steps[0].output

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

​
Executing a Task

Here’s how to execute a task:

# Execute a task
execution = client.executions.create(
  task_id=task.id,
  input={
      "document_text": "This is a sample document"
  }
)

# Monitor progress
while True:
  result = client.executions.get(execution.id)
  if result.status in ["succeeded", "failed"]:
      break
  time.sleep(1)

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

​
Relationship to Other Concepts

This section will help you understand how tasks relate to other concepts in Julep.

​
Agents

Julep agents can power tasks by providing memory, context, or tools. Tasks are multi-step workflows designed for complex, automated execution. Whenever you create a task, you can associate it with an agent if you want to leverage that agent’s capabilities. Unlike sessions, tasks are not meant for real-time interaction; they run through a defined workflow to achieve a goal.

For example:

import yaml

# Create an agent
agent = client.agents.create(
  name="Customer Support Agent",
  about="An agent that handles customer support requests",
  model="gpt-4o",
)

# Add a tool to the agent
client.agents.tools.create(
  agent_id=agent.id,
  **yaml.safe_load("""
  name: send_email
  type: integration
  integration:
    provider: email
    method: send
    setup:
      host: "smtp.example.com"
      port: 587
      user: "your_username"
      password: "your_password"
  """),
)

# Create a task that inherits this tool
task = client.tasks.create(
  agent_id=agent.id,
  **yaml.safe_load("""
    name: Handle Support Request

    # Make sure to set this to true if you want to inherit tools from the agent
    inherit_tools: true

    input_schema:
      type: object
      properties:
        customer_email:
          type: string
          description: The email of the customer
        subject:
          type: string
        body:
          type: string
          description: The body of the email

    main:
    - prompt:
      - role: system
        content: You are a customer support agent who works for Julep AI. You will be given a support request from a customer. You will need to handle the request by sending a reply email to the customer.
      - role: user
        content: |-
          $ f"""Handle the support request from this email: {steps[0].input.customer_email}
          The subject of the email is this:
          {steps[0].input.subject}

          ---

          The body of the email is this:
          {steps[0].input.body}
          """
      unwrap: true

    - tool: send_email
      arguments:
        to: $ steps[0].input.customer_email
        from: "support@julep.ai"
        subject: "$ f'Re: {steps[0].input.subject}'"
        body: $ steps[0].output
  """)
)

​
Tools

Task can leverage tools to perform complex operations. There are 2 ways of defining tools for tasks:

  1. Associate a tool with an agent, and inherit it in the task definition by setting inherit_tools to true while creating the task. Example:
client.agents.tools.create(
  agent_id="agent_id",
  **yaml.safe_load("""
    name: get_weather_info
    type: integration
    integration:
      provider: weather
      setup:
        api_key: "your_openweathermap_api_key"
  """)

task = client.tasks.create(
  agent_id="agent_id",
  **yaml.safe_load("""
    name: Get Weather Info
    inherit_tools: true
    main:
      - tool: get_weather_info
        arguments:
          location: New York
  """)
)
  1. Define a tool in the task definition. Example:
task = client.tasks.create(
  agent_id="agent_id",
  **yaml.safe_load("""
    name: Get Weather Info
    tools:
    - name: get_weather_info
      type: integration
      integration:
        provider: weather
        setup:
          api_key: "your_openweathermap_api_key"
    main:
      - tool: get_weather_info
        arguments:
          location: New York
  """)
)

When you define a tool in the task definition, it is available to all steps in that task only. On the other hand, when you associate a tool with an agent, it is available to all the Tasks associated with that agent.

​
Best Practices

Keep Tasks Focused

  • 1. Purpose: Each task should have a single, clear purpose
  • 2. Subtasks: Break complex workflows into smaller subtasks

Handle Errors Gracefully

  • 1. Error Handling: Use try/catch blocks for error-prone operations
  • 2. Error Messages: Provide helpful error messages
  • 3. Fallback Options: Include fallback options where appropriate

Optimize Performance

  • 1. Parallel Execution: Use parallel execution when steps are independent
  • 2. Map-Reduce: Use map-reduce to run steps in parallel

​
Next Steps

  • Workflow Steps - Learn about all available step types
  • Tools - Learn about tools and how to use them in tasks
  • Sessions - Learn about sessions and how to use them in tasks