Crear una búsqueda seleccionada para agentes de IA significa envolver una API de búsqueda con filtrado, reclasificación y compresión para que el agente reciba solo resultados de señal alta en lugar de ruido SERP sin procesar. Los resultados de búsqueda sin procesar desperdician tokens en anuncios, dominios irrelevantes y fragmentos detallados que diluyen el razonamiento de los agentes. Este tutorial crea un middleware de Python que se ubica entre su agente y la API de búsqueda de Scavio, aplicando listas de dominios permitidos, puntuación de relevancia y truncamiento de fragmentos para reducir el uso de tokens en un 70% y al mismo tiempo mejorar la calidad de las respuestas.
Requisitos previos
- Python 3.8+
- solicita biblioteca instalada
- Clave API de Scavio de scavio.dev
- Comprensión básica del conteo de tokens (tiktoken opcional)
Guia paso a paso
Paso 1: Definir filtros de dominio y reglas de calidad
Cree listas de permitidos y bloqueados para dominios, además de reglas para filtrar resultados de baja calidad, como foros sin respuestas o contenido de pago.
Python
BLOCKED_DOMAINS = [
'pinterest.com', 'quora.com', 'facebook.com',
'instagram.com', 'tiktok.com', 'twitter.com',
]
TRUSTED_DOMAINS = [
'docs.python.org', 'developer.mozilla.org', 'github.com',
'stackoverflow.com', 'arxiv.org', 'huggingface.co',
]
def domain_score(url):
domain = url.split('/')[2] if url else ''
if any(b in domain for b in BLOCKED_DOMAINS):
return -10
if any(t in domain for t in TRUSTED_DOMAINS):
return 5
return 0Paso 2: Construya el contenedor de búsqueda con compresión
Cree una función que llame a Scavio, filtre resultados, califique la relevancia y comprima fragmentos en un presupuesto simbólico.
Python
import requests, os
H = {'x-api-key': os.environ['SCAVIO_API_KEY'], 'Content-Type': 'application/json'}
def curated_search(query, max_results=5, max_snippet_chars=200):
data = requests.post('https://api.scavio.dev/api/v1/search',
headers=H, json={'query': query, 'country_code': 'us'}).json()
results = data.get('organic_results', [])
scored = []
for r in results:
ds = domain_score(r.get('link', ''))
if ds < 0:
continue
snippet = (r.get('snippet') or '')[:max_snippet_chars]
scored.append({
'title': r.get('title', ''),
'url': r.get('link', ''),
'snippet': snippet,
'score': ds + r.get('position', 10) * -0.5
})
scored.sort(key=lambda x: x['score'], reverse=True)
return scored[:max_results]Paso 3: Agregar reclasificación de relevancia
Califique los resultados por palabra clave que se superponen con la consulta original para llevar los resultados más relevantes a la cima.
Python
def relevance_score(query, result):
query_terms = set(query.lower().split())
text = f"{result['title']} {result['snippet']}".lower()
matches = sum(1 for t in query_terms if t in text)
return matches / max(len(query_terms), 1)
def curated_search_v2(query, max_results=5, max_snippet_chars=200):
raw = curated_search(query, max_results=15, max_snippet_chars=max_snippet_chars)
for r in raw:
r['score'] += relevance_score(query, r) * 3
raw.sort(key=lambda x: x['score'], reverse=True)
return raw[:max_results]Paso 4: Medir el ahorro de tokens
Compare los recuentos de tokens entre los resultados sin procesar y seleccionados para verificar la relación de compresión.
Python
def estimate_tokens(text):
return len(text.split()) * 1.3 # rough estimate
def compare_token_usage(query):
data = requests.post('https://api.scavio.dev/api/v1/search',
headers=H, json={'query': query, 'country_code': 'us'}).json()
raw_text = str(data.get('organic_results', []))
raw_tokens = estimate_tokens(raw_text)
curated = curated_search_v2(query)
curated_text = str(curated)
curated_tokens = estimate_tokens(curated_text)
savings = (1 - curated_tokens / raw_tokens) * 100
print(f'Raw: ~{int(raw_tokens)} tokens')
print(f'Curated: ~{int(curated_tokens)} tokens')
print(f'Savings: {savings:.0f}%')
compare_token_usage('how to deploy FastAPI to production')Ejemplo en Python
Python
import os, requests
H = {'x-api-key': os.environ['SCAVIO_API_KEY'], 'Content-Type': 'application/json'}
BLOCKED = ['pinterest.com', 'quora.com', 'facebook.com']
TRUSTED = ['docs.python.org', 'developer.mozilla.org', 'github.com', 'stackoverflow.com']
def curated_search(query, max_results=5, max_chars=200):
data = requests.post('https://api.scavio.dev/api/v1/search',
headers=H, json={'query': query, 'country_code': 'us'}).json()
results = []
query_terms = set(query.lower().split())
for r in data.get('organic_results', []):
domain = r.get('link', '').split('/')[2] if r.get('link') else ''
if any(b in domain for b in BLOCKED):
continue
snippet = (r.get('snippet') or '')[:max_chars]
text = f"{r.get('title', '')} {snippet}".lower()
relevance = sum(1 for t in query_terms if t in text) / max(len(query_terms), 1)
trust = 5 if any(t in domain for t in TRUSTED) else 0
results.append({
'title': r.get('title', ''),
'url': r.get('link', ''),
'snippet': snippet,
'score': trust + relevance * 3
})
results.sort(key=lambda x: x['score'], reverse=True)
return results[:max_results]
for r in curated_search('FastAPI deployment best practices 2026'):
print(f"[{r['score']:.1f}] {r['title']}")
print(f" {r['url']}")Ejemplo en JavaScript
JavaScript
const H = {'x-api-key': process.env.SCAVIO_API_KEY, 'Content-Type': 'application/json'};
const BLOCKED = ['pinterest.com', 'quora.com', 'facebook.com'];
const TRUSTED = ['docs.python.org', 'developer.mozilla.org', 'github.com', 'stackoverflow.com'];
async function curatedSearch(query, maxResults = 5, maxChars = 200) {
const data = await fetch('https://api.scavio.dev/api/v1/search', {
method: 'POST', headers: H,
body: JSON.stringify({query, country_code: 'us'})
}).then(r => r.json());
const queryTerms = new Set(query.toLowerCase().split(' '));
const results = (data.organic_results || []).map(r => {
const domain = (r.link || '').split('/')[2] || '';
if (BLOCKED.some(b => domain.includes(b))) return null;
const snippet = (r.snippet || '').slice(0, maxChars);
const text = \`\${r.title || ''} \${snippet}\`.toLowerCase();
const relevance = [...queryTerms].filter(t => text.includes(t)).length / queryTerms.size;
const trust = TRUSTED.some(t => domain.includes(t)) ? 5 : 0;
return {title: r.title, url: r.link, snippet, score: trust + relevance * 3};
}).filter(Boolean).sort((a, b) => b.score - a.score).slice(0, maxResults);
return results;
}
curatedSearch('FastAPI deployment best practices 2026').then(results => {
results.forEach(r => console.log(\`[\${r.score.toFixed(1)}] \${r.title}\`));
});Salida esperada
JSON
[8.0] FastAPI Deployment Guide - Official Docs
https://docs.python.org/fastapi-deploy
[5.5] Deploy FastAPI on AWS Lambda in 2026
https://github.com/example/fastapi-lambda
[3.0] Production FastAPI Checklist
https://example.com/fastapi-prod