📲 Social Media Agent: Arquitectura Multi-Agente con LangGraph & Human-in-the-Loop

📲 Social Media Agent — Sistema Multi-Agente de Curaduría y Publicación con LangGraph

Orquestación Multi-Agente End-to-End con Human-in-the-Loop (HITL) y Agent Inbox

Social Media Agent (desarrollado por el equipo oficial de LangChain, 2025-2026) es un sistema multi-agente de nivel productivo para la ingesta autónoma, curaduría, generación de contenido, revisión interactiva y publicación programada en Twitter / X y LinkedIn a partir de URLs arbitrarias (blogs, repositorios GitHub, videos de YouTube, Reddit y canales de Slack).

Implementa el patrón Human-in-the-Loop (HITL) mediante Agent Inbox, pausando la ejecución del grafo para permitir al usuario aprobar, editar o regenerar publicaciones antes de su lanzamiento.

• 💻 Repositorio Oficial: github.com/langchain-ai/social-media-agent
• 📦 Stack Principal: Node 22 · TypeScript · @langchain/langgraph · @langchain/anthropic · Claude 3.5 Sonnet · FireCrawl · Arcade AI · Supabase · Playwright
• 🖥️ Interfaz de Revisión: Agent Inbox (dev.agentinbox.ai)
• 🔗 Conexiones en la Bóveda: Modelos & Prompts IA · Short Video Factory (Automatización Contenido) · MOC General

---

🧭 Arquitectura del Sistema: Topología de Grafos LangGraph

El sistema está compuesto por 14 subgrafos especializados coordinados por un supervisor central, garantizando separación de responsabilidades, reintentos controlados y persistencia de estado:

flowchart TD
    subgraph Ingestion["📥 1. Ingesta & Monitoreo Asíncrono"]
        Slack["💬 Canales de Slack (Slack Bot)"]
        Cron["⏰ Cron Jobs Diarios (LangGraph CLI)"]
        Manual["🔗 Ingesta Manual (CLI / API URL)"]
        Sources["🌐 Fuentes Externas: Reddit, Latent Space, GitHub Trending"]
    end

    subgraph LangGraph["🧠 2. Motor de Grafos LangGraph"]
        Supervisor{"👑 Supervisor / Router Graph"}
        Curate["🔍 Curate Data Graph"]
        Verify["🛡️ Verify Links & Relevancy\n(GitHub, YouTube, Tweet, General)"]
        Report["📊 Generate Report Graph\n(Ángulo de marketing & síntesis de valor)"]
        Generate["✍️ Generate Post & Threads\n(Estructura Header-Body-CTA)"]
        Reflect["🪞 Reflection Graph\n(Crítica y refinamiento de estilo)"]
        Store[("💾 LangGraph Store\n(Deduplicación de URLs usadas)")]
    end

    subgraph HITL["🛑 3. Human-in-the-Loop (Agent Inbox)"]
        Interrupt["⏸️ Thread Interrupt State"]
        InboxUI["📱 Agent Inbox (dev.agentinbox.ai)\n- Aprobar publicación\n- Editar texto / imágenes\n- Regenerar o descartar"]
    end

    subgraph Dispatch["🚀 4. Despliegue & Publicación"]
        Arcade["🔑 Arcade AI (OAuth Universal)"]
        Native["🔐 OAuth Directo (Twitter v2 / LinkedIn REST)"]
        Supabase["🖼️ Supabase Storage (Imágenes / Media)"]
        Social["📢 Twitter/X & LinkedIn"]
    end

    Ingestion --> Supervisor
    Sources --> Curate --> Supervisor
    Supervisor --> Verify
    Verify <--> Store
    Verify --> Report --> Generate --> Reflect --> Interrupt
    Interrupt --> InboxUI
    InboxUI -- "✅ Aprobado" --> Dispatch
    Dispatch --> Social
    Dispatch -. "Guardar Assets" .-> Supabase

---

🦁 Catálogo de Subgrafos en langgraph.json

Subgrafo	Archivo Origen	Función Clave
supervisor	src/agents/supervisor/supervisor-graph.ts	Router maestro que orquesta los flujos de trabajo según el tipo de entrada.
ingest_data	src/agents/ingest-data/ingest-data-graph.ts	Extrae enlaces automáticamente desde canales de Slack o cron jobs.
generate_post	src/agents/generate-post/generate-post-graph.ts	Pipeline principal: extracción de URL $\to$ reporte $\to$ generación $\to$ pausa HITL.
curate_data	src/agents/curate-data/index.ts	Scraping de fuentes técnicas (Reddit r/LocalLLaMA, blogs IA, repositorios GitHub).
generate_report	src/agents/generate-report/index.ts	Analiza el contexto de negocio, identifica el gancho comercial y genera el brief.
reflection	src/agents/reflection/index.ts	Agente crítico que evalúa la coherencia, tono y cumplimiento de reglas editoriales.
generate_thread	src/agents/generate-thread/index.ts	Divide el contenido largo en un hilo estructurado de varios tweets concatenados.
verify_tweet / verify_reddit_post	src/agents/verify-*/	Verificación de relevancia contextual y filtrado de contenido fuera de foco.
curated_post_interrupt	src/agents/curated-post-interrupt/index.ts	Máquina de estados que gestiona la interrupción del hilo para revisión humana.
repurposer	src/agents/repurposer/index.ts	Volante de contenido (Content Flywheel): convierte contenido antiguo en nuevos posts.
upload_post	src/agents/upload-post/index.ts	Disparador final que gestiona la subida de imágenes y programación en redes.

