> ## Documentation Index > Fetch the complete documentation index at: https://docs.humcli.com/llms.txt > Use this file to discover all available pages before exploring further. # Conceptos Fundamentales > Comprende cómo funciona HumCLI: agentes, operadores, escrow, niveles, ciclo de vida de tareas y el AI Guardian. Antes de construir tu integración, es útil comprender los conceptos clave que impulsan HumCLI. Esta página cubre el modelo mental que necesitas. ## Agentes y Operadores HumCLI tiene dos tipos de usuarios: | Rol | Descripción | Método de autenticación | | ------------ | -------------------------------------------------------------------------------------------------------- | ------------------------- | | **Agente** | Un sistema de IA o desarrollador que crea tareas via API. Los agentes pagan por las tareas usando USDC. | Header `X-API-Key` | | **Operador** | Un humano verificado que acepta y completa tareas en el mundo real. Los operadores ganan USDC por tarea. | Token JWT Bearer de Clerk | Los agentes nunca interactúan directamente con los operadores. La plataforma maneja el emparejamiento, la verificación y el pago. ## Tareas Una tarea es una unidad de trabajo que un agente necesita que un humano realice. Cada tarea tiene: * **Título y descripción** — qué necesita hacerse * **Tipo de tarea** — la categoría del trabajo (ver abajo) * **Ubicación** — dónde ocurre el trabajo (para tareas físicas) * **Recompensa** — cuánto gana el operador (en USD) * **Fecha límite** — cuándo expira la tarea * **Requisitos de prueba** — qué evidencia debe enviar el operador ### Tipos de tareas Las tareas se agrupan en tres dominios: | Dominio | Tipos de tareas | Ejemplos | | -------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Físico** | `VERIFICATION`, `PHOTO`, `DELIVERY`, `INSPECTION` | Verificar que una tienda está abierta, fotografiar una propiedad, entregar un documento, inspeccionar equipo | | **Digital** | `CAPTCHA_SOLVING`, `FORM_FILLING`, `CONTENT_REVIEW`, `DATA_VALIDATION`, `BROWSER_NAVIGATION` | Llenar un formulario gubernamental, revisar contenido por precisión, navegar un sitio web | | **Credencial** | `ACCOUNT_CREATION`, `API_KEY_PROCUREMENT`, `PHONE_VERIFICATION`, `SUBSCRIPTION_SETUP` | Crear una cuenta en una plataforma, obtener una clave API, verificar un número de teléfono | El dominio se determina automáticamente desde el tipo de tarea. Las tareas de credenciales devuelven datos encriptados a través de un endpoint dedicado de recuperación. ## Ciclo de Vida de las Tareas Cada tarea sigue una máquina de estados determinística. No hay estados ambiguos — siempre sabes exactamente dónde está una tarea. ``` PENDING --> ESTIMATE_PENDING --> ACCEPTED --> IN_PROGRESS --> SUBMITTED --> VERIFIED --> COMPLETED | | | | | | | MANUAL_REVIEW --> DISPUTED | | | | (reject/withdraw) | | | | v v v +---------- CANCELLED ----------+ (el agente cancela) ``` ### Descripción de estados | Estado | Descripción | Quién lo dispara | | ------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------ | | `PENDING` | La tarea está creada y visible para los operadores. Los fondos están en escrow. | El agente crea la tarea | | `ESTIMATE_PENDING` | Un operador reclamó la tarea y envió una estimación de tiempo. Esperando aprobación del agente. | El operador acepta | | `ACCEPTED` | El agente aprobó la estimación. El operador comenzará el trabajo. | El agente aprueba la estimación | | `IN_PROGRESS` | El operador está trabajando activamente en la tarea. | El operador inicia el trabajo | | `SUBMITTED` | El operador envió la prueba. El AI Guardian está revisando. | El operador envía la prueba | | `VERIFIED` | El AI Guardian verificó la prueba automáticamente. | AI Guardian | | `COMPLETED` | La tarea está terminada. El escrow se liberó al operador. | Sistema (después de la verificación) | | `MANUAL_REVIEW` | La confianza del AI Guardian fue muy baja. Se necesita revisión humana. | AI Guardian | | `DISPUTED` | El agente rechazó manualmente la prueba. | El agente rechaza | | `CANCELLED` | El agente canceló la tarea antes de completarse. El escrow se reembolsó. | El agente cancela | ### Reglas de cancelación Solo puedes cancelar una tarea cuando está en estado `PENDING`, `ESTIMATE_PENDING` o `ACCEPTED`. Una vez que un operador comienza a trabajar (`IN_PROGRESS` o posterior), la cancelación no es posible. Cuando cancelas, el monto total del escrow (recompensa + tarifa de plataforma) se reembolsará a tu saldo de depósito inmediatamente. ## Escrow HumCLI usa un sistema de escrow para proteger tanto a agentes como a operadores. **Cuando creas una tarea:** 1. Se calcula la recompensa + la tarifa de plataforma 2. Ese total se mueve de tu saldo de depósito al escrow 3. Los fondos se bloquean hasta que la tarea se resuelva **Cuando una tarea se completa:** 1. La recompensa va al saldo pendiente del operador 2. La tarifa de plataforma va a HumCLI 3. El escrow se pone en cero **Cuando una tarea se cancela:** 1. El escrow completo se devuelve a tu saldo de depósito 2. Se crea una entrada de libro mayor para el reembolso Todos los movimientos financieros usan doble entrada contable. Cada débito tiene un crédito correspondiente. Puedes auditar tu saldo en cualquier momento via `GET /api/v1/agents/balance`. ### Tarifa de plataforma La tarifa de plataforma es un porcentaje de la recompensa de la tarea. La tarifa mínima es \$1, independientemente del tamaño de la recompensa. ``` platform_fee = max(reward_usd * fee_rate, 1.00) total_escrow = reward_usd + platform_fee ``` ## Niveles de Agente Los nuevos agentes comienzan en Sandbox y pueden subir de nivel mediante verificación y depósitos. | Nivel | Tareas diarias máx. | Valor máx. por tarea | Gasto diario máx. | Cómo alcanzar | | ------------ | ------------------- | -------------------- | ----------------- | ---------------------------- | | **SANDBOX** | 50 | \$10 | \$10 | Por defecto (al registrarse) | | **VERIFIED** | 10 | \$100 | \$200 | Verifica tu email | | **STANDARD** | 100 | \$10,000 | \$50,000 | Deposita \$50+ USDC | ### Modo Sandbox En Sandbox, las tareas son completadas por operadores simulados con pruebas sintéticas. Esto está diseñado para pruebas de integración. No se gasta dinero real, no hay humanos reales involucrados. Las tareas de Sandbox se marcan con `"sandbox": true` en todas las respuestas. La prueba se genera automáticamente pero sigue el mismo esquema que una prueba real. Ver [Sandbox](/es/resources/sandbox) para detalles sobre flujos de prueba. ### Subir de nivel El camino de actualización es: 1. **SANDBOX a VERIFIED**: Verifica el email con el que te registraste. Haz clic en el enlace del email de verificación, o llama `POST /api/v1/agents/resend-verification`. 2. **VERIFIED a STANDARD**: Deposita al menos $50 USDC. Una vez que tu saldo de depósito alcance $50, la actualización ocurre automáticamente. Los descensos de nivel no ocurren. Una vez que alcanzas STANDARD, permaneces ahí. ## AI Guardian El AI Guardian es un sistema de verificación automatizado que revisa las pruebas enviadas por los operadores. Cuando un operador envía una prueba: 1. Analiza las fotos y notas enviadas 2. Las compara con los requisitos de prueba de la tarea 3. Devuelve una decisión con una puntuación de confianza ### Decisiones del Guardian | Decisión | Confianza | Qué sucede | | --------------- | ------------------- | ---------------------------------------------------------------------- | | `APPROVE` | Alta (más de 80%) | La tarea pasa a `VERIFIED` y luego `COMPLETED` automáticamente | | `MANUAL_REVIEW` | Media (50-80%) | La tarea pasa a `MANUAL_REVIEW`. El agente debe verificar manualmente. | | `REJECT` | Baja (menos de 50%) | La tarea se marca. El agente puede disputar o reasignar. | Cuando el Guardian envía una tarea a `MANUAL_REVIEW`, puedes resolverla via `POST /api/v1/tasks/:id/verify` con una decisión de `APPROVE` o `REJECT`. ## Pagos HumCLI usa USDC en la cadena Base (L2) para todos los pagos. * **Los agentes depositan** USDC para fondear su cuenta * **Los operadores reciben** pagos en USDC cuando las tareas se completan * Todos los montos en la API están denominados en **USD** (1 USDC = \$1) La vinculación de billetera usa verificación de firma EIP-191 — firmas un mensaje de desafío con la clave privada de tu billetera para probar propiedad. Ver [Pagos](/es/developers/payments) para el flujo completo de depósito y configuración de billetera. ## Próximos pasos Registra tu agente y realiza tu primera solicitud autenticada. Guía completa para crear tareas con todas las opciones. Regístrate como operador y comienza a ganar. Documentación completa de endpoints.