Notas prácticas: Lo que aprendí al enviar un agente de IA de producción con Google
Guía paso a paso práctica: Lo que aprendí sobre el envío de un agente de IA de producción con Google, incluyendo contratos, verificaciones y espacios para código listo para usar destinados a los equipos que implementan este patrón.
Úselo como una versión reestructurada dirigida a los operadores de las ideas presentadas en “Lo que aprendí al enviar un agente de IA de producción con la función de llamadas Gemini de Google”: etapas claras, espacios ordenados para el código y notas de recuperación que perduran tras la transferencia de tareas. La etapa de Resumen funciona mejor si se considera como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas.
1. Declaraciones de función: Considérelas como un contrato API con el modelo
En la etapa de definición de las declaraciones de función para una sola función, se deben establecer las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se deben registrar los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el flujo pasa de entornos de demostración a entornos compartidos. Se debe separar la construcción del cliente del bucle de mensajes para que sea posible cambiar a proveedores sin tener que reescribir la máquina de estados de la conversación.
// ❌ Vague — model won’t know when to use it
{ name: ‘get_data’, description: ‘Gets data about a location.’ }
// ✅ Trigger-specific — model knows exactly when this is relevant
{
name: ‘find_backup_spots’,
description: ‘Finds nearby indoor/covered alternatives within walking distance ‘
+ ‘if the venue is crowded or weather turns.’,
}
{
name: ‘calculate_transit_route’,
description: ‘Calculates precise walking/driving/transit travel times to the venue.’,
parameters: {
type: ‘OBJECT’,
properties: {}, // No parameters — dispatcher injects from context
},
}
2. El bucle de herramientas de múltiples turnos: una máquina de estados, no una sola llamada
Para la etapa 2 de La Herramienta Multironda, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Separe la construcción del cliente del bucle de mensajes para que sea posible cambiar los proveedores sin tener que reescribir la máquina de estados de la conversación.
Turn 0: [user prompt + system instructions]
→ Model returns: functionCall { name: “tool_a”, args: {…} }
Turn 1: [user prompt, model’s functionCall, your functionResponse for tool_a]
→ Model returns: text response (synthesized from tool_a’s output)
Turn 0: [user prompt]
→ Model returns: functionCall { name: “tool_a”, args: {…} }
Turn 1: [user prompt, functionCall_a, functionResponse_a]
→ Model returns: functionCall { name: “tool_b”, args: {…} }
Turn 2: [user prompt, functionCall_a, functionResponse_a, functionCall_b, functionResponse_b]
→ Model returns: final text (synthesized from both tools)
3. Modelado en cascada: No se limite a un único modelo
Para la etapa 3 Model Cascading Don, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Separe la construcción del cliente del bucle de mensajes para que sea posible cambiar los proveedores sin tener que reescribir la máquina de estados de la conversación. Para la etapa 3 Model Cascading Don, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
Primary: gemini-3.5-flash-lite (fastest, cheapest, zero-thinking overhead)
Secondary: gemini-3.1-flash-lite (slightly older, same tier)
Tertiary: gemini-2.5-flash (thinking-capable, higher quality)
4. Arquitectura de la clave API: El patrón proxy
Al trabajar en las 4 etapas de la arquitectura de la clave API, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de los tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el entorno pasa de la versión de demostración a entornos compartidos. Registre el ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese registro, los errores intermitentes del proveedor parecen bugs de la aplicación.
La solución: un proxy del lado del servidor
Al trabajar en la etapa “The Solution A Server-Side”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el código. Registre el ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese registro, los errores intermitentes del proveedor parecen ser bugs de la aplicación.
const res = await Promise.race([
proxyCallable({ model: modelName, body: requestBody }),
new Promise((_, reject) =>
setTimeout(() => reject(new Error(‘AI proxy timeout’)), 15000)
),
]);
5. Compresión de contexto: Lo que le proporciona al modelo es más importante que el modelo que utilice
Al trabajar en la etapa de “5 Context Compression What”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta de éxito como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente. Registre el ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese registro, los errores intermitentes del proveedor parecen bugs de la aplicación. Al trabajar en la etapa de “5 Context Compression What”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas.
[CONTEXT]
Category: Coffee
Date: Saturday, Aug 30, 2026
Time: 10:00 AM — 11:30 AM (90 mins)
Group Size: 4/8 participants
User Role: Attendee
Country: AU
Currency: AUD
[END CONTEXT]
6. Diseño de agente con prioridad a modo offline: la solución determinista
La etapa 6 del diseño de agente con prioridad a modo offline funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Fije el intérprete y el archivo de bloqueo de dependencias antes de enseñar el bucle. La diferencia entre la computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de API.
7. Ajuste de generationConfig
La etapa de ajuste de configuration de la 7ª generación funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Fije el intérprete y el archivo de bloqueo de dependencias antes de enseñar el bucle. La diferencia entre la computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de API.
{
“responseMimeType”: “application/json”,
“temperature”: 0.4,
“maxOutputTokens”: 600
}
{
“temperature”: 0.7,
“maxOutputTokens”: 700
}
8. Ingeniería de prompts del sistema para el uso de herramientas
La etapa 8 de Ingeniería de Prompts del Sistema funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Fije el intérprete y el archivo de bloqueo de dependencias antes de enseñar el bucle. La diferencia entre la computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de API. La etapa 8 de Ingeniería de Prompts del Sistema funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas.
You have access to autonomous action tools. When users ask for rides,
ALWAYS call request_rideshare. When users ask to book a table,
ALWAYS call reserve_table. When users ask about cultural norms,
ALWAYS call get_cultural_etiquette.
NO RAW MARKDOWN HEADINGS: Never use ‘#’. Use **Bold Text** for headers.
NO ASTERISKS FOR BULLETS: Use clean unicode bullet points (• ).
CONCISE: Jump straight to the answer. No filler introductions.
9. Lecciones aprendidas
En la fase de las 9 lecciones aprendidas, defina los datos de entrada, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Separe la construcción del cliente del bucle de mensajes para que sea posible cambiar los proveedores sin tener que reescribir la máquina de estados de la conversación.
Lista de verificación operativa
Al trabajar en la fase de la lista de verificación operativa, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista garantiza que los cambios posteriores en el código se realicen de manera transparente.
Preferir unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado.
Registre el ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese registro, los errores intermitentes del proveedor parecen bugs de la aplicación.
Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Agregue una prueba básica que ejecute la ruta crítica en CI con fixtures, y no con APIs pagadas en tiempo real, siempre que lo permitan los presupuestos.
Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.
Nota por lotes para 0ead08720324: mantenga las claves del proveedor fuera del repositorio, establezca un límite máximo para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: Google acaba de construir un agente AI que nunca se retira — Guía paso a paso de Notas prácticas: Google acaba de construir un agente AI que nunca se retira: contratos, verificaciones y espacios de código listos para usar para los equipos que implementan este patrón.