---

🎛️ Características Técnicas & Patrones de Diseño

Innovaciones de Arquitectura de Producción

1. Deduplicación Inteligente con LangGraph Store: Al alcanzar el nodo humanNode, todas las URLs analizadas se persisten en el Store. Si una URL ya fue procesada en ejecuciones previas, el grafo redirige a END para evitar spam o contenido repetido (SKIP_USED_URLS_CHECK=true para omitir).
2. Human-in-the-Loop (HITL) Desacoplado: Utiliza la primitiva nativa interrupt() de LangGraph. El estado completo del hilo se congela en base de datos hasta que el operador envía una acción vía Agent Inbox.
3. Autenticación Delegada con Arcade AI: Elimina la fricción de crear apps de desarrollador en Twitter y LinkedIn usando Arcade.dev como broker seguro de tokens OAuth2.
4. Extracción Multi-Modal Adaptativa:
   • Artículos web: Extraídos limpiamente en Markdown usando FireCrawl.
   • Videos de YouTube: Transcripción y análisis de frames mediante Google Vertex AI / Gemini.
   • Repositorios GitHub: Lectura de Readmes, releases y árboles vía Octokit.
   • Screenshots: Renderizado headless de previsualizaciones con Playwright.

---

📊 Reglas de Redacción & Prompt Engineering

El agente sigue una estricta estructura compositiva configurable en src/agents/generate-post/prompts/:

┌────────────────────────────────────────────────────────┐
│ 1. HEADER (Gancho / Hook)                              │
│    - Máximo 1-2 líneas directas, sin clickbait barato │
│    - Enfoque en el problema o hito técnico real        │
├────────────────────────────────────────────────────────┤
│ 2. BODY (Cuerpo / Desglose Técnico)                    │
│    - 2 a 4 viñetas concisas con datos duros            │
│    - Lo que hace único al proyecto / arquitectura      │
├────────────────────────────────────────────────────────┤
│ 3. CALL TO ACTION (CTA & Enlace)                       │
│    - Invitación a probar, leer el repo o documentarse │
│    - Inserción limpia de la URL de origen             │
└────────────────────────────────────────────────────────┘

• BUSINESS_CONTEXT: Define la identidad y el ecosistema de la marca para que el LLM evalúe si el contenido es relevante.
• TWEET_EXAMPLES: Few-shot prompting con ejemplos reales de alto engagement en la industria tech.
• POST_CONTENT_RULES: Prohíbe frases cliché (“Dive in”, “Game changer”, emojis excesivos) y fuerza precisión técnica.

---

⚡ Guía de Instalación y Uso Rápido

Modo Quickstart (Básico)

1. Clonar e Instalar Dependencias

git clone https://github.com/langchain-ai/social-media-agent.git
cd social-media-agent
yarn install

2. Configurar Variables de Entorno (.env)

cp .env.quickstart.example .env

Variables mínimas requeridas:

# Trazas y observabilidad
LANGSMITH_API_KEY="lsv2_pt_..."
LANGSMITH_TRACING_V2=true
 
# Modelo LLM
ANTHROPIC_API_KEY="sk-ant-..."
 
# Scraping web profundo
FIRECRAWL_API_KEY="fc-..."
 
# Autenticación universal en Twitter & LinkedIn
ARCADE_API_KEY="arc_..."
USE_ARCADE_AUTH=true
TWITTER_USER_ID="tu_usuario_twitter"
LINKEDIN_USER_ID="tu_usuario_linkedin"

3. Levantar Servidor LangGraph en Memoria

# Inicia el servidor LangGraph en el puerto 54367
yarn langgraph:in_mem:up

4. Ejecutar Generación de Prueba

yarn generate_post

---

📱 Conexión con Agent Inbox (HITL)

Para gestionar las aprobaciones interactivas:

1. Ingresa a la interfaz web oficial: dev.agentinbox.ai.
2. Haz clic en Add Graph y configura:
   • Graph ID: generate_post
   • Graph API URL: http://localhost:54367
   • Nombre: Social Media Agent (Local)
3. Tan pronto como el grafo analice un enlace y genere el borrador, el hilo entrará en estado pausado y aparecerá en tu bandeja de entrada para Aprobar, Editar texto o Rechazar.

---

⏰ Automatización con Slack & Crons

Para automatizar la ingesta pasiva mientras trabajas:

# 1. Configurar el ID del canal de Slack en scripts/crons/create-cron.ts
# 2. Registrar el cron job diario en el servidor LangGraph:
yarn cron:create
 
# Listar crons activos
yarn cron:list
 
# Eliminar cron job
yarn cron:delete

Flujo de Trabajo Recomendado

Envía enlaces interesantes durante el día a un canal de Slack #content-ideas. El cron se ejecuta una vez al día a medianoche, analiza cada enlace, descarta duplicados, genera borradores para Twitter y LinkedIn, y los deja listos en tu Agent Inbox para revisión con un solo clic cada mañana.