Building Intelligent Multi-Agent Systems With OpenAI’s Swarm

Today, we’re diving into Agentic AI with OpenAI’s Swarm framework to create something fun and useful — a travel assistant that can help book your hotel, set up restaurant reservations, and even arrange a rental car, all in one place. What makes it special? We’re setting it up with multi-agent AI, which means we’ll have multiple “mini-assistants,” each taking care of one specific task, working together to make your travel planning smooth.

What Are Agents?

An Agent is like a digital helper designed to handle a single job. It’s autonomous, meaning once it’s set up, it can make decisions and respond to changes without needing constant instructions from a human. Think of it like this: you have one agent just for handling hotel bookings and another one focused on restaurant reservations. Each is designed to be an expert in its own little area.

Why Multiple Agents?

Why not just one big assistant? Well, by using multi-agent systems, we can have a collection of these agents working together, each focusing on what it does best. It’s like having a team of assistants — one manages the hotel, one handles the restaurant reservations, and another covers car rentals. This way, each agent specializes in its task, but together, they cover the whole travel process.

Step 1: Prerequisites

Before we dive in, make sure you have:

• Basic familiarity with Python (nothing too advanced). Python is installed on your machine and has access to a terminal.
• Editor of your choice (I used Microsoft Visual Studio Code)
• OpenAI API Key: Swarm uses OpenAI’s models, so you’ll need an API key. You can get one if you don’t have one by signing up at OpenAI. Make sure you check the API limits page if you have any questions about the API Limits and Permissions.

Step 2: Setting Up Your Project Environment

First, you’ll need to set up your API key. Here’s how to do it:

1. Go to the OpenAI API key page and create a new key.
2. Copy this key — you’ll need it for both the terminal and our code.

To set the key in your terminal, run:

export OPENAI_API_KEY="your_openai_api_key_here"

Also, don’t forget to replace "your_openai_api_key_here" with your actual API key.

You’ll also want to add this key directly in your code, which we’ll show in the next section.

Step 3: Setting Up and Structuring the Code

Our travel assistant will be built using multiple files, each representing a different agent. Let’s walk through each component step by step, explaining why we’ve made certain decisions and how each part functions.

Step 3.1: Setting Up Your Project Environment

Before we jump into coding, let's get our environment ready with Swarm.

1. Install Swarm: First, open your terminal and install Swarm with this command:

pip install git+https://github.com/openai/swarm.git

2. Organize Our Project: Next, set up a simple project structure:

SmartTravelConcierge/
├── main.py                 # Main script to run our travel assistant
├── agents/                 # Folder for all agents
│   ├── triage_agent.py     # Routes requests to the correct agent
│   ├── hotel_agent.py      # Handles hotel bookings
│   ├── restaurant_agent.py # Manages restaurant reservations
│   └── car_rental_agent.py # Takes care of car rentals

What Each Agent Does

• Triage Agent: Listens to user requests, decides which agent (hotel, restaurant, or car rental) should handle it, and hands off the task.
• Hotel Agent: Asks for hotel details like location, dates, and budget.
• Restaurant Agent: Gathers reservation info, such as date, time, and party size.
• Car Rental Agent: Collects car rental details, like pickup location, dates, and car type.

With everything set up, we’re ready to start coding each agent in its file. Let’s jump in!

Step 3.2: Building the Core Script (main.py)

main.py is the central script that runs our Smart Travel Concierge. It’s where we initialize the Swarm client, handle user input, and route requests to the right agents. Let’s take a look at the code:

import openai
from swarm import Swarm
from agents.triage_agent import triage_agent, user_context

# Set your OpenAI API key here
openai.api_key = "your_openai_api_key_here"  # Replace with your actual API key

# Initialize Swarm client
client = Swarm()

# Define ANSI color codes for a better experience in the terminal
COLOR_BLUE = "\033[94m"
COLOR_GREEN = "\033[92m"
COLOR_RESET = "\033[0m"

