Agentes del bot (orquestación)

curl -X POST "https://api.mosend.dev/organizations/${ORG_ID}/bot/agents" \
  -H "X-Api-Key: ${API_KEY}" -H "Content-Type: application/json" \
  -d '{
    "name": "Soporte",
    "description": "Resuelve dudas de uso, garantías y devoluciones de clientes que ya compraron.",
    "systemPrompt": "Eres el asesor de soporte de Tienda X. Responde corto y en español neutro…",
    "provider": "anthropic",
    "model": "claude-sonnet-4-5",
    "enabledTools": ["transfer_to_human", "transfer_to_agent"],
    "routeTags": ["soporte", "garantia"],
    "knowledgeDocIds": ["<docId-politicas>", "<docId-faq>"],
    "phoneNumberIds": [],
    "isDefault": false,
    "enabled": true
  }'

phoneNumberIds dice en qué canales atiende el agente. Los ids son los de phone-numbers, incluidos los números virtuales que representan un canal de web chat o una cuenta de Instagram. Con la lista vacía el agente atiende en todos. Un agente que no está en el canal de la conversación no puede recibirla: ni por etiqueta, ni por traspaso, ni por el router.

En cada turno el bot decide el agente en este orden; el primero que aplica gana:

1. Agente activo de la conversación (activeAgentId): lo fijó un traspaso, el router o un asesor a mano. Se respeta mientras siga habilitado y en ese canal.
2. Etiquetas: si la conversación o el contacto tiene una etiqueta que algún agente reclama en routeTags, ese agente empieza a atender. Sin distinguir mayúsculas; gana el primero por isDefault → sortOrder → fecha de creación.
3. Router IA: solo en el primer contacto y con dos o más agentes en el canal. Un modelo lee el mensaje y las descripciones de los agentes y elige uno.
4. Agente por defecto del canal (isDefault) si nada de lo anterior decidió.

• Cuando el agente cambia queda un evento AGENT_ROUTED en bot-events con via: tag | router | default.
• La etiqueta decide solo al empezar o cuando el activo dejó de estar vigente: no deshace un traspaso. Antes sí lo hacía y la conversación rebotaba entre dos agentes en el mismo mensaje.
• Una etiqueta → un agente. Si intentas dar a un agente una routeTag que otro ya tiene, la API responde 400: «La etiqueta «vip» ya activa al agente «Ventas». Quítasela a uno de los dos.»

Con la herramienta transfer_to_agent habilitada, un agente puede entregar la conversación a un hermano (por ejemplo, ventas detecta un reclamo y lo pasa a soporte). El traspaso es invisible para el cliente: el agente destino responde en el mismo turno, sin "te paso con…" ni silencio. Reglas:

• El destino debe ser un agente real, distinto, habilitado y presente en el canal; cualquier otra cosa se ignora y el agente actual sigue respondiendo.
• Máximo un traspaso por mensaje (evita el rebote A → B → A).
• Queda registrado como AGENT_TRANSFERRED y cuenta en las estadísticas como traspaso saliente de uno y entrante del otro.

Desde el inbox (o tu propio sistema) puedes decidir quién atiende, sin esperar al enrutador:

# Que Soporte atienda esta conversación desde ahora
curl -X PATCH "https://api.mosend.dev/organizations/${ORG_ID}/conversations/${CONVERSATION_ID}/agent" \
  -H "X-Api-Key: ${API_KEY}" -H "Content-Type: application/json" \
  -d '{ "agentId": "<agentId-soporte>" }'

# Soltar: que el enrutador vuelva a decidir en el próximo mensaje
curl -X PATCH "https://api.mosend.dev/organizations/${ORG_ID}/conversations/${CONVERSATION_ID}/agent" \
  -H "X-Api-Key: ${API_KEY}" -H "Content-Type: application/json" \
  -d '{ "agentId": null }'

# Tras un traspaso a humano, devolver la conversación al bot con su contexto
curl -X POST "https://api.mosend.dev/organizations/${ORG_ID}/conversations/${CONVERSATION_ID}/devolver-al-bot" \
  -H "X-Api-Key: ${API_KEY}"

Fijar el agente no reactiva un bot silenciado por handoff: para eso está devolver-al-bot. Y al revés, devolver-al-bot conserva el agente activo que había.

El paso transfer_to_ai de los flujos termina el flujo y deja la conversación en manos de la IA. Con agentId eliges cuál; sin él, el que corresponda por la precedencia de arriba.

{
  "type": "transfer_to_ai",
  "message": "Te dejo con nuestro asesor de ventas.",
  "agentId": "<agentId-ventas>"
}

GET /organizations/{orgId}/bot/agents/stats?dias=30 atribuye a cada agente lo que hizo en el período:

{
  "data": {
    "desde": "2026-08-08T…", "dias": 30,
    "agentes": [
      {
        "agentId": "…", "name": "Ventas", "enabled": true, "isDefault": true,
        "channels": [ { "phoneNumberId": "…", "displayPhoneNumber": "+57 3xx…" } ],
        "conversaciones": 212, "respuestas": 1480,
        "traspasosSalientes": 31, "traspasosEntrantes": 4, "escalamientosAHumano": 18,
        "ventas": 27, "citas": 0, "fallos": 2, "fallosDeModelo": 3,
        "tokensInput": 1900000, "tokensOutput": 210000, "costUsd": 9.4, "chargedUsd": 14.1,
        "latenciaPromedioMs": 2900,
        "porCanal": [ { "phoneNumberId": "…", "label": "+57 3xx…", "respuestas": 1480 } ],
        "ultimosFallos": [ { "at": "…", "conversationId": "…", "error": "…" } ]
      }
    ],
    "sinAtribuir": { "agentId": null, "name": "Sin atribuir (router, flujos o anterior a la medición)", "respuestas": 40, "…": "…" }
  }
}

• sinAtribuir agrupa lo que no tiene agente: el router IA, los flujos y las filas anteriores a que existiera la atribución. Es null si no hay nada huérfano.
• costUsd es el costo real del proveedor; chargedUsd lo que se descontó del saldo (con margen).

La biblioteca de documentos es una por organización; cada agente lee la parte que le asignes con knowledgeDocIds. Cómo cargar fuentes, probar la búsqueda y cerrar vacíos está en Memoria del bot.

1. Crea el agente general y márcalo isDefault en el canal principal.
2. Crea los especializados con una description clara (es lo que lee el router) y sus routeTags: soporte, reseller, vip…
3. Reparte la memoria: cada agente con sus knowledgeDocIds.
4. Habilita transfer_to_agent en los que deban derivar y prueba los cruces con POST …/{agentId}/probador.
5. Etiqueta contactos desde tu CRM (tags) para que el enrutamiento por etiqueta haga el trabajo sin pasar por el router.
6. Mira stats?dias=7 cada semana: muchos escalamientosAHumano o fallos en un agente señalan un prompt o una capacidad que falta.

• El agente resuelve solo en los modos con IA del número (AI_AGENT o RULES_PLUS_AI_FALLBACK en bot-config).
• Fuera del horario de atención, un pedido de asesor que nace del bot no traspasa: crea una tarea para el equipo y el agente sigue atendiendo. Ver Handoff a humano y Tareas.