# Agent Air

> Companhia aérea brasileira com voos, tarifas, bagagem e políticas legíveis por máquina. Todo o fluxo de reserva, da busca ao recibo, está disponível por API documentada, por tools WebMCP e por navegação comum.

Agent Air is a pilot airline built so that an autonomous agent can complete a
booking end to end. Flights, fares, arrival times, baggage policies and terms
are published both as prose and as structured data. The full booking flow,
through to the receipt, is available as a documented REST API and as WebMCP
tools.

Site content is written in Brazilian Portuguese. This index is in English
because that is what most agents parse first.

## Machine-readable entry points

- [WebMCP manifest](https://agentair.ori.lat/.well-known/webmcp.json): the tools a browser exposes via document.modelContext
- [OpenAPI 3.1 specification](https://agentair.ori.lat/openapi.json): every endpoint, request and response shape
- [Agent Layer profile](https://agentair.ori.lat/.well-known/agent-layer.json): organisation identity and declared capabilities
- [Authorization scopes](https://agentair.ori.lat/auth.md): OAuth scopes and how to obtain a token
- [OAuth server metadata](https://agentair.ori.lat/.well-known/oauth-authorization-server): issuer, endpoints, supported scopes
- [MCP endpoint](https://agentair.ori.lat/.well-known/mcp): JSON-RPC, initialize with protocolVersion 2024-11-05
- [Sitemap](https://agentair.ori.lat/sitemap.xml): every canonical URL with a last-modified date
- [Security contact](https://agentair.ori.lat/.well-known/security.txt): where to report a vulnerability

## How to book, in short

1. Find the flight: `GET /api/v1/flights?q=<city>`
2. Quote fares: `GET /api/v1/flights/{flightNumber}/fares?budget=<cents>` returns every fare with its
   arrival day, baggage and total, plus the cheapest that arrives the same day with a checked bag
3. Get a scoped token via OAuth 2.1 authorization code with PKCE
4. Create a booking: `POST /api/v1/bookings`
5. Create a payment mandate with an explicit ceiling: `POST /api/v1/mandates`
6. Confirm and emit the ticket: `POST /api/v1/orders`
7. Read the receipt: `GET /api/v1/orders/{id}/receipt`

No charge is possible without a valid mandate. A charge above the mandate
ceiling is refused with `mandate_limit_exceeded`. A fare that arrives the next
day or has no checked bag is excluded from the recommendation even if it is the
cheapest. Those refusals are correct behaviour, not an outage.

## WebMCP tools

The site exposes its agent contract through WebMCP. In a browser with the
feature enabled, `document.modelContext` registers these tools (see
`/.well-known/webmcp.json` for the static list):

- `search_flights` — find flights by city, airport code or flight number
- `get_flight` — read a flight and its fares
- `quote_fare` — quote fares under a budget and pick the best that meets the constraints
- `add_to_booking` — add a fare to a booking (requires OAuth)
- `place_booking` — confirm and pay (requires OAuth + mandate)

## Human-readable pages

- [Home](https://agentair.ori.lat/): what the site is and how to start
- [All flights](https://agentair.ori.lat/voos): every route with fares and baggage
- [Search](https://agentair.ori.lat/busca): by destination or flight number
- [API documentation](https://agentair.ori.lat/docs): the booking flow with worked examples
- [Agent traffic panel](https://agentair.ori.lat/painel): which AI agents read this site, published openly

## Destinations

- São Paulo (GRU)
- Porto Alegre (POA)
- Rio de Janeiro (GIG)
- Brasília (BSB)
- Recife (REC)
- Salvador (SSA)

## Flights

- Voo AA-001 (GRU → POA): Voo diário de São Paulo (GRU) para Porto Alegre (POA), com quatro tarifas que combinam preço, horário de chegada e bagagem despachada.
- Voo AA-014 (GRU → GIG): Voo direto de São Paulo (GRU) para o Rio de Janeiro (GIG), com tarifa única e bagagem despachada incluída.
- Voo AA-021 (GRU → BSB): Voo matinal de São Paulo (GRU) para Brasília (BSB) com duas tarifas: uma econômica sem bagagem e uma com bagagem despachada.
- Voo AA-033 (GRU → REC): Voo noturno de São Paulo (GRU) para Recife (REC), com conexão em Salvador e chegada no dia seguinte na tarifa mais barata.
- Voo AA-040 (GRU → SSA): Voo direto de São Paulo (GRU) para Salvador (SSA) com tarifa com bagagem despachada e chegada no mesmo dia.

## Policies

- [Baggage and fees](https://agentair.ori.lat/politicas/bagagem): what each fare includes
- [Cancellation and refunds](https://agentair.ori.lat/politicas/cancelamento): 24 hours, full refund window
- [Privacy](https://agentair.ori.lat/politicas/privacidade): what is collected, kept and shared
- [Terms of use](https://agentair.ori.lat/politicas/termos): rules for automated access and for agent bookings

## Important disclosure

This is a research pilot, not a real airline. The routes, fares and airports are
fictional; no passenger is carried and no real flight exists. Payments run
against an internal sandbox processor: no real card is charged. Contact:
contato@agentair.ori.lat.