Crea una experiencia de pedidos multimodal con la API de transmisión

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:

  1. 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_ID

  2. Autenticació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.

  3. 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 BidiProcessOrder es 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"

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:

  1. 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.).
  2. 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").
  3. 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 permisohttps://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.
  4. Token al cliente: Tu servicio de backend devuelve el token de acceso de Google generado a la app cliente.

  5. 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:

  1. Crea un canal de gRPC para el extremo de API del agente de IA para Pedidos de comida (p.ej., foodorderingaiagent.googleapis.com).
  2. Obtén un stub de cliente para FoodOrderingService.
  3. Invoca el método BidiProcessOrder, que devuelve un objeto de transmisión para enviar solicitudes y recibir respuestas.
  4. 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

Encabezados obligatorios:

  • Authorization: Bearer TOKEN, en el que TOKEN es 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 proto BidiProcessOrderRequest, que se envían como websocket.TextMessage.
  • Del servidor al cliente: Los mensajes que se reciban de la API (BidiProcessOrderResponse) se enviarán como websocket.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., customerAudio en AudioInput, agentAudio en AgentAudio) 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 BidiProcessOrderRequest que contenga el mensaje Config.
  • 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 de Store. Formato: projects/PROJECT/locations/LOCATION/brands/BRAND/stores/STORE.
      • El agente usa el store para cargar el menú y la configuración adecuados.
    • mode (opcional para BidiProcessOrder): El valor predeterminado es HYBRID (voz y texto). Ten en cuenta que, si usas la API unaria de REST o gRPC ProcessOrder en lugar de BidiProcessOrder, mode debe establecerse de forma explícita en TEXT.

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 Config inicial, el cliente puede enviar un flujo de mensajes BidiProcessOrderRequest que 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, como DriveOffEvent (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) o OrderStateUpdateEvent (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 campo oneof 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 la Order del 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 cualquier AgentAudio saliente.
    • AgentEvent: Son eventos especiales, como RestartOrder, 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_audio no puede superar los 25,600 bytes (800 ms) por mensaje. Con enable_echo_cancellation habilitado, el servidor rellena y entrelaza customer_audio y crew_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_cancellation en Config), proporciona customer_audio y crew_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 Order recibido.
  • Usa el custom_integration_attributes dentro de los elementos y modificadores de Order para asignar el contenido de Order a entidades equivalentes dentro del sistema de registro de tu aplicación.

InterruptionSignal

  • Cuando lo recibas, detén de inmediato la reproducción de cualquier AgentAudio y 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_ESCALATION o 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 Config inicial 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 AgentAudio y una entrega oportuna de AudioInput. 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)

  1. La app cliente (p.ej., una app para dispositivos móviles) inicia un pedido.
  2. Establece una conexión de gRPC/WebSocket con BidiProcessOrder.
  3. Envía BidiProcessOrderRequest con Config (ID de sesión, ID de tienda).
  4. Recibe el AgentAudio inicial (p.ej., un mensaje de bienvenida) y reprodúcelo.
  5. El usuario habla: Captura el audio y transmítelo en mensajes AudioInput.
  6. Recibe SpeechRecognition (mostrar transcripción), AgentAudio (reproducir respuesta) y, posiblemente, UpdatedOrderState (actualizar el carrito de la IU).
  7. Si el usuario interrumpe, recibe InterruptionSignal y detiene la reproducción.
  8. Continúa con el intercambio de entradas de audio o texto y respuestas del agente.
  9. El usuario confirma el pedido: El agente envía el UpdatedOrderState final.
  10. El agente envía EndSession: El cliente cierra la transmisión y finaliza el pedido en el sistema de PdV con los datos del último UpdatedOrderState.

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.'}});
}