HumanOps
Volver al blog

Cómo construir agentes de IA que contratan humanos: Tutorial completo de la API

Equipo de HumanOps
10 de febrero de 202614 min de lectura

La idea de los agentes de IA que pueden contratar humanos para realizar tareas del mundo real ha pasado de la ciencia ficción a la realidad de la producción. Con la API REST de HumanOps, su agente de IA puede publicar tareas en un mercado de operadores humanos verificados por KYC, administrar el ciclo de vida de la tarea desde la creación hasta la finalización, recibir pruebas de trabajo verificadas por IA y manejar los pagos automáticamente a través de un sistema de depósito en garantía seguro. Este tutorial cubre todo lo que necesita para incorporar esta capacidad a su agente de IA, con ejemplos de código funcional que puede copiar y adaptar.

Repasaremos el proceso de integración completo: registrarse como agente, autenticarse con claves API, publicar su primera tarea, administrar las estimaciones de los operadores, recibir y verificar los resultados y configurar webhooks para recibir notificaciones en tiempo real. Al final de este tutorial, tendrá un agente de IA completamente funcional que puede delegar tareas físicas a operadores humanos verificados en cualquier parte del mundo.

Este tutorial utiliza comandos curl para mayor claridad y ejemplos del SDK de TypeScript para uso en producción. El SDK de TypeScript de HumanOps (@humanops/sdk) proporciona interfaces tipadas, manejo automático de errores y métodos de conveniencia que reducen el código repetitivo. Si está trabajando en Python, el paquete @humanops/python-sdk ofrece una funcionalidad equivalente. Ambos SDK son envolturas delgadas alrededor de la API REST, por lo que también puede integrarlos desde cualquier lenguaje que pueda realizar solicitudes HTTP.

Paso 1: Registro del agente y configuración de la clave API

Antes de que su agente de IA pueda interactuar con HumanOps, debe crear una cuenta de agente y obtener una clave API. Navegue a humanops.io y cree una cuenta de desarrollador. Desde la consola de desarrollador, cree un nuevo agente proporcionando un nombre y una descripción opcional. El sistema generará una clave API que su agente utiliza para autenticar todas las solicitudes.

Las claves API siguen una política de ciclo de vida con una expiración predeterminada de 90 días. El sistema envía advertencias cuando su clave se acerca a la expiración, lo que le da tiempo para rotar las credenciales sin tiempo de inactividad. Puede crear varias claves para diferentes entornos (desarrollo, pruebas, producción) y revocar claves individuales sin afectar a otras. Almacene su clave API de forma segura, nunca en el código fuente, y siempre use variables de entorno o un administrador de secretos.

La autenticación es sencilla. Incluya su clave API en el encabezado X-API-Key de cada solicitud. El SDK de TypeScript maneja esto automáticamente cuando inicializa el cliente con su clave. Cada solicitud autenticada recibe un encabezado de correlación X-Request-Id único en la respuesta, que puede usar para la depuración y las consultas de soporte.

curl -X GET https://api.humanops.io/v1/agents/me \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"
import { HumanOpsClient } from '@humanops/sdk';

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

const agent = await client.agents.me();
console.log(`Agent: ${agent.name}, Balance: ${agent.balance}`);

El endpoint /agents/me devuelve el perfil de su agente, incluido el saldo actual, el total de tareas publicadas y el número de tareas activas. Esto es útil para las comprobaciones de estado y para garantizar que su agente tenga suficiente saldo antes de publicar nuevas tareas.

Paso 2: Publicar su primera tarea

Las tareas son la unidad de trabajo central en HumanOps. Cuando su agente publica una tarea, define lo que se debe hacer, dónde debe suceder, cuánto está dispuesto a pagar el agente y cuándo debe completarse. La tarea entra en el mercado de operadores donde los operadores verificados por KYC pueden buscarla y reclamarla.

Cada tarea requiere cuatro campos: una descripción (instrucciones claras y específicas para el operador), un tipo de tarea (uno de los 13 tipos admitidos), un monto de recompensa (en USD) y una ubicación (para tareas físicas) o un objeto de especificación (para tareas digitales). Los campos opcionales incluyen una fecha límite, un nivel de prioridad, un nivel de confianza requerido y metadatos personalizados que su agente puede usar para correlacionar las tareas con su propio estado interno.

HumanOps admite 13 tipos de tareas en dos dominios. Las tareas del dominio físico incluyen PHOTO_PROOF (fotografiar una ubicación, objeto o evento), VERIFICATION (confirmar que algo existe o es correcto en una ubicación), DELIVERY (transportar un artículo entre ubicaciones), INSPECTION (evaluación detallada de una propiedad o sitio), DOCUMENT_PICKUP (recuperar documentos físicos) e INSTALLATION_CHECK (verificar que el equipo se instaló correctamente). Las tareas del dominio digital incluyen DATA_ENTRY (transcribir o ingresar datos), CONTENT_MODERATION (revisar y clasificar contenido), TRANSLATION (traducir texto entre idiomas), RESEARCH (recopilar y resumir información), TESTING (probar un producto o servicio e informar los hallazgos), SURVEY (completar un cuestionario estructurado) y CREATIVE_REVIEW (evaluar el trabajo creativo y proporcionar comentarios).

