> ## Documentation Index
> Fetch the complete documentation index at: https://docs.julep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trip Planning

> Learn how to create a task that generates personalized travel itineraries based on weather conditions and tourist attractions for multiple locations

## Overview

The Trip Planning tutorial shows how to:

* Execute workflow steps in parallel
* Integrate with external APIs
* Combine data from multiple sources
* Generate personalized itineraries using AI

Follow each step of the tutorial:

Let's break down the task into its core components:

### 1. Input Schema

First, we define what inputs our task expects:

```yaml theme={"dark"}
input_schema:
  type: object
  properties:
    locations:
      type: array
      items:
        type: string
```

This schema specifies that our task expects an array of location strings (e.g., `["New York", "London", "Paris"]`).

### 2. Tools Configuration

Next, we define the external tools our task will use:

```yaml theme={"dark"}
- 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
```

We're using two integrations:

* The `weather` integration to fetch current weather conditions
* The `brave` search integration to find tourist attractions

### 3. Main Workflow Steps

<Steps>
  <Step title="Get Weather Data">
    ```yaml theme={"dark"}
    - over: $ steps[0].input.locations
      map:
        tool: weather
        arguments:
          location: $ _
    ```

    <Accordion title="Understanding the use of the _ Variable in iteration steps">
      When used inside a `map` or a `foreach` step, the `_` variable is a reference to the current value in the iteration.

      For example:

      ```yaml theme={"dark"}
      - over: $ ["Paris", "London"]
        map:
          tool: weather
          arguments:
            location: $ _ # _ will be "Paris", then "London"
      ```
    </Accordion>

    This step:

    * Iterates over each location in the input array
    * Calls the weather API for each location
  </Step>

  <Step title="Search for Tourist Attractions">
    ```yaml theme={"dark"}
    - over: $ steps[0].input.locations
      map:
        tool: internet_search
        arguments:
          query: $ 'tourist attractions in ' + _
    ```

    This step:

    * Iterates over the locations again
    * Searches for tourist attractions in each location
    * Constructs a search query by concatenating "tourist attractions in " with the location
  </Step>

  <Step title="Combine Data">
    ```yaml theme={"dark"}
    - evaluate:
        zipped: |-
          $ list(
            zip(
              steps[0].input.locations,
              [output['result'] for output in steps[0].output],
              steps[1].output
            )
          )
    ```

    This step:

    * Combines the data from previous steps into tuples
    * Each tuple contains: (location, weather\_data, attractions\_data)
    * Uses Python's `zip` function to align the data
  </Step>

  <Step title="Generate Itineraries">
    ```yaml [expandable] theme={"dark"}
    - 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
    ```

    This step:

    * Processes up to 3 locations in parallel
    * For each location tuple:
      * Sends a prompt to the AI model
      * Includes location, weather, and attraction data
      * Generates a personalized itinerary
  </Step>

  <Step title="Format Final Output">
    ```yaml theme={"dark"}
    - evaluate:
        final_plan: |-
          $ '\\n---------------\\n'.join(activity for activity in _)
    ```

    This step:

    * Combines all itineraries into a single output
    * Separates each itinerary with a divider
  </Step>
</Steps>

<Accordion title="Complete Task YAML" icon="code">
  ```yaml YAML [expandable] theme={"dark"}
  # 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 #######################
  ########################################################

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

  ########################################################
  ################### TOOLS ##############################
  ########################################################

  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 WORKFLOW ######################
  ########################################################

  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 _)
  ```
</Accordion>

## Usage

Here's how to use this task with the Julep SDK:

<CodeGroup>
  ```python Python [expandable] theme={"dark"}
  from julep import Client
  import time
  import yaml

  # Initialize the client
  client = Client(api_key=JULEP_API_KEY)

  # Create the agent
  agent = client.agents.create(
    name="Julep Trip Planning Agent",
    about="A Julep agent that can generate a detailed itinerary for visiting tourist attractions in some locations, considering the current weather conditions.",
  )

  # Load the task definition
  with open('trip_planning_task.yaml', 'r') as file:
    task_definition = yaml.safe_load(file)

  # Create the task
  task = client.tasks.create(
    agent_id=AGENT_ID,
    **task_definition
  )

  # Create the execution
  execution = client.executions.create(
      task_id=task.id,
      input={
          "locations": ["New York", "London", "Paris", "Tokyo", "Sydney"]
      }
  )

  # Wait for the execution to complete
  while (result := client.executions.get(execution.id)).status not in ['succeeded', 'failed']:
      print(result.status)
      time.sleep(1)

  # Print the result
  if result.status == "succeeded":
      print(result.output)
  else:
      print(f"Error: {result.error}")
  ```

  ```js Node.js [expandable] theme={"dark"}
  import { Julep } from '@julep/sdk';
  import fs from 'fs';
  import yaml from 'yaml';

  // Initialize the client
  const client = new Julep({
    apiKey: 'your_julep_api_key'
  });

  // Create the agent
  const agent = await client.agents.create({
    name: "Julep Trip Planning Agent",
    about: "A Julep agent that can generate a detailed itinerary for visiting tourist attractions in some locations, considering the current weather conditions.",
  });

  // Load the task definition
  const taskDefinition = yaml.parse(fs.readFileSync('trip_planning_task.yaml', 'utf8'));

  // Create the task
  const task = await client.tasks.create(
    agent.id,
    taskDefinition
  );

  // Create the execution
  const execution = await client.executions.create(
    task.id,
    {
      input: { 
        "locations": ["New York", "London", "Paris", "Tokyo", "Sydney"]
      }
    }
  );

  // Wait for the execution to complete
  let result;
  while (true) {
    result = await client.executions.get(execution.id);
    if (result.status === 'succeeded' || result.status === 'failed') break;
    console.log(result.status);
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  // Print the result
  if (result.status === 'succeeded') {
    console.log(result.output);
  } else {
    console.error(`Error: ${result.error}`);
  }
  ```
</CodeGroup>

## Example Output

An example output when running this task with an input of `["New York", "London", "Paris", "Tokyo", "Sydney"]`:

