Combinación de herramientas de servidor y cliente
En esta página
Flujos de trabajo híbridos
El verdadero potencial de la API de Responses surge al combinar herramientas de servidor (ejecutadas automáticamente por xAI) y herramientas de cliente (tus funciones personalizadas) en una única solicitud. El modelo orquesta estas herramientas de forma autónoma, creando flujos de trabajo complejos con apenas unas líneas de código.
Combinación de herramientas de servidor y funciones
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Search for the latest Ligue 1 soccer results and send a summary to my team.",
tools=[
{"type": "web_search"},
{
"type": "function",
"name": "send_team_message",
"description": "Sends a message to the team via Slack",
"parameters": {
"type": "object",
"properties": {
"channel": {"type": "string"},
"message": {"type": "string"}
},
"required": ["channel", "message"]
}
}
]
)
En este escenario, el modelo:
- Activa
web_searchautomáticamente (lado del servidor) para encontrar los resultados. - Incorpora los datos en un resumen.
- Llama a
send_team_message(lado del cliente) para que tu código envíe el mensaje de Slack.
El flujo de ejecución híbrido
El flujo varía según el tipo de herramienta:
Solo herramientas de servidor
Request → [model → web_search → result → model] → Final response
Todo ocurre en el lado de xAI. Recibes la respuesta final directamente con los resultados integrados.
Solo herramientas de cliente
Request → [model → function_call] → PAUSE
Your code executes the function
Result → [model] → Final response
El modelo se pausa, tu código se ejecuta y, a continuación, envías el resultado de vuelta.
Flujo híbrido
Request → [model → web_search → result → model → function_call] → PAUSE
Your code executes the function
Result → [model] → Final response
El modelo utiliza primero las herramientas de servidor (automáticamente) y luego llama a tu función cuando necesita tu infraestructura.
Patrones de combinación habituales
Búsqueda + Acción
Combina web_search o x_search con una función de acción:
tools = [
{"type": "web_search"},
{"type": "x_search"},
{
"type": "function",
"name": "create_report",
"description": "Creates a report in the CRM",
"parameters": {
"type": "object",
"properties": {
"title": {"type": "string"},
"content": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
},
"required": ["title", "content"]
}
}
]
Cálculo + Notificación
Combina code_interpreter con una función de notificación:
tools = [
{"type": "code_interpreter"},
{
"type": "function",
"name": "send_alert",
"description": "Sends an alert if a threshold is exceeded",
"parameters": {
"type": "object",
"properties": {
"metric": {"type": "string"},
"value": {"type": "number"},
"threshold": {"type": "number"}
},
"required": ["metric", "value"]
}
}
]
max_turns y herramientas híbridas
El comportamiento de max_turns es crucial en un contexto híbrido:
max_turnslimita los turnos del lado del servidor dentro de una única solicitud.- Cuando el modelo llama a una función de cliente y tu código devuelve el resultado, comienza una nueva asignación de
max_turns.
En la práctica, esto significa que las llamadas al cliente no agotan tu presupuesto de turnos de servidor. El modelo puede realizar 3 búsquedas web, llamar a tu función y, tras recibir el resultado, llevar a cabo 3 búsquedas adicionales.
Contexto multi-turno con almacenamiento
Para flujos de trabajo complejos que abarcan múltiples interacciones, combina el almacenamiento y el encadenamiento:
# Turn 1: initial search
r1 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze AI market trends.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}],
store=True,
max_turns=5
)
# Turn 2: deepen with your internal data
r2 = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Compare with our internal data.",
tools=[{
"type": "function",
"name": "query_internal_db",
"description": "Queries the internal database",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}}
}],
previous_response_id=r1.id,
store=True
)
Puntos clave
- Combina herramientas de servidor y funciones de cliente en una única solicitud para crear flujos de trabajo híbridos.
- Las herramientas de servidor se ejecutan automáticamente; las funciones de cliente pausan la generación.
max_turnsse restablece tras cada ida y vuelta con el cliente.- Patrones habituales: búsqueda + acción, cálculo + notificación, agregación de múltiples fuentes.
- Utiliza
store: trueyprevious_response_idpara flujos de trabajo multi-turno.