Construye un agente de research autónomo con MCP en 50 líneas

Un agente que recibe una pregunta abierta, decide qué herramientas necesita usar (búsqueda en Google, scraping, generación de imágenes), las ejecuta vía Model Context Protocol y devuelve un informe estructurado — todo en menos de 50 líneas de TypeScript, sin servidores propios.

Por qué MCP cambia las reglas para agentes

Hasta hace poco, dotar a un agente IA de "herramientas" significaba escribir tres capas: el contrato JSON Schema de cada función, el código que las ejecuta, y el loop que pasa los resultados de vuelta al modelo. Cuando querías añadir scraping web tenías que orquestar Puppeteer; para Google Search, integrar con Serper; para imágenes, gestionar tu propia API de Flux o DALL·E. Cada nueva capacidad era un nuevo servicio que mantener.

El Model Context Protocol de Anthropic resuelve esto a nivel de protocolo: un endpoint MCP expone un catálogo dinámico de tools que cualquier cliente compatible puede consumir. La parte importante para builders de agentes es que las tools se anuncian con su inputSchema — el agente puede aprender en runtime qué herramientas existen y cómo usarlas.

LLM4Agents combina dos cosas en una sola API key:

1. Un proxy OpenAI-compatible a 345+ modelos (Claude, GPT, Gemini, Llama, etc.)
2. Un endpoint MCP Streamable HTTP con scraper headless, Google Search, generación de imágenes y más

Esto significa que podemos construir un agente real — uno que decide, ejecuta y razona sobre los resultados — sin levantar infraestructura propia.

El objetivo

Construiremos un agente al que le pides cosas como:

"Investiga el último lanzamiento del modelo Claude Sonnet, busca opiniones de la comunidad y dame un resumen ejecutivo con un gráfico ilustrativo."

El agente debe:

• Decidir por sí mismo qué tools necesita (Google News, scraper, generador de imágenes)
• Ejecutarlas en el orden adecuado
• Combinar los resultados
• Devolver una respuesta coherente

Setup mínimo

Una sola dependencia, una sola API key, ningún servidor propio:

npm install @llmforagents/sdk
export LLM4AGENTS_API_KEY="sk-proxy-..."

Si todavía no tienes una API key, regístrala en un POST público (sin formulario, sin KYC):

curl -X POST https://api.llm4agents.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"research-agent"}'

Después genera una wallet de depósito y envía 5 USDT a esa dirección — el balance se acredita automáticamente al confirmarse on-chain.

El agente completo

Aquí está el código entero. Después lo desglosamos:

// research-agent.ts
import { LLM4AgentsClient } from '@llmforagents/sdk';
import { writeFileSync } from 'node:fs';

const client = new LLM4AgentsClient({
  apiKey: process.env.LLM4AGENTS_API_KEY!,
});

const agent = client.chat.conversation({
  model: 'anthropic/claude-sonnet-4',
  system: `Eres un analista de research técnico.
Usas las MCP tools disponibles para investigar y entregar informes
ejecutivos con datos verificados. Genera siempre una imagen
ilustrativa del tema al final del informe.`,
  tools: client.tools,
  maxToolRounds: 8,
  onToolCall: (name, args) => {
    console.log(`→ ${name}(${JSON.stringify(args).slice(0, 80)})`);
    return true;
  },
  onToolResult: (name, _result, durationMs) => {
    console.log(`✓ ${name} · ${durationMs}ms`);
  },
});

const question = process.argv.slice(2).join(' ') ||
  'Investiga el último lanzamiento de Claude Sonnet y resume opiniones de la comunidad.';

const answer = await agent.say(question);

writeFileSync('report.md', answer.content);
console.log(`\n📄 Informe guardado · ${answer.toolCalls.length} tool calls`);

Eso es todo. 43 líneas exactas, un solo archivo, sin servidor ni infraestructura propia. Lo ejecutas con:

npx tsx research-agent.ts "Compara LangGraph vs CrewAI para flujos de research"

Qué está pasando por dentro

La línea clave es tools: client.tools. El SDK auto-introspecta el endpoint MCP, obtiene la lista completa de tools disponibles (scraper, búsqueda, imágenes…) y las traduce al formato function-calling que entiende cualquier modelo OpenAI-compatible. Cuando el modelo emite tool_calls, el SDK las ejecuta contra el endpoint MCP usando la misma API key — y luego devuelve los resultados al modelo en el siguiente turno del loop.

