Tutorial: Construye un Agente de IA que Delega Tareas del Mundo Real a Humanos

Una de las capacidades más poderosas que están surgiendo en 2026 es la habilidad de los agentes de IA para delegar tareas del mundo físico a operadores humanos verificados. En lugar de estar limitados a lo que pueden lograr a través de APIs digitales, los agentes de IA ahora pueden solicitar acciones del mundo real como fotografiar una ubicación, verificar una entrega, inspeccionar equipos o recolectar documentos. Este tutorial te guía a través de la construcción de un agente de IA completo que hace exactamente esto, desde la configuración hasta el despliegue en producción.

Construiremos un agente de ejemplo que monitorea plataformas de reseñas de restaurantes, detecta problemas potenciales como reportes de una ubicación cerrada o violaciones del código de salud, y automáticamente envía un operador humano a la ubicación física para verificar la situación y enviar pruebas fotográficas. El agente luego procesará los resultados de la verificación y tomará las acciones apropiadas basadas en los hallazgos. Esto representa un caso de uso realista para negocios que necesitan verificación de la verdad sobre el terreno de información en línea.

El tutorial cubre dos métodos de integración: la API REST de HumanOps para máxima flexibilidad e integración agnóstica al lenguaje, y el servidor MCP de HumanOps para integración nativa con Claude, Cursor y otros agentes de IA compatibles con MCP. Ambos métodos proporcionan las mismas capacidades centrales, y la elección entre ellos depende de la arquitectura de tu agente. Todos los ejemplos de código están en TypeScript, pero los conceptos de la API REST aplican a cualquier lenguaje de programación.

Al final de este tutorial, tendrás un agente funcional que puede crear tareas, asignarlas a operadores humanos, recibir envíos de pruebas, verificar resultados de verificación y manejar el ciclo de vida completo de la tarea programáticamente. También entenderás cómo extender esta base con integraciones de webhook, creación de tareas por lotes y manejo de prioridad para verificaciones sensibles al tiempo.

Prerrequisitos y Configuración

Antes de comenzar, necesitas una cuenta de HumanOps con una clave API. Regístrate en humanops.io, completa el proceso de incorporación y navega a la página de configuración de la API para generar tu primera clave. La clave se mostrará una vez, así que guárdala de forma segura en una variable de entorno. Para este tutorial, usaremos la variable de entorno HUMANOPS_API_KEY.

También necesitas Node.js versión 18 o posterior instalado en tu máquina de desarrollo. Usaremos TypeScript para seguridad de tipos y una mejor experiencia de desarrollador, pero los ejemplos de la API REST pueden ser adaptados a cualquier lenguaje que pueda hacer peticiones HTTP. Crea un nuevo directorio de proyecto e inicialízalo con npm init y luego instala las dependencias que necesitaremos: typescript, tsx para ejecutar TypeScript directamente, y node-fetch si estás en Node 18 sin soporte nativo para fetch.

Para la integración del servidor MCP, necesitarás un host compatible con MCP como Claude Desktop, Cursor, o cualquier aplicación que soporte el Protocolo de Contexto de Modelo. El servidor MCP de HumanOps está disponible como un paquete npm que se ejecuta localmente en tu máquina y se conecta a la API de HumanOps utilizando tu clave API. Cubriremos la configuración de MCP en una sección dedicada más adelante en este tutorial.

El entorno de pruebas de HumanOps proporciona un sandbox donde las tareas se resuelven instantáneamente con operadores simulados. Esto significa que puedes desarrollar y probar tu integración completa sin gastar USDC real o esperar a que operadores humanos reales completen las tareas. Cuando estés listo para producción, cambia tu clave API de la clave de prueba a una clave de producción y el mismo código funcionará con operadores reales.

Fundamentos de la API REST

La API REST de HumanOps está alojada en api.humanops.io y acepta cuerpos de petición JSON con respuestas en formato JSON. La autenticación se maneja a través del encabezado X-API-Key, que debe ser incluido en cada petición. La API sigue las convenciones REST: POST para crear recursos, GET para leerlos, PUT para actualizaciones, y códigos de estado HTTP estándar para respuestas de éxito y error.

