Build a Hotel Finder Agent

Time: 10 minutes | What you'll build: A conversational agent that helps users find hotels in a specific city and check availability through natural conversation, with session-scoped memory so the user can refer back to earlier messages.

Prerequisites

WSO2 Integrator installed

Visual designer
Ballerina code

Step 1: Create the integration

Open WSO2 Integrator.
Select Create in the Create New Integration card.
Set Integration Name to HotelFinder.
Set Project Name as AI-Integrations.
Select Create Integration.

Create Integration form with Integration Name set to HotelFinder and Project Name set to AI-Integrations

Step 2: Add an AI chat agent

In the design view, select + Add Artifact.
Select AI Chat Agent under AI Integration.
Set Name to HotelFinderAssistant.
Select Create.

AI Chat Agent wizard with Name set to HotelFinderAssistant

Default model provider

By default, the agent is created with the WSO2 model provider. If you have not signed in to WSO2 Integrator Copilot yet, sign in when prompted. No third-party API key is required.

To use a different LLM instead, see Model providers for the full list of supported providers (OpenAI, Anthropic, Azure OpenAI, and others).

Step 3: Configure the agent

Select the AI Agent node in the design canvas.
Set Role to HotelFinderAssistant.

Set Instructions to:

You are a friendly hotel finder assistant.

Your responsibilities:
- Help users find hotels and check availability through natural conversation.
- Ask clarifying questions when information is missing.

Tool usage:
- Use searchHotels when the user mentions a city or destination.
- Use checkAvailability when the user wants to verify dates and pricing.

Presentation:
- Show hotels clearly with price, rating, and key amenities.

Select Save.

AI Agent configuration panel with Role and Instructions filled in

Step 4: Add the `searchHotels` tool

Create the `searchHotels` tool

Select the + button on the AI Agent node.
Select Create Custom Tool.
Set Name to searchHotels.
Set Description to Searches for hotels in a city.
Under Parameters, select + Add Parameter and add:

Type Name Description
string city City name, e.g. "Paris" or "New York"
Under Return Type, select the field and choose Create New Type. The Create New Type dialog opens:

a. Set Kind to Record and Name to Hotel.

b. Add the following fields:

Name Type
hotelId string
name string
city string
pricePerNight decimal
rating float
amenities string[]

c. Select Save.

Type	Name	Description
`string`	`city`	City name, e.g. "Paris" or "New York"

Name	Type
`hotelId`	`string`
`name`	`string`
`city`	`string`
`pricePerNight`	`decimal`
`rating`	`float`
`amenities`	`string[]`

Create New Type dialog open over the Create New Agent Tool form, with Kind set to Record and Name set to Hotel, showing all six fields

Set Return Type to Hotel[].
Set Description (return value) to Hotels available in the city.
Select Create.

Completed Create New Agent Tool form for searchHotels showing the city parameter, Hotel[] return type, and return description

Build the `searchHotels` logic

The tool's visual flow opens. Add the logic:

Select the + button and select Declare Variable under Statement. Set Name to allHotels and Type to Hotel[]. Set the Expression to the following hotel array and select Save:

[
  {hotelId: "HTL-001", name: "Grand Plaza Hotel", city: "Paris", pricePerNight: 199.99, rating: 4.5, amenities: ["WiFi", "Pool", "Gym"]},
  {hotelId: "HTL-002", name: "City Center Inn", city: "Paris", pricePerNight: 129.99, rating: 4.0, amenities: ["WiFi", "Breakfast"]},
  {hotelId: "HTL-003", name: "Luxury Suites", city: "New York", pricePerNight: 349.99, rating: 4.8, amenities: ["WiFi", "Pool", "Spa", "Restaurant"]}
]

note

This uses hardcoded sample data. In a real scenario, you would call an external hotel API, query a database, or connect an MCP tool.

Declare Variable node configured with Name set to allHotels, Type set to Hotel[], and the hotel array set as the Expression

Select + and select Declare Variable under Statement. Set Name to hotels and Type to Hotel[]. Set the Expression to the following and select Save:
```
allHotels.filter(h => h.city == city)
```

Declare Variable node configured with Name set to hotels, Type set to Hotel[], and the filter expression set as the Expression

