Guía de migración de Gemini Interactions API: cómo depurar después de cambiar outputs por steps

Sun, 12 Jul 2026 10:33:00 +0800

La API de Gemini Interactions se ha convertido en la interfaz unificada recomendada para nuevos proyectos. Representa una generación, una llamada a una herramienta, un proceso de pensamiento, un resultado de una herramienta y una respuesta final como pasos de ejecución observables, adecuados para Agentes, tareas largas y aplicaciones que necesitan mostrar estados intermedios.

Esto también significa que el código heredado ya no puede asumir outputs en la respuesta. A partir de mayo de 2026, el nuevo esquema será el predeterminado; el esquema anterior se eliminó el 8 de junio. Si hay respuestas vacías, las llamadas a herramientas se pierden, los eventos SSE no se activan o el contexto histórico se rompe después de la migración, generalmente no es un problema del modelo, sino que los datos aún se están leyendo de acuerdo con la estructura anterior.

Primero confirme a qué capa está migrando

Antes de solucionar el problema, primero categorice el problema para evitar cambiar solo un campo:

Jerarquía	Camino antiguo	Nueva manera
Texto final	Recorra `outputs` para buscar texto	Lectura de escena simple `interaction.output_text`
Respuesta completa	Encuentre contenido, herramientas o resultados de búsqueda en `outputs`	Atraviese `interaction.steps`, procese como `type`
Llamada de herramienta	Analizar desde el tipo de contenido antiguo	Pasos del proceso como `function_call`, `function_result`
Transmisión de eventos	`content.start`, `content.delta`, `content.stop`	`step.start`, `step.delta`, `step.stop`
Historia de varias rondas	Devolver el antiguo `outputs`	Utilice `previous_interaction_id` en el servidor o devuelva `steps` en el cliente.

Si el SDK sigue siendo Python 1.x o JavaScript 1.x, primero confirme la versión. Las instrucciones oficiales de migración requieren el uso de Python ≥2.0.0 o JavaScript ≥2.0.0 para adoptar automáticamente el nuevo esquema; pero actualizar el SDK no reparará automáticamente el analizador outputs, el procesador SSE y la máquina de estado frontal que usted mismo escribió.

Solución más sencilla: lea el texto final con `output_text`

Al procesar solo preguntas y respuestas en texto sin formato, no es necesario buscar manualmente el último texto de steps. La nueva versión del SDK proporciona output_text, que extrae y une bloques de texto consecutivos al final de la respuesta:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="用三句话解释什么是 prompt caching。",
)

print(interaction.output_text)

Si deja interaction.outputs[-1].text como está después de la migración, los resultados comunes son que la propiedad no existe, la indexación falla o el objeto se serializa incorrectamente en una cadena vacía. Primero reemplácelo con interaction.output_text y luego agregue el análisis de pasos de escenarios complejos.

output_text no es adecuado para todas las respuestas: cuando el texto está separado por pensamientos, imágenes, audio o llamadas de herramientas, no restaurará todo el contenido entrelazado. Cuando necesite mostrar el proceso de ejecución completo, debe atravesar steps.

Cómo atravesar correctamente `steps`

El nuevo esquema representa los procesos como pasos escritos. Como mínimo, se reconocerán user_input, model_output, function_call y function_result; Si utiliza herramientas del lado del servidor, también verá google_search_call, google_search_result u otros pasos específicos de la herramienta.

El siguiente ejemplo solo recopila texto del resultado final del modelo:

def collect_model_text(interaction):
    chunks = []

    for step in interaction.steps:
        if step.type != "model_output":
            continue

        for item in step.content or []:
            if item.type == "text":
                chunks.append(item.text)

    return "".join(chunks)


print(collect_model_text(interaction))

En proyectos reales, no asuma que content existe para cada paso y no trate a thought como la respuesta final. Primero bifurque según step.type y luego lea los campos permitidos por este tipo. Registre los pasos desconocidos como tipo, ID y estado para preservar la compatibilidad futura; no permita que toda la solicitud falle solo porque aparece un nuevo paso de herramienta.

¿Por qué la herramienta llama “desaparecer”?

Los esquemas más antiguos a menudo envuelven las operaciones de herramientas del lado del servidor en un tipo de contenido específico llamado outputs. El nuevo esquema los divide en pasos independientes, por lo que escanear solo model_output no verá la búsqueda, las llamadas a funciones ni los resultados de las funciones.

Por ejemplo, la llamada a la función se leería así:

for (const step of interaction.steps) {
  if (step.type === 'function_call') {
    console.log(`Calling ${step.name}`);
    console.log(step.arguments);
  }
}

La Búsqueda de Google del lado del servidor también debería manejar los pasos de llamada y resultado por separado, en lugar de adivinar a partir del texto final si se realizó una búsqueda o no. Para las herramientas de función del cliente, después de recibir requires_action, envíe el function_result correspondiente y continúe usando el estado de la interacción para completar el proceso posterior.