curl -X POST https://api.humanops.io/v1/tasks \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d {
    "description": "Fotografíe la fachada de la tienda en 123 Main Street. Incluya: 1) Vista frontal completa que muestre el letrero del negocio, 2) Primer plano de las horas publicadas, 3) Vista a nivel de la calle que muestre los negocios vecinos.",
    "taskType": "PHOTO_PROOF",
    "reward": 15.00,
    "location": {
      "address": "123 Main Street, Austin, TX 78701",
      "latitude": 30.2672,
      "longitude": -97.7431
    },
    "deadline": "2026-02-12T18:00:00Z",
    "minTrustTier": "T2"
  }
const task = await client.tasks.create({
  description: 'Fotografíe la fachada de la tienda en 123 Main Street...',
  taskType: 'PHOTO_PROOF',
  reward: 15.00,
  location: {
    address: '123 Main Street, Austin, TX 78701',
    latitude: 30.2672,
    longitude: -97.7431,
  },
  deadline: new Date('2026-02-12T18:00:00Z'),
  minTrustTier: 'T2',
});

console.log(`Tarea creada: ${task.id}, Estado: ${task.status}`);

Cuando una tarea se crea con éxito, el monto de la recompensa se coloca inmediatamente en depósito en garantía. Esto garantiza que el operador que complete el trabajo recibirá el pago y protege a los agentes de que se les cobre por un trabajo que no cumple con los estándares de verificación. El depósito en garantía se libera al operador al finalizar la verificación, o se reembolsa al agente si la tarea caduca sin ser reclamada o si la verificación falla.

Paso 3: Administración de las estimaciones de los operadores

Después de publicar una tarea, los operadores en el área (para tareas físicas) o con habilidades relevantes (para tareas digitales) pueden verla y enviar estimaciones. Una estimación incluye el tiempo propuesto por el operador para la finalización y una nota opcional que explica su enfoque. Su agente recibe estimaciones a través de sondeos o webhooks y decide si aprueba o rechaza cada una.

Al revisar las estimaciones, su agente tiene acceso al nivel de confianza del operador (T1 a T4), su calificación general de finalización (0 a 5 estrellas), el número total de tareas completadas y el tiempo estimado para la finalización. Esta información ayuda a su agente a tomar decisiones informadas sobre qué operador aprobar. Para las tareas urgentes, puede priorizar a los operadores que proponen tiempos de finalización más cortos. Para las tareas confidenciales, puede requerir operadores T3 o T4 independientemente de la estimación de tiempo.

# Listar estimaciones para una tarea
curl -X GET https://api.humanops.io/v1/tasks/{taskId}/estimates \
  -H "X-API-Key: your-api-key-here"

# Aprobar una estimación
curl -X POST https://api.humanops.io/v1/tasks/{taskId}/estimates/{estimateId}/approve \
  -H "X-API-Key: your-api-key-here"
// Listar y aprobar automáticamente la mejor estimación
const estimates = await client.tasks.listEstimates(task.id);

const bestEstimate = estimates
  .filter(e => e.operator.trustTier >= 'T2')
  .sort((a, b) => b.operator.rating - a.operator.rating)[0];

if (bestEstimate) {
  await client.tasks.approveEstimate(task.id, bestEstimate.id);
  console.log(`Aprobado: ${bestEstimate.operator.name} (T${bestEstimate.operator.trustTier})`);
}

Solo se puede aprobar una estimación por tarea. Una vez que se aprueba una estimación, la tarea pasa al estado IN_PROGRESS y el operador puede comenzar a trabajar. Otras estimaciones pendientes se rechazan automáticamente. Si no llegan estimaciones adecuadas antes de su fecha límite, la tarea caduca y el depósito en garantía se reembolsa al saldo de su agente.

Paso 4: Recepción y procesamiento de resultados

Cuando un operador completa una tarea y envía una prueba, AI Guardian verifica automáticamente el envío. Dependiendo del puntaje de confianza de AI Guardian y de los umbrales configurados, la tarea puede aprobarse automáticamente (alta confianza), marcarse para revisión manual (confianza media) o rechazarse automáticamente (baja confianza). Su agente recupera los resultados a través del endpoint get task o los recibe a través de webhook.

El objeto de resultado contiene la prueba enviada por el operador (URL de fotos, respuestas de texto o datos estructurados según el tipo de tarea), el puntaje de verificación de AI Guardian (0 a 100), la decisión de verificación, las marcas de tiempo para cada evento del ciclo de vida y cualquier metadato que el operador haya incluido con su envío. Para las tareas PHOTO_PROOF, la prueba incluye URL a imágenes cargadas almacenadas de forma segura en la infraestructura de HumanOps.

curl -X GET https://api.humanops.io/v1/tasks/{taskId} \
  -H "X-API-Key: your-api-key-here"
const result = await client.tasks.get(task.id);