Select + and select Return under Control. Set Expression to hotels and select Save.

Return node configuration panel with Expression set to hotels

Step 5: Add the `checkAvailability` tool

Create the `checkAvailability` tool

Navigate back to the AI Chat Agent view.
Select + on the AI Agent node and choose Create Custom Tool.
Set Name to checkAvailability.
Set Description to Checks whether a hotel has rooms available between two dates.
Under Parameters, select + Add Parameter and add:

Type Name Description
string hotelId Hotel identifier returned from searchHotels
string checkIn Check-in date in YYYY-MM-DD format
string checkOut Check-out date in YYYY-MM-DD format
Under Return Type, select the field and choose Create New Type. The Create New Type dialog opens:

a. Set Kind to Record and Name to Availability.

b. Add the following fields:

Name Type
hotelId string
hotelName string
available boolean
totalPrice decimal
nights int

c. Select Save.

Type	Name	Description
`string`	`hotelId`	Hotel identifier returned from `searchHotels`
`string`	`checkIn`	Check-in date in `YYYY-MM-DD` format
`string`	`checkOut`	Check-out date in `YYYY-MM-DD` format

Name	Type
`hotelId`	`string`
`hotelName`	`string`
`available`	`boolean`
`totalPrice`	`decimal`
`nights`	`int`

Create New Type dialog open over the checkAvailability form, with Kind set to Record and Name set to Availability, showing all five fields

Set Return Type to Availability.
Set Description (return value) to Availability result with total price and nights.
Select Create.

Completed checkAvailability tool form showing hotelId, checkIn, checkOut parameters, Availability return type, and return description

Build the `checkAvailability` logic

In the tool's visual flow, select + and select Return under Control. Set Expression to the following and select Save:

{
    hotelId,
    hotelName: "Grand Plaza Hotel",
    available: true,
    totalPrice: 599.97,
    nights: 3
}

note

This returns hardcoded sample data. In a real scenario, you would query a booking system, call an availability API, or connect an MCP tool.

Return node configuration panel for checkAvailability with the hardcoded Availability record set as the Expression

After both tools are created, the agent shows them connected in the design canvas.

AI Chat Agent design view showing the agent node connected to searchHotels and checkAvailability tools with the system prompt visible

Step 6: Run and test

Select Run.
Select Chat.
Type Show me hotels in Paris to check if it works.

The agent calls searchHotels and returns matching options. Continue the conversation using the same session to check availability.

Agent Chat panel showing the user asking for hotels in Paris, with the agent responding with Grand Plaza Hotel, City Center Inn, and Luxury Suites options

Step 1: Define data types

Create a file named types.bal to hold the domain types:

type Hotel record {|
    string hotelId;
    string name;
    string city;
    decimal pricePerNight;
    float rating;
    string[] amenities;
|};

type Availability record {|
    string hotelId;
    string hotelName;
    boolean available;
    decimal totalPrice;
    int nights;
|};

Step 2: Configure the model provider

Create a file named connections.bal to initialize the model provider:

import ballerina/ai;

final ai:Wso2ModelProvider wso2ModelProvider = check ai:getDefaultModelProvider();

Step 3: Define tools and create the agent

Create a file named agents.bal. Each tool is an isolated function annotated with @ai:AgentTool. The LLM uses the summary line and + param - description lines from the Ballerina doc comment to decide when and how to call the tool.

note

Both tools use hardcoded sample data. In a real scenario, you would call external APIs, query a database, or connect MCP tools.

import ballerina/ai;

final ai:Agent hotelFinderAssistantAgent = check new (
    systemPrompt = {
        role: string `HotelFinderAssistant`,
        instructions: string `You are a friendly hotel finder assistant.

Your responsibilities:
- Help users find hotels and check availability through natural conversation.
- Ask clarifying questions when information is missing.

Tool usage:
- Use searchHotels when the user mentions a city or destination.
- Use checkAvailability when the user wants to verify dates and pricing.

Presentation:
- Show hotels clearly with price, rating, and key amenities.`
    }, model = wso2ModelProvider, tools = [searchHotels, checkAvailability]
);

