Streaming y herramientas
En esta página
- Streaming con llamada a funciones
- La regla fundamental
- Implementación del streaming con herramientas
- Reconstrucción de llamadas a herramientas en streaming
- Arquitectura para streaming con herramientas
- Latencia y experiencia de usuario
- Eventos enviados por el servidor (SSE) para aplicaciones web
- Puntos clave
Streaming con llamada a funciones
El streaming te permite recibir la respuesta del modelo de forma incremental, token a token. Esto es esencial para crear interfaces de usuario receptivas. Pero, ¿cómo interactúa el streaming con la llamada a funciones?
La regla fundamental
Las llamadas a funciones se devuelven en un único fragmento, no se transmiten de forma progresiva. Esta es una diferencia importante respecto al texto normal, que llega token a token.
En la práctica:
- El texto de la respuesta se transmite de forma progresiva
- Las tool_calls llegan todas juntas en un único evento
Esta restricción existe por una buena razón: una llamada a herramienta debe estar completa (nombre + argumentos JSON válidos) para que puedas ejecutarla. Un JSON parcial sería inutilizable.
Implementación del streaming con herramientas
stream = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools,
stream=True
)
collected_tool_calls = []
collected_content = ""
for chunk in stream:
delta = chunk.choices[0].delta
# Texto transmitido
if delta.content:
collected_content += delta.content
print(delta.content, end="", flush=True)
# Llamadas a herramientas (llegan en un único bloque)
if delta.tool_calls:
for tc in delta.tool_calls:
collected_tool_calls.append(tc)
# Comprobación del final del stream
if chunk.choices[0].finish_reason == "tool_calls":
# El modelo espera resultados de las herramientas
break
elif chunk.choices[0].finish_reason == "stop":
# La respuesta ha terminado, no se ha llamado a ninguna herramienta
break
Reconstrucción de llamadas a herramientas en streaming
En algunos casos, los argumentos de la llamada a la herramienta pueden llegar en varias partes dentro del stream. Necesitas reconstruirlos:
tool_calls_buffer = {}
for chunk in stream:
delta = chunk.choices[0].delta
if delta.tool_calls:
for tc_chunk in delta.tool_calls:
idx = tc_chunk.index
if idx not in tool_calls_buffer:
tool_calls_buffer[idx] = {
"id": tc_chunk.id,
"function": {
"name": tc_chunk.function.name or "",
"arguments": ""
}
}
if tc_chunk.function.name:
tool_calls_buffer[idx]["function"]["name"] = tc_chunk.function.name
if tc_chunk.function.arguments:
tool_calls_buffer[idx]["function"]["arguments"] += tc_chunk.function.arguments
Este enfoque de búfer garantiza que reconstruyas correctamente cada llamada a herramienta, incluso si los datos llegan fragmentados.
Arquitectura para streaming con herramientas
En una aplicación real, necesitas gestionar dos flujos simultáneos:
- Visualización en tiempo real: mostrar el texto a medida que llega
- Acumulación de llamadas a herramientas: recoger las llamadas para su ejecución
async def handle_streaming_response(stream):
content_parts = []
tool_calls = []
current_tool = None
async for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
content_parts.append(delta.content)
yield {"type": "text", "data": delta.content}
if delta.tool_calls:
for tc in delta.tool_calls:
tool_calls.append(tc)
if chunk.choices[0].finish_reason == "tool_calls":
# Ejecutar herramientas y reiniciar
results = await execute_tools(tool_calls)
yield {"type": "tool_results", "data": results}
Latencia y experiencia de usuario
El streaming con herramientas implica pausas naturales en el flujo:
- El usuario formula su pregunta
- El modelo empieza a «pensar» (no hay tokens visibles)
- El modelo decide llamar a una herramienta (recibes la tool_call)
- Pausa — ejecutas la función
- Envías el resultado de vuelta
- El modelo genera su respuesta (transmitida de forma progresiva)
Para la experiencia de usuario, muestra un indicador durante el paso 4:
🔍 Buscando el tiempo en París...
Esto evita que el usuario piense que la aplicación se ha quedado bloqueada.
Eventos enviados por el servidor (SSE) para aplicaciones web
Si estás construyendo una API web, utiliza SSE para retransmitir el stream:
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
@app.get("/chat")
async def chat(message: str):
async def event_stream():
stream = client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": message}],
tools=tools,
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
yield f"data: {chunk.choices[0].delta.content}\n\n"
return StreamingResponse(event_stream(), media_type="text/event-stream")
Puntos clave
- Las llamadas a herramientas llegan en un único fragmento, no se transmiten de forma progresiva
- El texto normal sigue transmitiéndose token a token
- Reconstruye las llamadas a herramientas fragmentadas con un búfer indexado por
index - Gestiona dos flujos en paralelo: visualización de texto + recopilación de llamadas a herramientas
- Muestra un indicador durante la ejecución de la herramienta para mejorar la UX
- Utiliza SSE para aplicaciones web