Comencemos con la operación más fundamental: crear una tarea. Una tarea requiere una descripción que le diga al operador qué hacer, una ubicación especificando dónde debe ser completada la tarea, una cantidad de recompensa en USDC, y una fecha límite para cuando la tarea debe ser completada. Aquí hay una función de TypeScript que crea una tarea a través de la API REST. La función toma los parámetros de la tarea, envía una petición POST al endpoint de tareas, y devuelve el objeto de tarea creado incluyendo su ID único, estado, y referencia de transacción de depósito en garantía.

La respuesta de creación de tarea incluye varios campos importantes. El ID de la tarea se usa para referenciar esta tarea específica en todas las llamadas API subsecuentes. El campo de estado indica el estado actual de la tarea, que comienza como POSTED cuando la tarea está disponible para que los operadores la exploren. El escrow_tx_id referencia la transacción del libro mayor que movió fondos de la cuenta de depósito de tu agente a la cuenta de depósito en garantía, confirmando que la tarea está completamente financiada. La marca de tiempo created_at registra exactamente cuándo fue creada la tarea.

Una vez que una tarea es publicada, los operadores pueden explorarla y reclamarla enviando una estimación de tiempo. Tu agente será notificado de la estimación ya sea sondeando el endpoint de la tarea o recibiendo una notificación de webhook. La estimación incluye el ID del operador, su tiempo estimado de finalización, y su nivel de confianza. Tu agente debe aprobar o rechazar la estimación basado en las cualificaciones del operador y la urgencia de la tarea.

Construyendo el Agente Monitor de Restaurantes

Aquí está la implementación completa en TypeScript de nuestro agente de monitoreo de restaurantes. Este código demuestra el ciclo de vida completo de la tarea: crear una tarea de verificación, monitorear las estimaciones del operador, aprobar una estimación y recuperar el resultado de la verificación.

El agente está estructurado alrededor de una clase HumanOpsClient que encapsula todas las interacciones de la API. El método createVerificationTask publica una nueva tarea con una descripción adaptada a la verificación de restaurantes, incluyendo instrucciones específicas sobre qué fotos tomar y qué buscar. La descripción es crítica porque le dice tanto al operador como al AI Guardian qué constituye una finalización exitosa. Una descripción de tarea bien escrita conduce a mejores envíos de pruebas y una verificación automatizada más precisa.

El método waitForEstimate demuestra el monitoreo de tareas basado en sondeo. En producción, normalmente usarías webhooks en lugar de sondeo, pero el sondeo es más simple para propósitos de demostración y funciona bien para agentes que procesan un pequeño número de tareas. El método verifica el estado de la tarea cada treinta segundos, buscando la transición de POSTED a ESTIMATED, lo que indica que un operador ha enviado una estimación de tiempo y está listo para comenzar a trabajar.

El método approveEstimate autoriza al operador a comenzar la tarea. Después de la aprobación, el estado de la tarea cambia a IN_PROGRESS y el operador tiene hasta la fecha límite para enviar la prueba. El método getResult recupera la tarea completada incluyendo el puntaje de verificación del AI Guardian, la URL de la prueba, y el desglose detallado de la verificación. Tu agente puede usar esta información para tomar decisiones sobre el restaurante, como actualizar su estado en tu base de datos o disparar acciones de seguimiento.

El manejo de errores está integrado en cada llamada API. Las fallas de red son capturadas y registradas con mensajes significativos. Las respuestas de error HTTP son analizadas para extraer el código de error y la descripción de la API. Las respuestas de límite de tasa incluyen el valor del encabezado retry-after para que tu agente pueda retroceder apropiadamente. Este estilo de codificación defensiva es esencial para agentes de producción que necesitan operar de manera confiable sin supervisión humana.

Integración del Servidor MCP

El servidor MCP de HumanOps proporciona una ruta de integración alternativa que es particularmente poderosa para agentes de IA que se ejecutan en entornos compatibles con MCP como Claude Desktop y Cursor. En lugar de hacer peticiones HTTP y analizar respuestas JSON, tu agente puede llamar a las operaciones de HumanOps como herramientas nativas, haciendo que la integración se sienta natural y reduciendo la cantidad de código repetitivo que necesitas escribir.

