> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnexor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear Agente

<span class="badge--post">POST</span> <code class="endpoint-url">/workflows</code>

Crea un agente nuevo (funnel + statuses) desde cero — completamente vía API. Este es el primer paso del ciclo de vida API-first de un agente:

1. **Crear** el agente (este endpoint). Nace **pausado**.
2. [Configurar su prompt](/docs/es/api/workflows/set-workflow-prompt) — qué dice y cómo se comporta.
3. Opcionalmente [agregar statuses/campos personalizados](/docs/es/api/workflows/update-workflow-structure) o [tools personalizadas](/docs/es/api/workflow-tools/create-workflow-tool) que pueda llamar.
4. [Activarlo](/docs/es/api/workflows/update-workflow) seteando `is_paused: false`.

**Idempotente.** Si ya existe un agente con el mismo `name` en tu cuenta, devuelve el existente (`status: "existed"`) en lugar de crear un duplicado — seguro de reintentar.

## Cuerpo de la Solicitud

| Campo           | Tipo   | Requerido | Descripción                                                                                                                                                         |
| --------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | string | **Sí**    | Nombre del agente. Se usa para el chequeo de idempotencia                                                                                                           |
| `goal_type`     | string | **Sí**    | Uno de: `appointment`, `sale`, `qualification`, `information`, `payment_link`, `support`, `custom`                                                                  |
| `statuses`      | array  | **Sí**    | Array no vacío de statuses del funnel (ver abajo). Si ninguno está marcado `is_initial`, se usa el primero; si ninguno está marcado `is_terminal`, se usa el último |
| `description`   | string | No        | Descripción del agente                                                                                                                                              |
| `global_prompt` | string | No        | Prompt base. También se puede configurar después vía `PATCH /workflows/:id/prompt`                                                                                  |
| `language`      | string | No        | Por defecto `es`                                                                                                                                                    |
| `channels`      | array  | No        | Canales a habilitar, ej. `["whatsapp", "email"]`. Por defecto `["whatsapp"]`                                                                                        |
| `fields`        | array  | No        | Campos personalizados a recolectar (ver [Actualizar Estructura](/docs/es/api/workflows/update-workflow-structure) para la forma exacta)                             |

### Forma de `statuses[]`

| Campo         | Tipo    | Requerido | Descripción                                    |
| ------------- | ------- | --------- | ---------------------------------------------- |
| `key`         | string  | **Sí**    | Identificador estable del status               |
| `name`        | string  | **Sí**    | Etiqueta visible (`label` también es aceptado) |
| `is_initial`  | boolean | No        | Marca el status de entrada del funnel          |
| `is_terminal` | boolean | No        | Marca un status de cierre del funnel           |
| `sort_order`  | integer | No        | Por defecto, el índice del array               |

## Respuestas

### `201` — Agente creado

```json theme={null}
{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created"
}
```

### `200` — Ya existía (respuesta idempotente)

```json theme={null}
{
  "success": true,
  "workflow_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "existed"
}
```

### `400` — Error de validación

```json theme={null}
{
  "error": "Invalid input",
  "message": "name is required"
}
```

Otros errores de validación:

* `"goal_type must be one of: appointment, sale, qualification, information, payment_link, support, custom"`
* `"statuses must be a non-empty array"`
* `"each status needs a key and a name"`

### `401` — Error de autenticación

Ver [Autenticación](/docs/es/api/authentication).

### `500` — Error interno del servidor