<Accordion title="Example Output">
  Here's a detailed itinerary for visiting top tourist attractions in New York, considering the current weather conditions.

  ### Day 1: Iconic Landmarks and Observation Decks

  * **Morning:**
    * **Top of the Rock Observation Deck:** Start your day with a visit to the Top of the Rock Observation Deck at Rockefeller Plaza. The panoramic 360-degree views from the 70th floor are a must-see. Dress warmly as it feels like 5.2°C outside, and it’s quite windy.
    * **Link for more info:** [Tripadvisor - Top of the Rock](https://www.tripadvisor.com/Attractions-g60763-Activities-New_York_City_New_York.html)

  * **Afternoon:**
    * **St. Patrick’s Cathedral:** Just a short walk from Rockefeller Plaza, explore the stunning architecture of St. Patrick’s Cathedral. The overcast skies will provide a dramatic backdrop for photos.
    * **Fifth Avenue:** Enjoy a leisurely stroll along Fifth Avenue, visiting iconic stores and landmarks.

  * **Evening:**
    * **Times Square:** Experience the vibrant lights and energy of Times Square. The overcast clouds might enhance the brightness of the neon lights.

  ### Day 2: Culture and History

  * **Morning:**
    * **The Museum of Modern Art (MoMA):** Spend your morning exploring MoMA’s vast collection of modern and contemporary art. This indoor activity is perfect for a cloudy day.

  * **Afternoon:**
    * **Central Park:** Head to Central Park for a refreshing walk. With 100% cloud cover, it's a great day to explore the park without the harsh sun. Consider visiting the Central Park Zoo or taking a guided tour.

  * **Evening:**
    * **Broadway Show:** End your day with a Broadway show. It’s an ideal indoor activity to avoid the chilly weather outside. Book tickets in advance for popular shows.

  ### Day 3: Historical and Educational

  * **Morning:**
    * **Statue of Liberty and Ellis Island:** Take a ferry to visit these iconic sites. Dress warmly for the ferry ride. The cloud cover will provide a unique perspective for photos.

  * **Afternoon:**
    * **9/11 Memorial and Museum:** Spend your afternoon reflecting at the 9/11 Memorial and exploring the museum exhibits.

  * **Evening:**
    * **Brooklyn Bridge:** Walk across the Brooklyn Bridge and enjoy the city skyline. With the wind speed at 5.81 m/s, be prepared for breezy conditions.

  ### Additional Tips:

  * **Clothing:** Wear layers to keep warm, as the temperature feels colder than it actually is.
  * **Dining:** New York offers a plethora of dining options. Consider trying some local favorites like a classic New York bagel or pizza.
  * **Transportation:** Utilize the subway for efficient travel across the city. Taxis and ride-sharing services are also readily available.

  For more details on attractions and guided tours, you can visit [USA Guided Tours](https://usaguidedtours.com/nyc/attraction/) and [I Love NY](https://www.iloveny.com/places-to-go/new-york-city/attractions/).

  ## Enjoy your trip to New York City!

  **Day 1: Exploring Iconic London Landmarks**

  **Morning:**

  1. **Buckingham Palace**
     * Start your day early with a visit to Buckingham Palace. Arrive by 9:30 AM to catch the Changing of the Guard ceremony, which typically starts at 11:00 AM. Enjoy the majestic architecture and the surrounding gardens.
     * Weather Tip: With the overcast clouds, it might feel chilly, so dress warmly and bring an umbrella just in case.

  **Midday:**
  2\. **Westminster Abbey**

  * Head towards Westminster Abbey, a short walk from Buckingham Palace. This historic church has been the site of many significant events, including royal weddings and coronations. Spend about 1.5 hours exploring.

  3. **Lunch at Borough Market**
     * Take a tube or walk to Borough Market for a variety of food options. It's a great place to warm up with some hot street food and explore the diverse culinary offerings.

  **Afternoon:**
  4\. **London Eye**

  * After lunch, head to the London Eye. The overcast sky might not offer the clearest views, but the experience is still worthwhile. Pre-book your tickets to avoid long lines and enjoy a 30-minute ride on this iconic Ferris wheel.

  **Evening:**
  5\. **The Globe Theatre**

  * As the day winds down, visit Shakespeare's Globe Theatre. If there's a performance, consider attending or simply take a guided tour to learn about the history of this famous theater.

  **Day 2: Museums and Cultural Exploration**

  **Morning:**

  1. **The British Museum**
     * Start your second day at the British Museum. Spend a few hours exploring the vast collection of art and antiquities. Highlights include the Rosetta Stone and the Elgin Marbles.

  **Midday:**
  2\. **Lunch near Covent Garden**

  * Head to Covent Garden for lunch. This area is bustling with restaurants and cafes, perfect for a cozy indoor meal.

  **Afternoon:**
  3\. **The Tower of London**

  * After lunch, make your way to the Tower of London. Delve into England's rich history and see the Crown Jewels. Allocate about 2-3 hours for this visit.

  **Evening:**
  4\. **Tower Bridge**

  * Conclude your day with a walk across Tower Bridge. The views of the Thames River and the cityscape are beautiful, even on a cloudy evening.

  **Day 3: Leisure and Local Experiences**

  **Morning:**

  1. **Natural History Museum**
     * Begin your last day at the Natural History Museum. It's a family-friendly museum with fascinating exhibits, including dinosaur skeletons and a model of a blue whale.

  **Midday:**
  2\. **Lunch at South Kensington**

  * Enjoy a relaxed lunch in South Kensington. There are plenty of options, from casual cafes to high-end dining.

  **Afternoon:**
  3\. **Hyde Park**

  * Spend your afternoon strolling through Hyde Park. Visit the Serpentine Galleries if you're interested in contemporary art. The park's natural beauty is a peaceful retreat amidst the city hustle.

  **Evening:**
  4\. **Dinner and a Show in the West End**

  * End your London adventure with a memorable dinner followed by a theater show in the West End. Book your tickets in advance for popular shows.

  **Additional Tips:**

  * Always check the attraction websites for any specific COVID-19 guidelines or changes in operating hours.
  * London’s public transport system is efficient; consider getting an Oyster card for convenient travel.
  * Don't forget to dress in layers to adapt to the chilly weather, and always have your camera ready to capture memories.

  ***

  Here’s a detailed itinerary for your visit to Paris, considering the current snowy weather conditions and top attractions:

  ### Day 1: Embrace the Iconic Landmarks

  **Morning: Eiffel Tower**

  * **Time:** 9:00 AM
  * **Details:** Begin your day with a visit to the Eiffel Tower. Even in the snow, the tower offers stunning views of Paris. Dress warmly and enjoy hot chocolate from nearby cafes.
  * **Link for more info:** [Tripadvisor - Things to Do in Paris](https://www.tripadvisor.com/Attractions-g187147-Activities-Paris_Ile_de_France.html)

  **Afternoon: Louvre Museum**

  * **Time:** 1:00 PM
  * **Details:** Spend your afternoon indoors at the Louvre Museum. With its vast collection of art and history, it's a perfect way to escape the cold. Consider taking a guided tour to make the most of your visit.
  * **Link for more info:** [U.S. News Travel - Things To Do](https://travel.usnews.com/Paris_France/Things_To_Do/)

  **Evening: Seine River Cruise**

  * **Time:** 6:00 PM
  * **Details:** End your day with a magical Seine River cruise. The snow adds a picturesque touch to the illuminated landmarks. Ensure to book a heated cruise for comfort.

  ### Day 2: Explore Cultural and Historical Treasures

  **Morning: Notre-Dame Cathedral**

  * **Time:** 9:30 AM
  * **Details:** Visit the iconic Notre-Dame Cathedral. Although some areas may be under restoration, its architecture and history are worth experiencing. Warm clothing is essential as the interior can be chilly.

  **Afternoon: Musée d'Orsay**

  * **Time:** 1:30 PM
  * **Details:** Head to the Musée d'Orsay, renowned for its Impressionist masterpieces. This indoor activity is ideal for escaping the cold and enjoying world-class art.

  **Evening: Montmartre and Sacré-Cœur**

  * **Time:** 5:00 PM
  * **Details:** Wander through the charming streets of Montmartre and visit the Sacré-Cœur Basilica. The view of Paris in the snow is breathtaking. Enjoy a cozy dinner at a local bistro in Montmartre.

  ### Day 3: Discover Hidden Gems and Local Flavors

  **Morning: Le Marais District**

  * **Time:** 10:00 AM
  * **Details:** Explore Le Marais, known for its vibrant street art, boutiques, and cafes. Enjoy a leisurely breakfast and shop for unique souvenirs.

  **Afternoon: Palais Garnier (Opera House)**

  * **Time:** 2:00 PM
  * **Details:** Tour the opulent Palais Garnier. Its stunning interiors are a must-see, especially when it's snowy outside.

  **Evening: Moulin Rouge Show**

  * **Time:** 8:00 PM
  * **Details:** Conclude your trip with a classic Parisian experience at the Moulin Rouge. Book in advance to secure a good seat and enjoy the legendary cabaret performance.

  ### Additional Tips:

  * **Weather Preparation:** Wear layers, waterproof boots, and carry an umbrella. The snow and cold wind can be intense.
  * **Dining:** Indulge in warm, hearty French cuisine at local cafes and restaurants. Try dishes like French onion soup, coq au vin, and tarte Tatin.
  * **Transport:** Use public transportation to avoid the snowy streets, and consider purchasing a Paris Visite pass for unlimited travel.

  ## Enjoy your snowy adventure in Paris!

  **Tokyo Itinerary**

  **Day 1: Arrival and Exploration of Historical and Cultural Sites**

  * **Morning:**
    * **Asakusa District**: Begin your day with a visit to the historic Asakusa district. Explore the iconic Senso-ji Temple, Tokyo's oldest temple. Enjoy the traditional market streets like Nakamise Street for some shopping and snacks.

  * **Afternoon:**
    * **Tokyo National Museum**: Head to Ueno Park and visit the Tokyo National Museum. Discover Japan’s extensive collection of art and antiquities. This is a great spot to dive into Japanese history and culture.

  * **Evening:**
    * **Dinner in Ueno**: Explore the local dining options around Ueno and enjoy a traditional Japanese dinner.

  **Day 2: Modern Tokyo and Unique Experiences**

  * **Morning:**
    * **Ghibli Museum**: Start your day with a magical visit to the Ghibli Museum in Mitaka. Perfect for fans of Studio Ghibli's animated films, this museum offers a whimsical look into the creative world of Hayao Miyazaki.

  * **Afternoon:**
    * **Shibuya and Harajuku**: Head towards the bustling areas of Shibuya and Harajuku. Witness the famous Shibuya Crossing and explore the trendy shops of Harajuku, especially Takeshita Street.

  * **Evening:**
    * **Golden Gai**: Conclude your day in the vibrant Golden Gai district. This area is renowned for its narrow alleys filled with small bars and eateries. Experience the unique nightlife of Tokyo here.

  **Day 3: Relax and Explore Green Spaces**

  * **Morning:**
    * **Shinjuku Gyoen National Garden**: Spend a peaceful morning strolling through the beautiful Shinjuku Gyoen, one of Tokyo's largest and most beautiful parks. It's a perfect spot for relaxation and enjoying nature.

  * **Afternoon:**
    * **Meiji Shrine**: Visit the Meiji Shrine, located in a forested area near Harajuku and Shibuya. It's a serene place to learn about Shinto traditions and enjoy the tranquil setting.

  * **Evening:**
    * **Tokyo Tower or Skytree**: End your trip with a visit to either Tokyo Tower or Tokyo Skytree for a panoramic view of the city. It's an unforgettable way to see Tokyo illuminated at night.

  **Weather Considerations:**

  * With the current weather of few clouds and a mild temperature around 10.32°C, it is advisable to wear layers and carry a light jacket for comfort during outdoor activities.
  * Humidity is high (92%), so be prepared for a slightly damp feeling and consider moisture-wicking clothing.

  **Additional Tips:**

  * Always check the opening hours of attractions and book tickets in advance where necessary.
  * Use Tokyo’s efficient public transport to move around easily.
  * Consider visiting the websites linked in the attraction descriptions for more detailed information and current updates.

  ***

  Here's a detailed itinerary for exploring some of Sydney's top tourist attractions with the current weather conditions in mind. With clear skies and pleasant temperatures, it's a perfect day to explore the outdoors and enjoy what Sydney has to offer.

  ### Morning

  **9:00 AM - Sydney Opera House**

  * Begin your day with a visit to the iconic Sydney Opera House. Take a guided tour to learn about its history and architecture. Tours are available in multiple languages.
  * **Link:** [Top attractions in Sydney | Sydney.com](https://www.sydney.com/things-to-do/attractions)

  **11:00 AM - Royal Botanic Garden Sydney**

  * Just a short walk from the Opera House, enjoy a leisurely stroll through the Royal Botanic Garden. The clear skies will offer beautiful views of the diverse plant life and the Sydney Harbour.

  ### Afternoon

  **12:30 PM - Lunch at Opera Bar**

  * Head back to Opera Bar for lunch. Enjoy a refreshing cocktail with stunning views of the Sydney Harbour Bridge and the waterfront.
  * **Link:** [Top attractions in Sydney | Sydney.com](https://www.sydney.com/things-to-do/attractions)

  **2:00 PM - Sydney Harbour Bridge**

  * After lunch, take a scenic walk across the Sydney Harbour Bridge. If you're up for it, consider the BridgeClimb for breathtaking panoramic views of the city.

  **4:00 PM - The Rocks**

  * Explore The Rocks, one of Sydney's most historic areas. Wander through the cobbled streets, visit the local markets, and perhaps enjoy a cup of coffee at a nearby café.

  ### Evening

  **6:00 PM - Darling Harbour**

  * Make your way to Darling Harbour for the evening. Here you can visit attractions such as the SEA LIFE Sydney Aquarium or simply enjoy the lively atmosphere by the waterfront.

  **8:00 PM - Dinner at a Local Restaurant**

  * Conclude your day with dinner at one of Darling Harbour's many restaurants. Choose from a variety of cuisines while enjoying the vibrant night scene.

  ### Additional Suggestions

  * If you're interested in more unique experiences, consider visiting some of the attractions listed on [Time Out Sydney](https://www.timeout.com/sydney/attractions/tourist-attractions-that-dont-suck), which includes thrilling adventures and scenic tours.

  With clear skies and mild temperatures, this itinerary offers a balanced mix of cultural, historical, and scenic experiences. Enjoy your visit to Sydney!
</Accordion>

## Next Steps

* Try this task yourself, check out the full example, see the [trip-planning cookbook](https://github.com/julep-ai/julep/blob/main/cookbooks/advanced/03-trip-planning-assistant.ipynb).
* To learn more about the integrations used in this task, check out the [integrations](/integrations/supported-integrations) page.

**Also See:**

1. [Input Schema](./trip-planning-input)
2. [Tools Configuration](./trip-planning-tools)
3. [Workflow Steps](./trip-planning-workflow)
4. [Running the Task](./trip-planning-running)

## Related Concepts

* [Agents](/concepts/agents)
* [Tasks](/concepts/tasks)
* [Tools](/concepts/tools)