En esta guía, se proporcionan instrucciones y prácticas recomendadas para los ingenieros que crean experiencias de pedidos de comida con el método RPC FoodOrderingService.BidiProcessOrder.
Esta API de transmisión bidireccional en tiempo real es el núcleo del agente de IA de pedidos de comida,
lo que permite tomar pedidos de forma dinámica y conversacional en varias aplicaciones, como
apps para dispositivos móviles, asistentes de voz, autoservicios y kioscos.
Descripción general de BidiProcessOrder
El método BidiProcessOrder establece un canal de comunicación bidireccional persistente entre tu aplicación cliente y el agente de IA de Pedidos de comida. A diferencia de
las RPC de solicitud y respuesta unarias estándar, este enfoque de transmisión permite lo siguiente:
- Interacción de baja latencia: Intercambio continuo de información sin la sobrecarga de solicitudes HTTP repetidas.
- Entrada multimodal: Control de transmisiones de audio (para pedidos por voz), entradas de texto y eventos del cliente.
- Respuestas en tiempo real: El agente puede enviar audio, texto, actualizaciones de pedidos y otros indicadores a medida que se desarrolla la conversación.
BidiProcessOrder no se puede invocar con REST. Las integraciones deben usar un
protocolo orientado a la conexión:
- gRPC (recomendado): Proporciona un framework sólido y eficiente para la transmisión bidireccional.
- WebSocket: Es adecuado para clientes o entornos en los que gRPC no es apropiado debido a restricciones de lenguaje de programación o de red.
Consulta la referencia de la API de BidiProcessOrder para obtener definiciones de tipos detalladas. Las integraciones de WebSocket usan representaciones JSON de estos tipos, como se describe en la sección de WebSocket.
Requisitos previos
Antes de realizar la integración con BidiProcessOrder, haz lo siguiente:
Habilita la API: Asegúrate de que la API del agente de IA de Pedidos de comida esté habilitada en tu proyecto de Google Cloud.
bash gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT_IDAutenticación: Decide tu enfoque de autenticación y configura las cuentas de servicio y los roles de IAM necesarios, como se describe en Autenticación.
Transferencia de menú: Se debe transferir un menú válido y asociarlo con un
Store. Consulta Cómo integrar datos de menú para obtener más detalles.
Autenticación
Para conectarte de forma segura a la RPC de BidiProcessOrder, tu aplicación debe
autenticarse con una cuenta de servicio de Google Cloud .
1. Configura una cuenta de servicio
- Crea una cuenta de servicio: En tu proyecto de Google Cloud , crea una cuenta de servicio que tu aplicación usará para autenticarse en la API de Food Ordering AI Agent. Consulta Crea y administra cuentas de servicio.
Otorga roles de IAM: Otorga los roles de IAM necesarios a esta cuenta de servicio. El rol principal necesario para llamar a
BidiProcessOrderes el siguiente:- Usuario del agente de pedidos de comida (
roles/foodorderingaiagent.agentUser): Permite que la cuenta de servicio se conecte al servicio de pedidos y procese las sesiones.
Puedes otorgar este rol con la consola de Google Cloud o
gcloud:bash gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ --role="roles/foodorderingaiagent.agentUser"- Usuario del agente de pedidos de comida (
2. Flujo de autenticación de la aplicación
El flujo de autenticación exacto depende de la arquitectura de tu aplicación, en especial, de si la aplicación cliente (p.ej., app para dispositivos móviles, software de kiosco) se conecta directamente o a través de tu propio backend.
Situación común: Autentica una aplicación cliente para el consumidor
Este es un patrón típico para las aplicaciones web o para dispositivos móviles:
- Client-to-YourAuth: La app cliente del usuario final (dispositivo móvil, Web) se autentica con tu sistema de autenticación de usuarios existente (puede ser Firebase Authentication, tu propio servidor de OAuth, etc.).
- Intercambio de tokens: La app cliente, después de autenticar al usuario, solicita un token de corta duración de un servicio de backend seguro que tú controlas (p.ej., un "Servicio de tokens de API").
Generación de tokens de acceso: Tu servicio de backend, con las credenciales de la principal de la cuenta de servicio de Google Cloud configurada en el paso 1, genera un token de acceso de OAuth 2.0 estándar para el permiso
https://www.googleapis.com/auth/cloud-platform. Esto se puede hacer con las bibliotecas cliente de autenticación de Google Cloud .- Seguridad: Las claves o credenciales de la cuenta de servicio que se usan para generar estos tokens se deben almacenar y administrar de forma segura en tu backend. Nunca expongas las claves privadas de las cuentas de servicio directamente a las aplicaciones cliente de los usuarios finales. Consulta las prácticas recomendadas para administrar claves de cuenta de servicio.
Token al cliente: Tu servicio de backend devuelve el token de acceso de Google generado a la app cliente.
Llamada a la API: La app cliente usa este token de acceso de Google para autenticar su conexión de gRPC o WebSocket a la RPC de
BidiProcessOrder.
3. Cómo usar el token
- gRPC: Por lo general, las bibliotecas cliente de gRPC de Google controlan la actualización y la inclusión de tokens en los metadatos de la llamada cuando se proporcionan las credenciales de la cuenta de servicio.
- WebSocket (sin navegador): Incluye el token en el encabezado
Authorization: Bearer TOKEN. - WebSocket (navegador): Como se indica en la sección de WebSocket, las conexiones directas de WebSocket del navegador no pueden usar encabezados de autorización. Se necesita un proxy de transmisión del servidor para autenticar la conexión de tus clientes a Google Cloud.
Conéctate a la API
Puedes establecer una transmisión con las bibliotecas cliente de gRPC o una conexión de WebSocket.
gRPC
Se recomienda usar gRPC. Usarás las bibliotecas cliente para el lenguaje que elijas (p.ej., Node.js), que se basan en la referencia de la API de BidiProcessOrder.
Los pasos básicos son los siguientes:
- Crea un canal de gRPC para el extremo de API del agente de IA para Pedidos de comida (p.ej.,
foodorderingaiagent.googleapis.com). - Obtén un stub de cliente para
FoodOrderingService. - Invoca el método
BidiProcessOrder, que devuelve un objeto de transmisión para enviar solicitudes y recibir respuestas. - Implementa la lógica empresarial según tu caso de uso, que, de forma simultánea, hace lo siguiente:
- Envía entradas de audio, texto y eventos del usuario final.
- Controla los mensajes del agente, incluidos el audio, el texto y los eventos.
Node.js
const {FoodOrderingServiceClient} = require('@google-cloud/foodorderingaiagent');
const client = new FoodOrderingServiceClient();
// The stream is initialized immediately. You can now write commands and attach listeners.
const stream = client.bidiProcessOrder();
WebSocket
Para las conexiones de WebSocket, la ruta de URL es la siguiente:
wss://foodorderingaiagent.googleapis.com/ws/google.cloud.foodorderingaiagent.v1beta.FoodOrderingService/BidiProcessOrder/locations/LOCATION
LOCATION: Es la ubicación de tu tienda y su menú, por ejemplo,us. Usa la misma ubicación en los campossessionystoredel mensajeConfig. Para conocer las ubicaciones admitidas, consulta Ubicaciones del agente de IA de Pedidos de comida.
Encabezados obligatorios:
Authorization:Bearer TOKEN, en el queTOKENes un token de acceso de OAuth 2.0 obtenido para tu cuenta de servicio.
Formato del mensaje:
- Del cliente al servidor: Los mensajes que se envían a la API (p.ej.,
Config,AudioInput,TextInput,EventInput) deben ser representaciones JSON del protoBidiProcessOrderRequest, que se envían comowebsocket.TextMessage. - Del servidor al cliente: Los mensajes que se reciban de la API
(
BidiProcessOrderResponse) se enviarán comowebsocket.BinaryMessage, pero el contenido de estos mensajes binarios es una carga útil de JSON. - Datos binarios: Los datos binarios dentro de las cargas útiles de JSON (p.ej.,
customerAudioenAudioInput,agentAudioenAgentAudio) deben estar codificados en Base64.
Ejemplo de WebSocket de Node.js
Este es un ejemplo de cómo conectarse e interactuar con la API usando WebSockets
en Node.js con la biblioteca ws:
const WebSocket = require('ws');
// Replace with your actual values
const location = 'LOCATION';
const projectId = 'PROJECT_ID';
const sessionId = 'SESSION_ID';
const brandId = 'BRAND_ID';
const storeId = 'STORE_ID';
const token = 'OAUTH_TOKEN';
const wsUrl = `wss://foodorderingaiagent.googleapis.com/ws/google.cloud.foodorderingaiagent.v1beta.FoodOrderingService/BidiProcessOrder/locations/${location}`;
const ws = new WebSocket(wsUrl, {
headers: {
'Authorization': `Bearer ${token}`
}
});
ws.on('open', () => {
console.log('Connected to WebSocket');
// 1. Send the required initial Config message
const configRequest = {
config: {
session: `projects/${projectId}/locations/${location}/sessions/${sessionId}`,
store: `projects/${projectId}/locations/${location}/brands/${brandId}/stores/${storeId}`
}
};
// Client-to-server messages are sent as TextMessage
ws.send(JSON.stringify(configRequest));
console.log('Sent Config message');
});
ws.on('message', (data, isBinary) => {
// The documentation specifies that server-to-client messages
// are sent as BinaryMessage containing a JSON payload.
if (isBinary) {
try {
const response = JSON.parse(data.toString('utf8'));
console.log('Received response:', response);
if (response.agentText) {
console.log(`Agent: ${response.agentText.text}`);
}
if (response.agentAudio) {
const audioBytes = Buffer.from(response.agentAudio.agentAudio, 'base64');
console.log(`Received ${audioBytes.length} bytes of agent audio.`);
// Play or process the audio bytes here
}
if (response.endSession) {
console.log('Session ended by agent.');
ws.close();
}
} catch (e) {
console.error('Failed to parse JSON response:', e);
}
}
});
ws.on('close', () => {
console.log('Connection closed');
});
Ciclo de vida de la sesión
Cada llamada a BidiProcessOrder inicia una sesión. La sesión permanece activa
mientras la transmisión esté abierta.
1. Iniciación (mensaje de configuración)
- Cuando se establece la conexión, el primer mensaje que envía el cliente
debe ser un
BidiProcessOrderRequestque contenga el mensajeConfig. - Campos obligatorios en
Config:session: Es un identificador de sesión único generado por el cliente. Formato:projects/PROJECT/locations/LOCATION/sessions/SESSION_ID.store: Es el nombre del recurso deStore. Formato:projects/PROJECT/locations/LOCATION/brands/BRAND/stores/STORE.- El agente usa el
storepara cargar el menú y la configuración adecuados.
- El agente usa el
mode(opcional paraBidiProcessOrder): El valor predeterminado esHYBRID(voz y texto). Ten en cuenta que, si usas la API unaria de REST o gRPCProcessOrderen lugar deBidiProcessOrder,modedebe establecerse de forma explícita enTEXT.
Node.js
// Send the first message containing Config
stream.write({
config: {
session: client.sessionPath(projectId, location, sessionId),
store: client.storePath(projectId, location, brandId, storeId),
}
});
2. Envía entradas
- Después del
Configinicial, el cliente puede enviar un flujo de mensajesBidiProcessOrderRequestque contengan una de las siguientes entradas:AudioInput: Son datos de audio sin procesar (por lo general, PCM lineal de 16 bits a 16,000 Hz, sin encabezados). Se usa para las interacciones por voz.TextInput: Son los mensajes de texto del usuario.EventInput: Son indicadores de eventos, comoDriveOffEvent(para casos de uso de autoservicio cuando el vehículo se va),CrewInterjectionEvent(para cualquier situación en la que una persona asume el rol de tomar el pedido a mitad de la conversación) oOrderStateUpdateEvent(si el pedido se modifica en el cliente, p.ej., con una interfaz táctil).
Node.js
// Stream user inputs over the active connection
stream.write({textInput: {text: 'Hi, I\'d like to order a cheeseburger.'}});
3. Recibe respuestas
- Al mismo tiempo, el agente devuelve un flujo de mensajes de
BidiProcessOrderResponse. Tu cliente debe estar preparado para controlar varios tipos de respuesta dentro del campooneof response:AgentAudio: Son los bytes de audio sintetizados que se reproducirán para el usuario y que se usan en las interacciones por voz.AgentText: Es la versión de texto de la respuesta del agente.SpeechRecognition: Es la transcripción de la voz del usuario reconocida.UpdatedOrderState: Contiene el estado actual completo de laOrderdel cliente cada vez que el agente la actualiza. Usa esta información para actualizar la representación del pedido de tu aplicación. Por lo general, esto debería dar como resultado una actualización de una interfaz de usuario o un sistema de registro para la información del estado del pedido, como un sistema de punto de venta.InterruptionSignal: Indica que el usuario interrumpió el discurso del agente. El cliente debe detener de inmediato la reproducción de cualquierAgentAudiosaliente.AgentEvent: Son eventos especiales, comoRestartOrder, que requieren una acción del cliente.SuggestedOptions: Proporciona opciones contextualmente relevantes que un usuario podría seleccionar a continuación, lo que resulta útil para mostrar en una pantalla.EndSession: Indica que el agente finalizó la sesión (p.ej., pedido completado, salida del usuario o derivación del agente).
Node.js
// Attach event listeners to handle responses sequentially
stream.on('data', (response) => {
if (response.agentAudio) {
console.log(`Received ${response.agentAudio.agentAudio.length} bytes of agent audio.`);
} else if (response.agentText) {
console.log(`Agent: ${response.agentText.text}`);
} else if (response.speechRecognition) {
console.log(`Recognized User Speech: ${response.speechRecognition.transcript}`);
} else if (response.updatedOrderState) {
console.log('Order updated.');
} else if (response.interruptionSignal) {
console.log('User interrupted the agent. Stop playing audio!');
} else if (response.endSession) {
console.log(`Session ended. Type: ${response.endSession.type}, Reason: ${response.endSession.reason}`);
stream.end();
}
});
stream.on('error', (err) => {
console.error('Stream error:', err);
});
4. Cómo cerrar la transmisión
- El cliente o el servidor pueden cerrar la transmisión. Por lo general, el servidor
indica el final de una conversación con un mensaje
EndSession. El cliente debe cerrar la transmisión cuando se reciba este mensaje.
Cómo controlar tipos de mensajes específicos
En las siguientes secciones, se describe cómo controlar los tipos de respuesta específicos que recibirá tu cliente cuando llame a BidiProcessOrder.
AudioInput
- Transmite audio en fragmentos a medida que esté disponible. Envía fragmentos de 160 a 256 ms
(de 5,120 a 8,192 bytes por transmisión, como 200 ms o 6,400 bytes). Los fragmentos muy pequeños (de 20 a 100 ms) aumentan la sobrecarga de encuadre y pueden provocar que se pierda el discurso en caso de inestabilidad de la red. Sin la cancelación de eco,
customer_audiono puede superar los 25,600 bytes (800 ms) por mensaje. Conenable_echo_cancellationhabilitado, el servidor rellena y entrelazacustomer_audioycrew_audio, por lo que ningún canal puede superar los 12,800 bytes (400 ms) por mensaje. - Formato: PCM lineal mono con formato little-endian de 16 bits con signo y una tasa de muestreo de 16,000 Hz.
- Los fragmentos de audio no incluyen los encabezados de audio que suelen preceder a un archivo WAV.
- Durante los períodos de silencio, sigue transmitiendo fotogramas de silencio de PCM con ceros en tu
cadencia normal de 160 a 256 ms. Los fotogramas de silencio continuo permiten que la detección de actividad de voz
finalice el turno y evite el tiempo de espera de inactividad de 30 segundos.
No cambies a keepalives dispersos justo después de que termine la voz, o el turno puede
detenerse o interrumpirse. Si pausas la captura entre turnos completados (o después de
2 segundos de silencio), envía un fotograma de 3,200 a 6,400 bytes relleno de ceros al menos
cada 5 segundos. Los fotogramas silenciosos no restablecen el tiempo de espera de 120 segundos sin voz,
lo que cierra la transmisión con el código
1007(handle CES message). - Para situaciones de autoservicio con la cancelación de eco habilitada
(
enable_echo_cancellationenConfig), proporcionacustomer_audioycrew_audio.
UpdatedOrderState
- Este mensaje proporciona el estado completo del pedido cada vez que se envía.
Reemplaza cualquier caché local del pedido por el contenido del mensaje
Orderrecibido. - Usa el
custom_integration_attributesdentro de los elementos y modificadores deOrderpara asignar el contenido deOrdera entidades equivalentes dentro del sistema de registro de tu aplicación.
InterruptionSignal
- Cuando lo recibas, detén de inmediato la reproducción de cualquier
AgentAudioy borra cualquier audio del agente almacenado en búfer. Esto garantiza un flujo de conversación natural cuando el usuario interrumpe el discurso del agente.
EndSession
- Verifica el
EndType(p.ej.,DRIVE_OFF,AGENT_ESCALATION). - Tu aplicación debería cerrar la conexión de forma correcta y realizar la transición del usuario de manera adecuada (p.ej., notificar a un supervisor humano en el caso de
AGENT_ESCALATIONo realizar la transición a un estado de confirmación del pedido).
Prácticas recomendadas
- Controla los mensajes de forma asíncrona: Minimiza la latencia con subprocesos o E/S sin bloqueo para enviar solicitudes y procesar respuestas entrantes de forma simultánea.
- Lógica de reconexión: Implementa una lógica de reconexión sólida en caso de
problemas de red y recuerda enviar el mensaje
Configinicial con el mismo ID de sesión para intentar reanudarla. - Manejo de errores: Supervisa la transmisión para detectar errores. Las bibliotecas de gRPC y WebSocket proporcionan mecanismos para detectar el cierre de la transmisión o los errores de transporte. Registra estos eventos y contrólalos de forma correcta. Para conocer los errores que devuelve la API y cómo resolverlos, consulta Errores de la API de transmisión.
- Almacenamiento en búfer de audio: Administra los búferes de audio con cuidado y, si es necesario, implementa el almacenamiento en búfer para garantizar una reproducción fluida de
AgentAudioy una entrega oportuna deAudioInput. Considera con cuidado la compensación entre la latencia y la calidad de reproducción cuando decidas tu esquema de almacenamiento en búfer. - Administración de IDs de sesión: Asegúrate de que los IDs de sesión sean únicos para cada pedido o conversación distintos.
- Administración de recursos: Cierra las transmisiones y libera los recursos cuando se complete la sesión o si se producen errores irrecuperables.
- Tiempos de espera: Si bien la transmisión en sí puede ser de larga duración (hasta 15 minutos de forma predeterminada), considera los tiempos de espera a nivel de la aplicación para estados específicos si es necesario.
Ejemplo de flujo de integración (conceptual)
- La app cliente (p.ej., una app para dispositivos móviles) inicia un pedido.
- Establece una conexión de gRPC/WebSocket con
BidiProcessOrder. - Envía
BidiProcessOrderRequestconConfig(ID de sesión, ID de tienda). - Recibe el
AgentAudioinicial (p.ej., un mensaje de bienvenida) y reprodúcelo. - El usuario habla: Captura el audio y transmítelo en mensajes
AudioInput. - Recibe
SpeechRecognition(mostrar transcripción),AgentAudio(reproducir respuesta) y, posiblemente,UpdatedOrderState(actualizar el carrito de la IU). - Si el usuario interrumpe, recibe
InterruptionSignaly detiene la reproducción. - Continúa con el intercambio de entradas de audio o texto y respuestas del agente.
- El usuario confirma el pedido: El agente envía el
UpdatedOrderStatefinal. - El agente envía
EndSession: El cliente cierra la transmisión y finaliza el pedido en el sistema de PdV con los datos del últimoUpdatedOrderState.
Ejemplo de extremo a extremo
Si bien las instrucciones anteriores desglosan los conceptos de transmisión paso a paso, aquí se muestra cómo se ve un flujo de integración completo de extremo a extremo.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido del agente de IA de Pedidos de comida con bibliotecas cliente.
Para autenticarte en el agente de IA de Pedidos de comida, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
const {FoodOrderingServiceClient} = require('@google-cloud/foodorderingaiagent');
async function bidiProcessOrderSample(projectId, location, brand, store, sessionId) {
const client = new FoodOrderingServiceClient();
// Create the resource names
const sessionPath = client.sessionPath(projectId, location, sessionId);
const storePath = client.storePath(projectId, location, brand, store);
// Initialize the stream using gRPC. See the WebSocket section for the equivalent WebSocket implementation.
const stream = client.bidiProcessOrder();
// Attach event listeners to handle responses sequentially
stream.on('data', (response) => {
if (response.agentAudio) {
console.log(`Received ${response.agentAudio.agentAudio.length} bytes of agent audio.`);
} else if (response.agentText) {
console.log(`Agent: ${response.agentText.text}`);
} else if (response.speechRecognition) {
console.log(`Recognized User Speech: ${response.speechRecognition.transcript}`);
} else if (response.updatedOrderState) {
console.log('Order updated.');
} else if (response.interruptionSignal) {
console.log('User interrupted the agent. Stop playing audio!');
} else if (response.endSession) {
console.log(`Session ended. Type: ${response.endSession.type}, Reason: ${response.endSession.reason}`);
stream.end();
}
});
stream.on('error', (err) => {
console.error('Stream error:', err);
});
// 1. Send the first message containing Config
stream.write({
config: {
session: sessionPath,
store: storePath,
}
});
// 2. Stream user inputs over the active connection
stream.write({textInput: {text: 'Hi, I\'d like to order a cheeseburger.'}});
}