This document provides a high-level overview of the key concepts in the
Food Ordering AI Agent API.

## Agent configuration

The behavior of the Food Ordering AI Agent is influenced by the configuration of
several API resources: [`Brand`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#brand), [`Store`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#store), and [`Menu`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#menu). These resources define
the restaurant's identity, its physical locations, and the products it offers,
providing the necessary context for the AI agent to handle orders.

### Brand

A [`Brand`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#brand) is the top-level resource, representing a restaurant brand corresponding to one or more locations of that restaurant brand.
It contains configuration which is shared across all locations of that restaurant.
`Brand` can include configuration of many features of the agent persona, such as greeting behavior and voice characteristics. Many of those features can be overridden by values configured in the [Store](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/concepts.md.txt#store) resource
or even in per-session configuration (see [Session lifecycle](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/concepts.md.txt#session_lifecycle))

### Store

A [`Store`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#store) resource represents a single physical restaurant location belonging to a
[`Brand`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#brand). It defines configuration specific to that location, such as its
time zone, status (e.g., `ACTIVE`, `DISABLED`), operating hours, and
*dayparts* (e.g., periods like "Breakfast" or "Lunch" during which certain menu
items are available).

### Menu

A [`Menu`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#menu) resource defines all the products offered by a restaurant, including
all possible choices and customizations for every sellable product. A [`Menu`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#menu)
must be associated with a [`Store`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#store).
Menu is designed to be flexible and accommodate various menu structures, from
small lists of standalone items to complex trees of combination meals with nested modifiers.

Key components of a [`Menu`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#menu) include:

- **Items**: Sellable top-level products like a-la-carte entrees, drinks, sides, or combination meals.
- **ModifierGroups** : Collections of choices applicable to an [`Item`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#item) or another [`Modifier`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#modifier), such as "Choose a Side" or "Add Toppings".
- **Modifiers** : Individual options within a [`ModifierGroup`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#modifiergroup), like "Fries", "Extra Cheese", or "Cola". Modifiers can adjust the item price and can contain nested [`ModifierGroup`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#modifiergroup)s for further customization.
- **MenuCategories**: Organizational units like "Appetizers" or "Drinks".

A [`Menu`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#menu) resource is identified by a name in the following format:
`projects/{project}/locations/{location}/menus/{menu}`.

For more details on structuring menu data, see
[Integrating menu data](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/menu-integration.md.txt).

## Food ordering sessions

Food ordering sessions are at the core of Food Ordering AI Agent, enabling
conversational interactions between a customer and the AI agent. Each session
represents a single food ordering conversation and is managed using either the
real-time bidirectional streaming method
([`FoodOrderingService.BidiProcessOrder`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#google.cloud.foodorderingaiagent.v1beta.FoodOrderingService.BidiProcessOrder))
or the turn-based unary request-response method
([`FoodOrderingService.ProcessOrder`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#google.cloud.foodorderingaiagent.v1beta.FoodOrderingService.ProcessOrder)).

### BidiProcessOrder RPC method

This is a bidirectional streaming RPC: the client application streams input to
the agent, and the agent concurrently streams responses back to the client. This
allows for low-latency, real-time multimodal (voice and text) interactions.

- **Client-to-Agent Stream** : The client sends a stream of [`BidiProcessOrderRequest`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#bidiprocessorderrequest) messages containing audio input (customer speech), text input, or event inputs (such as a client-side cart update performed by a customer using a tap interface, or a hardware-detected drive-off event from drive-thru restaurant hardware).
- **Agent-to-Client Stream** : The agent returns a stream of [`BidiProcessOrderResponse`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#bidiprocessorderresponse) messages containing audio output (synthesized agent speech), text output, transcripts of recognized speech, updates to the customer's order state, or other signals such as detected interruptions.

### ProcessOrder RPC and REST method

`ProcessOrder` is a unary request-response method designed for text-based, turn-by-turn food ordering integrations (such as chat widgets, web forms, and REST clients). It is accessible over gRPC and REST (`POST /v1/{config.session=projects/*/locations/*/sessions/*}:processOrder`).

Unlike `BidiProcessOrder`, `ProcessOrder` operates on discrete request-response turns and is text-only:

- **Mode Requirement** : `config.mode` must be explicitly set to `TEXT` (or `2` in JSON).
- **Turn Lifecycle** : `turn_type` should be set to `INITIALIZE` on the initial turn to inject session variables (such as menu and store metadata), and `SUBSEQUENT` on follow-up turns.

### Session lifecycle

Every Session in Food Ordering AI Agent must begin with client-provided configuration
specified using a [`Config`](https://docs.cloud.google.com/gemini-enterprise-cx/commerce-agents/food/reference/rpc/google.cloud.foodorderingaiagent.v1beta.md.txt#config) message. The `Config` specifies:

- `store`: The full resource name of the `Store` for which the order is being placed (e.g. `projects/PROJECT/locations/LOCATION/brands/BRAND/stores/STORE`). The session takes on configuration specified in the referenced `Store` resource and that store's parent `Brand` resource. Where configuration conflicts across the `Brand` and `Store`, the `Store` configuration takes precedence.
- `session`: A unique session identifier in the format `projects/PROJECT/locations/LOCATION/sessions/SESSION`. The `session_id` is a client-generated ID that uniquely identifies one customer interaction or conversation.
- `mode`: The mode of the session (`HYBRID` or `TEXT`). For `BidiProcessOrder`, `mode` is optional and defaults to `HYBRID` (voice and text). For `ProcessOrder` (unary / REST), `mode` **must** be explicitly set to `TEXT`.

> [!TIP]
> **Tip:** If a client disconnects (e.g., due to network issues) and reconnects to `BidiProcessOrder` using the same `session` identifier in the initial `Config` message, the agent resumes the session from its previous state. If a new `session` identifier is provided, the API initiates a new ordering session.