Flight Offers

When to useCopy Anchor Link

• The user searched for flights and should compare a few bookable options and pick one: "flights to Athens for the family in November", "cheapest nonstop to Lisbon next week".

When not to useCopy Anchor Link

• The user already booked. Use a Flight Ticket.
• The user asks about a flight in progress. Use Flight Status.
• The agent has no live fares. Search first; never invent prices or times.
• More than 10 options. Narrow the search (nonstop, time of day) first.

How the agent should use itCopy Anchor Link

• Every price, time and fare rule comes from the fare search result. price is the total for all passengers in the search, taxes included.
• Send times with the airport's offset and each airport's IANA timezone. Times show local to each airport, so a 21:30 departure from JFK reads 21:30 for every viewer, and an arrival on the next local day gets a "+1".
• Order offers by what the user asked for (cheapest, fastest) and set sort to match.
• Pass search.passengers so the footer says who the prices are for: "Prices for 3 adults, 1 child, 1 infant".
• Act only on a select result, then confirm the fare before booking: prices change.
• Lifecycle: fares are live, so set fetchedAt and staleAfterMs (about 10 minutes) on the call. When the provider holds the fares until a deadline, set expiresAt too. Use supersede when the agent re-runs the search with new dates or filters.

InteractionCopy Anchor Link

While streaming, offers appear one at a time in the agent's order. Sort and the badges wait for the whole list, so nothing jumps.

The helpers in flight-offers-utils.ts (sortOffers, cheapestIds, fastestIds, legMinutes, layoverText, legDayOffset, pricesForText) are pure, so the server can reuse them, for example to check that an "it's the cheapest" reply matches the data.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/flight-offers.json

UsageCopy Anchor Link

import { tool } from "ai"
import { flightOffersTool } from "@/components/genui/flight-offers.schema"

const tools = {
  // No execute(): the call is completed by the user's choice.
  [flightOffersTool.name]: tool({
    description: flightOffersTool.description,
    inputSchema: flightOffersTool.inputSchema,
  }),
}

<FlightOffers
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : undefined}
  result={part.state === "output-available" ? part.output : undefined}
  onResult={(result) =>
    addToolResult({ tool: "compare_flights", toolCallId: part.toolCallId, output: result })
  }
/>

The agent receives:

{ action: "select", offerId: "mr-412" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "compare_flights", props: { toolCallId, ...args } }, { message }), then interrupt() until the user's result arrives. Render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

Pass the stored result back as result. The list renders read-only, with the chosen offer ringed and checked (shown even if it's past the first 5), and the footer shows "Selected Meridian Air · $1,486". Sorting still works. It never calls onResult again.

<FlightOffers
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

Search

Offer

Segment

Host props: status (streaming, ready, submitting, selected), onResult, result and className.

SourceCopy Anchor Link