El parámetro maxToolRounds: 8 es la barandilla de seguridad: si el agente entra en un loop infinito (alucina la necesidad de seguir buscando indefinidamente), el SDK aborta tras 8 rondas. Para investigaciones complejas, 5-10 rondas es lo típico.

Output real de una ejecución

Un ejemplo con "Compara LangGraph vs CrewAI para flujos de research":

→ google_search({"q":"LangGraph vs CrewAI comparison 2026"})
✓ google_search · 412ms
→ google_search({"q":"CrewAI features research workflows"})
✓ google_search · 389ms
→ markdown({"url":"https://www.langchain.com/langgraph"})
✓ markdown · 1240ms
→ markdown({"url":"https://docs.crewai.com/concepts/agents"})
✓ markdown · 1189ms
→ google_news({"q":"CrewAI release","tbs":"qdr:m"})
✓ google_news · 401ms
→ generate_image({"prompt":"comparison diagram of LangGraph and CrewAI..."})
✓ generate_image · 4521ms

📄 Informe guardado · 6 tool calls

El agente decidió por sí solo hacer dos búsquedas Google para cubrir ambos productos, scrapear sus respectivas docs, hacer una búsqueda de noticias recientes para frescura, y cerrar con un diagrama generado por IA. Ningún paso lo programamos explícitamente.

Costos reales

Cada llamada al chat completion devuelve un header X-Cost-Usd-Cents con el costo exacto. Para esta corrida típica:

• Chat completions (3 turnos del loop con Claude Sonnet 4): ~3.2¢
• 2× google_search: 0.24¢
• 2× markdown: 0.20¢
• 1× google_news: 0.12¢
• 1× generate_image: 1.0¢
• Total: ~4.76¢ por informe completo con imagen

Un agente con 5 USDT puede ejecutar ~100 informes así. Sin tarjeta, sin suscripción, debitando del mismo balance.

Sin SDK propio: el patrón equivalente con OpenAI SDK

Si tu stack está atado al SDK oficial de OpenAI, el patrón es ligeramente más verboso pero igual de directo:

from openai import OpenAI
import requests, json

API_KEY = "sk-proxy-..."
HDRS    = {"Authorization": f"Bearer {API_KEY}"}

# Auto-fetch de TODAS las MCP tools
mcp_tools = requests.post("https://mcp.llm4agents.com/mcp", headers=HDRS,
    json={"jsonrpc":"2.0","id":1,"method":"tools/list"}).json()["result"]["tools"]

tools = [{"type":"function","function":{
    "name":t["name"],"description":t["description"],
    "parameters":t["inputSchema"]}} for t in mcp_tools]

client = OpenAI(api_key=API_KEY, base_url="https://api.llm4agents.com/v1")
# El modelo elige; tú haces el loop manualmente sobre tool_calls

El loop tool→model lo escribes tú, pero la lista de tools es dinámica — añade nuevas tools al endpoint MCP y tu agente las descubre sin cambios de código.

Ideas para extender

• Streaming SSE: cambia conv.say() por conv.stream() y procesa eventos tool_start, tool_end, text, done en tiempo real para una UI tipo Perplexity.
• Memoria persistente: conv.messages es un array JSON-serializable — guárdalo en KV, Postgres o S3, y rehidrata con client.chat.conversation({ history: saved }).
• Multi-agente: lanza N instancias del mismo agente con prompts especializados (Researcher, Critic, Writer) y orquesta entre ellos. Cada uno con su propia API key y balance aislado.
• Auto-recarga: cuando el balance baja de un umbral, el agente puede transferir USDT desde una wallet "treasury" usando el endpoint /v1/tx/send gasless.

El punto importante

El código de un agente real no debería ser 500 líneas de orquestación. Si tu modelo tiene acceso a las tools correctas y un prompt claro, el agente decide. Tu trabajo es proporcionar el catálogo de capacidades y dejar que el modelo elija.

Eso es exactamente lo que hace el patrón tools: client.tools: en una línea, expones todo el universo de MCP tools y dejas que cualquiera de los 345+ modelos disponibles las orqueste según el prompt.