# Searches for hotels in a city
# + city - City name, e.g. "Paris" or "New York"
# + return - Hotels available in the city
@ai:AgentTool
isolated function searchHotels(string city) returns Hotel[] {
    Hotel[] allHotels = [
        {hotelId: "HTL-001", name: "Grand Plaza Hotel", city: "Paris", pricePerNight: 199.99, rating: 4.5, amenities: ["WiFi", "Pool", "Gym"]},
        {hotelId: "HTL-002", name: "City Center Inn", city: "Paris", pricePerNight: 129.99, rating: 4.0, amenities: ["WiFi", "Breakfast"]},
        {hotelId: "HTL-003", name: "Luxury Suites", city: "New York", pricePerNight: 349.99, rating: 4.8, amenities: ["WiFi", "Pool", "Spa", "Restaurant"]}
    ];
    Hotel[] hotels = allHotels.filter(h => h.city == city);
    return hotels;
}

# Checks whether a hotel has rooms available between two dates
# + hotelId - Hotel identifier returned from searchHotels
# + checkIn - Check-in date in YYYY-MM-DD format
# + checkOut - Check-out date in YYYY-MM-DD format
# + return - Availability result with total price and nights
@ai:AgentTool
isolated function checkAvailability(string hotelId, string checkIn, string checkOut) returns Availability {
    return {
        hotelId,
        hotelName: "Grand Plaza Hotel",
        available: true,
        totalPrice: 599.97,
        nights: 3
    };
}

Step 4: Expose the agent as a chat service

Create a file named main.bal. The ai:Listener provides session-scoped chat memory. Pass the sessionId into agent.run(...) and the runtime retrieves and updates the conversation history for that session automatically.

import ballerina/ai;
import ballerina/http;

listener ai:Listener chatAgentListener = new (listenOn = check http:getDefaultListener());

service /hotelFinderAssistant on chatAgentListener {
    resource function post chat(@http:Payload ai:ChatReqMessage request) returns ai:ChatRespMessage|error {
        string stringResult = check hotelFinderAssistantAgent.run(request.message, sessionId = request.sessionId);
        return {message: stringResult};
    }
}

Step 5: Run and test

Run the project:

bal run

Have a multi-turn conversation. Use the same sessionId across requests so the agent remembers context:

# Turn 1 — search for hotels
curl -X POST http://localhost:9090/hotelFinderAssistant/chat \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "guest-42", "message": "Show me hotels in Paris"}'

# Turn 2 — refer back to an earlier result
curl -X POST http://localhost:9090/hotelFinderAssistant/chat \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "guest-42", "message": "Can you check the City Center Inn from March 20 to March 23?"}'

Because the listener keeps session history, the agent resolves "the City Center Inn" from the earlier message without the user having to repeat themselves.

How it works

This example demonstrates two patterns you will reuse in production agents:

Session-scoped memory: ai:Listener keeps a short history of messages per sessionId, so the LLM sees recent turns on every call.
Sequential tool calls: The agent calls searchHotels and then checkAvailability, using each result to inform the next step. The chaining is driven entirely by the LLM's reasoning.

What's next

Creating an agent — Full reference for agent configuration
Tools — Advanced tool patterns, including connection-backed tools and MCP servers
Memory — Custom memory strategies beyond the default session store

Step 1: Create the integration​

Step 2: Add an AI chat agent​

Step 3: Configure the agent​

Step 4: Add the searchHotels tool​

Create the searchHotels tool​

Build the searchHotels logic​

Step 5: Add the checkAvailability tool​

Create the checkAvailability tool​

Build the checkAvailability logic​

Step 6: Run and test​

Step 1: Define data types

Step 2: Configure the model provider

Step 3: Define tools and create the agent

Step 4: Expose the agent as a chat service

Step 5: Run and test

How it works​

What's next​

Step 1: Create the integration

Step 2: Add an AI chat agent

Step 3: Configure the agent

Step 4: Add the `searchHotels` tool

Create the `searchHotels` tool

Build the `searchHotels` logic

Step 5: Add the `checkAvailability` tool

Create the `checkAvailability` tool

Build the `checkAvailability` logic

Step 6: Run and test

How it works

What's next