def handle_request():
    print("Welcome to your Smart Travel Concierge!")
    print("You can ask me to book hotels, reserve restaurants, or arrange car rentals.")

    while True:
        user_input = input(f"{COLOR_GREEN}You:{COLOR_RESET} ")
        
        if user_input.lower() in ["exit", "quit", "stop"]:
            print("Goodbye! Safe travels!")
            break

        # Route the request to the Triage Agent for delegation
        response = client.run(agent=triage_agent, messages=[{"role": "user", "content": user_input}])

        # Extract the final response content
        final_content = None
        for message in response.messages:
            if message['role'] == 'assistant' and message['content'] is not None:
                final_content = message['content']

        # Print the assistant’s response if available
        if final_content:
            print(f"{COLOR_BLUE}Bot:{COLOR_RESET} {final_content}")

            # Only add additional prompts if the final content doesn't include detailed instructions
            if ("check-in" not in final_content.lower() and "location" not in final_content.lower()
                and "budget" not in final_content.lower() and user_context["intent"] == "hotel"
                and not user_context["details_provided"]):
                
                print(f"{COLOR_BLUE}Bot:{COLOR_RESET} Please provide your location, check-in and check-out dates, and budget.")
                user_context["details_provided"] = True  # Avoid further prompts once requested

            elif ("reservation" not in final_content.lower() and user_context["intent"] == "restaurant"
                  and not user_context["details_provided"]):
                
                print(f"{COLOR_BLUE}Bot:{COLOR_RESET} Please provide your reservation date, time, and party size.")
                user_context["details_provided"] = True

            elif ("pickup" not in final_content.lower() and user_context["intent"] == "car_rental"
                  and not user_context["details_provided"]):
                
                print(f"{COLOR_BLUE}Bot:{COLOR_RESET} Please provide the pickup location, rental dates, and preferred car type.")
                user_context["details_provided"] = True
        
        else:
            print(f"{COLOR_BLUE}Bot:{COLOR_RESET} (No response content found)")

if __name__ == "__main__":
    handle_request()

How It Works

Here’s a breakdown of the main script:

• Set Up OpenAI API: First, we set up our API key so we can interact with OpenAI's models.
• Initialize the Swarm Client: This connects us to the Swarm framework, allowing us to run agents.
• User Interaction Loop: The handle_request() function creates a loop for continuous user interaction, where each input is analyzed and routed to the Triage Agent.
• Response Handling: Based on the Triage Agent’s decision, the relevant agent responds, and we handle any missing information by prompting the user.

Step 3.3: Routing Requests to the Right Agent (triage_agent.py)

The Triage Agent decides which agent should handle the user’s request — like a concierge dispatcher. Let’s see the code:

from swarm import Agent
from agents.hotel_agent import hotel_agent
from agents.restaurant_agent import restaurant_agent
from agents.car_rental_agent import car_rental_agent

# Context dictionary to track user intent and state
user_context = {"intent": None, "details_provided": False}

def transfer_to_hotel():
    user_context["intent"] = "hotel"
    return hotel_agent

def transfer_to_restaurant():
    user_context["intent"] = "restaurant"
    return restaurant_agent

def transfer_to_car_rental():
    user_context["intent"] = "car_rental"
    return car_rental_agent

# Main triage agent
triage_agent = Agent(
    name="Triage Agent",
    description="""
        You are a triage agent that understands the user’s intent and delegates it to the appropriate service:
        - Book a hotel
        - Reserve a restaurant
        - Rent a car
        Once you identify the user’s intent, immediately transfer the request to the relevant agent.
        Track user intent and avoid redundant questions by confirming and passing any provided information.
    """,
    functions=[transfer_to_hotel, transfer_to_restaurant, transfer_to_car_rental]
)

What This Agent Does

Here’s how the Triage Agent makes decisions:

• Intent Tracking: Tracks user intent, ensuring repeated details aren’t requested.
• Directing Requests: Routes hotel bookings to the Hotel Agent, restaurant bookings to the Restaurant Agent, and car rentals to the Car Rental Agent.
• Using user_context: Keeps user data in memory for smooth conversation flow.

