Tasks

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

⚠️ Workflow Input Size Warning: Avoid passing extremely large objects as input to your workflows, as this can cause execution failures. Large inputs (such as massive JSON objects, extensive arrays, or huge text files) may exceed memory limits or hit serialization constraints.What to do instead:

Break large data into smaller chunks and process them iteratively
Use file uploads and pass file references instead of raw content
Implement pagination for large datasets

Rule of thumb: If your input data is larger than a few megabytes, consider alternative approaches.

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:
      brave_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.

Name	Description
Tool Call	Execute tools defined in the task
Prompt	Send messages to the AI model
Evaluate	Perform calculations or data manipulation
Wait for Input	Pause workflow for user input
Subworkflow	Execute a subworkflow
Set	Store values for later use
Get	Retrieve values from storage
Foreach	Iterate over a collection
Map-reduce	Process collections in parallel
Switch	Multiple condition handling
If-else	Conditional execution
Sleep	Pause execution
Return	Return values from workflow
Yield	Execute subworkflows
Log	Log messages or specific values
Error	Handle 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

How to access the input and output of a step

In any step, you can access the input and output of a step using the steps[index].output or steps[index].input variable. For example:

- evaluate:
    topic: $ steps[0].input.topic

- evaluate:
    topic: $ steps[0].output.topic

In Julep, the steps are indexed from 0. So the first step is steps[0] and the second step is steps[1] and so on. Furthermore the first step input is nothing but the task input and the last step output is nothing but the output of the task.

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:
      openweathermap_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

import yaml
import os

task_def = yaml.safe_load(open("task.yaml"))

task = client.tasks.create(
    agent_id="agent_id",
    **task_def
)

// Create a task
import yaml from "yaml";
import fs from "fs";

const task_definition = yaml.parse(fs.readFileSync("task.yaml", "utf8"));

async function createTask(agentId) {
  const task = await client.tasks.create(agentId, task_definition);
  return task;
}

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)

// Execute a task
async function executeTask(taskId) {
  const execution = await client.executions.create(taskId, {
    input: { idea: "A cat who learns to fly" },
  });

  while (true) {
    const result = await client.executions.get(execution.id);
    console.log(result.status, result.output);

    if (result.status === "succeeded" || result.status === "failed") {
      // 📦 Once the execution is finished, retrieve the results
      if (result.status === "succeeded") {
        console.log(result.output);
      } else {
        throw new Error(result.error);
      }
      break;
    }

    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
}

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

// Create an agent
const agent = await client.agents.create({ 
  name: "Customer Support Agent",
  about: "An agent that handles customer support requests",
  model: "gpt-4o",
  });

// Add a tool to the agent
await client.agents.tools.create(
  agent.id,
  yaml.parse(`
    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
const task = await client.tasks.create(
  agent.id, 
  yaml.parse(`
    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:

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:
        openweathermap_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
  """)
)

await client.agents.tools.create(
  agent.id,
  yaml.parse(`
    name: get_weather_info
    type: integration
    integration:
      provider: weather
      setup:
        openweathermap_api_key: "your_openweathermap_api_key"
  `)
);

task = await client.tasks.create(
  agent.id,
  yaml.parse(`
    name: Get Weather Info
    inherit_tools: true
    main:
      - tool: get_weather_info
        arguments:
          location: New York
  `)
);

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:
          openweathermap_api_key: "your_openweathermap_api_key"
    main:
      - tool: get_weather_info
        arguments:
          location: New York
  """)
)

task = await client.tasks.create(
  agent.id,
  yaml.parse(`
    name: Get Weather Info
    tools:
    - name: get_weather_info
      type: integration
      integration:
        provider: weather
        setup:
          openweathermap_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.

Overview

Components

Input Schema

Tools

Sub-Workflows

Steps

Context Variables

Input Variables

Step Results

Environment Context

Metadata

How to Use Tasks ?

Creating a Task

Executing a Task

Relationship to Other Concepts

Agents

Tools

Best Practices

Keep Tasks Focused

Handle Errors Gracefully

Optimize Performance

Next Steps

See Examples

​Overview

​Components

​Input Schema

​Tools

​Sub-Workflows

​Steps

​Context Variables

​Input Variables

​Step Results

​Environment Context

​Metadata

​How to Use Tasks ?

​Creating a Task

​Executing a Task

​Relationship to Other Concepts

​Agents

​Tools

​Best Practices

Keep Tasks Focused

Handle Errors Gracefully

Optimize Performance

​Next Steps

​See Examples

Overview

Components

Input Schema

Tools

Sub-Workflows

Steps

Context Variables

Input Variables

Step Results

Environment Context

Metadata

How to Use Tasks ?

Creating a Task

Executing a Task

Relationship to Other Concepts

Agents

Tools

Best Practices

Next Steps

See Examples