Combinar herramientas de servidor y de cliente
En esta página
Dos categorías de herramientas en la misma plataforma
La API de Grok distingue dos tipos de herramientas fundamentalmente diferentes según su ejecución. Entender esta distinción es esencial para diseñar arquitecturas robustas.
Herramientas integradas (lado del servidor)
xAI ejecuta estas herramientas automáticamente en sus propios servidores. No tienes que gestionar nada: ni ejecución local, ni reenvío de resultados. El modelo las invoca y recibe los resultados directamente.
| Herramienta | Identificador | Descripción |
|---|---|---|
| Búsqueda web | web_search | Búsqueda web en tiempo real |
| Búsqueda en X | x_search | Búsqueda en X/Twitter |
| Intérprete de código | code_interpreter | Ejecución de Python en entorno aislado (sandbox) |
| Búsqueda en colecciones | collections_search | Búsqueda dentro de tus documentos subidos |
| MCP remoto | mcp | Conexión a servidores MCP externos |
Funciones personalizadas (lado del cliente)
Estas son tus propias funciones, definidas mediante llamadas a funciones (function calling). El modelo devuelve un tool_call, tu código ejecuta la función y tú envías el resultado de vuelta. Este es el mecanismo que aprendiste en lecciones anteriores.
Combinar ambas en una única solicitud
La potencia de la API de Grok reside en la capacidad de mezclar herramientas de servidor y de cliente en una única solicitud:
tools = [
# Herramienta de servidor: ejecutada automáticamente por xAI
{"type": "web_search"},
# Herramienta de cliente: ejecutada por tu código
{
"type": "function",
"function": {
"name": "save_to_database",
"description": "Guardar información en la base de datos",
"parameters": {
"type": "object",
"properties": {
"key": {"type": "string"},
"value": {"type": "string"}
},
"required": ["key", "value"]
}
}
}
]
Cuando el modelo recibe esta solicitud, puede:
- Usar
web_searchpara encontrar información (ejecución automática en el servidor) - Llamar a
save_to_databasepara guardar el resultado (devuelve el control al cliente)
El flujo híbrido
El comportamiento varía según el tipo de herramienta:
- Herramienta de servidor: el modelo llama a la herramienta, xAI la ejecuta, el resultado se integra automáticamente y el modelo continúa.
- Herramienta de cliente: el modelo devuelve el
tool_callal cliente, la ejecución se detiene y se reanuda cuando tú envías el resultado de vuelta.
Cuando el modelo utiliza ambos tipos en la misma solicitud, las herramientas de servidor se ejecutan primero (sin tu intervención). A continuación, si el modelo también necesita una herramienta de cliente, te devuelve el tool_call con los resultados de las herramientas de servidor ya integrados en su contexto.
Ejemplos del mundo real
Búsqueda web + lógica de negocio
# El usuario pregunta: "Busca el precio del Bitcoin y guárdalo"
# El modelo:
# 1. Llama a web_search para encontrar el precio (lado del servidor, automático)
# 2. Llama a save_price(symbol="BTC", price=68432) (lado del cliente)
Búsqueda en X + notificación
# "Avísame de los tuits sobre nuestro producto desde ayer"
# El modelo:
# 1. Llama a x_search para encontrar tuits (lado del servidor)
# 2. Llama a send_notification(count=12, summary="...") (lado del cliente)
Intérprete de código + almacenamiento
# "Calcula la media de estos datos y guarda el resultado"
# El modelo:
# 1. Llama a code_interpreter para el cálculo (lado del servidor)
# 2. Llama a save_result(key="avg", value="42.5") (lado del cliente)
Facturación de las herramientas de servidor
Las herramientas integradas se facturan de dos formas:
- Tokens: consumo estándar (entrada + salida)
- Invocaciones: coste fijo por llamada a la herramienta
El modelo puede llamar a varias herramientas de servidor en una única solicitud; los costes se acumulan. Tenlo en cuenta cuando habilites web_search: el modelo podría realizar múltiples búsquedas para refinar sus resultados.
Puntos clave
- Dos tipos de herramientas: servidor (automáticas) y cliente (llamadas a funciones)
- Las herramientas de servidor (
web_search,x_search,code_interpreter) se ejecutan sin tu intervención - Puedes mezclar ambos tipos en una única solicitud
- Las herramientas de servidor se ejecutan primero; luego, el modelo puede llamar a tus funciones
- Cada invocación de una herramienta de servidor tiene coste (tokens + coste por llamada)
- Las citas se generan automáticamente para los datos procedentes de herramientas de servidor