Un agente que reacciona a la publicación de resultados necesita datos en vivo, no la memoria de su modelo. Un modelo entrenado hace meses no sabe que Nvidia acaba de superar ingresos y fallar en la guía hace una hora, y si le pides un comentario se inventará algo con total seguridad. La solución es traer los resultados de búsqueda en vivo del ticker justo cuando salen las cifras y pasarle ese texto estructurado al LLM como contexto. Este tutorial conecta tres endpoints de Scavio en un paquete de grounding: SERP de Google (2 créditos con light_request en false), búsqueda de Reddit y búsqueda de YouTube. Para que quede claro el alcance: Scavio es solo la capa de datos y grounding. Devuelve resultados de búsqueda. No genera señales de trading, y nada aquí es asesoría financiera. Lo que tu agente haga con los datos, y si operas con ellos, es tu propia decisión y tu propio riesgo.
Requisitos previos
- Una API key de Scavio (50 créditos gratis al registrarte, sin tarjeta) — se usa como Authorization: Bearer {API_KEY}
- Python 3.9+ o Node 18+, más un cliente LLM (cualquier proveedor) que consuma el paquete de grounding
- Un símbolo de ticker y el nombre de la empresa (por ejemplo AAPL / Apple) y la fecha de resultados a la que quieres reaccionar
Guia paso a paso
Paso 1: 1. Trae la SERP de Google en vivo del ticker en la fecha de resultados
En el momento en que se publican los resultados, llama a POST /api/v1/google con light_request en false (2 créditos) para la consulta "<ticker> earnings". Con todas las funciones devuelve resultados orgánicos, people_also_ask, knowledge_graph y related_searches en una sola llamada. Los resultados orgánicos traen titulares de agencias de prensa y casas de análisis; knowledge_graph suele tener la cotización actual y datos básicos; people_also_ask muestra las preguntas que el inversor minorista escribe de verdad. Esta es tu columna factual. Nota: Scavio no devuelve los AI Overviews de Google, así que no dependas de una caja de respuesta sintetizada: te apoyas en los resultados crudos.
curl -X POST https://api.scavio.dev/api/v1/google \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "NVDA earnings", "light_request": false}'Paso 2: 2. Trae el sentimiento de Reddit para medir la reacción minorista
Llama a POST /api/v1/reddit/search para "<ticker> earnings" y ve qué dicen los traders minoristas en los minutos posteriores a la cifra. Los hilos en subs como r/wallstreetbets y r/stocks reaccionan rápido y con emoción, justo la señal que una SERP de noticias se pierde. No tratas los upvotes como verdad: le das al agente una lectura del ánimo de la multitud para que marque divergencias entre los números del titular y cómo los toma la gente. La búsqueda de Reddit son 1 crédito; un post completo con su árbol de comentarios son 2.
curl -X POST https://api.scavio.dev/api/v1/reddit/search \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "NVDA earnings"}'Paso 3: 3. Opcionalmente trae la cobertura de YouTube para análisis
Si quieres comentario en video, llama a POST /api/v1/youtube/search. El cuerpo usa search, no query: este endpoint es la única excepción, así que no envíes query aquí. YouTube muestra desgloses de analistas y reacciones en directo que se publican en la hora siguiente a la llamada. Los títulos y descripciones suelen bastar como contexto para grounding; rara vez necesitas las transcripciones. Este paso es opcional y cuesta 1 crédito. Sáltalo si optimizas por latencia o créditos.
curl -X POST https://api.scavio.dev/api/v1/youtube/search \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"search": "NVDA earnings reaction"}'Paso 4: 4. Pasa el paquete estructurado al agente como contexto de grounding
Une las respuestas de SERP, Reddit y YouTube en un solo objeto JSON y mételo en el prompt del LLM como contexto recuperado, con una instrucción explícita: resume solo lo que respaldan los resultados aportados y dilo cuando los datos sean escasos. Ese es todo el punto: el modelo ahora describe lo que de verdad pasó en la última hora en lugar de recitar datos viejos de entrenamiento. Mantén el trabajo del agente en resumir y extraer de forma estructurada. Es un consumidor de grounding, no un generador de señales, y nunca debe ser lo que coloque una operación por su cuenta.
# Pseudocódigo: pasa el paquete como contexto, limita el modelo a afirmaciones con grounding
prompt = f"""Estás resumiendo una reacción a resultados. Usa SOLO los datos de abajo.
Si los datos no respaldan una afirmación, di que se desconoce. No des consejos.
GROUNDING:
{json.dumps(bundle)}
"""
response = llm.complete(prompt)Ejemplo en Python
import os, json, requests
API = "https://api.scavio.dev/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}",
"Content-Type": "application/json"}
def post(path, body):
r = requests.post(f"{API}{path}", headers=HEADERS, json=body, timeout=30)
r.raise_for_status()
return r.json()
def ground_earnings(ticker):
serp = post("/google", {"query": f"{ticker} earnings", "light_request": False})
reddit = post("/reddit/search", {"query": f"{ticker} earnings"})
youtube = post("/youtube/search", {"search": f"{ticker} earnings reaction"})
return {
"ticker": ticker,
"serp": {
"organic": serp.get("organic", [])[:5],
"people_also_ask": serp.get("people_also_ask", []),
"knowledge_graph": serp.get("knowledge_graph", {}),
},
"reddit": reddit.get("results", [])[:5],
"youtube": youtube.get("results", [])[:5],
}
# Scavio devuelve los datos; tu agente/LLM decide qué hacer con ellos.
# Esto no es asesoría financiera ni una señal de trading.
bundle = ground_earnings("NVDA")
print(json.dumps(bundle, indent=2)[:2000])Ejemplo en JavaScript
const API = "https://api.scavio.dev/api/v1";
const HEADERS = {
"Authorization": `Bearer ${process.env.SCAVIO_API_KEY}`,
"Content-Type": "application/json",
};
async function post(path, body) {
const res = await fetch(`${API}${path}`, {
method: "POST",
headers: HEADERS,
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${path} ${res.status}`);
return res.json();
}
async function groundEarnings(ticker) {
const [serp, reddit, youtube] = await Promise.all([
post("/google", { query: `${ticker} earnings`, light_request: false }),
post("/reddit/search", { query: `${ticker} earnings` }),
post("/youtube/search", { search: `${ticker} earnings reaction` }),
]);
return {
ticker,
serp: {
organic: (serp.organic || []).slice(0, 5),
people_also_ask: serp.people_also_ask || [],
knowledge_graph: serp.knowledge_graph || {},
},
reddit: (reddit.results || []).slice(0, 5),
youtube: (youtube.results || []).slice(0, 5),
};
}
// Scavio es la capa de grounding. Las decisiones y operaciones son tuyas, y arriesgadas.
const bundle = await groundEarnings("NVDA");
console.log(JSON.stringify(bundle, null, 2).slice(0, 2000));Salida esperada
{
"ticker": "NVDA",
"serp": {
"organic": [
{"title": "Nvidia reports Q earnings, revenue tops estimates", "link": "https://...", "snippet": "Nvidia posted revenue above consensus while guidance ..."},
{"title": "Analysts react to Nvidia's print", "link": "https://...", "snippet": "..."}
],
"people_also_ask": [
{"question": "Did Nvidia beat earnings this quarter?"},
{"question": "What is Nvidia's guidance for next quarter?"}
],
"knowledge_graph": {"title": "NVIDIA Corporation", "type": "Technology company"}
},
"reddit": [
{"title": "NVDA earnings thread", "subreddit": "wallstreetbets", "score": 1840, "url": "https://..."}
],
"youtube": [
{"title": "NVDA earnings reaction LIVE", "channel": "...", "url": "https://..."}
]
}
# El agente consume este paquete como contexto de grounding. Resume lo que los
# resultados dicen de verdad. No inventa cifras ni coloca operaciones.