Los eventos de streaming SSE se migran juntos

Si solo cambia el análisis de la respuesta REST y no cambia el procesador de flujo, la interfaz generalmente se comportará como “la solicitud se realizó correctamente pero la página no se actualizó”. Los nuevos nombres de los eventos son los siguientes:

Eventos antiguos	Nuevos eventos
`interaction.start`	`interaction.created`
`interaction.complete`	`interaction.completed`
`content.start`	`step.start`
`content.delta`	`step.delta`
`content.stop`	`step.stop`
`interaction.status_update`	`interaction.in_progress`, `interaction.requires_action` y otros eventos de estado

Ya no se garantiza que los parámetros de la llamada a la función lleguen completamente a la vez. En la transmisión, step.start primero proporcionará el nombre de la función y luego se entregarán varios eventos step.delta pieza por pieza con algunos parámetros JSON. El cliente debe acumular parámetros y analizar el JSON completo después de step.stop o un estado que requiera acción; no haga JSON.parse() directamente para cada delta.

let rawArguments = '';

for await (const event of stream) {
  if (event.event_type === 'step.delta' && event.delta?.type === 'arguments') {
    rawArguments += event.delta.partial_arguments;
  }

  if (event.event_type === 'step.stop') {
    // 只在对应 function_call 步骤完成后解析 rawArguments。
  }
}

No responder después de varias rondas de diálogo `outputs`

La antigua implementación sin estado a menudo recopila la ronda anterior de outputs y la vuelve a incluir en la siguiente ronda de input. Hay dos opciones más claras después de la migración:

Continúe la misma sesión a través de previous_interaction_id usando el estado predeterminado del lado del servidor;
Cuando deba administrar el historial usted mismo, regrese la ronda anterior de steps y agregue un nuevo paso user_input.

El estado del lado del servidor es más adecuado para conversaciones ordinarias de varias rondas; El estado del lado del cliente se utiliza cuando se requiere un control estricto del contenido guardado, la migración entre sistemas o la reproducción sin conexión. No importa cuál elija, no empalme el antiguo outputs y el nuevo steps al mismo tiempo; de lo contrario, es fácil producir contextos duplicados, discrepancias en los resultados de las herramientas o proliferación de tokens.

`response_format` también puede ser la fuente del error

Esta migración no solo cambia la matriz de salida. La salida estructurada y la configuración multimodal también se unifican en el response_format de nivel superior:

Se ha eliminado el response_mime_type original; especifique mime_type en la entrada response_format.
El esquema JSON debe colocarse en un objeto de formato con type: "text".
La configuración de imagen se movió de generation_config a la entrada response_format en type: "image".
La salida multimodal requiere una serie de entradas de formato.

Si la interfaz devuelve 400, además de buscar steps, también se busca en el código response_mime_type, generation_config.image_config y el objeto único heredado response_format. Estos campos antiguos suelen aparecer junto con el problema outputs después de la misma actualización.

Un procedimiento práctico de resolución de problemas

Actualice el SDK de Google GenAI y documente la versión real.
Verifique interaction.output_text con una solicitud mínima sin herramientas y sin transmisión.
Imprima el tipo y el estado de interaction.steps para confirmar que el programa ha recibido el nuevo esquema.
Migre la lógica de análisis de llamadas a funciones, búsquedas del lado del servidor y resultados de herramientas, respectivamente.
Modifique la suscripción de eventos SSE y la lógica de acumulación de parámetros.
Compruebe si el historial de rondas múltiples ha cambiado a previous_interaction_id o steps.
Busque y reemplace los antiguos campos relacionados con response_format.
Ejecute pruebas de regresión, una con texto, llamadas a herramientas, salida de transmisión y reintentos fallidos.

No confíe en el antiguo encabezado Api-Revision para restaurar temporalmente el código antiguo. El período de transición del antiguo esquema ha terminado; La migración ahora debería considerarse una solución de compatibilidad oficial, en lugar de seguir teniendo dos conjuntos de analizadores inconsistentes.

Resumen

La esencia de cambiar outputs a steps es que la API de Interacciones ya no agrupa todos los procesos en una lista de salida, sino que expone explícitamente entradas, reflexiones, herramientas, resultados y salidas finales. Las escenas de texto puro utilizan preferentemente interaction.output_text; Agentes, herramientas, streaming y escenas multimodales utilizan step.type para establecer ramas explícitas; Las sesiones de varias rondas utilizan previous_interaction_id o steps en su lugar. Al migrar de acuerdo con estos tres principios, se pueden localizar la mayoría de los problemas de “no hay salida”, “falta herramienta” y “SSE no se actualiza”.

Información oficial:

Gemini API on KnightLi Blog