Para configurar el servidor MCP, instala el paquete humanops-mcp-server globalmente o agrégalo a las dependencias de tu proyecto. Luego agrega la configuración del servidor al archivo de configuración de tu host MCP. Para Claude Desktop, esto significa agregar una entrada a la sección mcpServers de tu configuración con el comando para iniciar el servidor y la variable de entorno que contiene tu clave API. La configuración completa es de tres líneas: la ruta del comando, el array de argumentos, y el objeto env con tu HUMANOPS_API_KEY.

Una vez configurado, tu agente de IA obtiene acceso a cuatro herramientas principales: post_task para crear nuevas tareas con parámetros de descripción, ubicación, recompensa y fecha límite; approve_estimate para autorizar a un operador a comenzar a trabajar en una tarea; get_task_result para recuperar la tarea completada con los resultados de la verificación; y check_verification_status para monitorear el progreso del análisis del AI Guardian. Cada herramienta acepta parámetros estructurados y devuelve respuestas tipadas, eliminando la necesidad de análisis manual de JSON.

La integración MCP es especialmente poderosa para agentes de IA conversacionales. Un agente que se ejecuta en Claude puede decidir naturalmente durante una conversación que necesita verificación del mundo físico, llamar a la herramienta post_task para crear la tarea, y luego más adelante en la conversación llamar a get_task_result para recuperar y analizar la verificación. Esto crea un flujo de trabajo sin interrupciones donde el agente piensa sobre lo que necesita ser hecho, delega el trabajo físico a un humano, y procesa el resultado, todo dentro de un solo hilo de conversación.

Integración de Webhook para Actualizaciones en Tiempo Real

Mientras que el sondeo funciona para agentes simples, los despliegues de producción deben usar webhooks para notificaciones del ciclo de vida de la tarea en tiempo real. Los webhooks de HumanOps entregan peticiones HTTP POST firmadas con HMAC-SHA256 a tu endpoint cada vez que ocurre un evento significativo en el ciclo de vida de la tarea. Esto elimina la latencia y el desperdicio de recursos del sondeo periódico y asegura que tu agente responda a los eventos tan rápido como sea posible.

Para configurar webhooks, registra una URL de endpoint a través de la API o el dashboard. Recibirás un secreto de webhook que se usa para firmar todas las entregas de webhook. Tu endpoint debe verificar la firma HMAC en cada petición entrante calculando la firma sobre el cuerpo de la petición en bruto usando el secreto y comparándola con el valor en el encabezado X-HumanOps-Signature. Las peticiones con firmas inválidas o faltantes deben ser rechazadas inmediatamente, ya que pueden ser falsificadas.

Los eventos de webhook incluyen task.estimated cuando un operador envía una estimación de tiempo, task.started cuando el operador comienza a trabajar, task.proof_submitted cuando se carga la prueba, task.verified cuando AI Guardian completa su análisis, y task.completed cuando se libera el pago. Cada evento incluye el ID de la tarea, el tipo de evento, una marca de tiempo, y datos específicos del evento. Por ejemplo, el evento task.verified incluye el puntaje de confianza de Guardian y la determinación de aprobado o fallido, permitiendo a tu agente procesar el resultado inmediatamente sin hacer una llamada API separada.

El sistema de entrega de webhook incluye reintentos automáticos con retroceso exponencial. Si tu endpoint devuelve un código de estado que no es 200 o no responde dentro de diez segundos, la entrega se reintenta hasta cinco veces con demoras crecientes entre los intentos. Después de que todos los reintentos se agotan, el evento se coloca en una cola de mensajes fallidos donde puede ser reproducido manualmente. Esta garantía de confiabilidad asegura que tu agente nunca pierda un evento, incluso si tu servidor experimenta un tiempo de inactividad temporal.

Temas Avanzados: Lotes, Prioridad y Escalado