Step 3.4: Arranging Hotel Bookings (hotel_agent.py)

The Hotel Agent handles all hotel-related requests, gathering details like location, dates, and budget.

from swarm import Agent

def book_hotel(location, checkin_date, checkout_date, budget):
    # A mock response for hotel booking
    return f"Hotel booked in {location} from {checkin_date} to {checkout_date} within a budget of ${budget} per night."

hotel_agent = Agent(
    name="Hotel Agent",
    description="Handles hotel bookings, including location, dates, and budget.",
    functions=[book_hotel]
)

How the Hotel Agent Operates

Here’s what makes this agent effective:

• Booking Details: Asks for location, check-in/out dates, and budget to complete hotel bookings.
• Dedicated Functionality: With book_hotel(), this agent is entirely focused on hotels, making it easy to expand or improve without affecting other agents.

Step 3.5: Managing Restaurant Reservations (restaurant_agent.py)

The Restaurant Agent handles all restaurant-related tasks, such as date, time, and party size.

from swarm import Agent

def reserve_restaurant(location, date, time, party_size):
    # A mock response for restaurant reservations
    return f"Restaurant reservation made in {location} on {date} at {time} for {party_size} people."

restaurant_agent = Agent(
    name="Restaurant Agent",
    description="Manages restaurant reservations, including date, time, and party size.",
    functions=[reserve_restaurant]
)

What the Restaurant Agent Handles

Let’s see how it works:

• Reservation Details: Collects specifics such as location, date, and time.
• Independent Operations: By handling only restaurant reservations, it ensures a seamless experience without overlapping tasks with other agents.

Step 3.5: Arranging Car Rentals (car_rental_agent.py)

Finally, the Car Rental Agent handles car rentals by asking for pickup location, rental dates, and car preferences.

from swarm import Agent

def rent_car(location, start_date, end_date, car_type):
    # A mock response for car rentals
    return f"Car rental booked at {location} from {start_date} to {end_date} with a {car_type} car."

car_rental_agent = Agent(
    name="Car Rental Agent",
    description="Arranges car rentals, including pickup location, rental dates, and car type.",
    functions=[rent_car]
)

Inside the Car Rental Agent

Here’s how it operates:

• Rental Details: Manages details like pickup location, dates, and car type.
• Focused Functionality: With rent_car(), the agent’s focus is entirely on car rentals, keeping it streamlined and easy to modify.

Step 4: Running the Program

To test our Smart Travel Agent:

1. Navigate to the project folder in your terminal.
2. Run the program: python main.py

When prompted, you can enter requests like “I need to book a hotel in Chicago,” and the bot will guide you through providing the necessary details.

Interact with the bot as follows:

You: I need to book a hotel
Bot: Great! Could you provide the location, check-in, and check-out dates, and your budget?
You: Chicago, check-in 18th Nov, check-out 19th Nov, budget $200

Live Output

How Context Is Handled Through the Chat?

The user_context dictionary in the triage_agent.py code keeps track of the user’s intent, so agents don’t keep asking for the same details. This context ensures the conversation flows smoothly without repetitive questions.

What's Next? 

Ready to take this tutorial to the next level? Here’s how to make your Smart Travel Agent production-ready:

• Integrate Real APIs: Connect each agent with real-time APIs for hotels, restaurants, and car rentals. For example: 
  • Use Booking.com API for hotels.
  • Integrate OpenTable API for restaurant reservations.
  • Leverage RentalCars API for car rentals.
• Add Authentication: Protect API calls with secure tokens to prevent unauthorized access.
• Database Support: Add a database to keep track of previous bookings, user preferences, and chat history.
• Enhance Context Management: Expand user_context to retain more information across conversations, making interactions more seamless.

Conclusion

And there you have it! You've built a fully functioning travel concierge using multi-agent systems and OpenAI’s Swarm framework. With each agent handling a specific task, your bot is now smart enough to make travel bookings feel like a breeze.