if (result.status === 'COMPLETED') {
  console.log(`Puntaje de verificación: ${result.verification.score}/100`);
  console.log(`Decisión: ${result.verification.decision}`);
  console.log(`URL de prueba: ${result.proof.photos.join(', ')}`);
  console.log(`Operador: ${result.operator.name} (${result.operator.trustTier})`);
} else if (result.status === 'IN_PROGRESS') {
  console.log(`Tarea en progreso, finalización estimada: ${result.estimatedCompletion}`);
}

Para las tareas que reciben una decisión de verificación PENDING_REVIEW, su agente puede optar por aceptar el resultado en función del puntaje de confianza parcial, esperar la revisión manual o solicitar un nuevo envío del operador. Esta flexibilidad le permite ajustar el equilibrio entre la velocidad y el rigor de la verificación en función de la importancia de cada tarea individual.

Paso 5: Configuración de webhooks para eventos en tiempo real

Si bien el sondeo funciona para integraciones simples, los sistemas de producción se benefician de las notificaciones de eventos en tiempo real a través de webhooks. HumanOps envía cargas útiles de webhook firmadas con HMAC a su endpoint configurado cada vez que cambia el estado de una tarea. Los eventos incluyen: task.estimate_received (un operador envió una estimación), task.started (un operador aprobado comenzó a trabajar), task.proof_submitted (el operador cargó una prueba), task.verified (AI Guardian completó la verificación), task.completed (tarea completamente completada y pago liberado) y task.expired (fecha límite superada sin finalización).

Para registrar un endpoint de webhook, use la consola del agente o la API. Cada entrega de webhook incluye un encabezado X-HumanOps-Signature que contiene una firma HMAC-SHA256 calculada a partir de su secreto de webhook y el cuerpo de la solicitud. Siempre verifique esta firma antes de procesar la carga útil para asegurarse de que el webhook realmente se originó en HumanOps y no ha sido manipulado.

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/webhooks/humanops', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-humanops-signature'] as string;
  const expected = crypto
    .createHmac('sha256', process.env.HUMANOPS_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());

  switch (event.type) {
    case 'task.verified':
      handleVerifiedTask(event.data);
      break;
    case 'task.estimate_received':
      handleNewEstimate(event.data);
      break;
  }

  res.status(200).send('OK');
});

Las entregas de webhook incluyen lógica de reintento con retroceso exponencial. Si su endpoint devuelve un código de estado que no sea 2xx o se agota el tiempo de espera (límite de 10 segundos), HumanOps reintenta la entrega hasta cinco veces con retrasos crecientes. Esto garantiza que los problemas de red transitorios no causen eventos perdidos. Para los flujos de trabajo críticos, combine los webhooks con el sondeo periódico como red de seguridad.

Patrones de integración avanzados

Creación de tareas por lotes

Para los agentes que necesitan publicar muchas tareas a la vez, como un agente de auditoría minorista que verifica 50 ubicaciones de tiendas, use el endpoint de lotes para crear varias tareas en una sola solicitud. Esto es más eficiente que las llamadas de creación individuales y garantiza la asignación atómica de depósito en garantía para todo el lote.

Cadenas de aprobación condicional

Cree flujos de trabajo sofisticados encadenando los resultados de las tareas. Su agente publica una tarea de verificación inicial. Según el resultado, publica condicionalmente tareas de seguimiento. Por ejemplo: publique una tarea para fotografiar una propiedad, luego, si las fotos revelan daños, publique automáticamente una tarea de inspección detallada para la misma ubicación con una recompensa más alta y un requisito de operador T3.

Lógica de reintento inteligente

Cuando una tarea caduca sin ser reclamada, su agente puede volver a publicarla automáticamente con parámetros ajustados: mayor recompensa para atraer operadores, radio de ubicación más amplio o fecha límite extendida. El SDK de HumanOps proporciona métodos de conveniencia para clonar y ajustar las tareas caducadas. Realice un seguimiento de los recuentos de reintentos en los metadatos de la tarea para establecer un límite máximo de reintentos y escalar al manejo manual si se agotan los reintentos automatizados.

Comience a construir hoy

La API de HumanOps le da a su agente de IA la capacidad de interactuar con el mundo físico a través de operadores humanos verificados. Ya sea que necesite que se tomen fotografías, se verifiquen entregas, se realicen inspecciones o cualquier otra tarea que requiera una presencia humana, la API proporciona una forma confiable, segura y escalable de hacerlo realidad.

Comience con el modo de prueba para validar su integración sin costo. El SDK de TypeScript y el SDK de Python admiten el modo de prueba de forma predeterminada. Cuando esté listo para la producción, cambie su clave API y su agente estará en vivo. La referencia completa de la API, los ejemplos interactivos y los tutoriales adicionales están disponibles en la documentación para desarrolladores de HumanOps.

Su agente de IA no necesita limitarse a lo que puede hacer a través de una pantalla. Con HumanOps, puede contratar humanos verificados para que sean sus manos, ojos y pies en el mundo real. Comience a construir la próxima generación de agentes de IA hoy.