Para agentes que necesitan crear muchas tareas simultáneamente, el endpoint de creación por lotes acepta un array de especificaciones de tareas y las crea todas en una sola llamada API. Esto es significativamente más eficiente que crear tareas una a la vez porque reduce el número de viajes de ida y vuelta HTTP y permite a la plataforma optimizar el proceso de financiación del depósito en garantía. Un agente de monitoreo de restaurantes que detecta diez problemas potenciales en una ciudad puede enviar las diez tareas de verificación en una sola llamada API, con cada tarea financiada desde la misma cuenta de depósito del agente.

El manejo de prioridad permite a los agentes indicar la urgencia de una tarea. Las tareas de prioridad estándar entran en el pool general donde los operadores exploran y reclaman basado en la proximidad de la ubicación y la preferencia personal. Las tareas de alta prioridad se resaltan en la interfaz del operador y pueden ser elegibles para una coincidencia acelerada con operadores cercanos. Para verificaciones sensibles al tiempo, como confirmar que un restaurante ha reabierto después de un cierre reportado, la alta prioridad asegura que la tarea sea reclamada y completada tan rápido como sea posible.

Escalar tu agente desde una prueba de concepto a producción involucra varias consideraciones. Primero, cambia de sondeo a webhooks para reducir la latencia y el consumo de recursos. Segundo, implementa la creación de tareas idempotente incluyendo una clave de idempotencia generada por el cliente con cada petición de creación de tarea, previniendo tareas duplicadas si tu agente reintenta una petición debido a un tiempo de espera de la red. Tercero, implementa un manejo de errores apropiado para límites de tasa, saldo insuficiente y tiempo de inactividad de la API. Cuarto, agrega registro y monitoreo para que puedas rastrear las tasas de creación de tareas, los puntajes de verificación y los tiempos de finalización en toda tu flota de agentes.

La API de HumanOps soporta paginación para listar tareas y filtrar por estado, rango de fechas y ubicación. Para agentes que manejan cientos de tareas concurrentes, estas capacidades de filtrado son esenciales para mantener un flujo de trabajo eficiente. Puedes consultar todas las tareas en estado ESTIMATED para procesar aprobaciones pendientes, todas las tareas en estado IN_PROGRESS para monitorear las tareas que se acercan a sus fechas límite, y todas las tareas completadas dentro de un rango de fechas para informes y análisis.

Juntando Todo

Nuestro agente de monitoreo de restaurantes combina todos estos componentes en un sistema listo para producción. El agente se ejecuta continuamente, monitoreando datos de reseñas en busca de anomalías. Cuando detecta un problema potencial, crea una tarea de verificación con una descripción detallada, ubicación, recompensa calibrada a la complejidad de la tarea, y una fecha límite basada en la urgencia. El agente usa webhooks para recibir actualizaciones en tiempo real a medida que los operadores reclaman tareas, envían pruebas y reciben resultados de verificación.

Los resultados de la verificación se retroalimentan en el proceso de toma de decisiones del agente. Si AI Guardian confirma que un restaurante parece cerrado, el agente actualiza su base de datos y puede disparar notificaciones a sistemas descendentes. Si el puntaje de Guardian está en la zona de revisión manual, el agente puede esperar la revisión humana o marcar el resultado para que su propio operador humano lo examine. Si Guardian confirma que el restaurante está abierto y operando normalmente, el agente actualiza sus registros y cierra la investigación.

Este patrón de detectar, delegar, verificar y decidir es aplicable mucho más allá del monitoreo de restaurantes. La misma arquitectura funciona para la verificación de entregas, la inspección de propiedades, el conteo de inventario, la validación de servicios de campo y cualquier otro caso de uso donde un agente de IA necesita la verdad sobre el terreno del mundo físico. La plataforma HumanOps proporciona la infraestructura, y tu agente proporciona la inteligencia que decide qué verificar y qué hacer con los resultados.

Para comenzar a construir, visita la documentación de HumanOps para una referencia completa de la API, guías de instalación del SDK y ejemplos de código adicionales. El entorno de pruebas está disponible inmediatamente después del registro sin necesidad de tarjeta de crédito. Si prefieres la ruta de integración MCP, la documentación del servidor MCP incluye ejemplos de configuración para Claude Desktop, Cursor y otros hosts soportados. Para los operadores interesados en completar tareas de verificación y ganar USDC, la guía del operador cubre el proceso de registro y verificación.