Citas automáticas y buenas prácticas
En esta página
Respuestas con fuentes y fiables
Cuando el modelo utiliza la búsqueda web o la búsqueda en X, la API de Responses incluye automáticamente citas en la respuesta. Estas citas permiten a tus usuarios verificar las fuentes y generar confianza en las respuestas generadas.
Cómo funcionan las citas
Las citas aparecen en el array annotations de cada elemento de contenido:
{
"output": [{
"type": "message",
"content": [{
"type": "output_text",
"text": "According to the latest data, the AI market...",
"annotations": [
{
"type": "url_citation",
"url": "https://example.com/article",
"title": "AI Market Analysis in 2026",
"start_index": 35,
"end_index": 68
}
]
}]
}]
}
Campos de la cita
| Campo | Descripción |
|---|---|
type | Siempre url_citation |
url | URL de la fuente |
title | Título de la página de origen |
start_index | Posición de inicio en el texto |
end_index | Posición de fin en el texto |
Mostrar citas en tu aplicación
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest advancements in AI?",
tools=[{"type": "web_search"}]
)
text = response.output[0].content[0].text
annotations = response.output[0].content[0].annotations
# Construir texto con notas al pie
footnotes = []
for i, ann in enumerate(annotations, 1):
footnotes.append(f"[{i}] {ann.title} — {ann.url}")
print(text)
print("\n--- Fuentes ---")
for fn in footnotes:
print(fn)
En HTML
def render_with_citations(text, annotations):
# Ordenar por posición (de fin a inicio para evitar desplazar índices)
sorted_anns = sorted(annotations, key=lambda a: a.start_index, reverse=True)
html = text
for i, ann in enumerate(sorted_anns):
ref_num = len(sorted_anns) - i
link = f'<a href="{ann.url}" title="{ann.title}" target="_blank">[{ref_num}]</a>'
html = html[:ann.end_index] + link + html[ann.end_index:]
return html
Buenas prácticas para producción
1. Validar siempre el estado
response = client.responses.create(...)
if response.status != "completed":
handle_error(response)
return
2. Gestionar respuestas vacías
if not response.output or not response.output[0].content:
return "The model did not generate a response."
text = response.output[0].content[0].text
3. Registrar métricas
Para cada solicitud en producción, registra:
response.idpara la trazabilidadusage.total_tokenspara el consumousage.cost_in_nano_usdpara los costes- Tiempo de respuesta del lado del cliente
- Estado de la respuesta
4. Proteger tu clave de API
- Almacénala en una variable de entorno, nunca en el código
- Utiliza un gestor de secretos en producción (Vault, AWS Secrets Manager)
- Rota tus claves periódicamente
- No las expongas nunca del lado del cliente (navegador)
5. Gestionar el contenido generado
Las respuestas del modelo pueden contener contenido inapropiado a pesar de los filtros. Implementa una capa de moderación si muestras respuestas públicamente.
6. Planificar la escalabilidad
- Utiliza streaming para reducir el tiempo de espera percibido
- Implementa un sistema de colas para solicitudes pesadas
- Almacena en caché las respuestas frecuentes
- Supervisa tus cuotas de limitación de tasa (rate limiting)
Lista de comprobación para el despliegue
- Tiempo de espera (timeout) establecido en 3600 segundos
- Reintento con retroceso exponencial (exponential backoff)
- Limitación de tasa del lado del cliente
- Registro de métricas (tokens, costes, latencia)
- Gestión de errores (401, 429, 500, timeout)
- Clave de API segura
- Moderación de contenido si es necesario
- Supervisión de costes y alertas
- Interruptor de circuito (circuit breaker) para la resiliencia
Puntos clave
- Las citas son automáticas cuando el modelo utiliza
web_searchox_search - Contienen la URL, el título y la posición en el texto
- Valida siempre el estado y gestiona las respuestas vacías
- Protege tu clave de API: nunca en el código fuente ni del lado del cliente
- Implementa registro, reintentos, limitación de tasa y supervisión antes de pasar a producción
Pon a prueba tus conocimientos
La API de Responses en profundidad: la comprobación final.
1. ¿Qué ofrece la API de Responses en comparación con Chat Completions?
Respuesta: El formato moderno: persistencia de respuestas del lado del servidor (GET/DELETE, encadenamiento por ID), herramientas integradas y funciones recientes; la API donde xAI centra su evolución.
2. ¿Cómo se encadena una conversación?
Respuesta: Haciendo referencia a la respuesta anterior: el contexto se mantiene del lado del servidor, sin necesidad de reenviar todo el historial en cada turno.
3. ¿Qué es el razonamiento cifrado?
Respuesta: El razonamiento interno del modelo devuelto en forma cifrada: reutilizable en turnos siguientes sin ser legible; el proceso de pensamiento viaja, la confidencialidad se mantiene.
4. ¿Qué permite combinar herramientas del servidor y del cliente?
Respuesta: Combinar herramientas integradas ejecutadas por xAI (búsqueda web, etc.) y tus funciones personalizadas ejecutadas por tu código; cada herramienta en su lugar, orquestadas en la misma solicitud.
5. ¿Cuáles son las buenas prácticas para producción?
Respuesta: Gestionar el tiempo de espera y los reintentos, rastrear la facturación (tokens, herramientas) y aprovechar las citas automáticas para respuestas verificables; robustez y confianza juntas.
Persistencia, herramientas, razonamiento cifrado, citas: la API de Responses es la base moderna; aquí es donde se construyen tus aplicaciones con Grok.