# Plantillas de agente

> Crea un agente a partir de una plantilla lista para usar.

Fuente: https://developers.plazbot.com/cli/agent/templates/

### Crear desde una plantilla

Crea un agente a partir de una plantilla con prompt, persona, instrucciones, acciones y Tool Calling ya configurados. Solo necesitas completar los datos de tu negocio. Funciona de forma interactiva o sin preguntas con flags.

```bash
plazbot agent templates [options]
```

### Plantillas disponibles

| # | ID | Nombre | Industria | Datos que pide |
|---|----|--------|-----------|----------------|
| 1 | `sales` | Sales Assistant | Sales | `--business`, `--address`, `--contact-phone` |
| 2 | `it-support` | IT Technical Support | Technology | `--business`, `--contact-phone`, `--support-email` |
| 3 | `clinic` | Clinic Assistant | Health | `--business`, `--address`, `--contact-phone` |
| 4 | `restaurant` | Restaurant Assistant | Food & beverage | `--business`, `--address`, `--contact-phone` |
| 5 | `real-estate` | Real Estate Assistant | Real estate | `--business`, `--address`, `--contact-phone` |

Las plantillas están escritas en español y usan OpenAI (`gpt-4o`): el agente necesita una API key de OpenAI para responder.

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Listar | `--list` | No | Lista las plantillas disponibles y termina. |
| Plantilla | `-t, --template <id>` | No (sí sin terminal) | `sales`, `it-support`, `clinic`, `restaurant`, `real-estate`, o su número (1 a 5). |
| Nombre | `--name <name>` | No | Nombre del agente. Por defecto: el nombre de la plantilla. |
| Negocio | `--business <name>` | No | Nombre del negocio que se usa en el prompt. |
| Dirección | `--address <text>` | No | Dirección del negocio (plantillas que la usan). |
| Teléfono | `--contact-phone <number>` | No | Teléfono del negocio que se muestra a los clientes (plantillas que lo usan). |
| Email de soporte | `--support-email <email>` | No | Email de soporte (plantilla `it-support`). |
| Zona horaria | `--timezone <iana>` | No | Zona horaria IANA, por ejemplo `America/Lima`. Por defecto: `America/Lima`. |
| API token | `--api-token <key>` | No | API key de OpenAI para el agente. |
| Sin canales | `--skip-channels` | No | No ofrece conectar canales. |
| JSON | `--json` | No | Imprime la configuración resultante como JSON sin crear el agente (no llama a la API). Con `--list`, imprime las plantillas en JSON. Por defecto: `false`. |
| Confirmar | `-y, --yes` | No | Omite la confirmación (scripts y CI). Por defecto: `false`. |

### Ejemplos

```bash
# Elegir una plantilla y crear el agente paso a paso
plazbot agent templates

# Listar las plantillas en JSON
plazbot agent templates --list --json

# Crear un agente de clínica sin preguntas
plazbot agent templates -t clinic --name "Clinic Bot" --business "Clínica Sol" --address "Av. Arequipa 123, Lima" --contact-phone "+51 1 234 5678" --api-token sk-xxx --yes

# Ver la configuración sin crear nada y guardarla para agent create
plazbot agent templates -t sales --business "Acme" --address "Calle 1" --contact-phone "+51912345678" --json > agent.json
```

### Flujo interactivo

1. Elegir la plantilla (si no pasaste `-t`).
2. Completar los datos del negocio que falten (los que pasaste por flag no se preguntan).
3. Conectar un canal (WhatsApp, Messenger, Instagram, Telegram), salvo con `--skip-channels`.
4. Agregar la API key de OpenAI (si no pasaste `--api-token`).
5. Zona horaria (si no pasaste `--timezone`).
6. Resumen y confirmación.

Sin terminal (CI, pipes) debes pasar `--template`, los datos del negocio y `--yes`. Los canales solo se ofrecen en modo interactivo.

### Resultado

```text
Summary
────────────────────────────────────────
Template: Clinic Assistant (clinic)
Agent name: Clinic Bot
Clinic name: Clínica Sol
Clinic address: Av. Arequipa 123, Lima
Clinic phone: +51 1 234 5678
Channels: Not connected
OpenAI API key: Set
Timezone: America/Lima
Actions: 6
AI: openai / gpt-4o

✔ Agent created

Agent details
────────────────────────────────────────
ID: age_AbcDef123
Name: Clinic Bot
Template: Clinic Assistant
Actions: 6

Next steps
────────────────────────────────────────
1. Test the agent: plazbot agent chat age_AbcDef123
2. Connect a WhatsApp number: plazbot whatsapp assign -p <phone> -a age_AbcDef123
```

Si no se configuró la API key, el primer paso sugerido es `plazbot agent ai-config <agentId> --provider openai --api-token <key>` y se muestra el aviso `The agent will not reply until an OpenAI API key is configured.` Para asignar el número usa [`plazbot whatsapp assign -p <número> -a <agentId>`](https://developers.plazbot.com/whatsapp/cli/assign).

### Salida JSON

`--list --json`:

```json
[
{
  "id": "sales",
  "name": "Sales Assistant",
  "industry": "Sales",
  "description": "Sales management, quotes and orders",
  "persona": "Carlos - Asesor Comercial Virtual",
  "actions": 4,
  "fields": [
    { "flag": "--business", "label": "Company name" },
    { "flag": "--address", "label": "Company address" },
    { "flag": "--contact-phone", "label": "Contact phone" }
  ]
}
]
```

`-t <id> --json` imprime la configuración completa del agente (la misma que acepta [`plazbot agent create`](https://developers.plazbot.com/cli/agent/create)), con `channels: []`:

```json
{
"name": "Asistente de Ventas",
"description": "Asistente virtual para gestion comercial y atencion al cliente",
"prompt": "Eres el asistente virtual de ventas de Acme...",
"zone": "LA",
"timezone": "America/Lima",
"buffer": 8,
...
}
```

Con `--json` no se llama a la API, no se pregunta nada y el API token no se incluye (si pasas `--api-token` se muestra un aviso en stderr). Si faltan datos del negocio, los marcadores quedan sin completar (por ejemplo `[DIRECCION COMPLETA]`) y se avisa en stderr con `Placeholders left unfilled: ...`.

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `A template is required when running without prompts.` | Sin terminal y sin `--template`. | Pasa `--template <id>`. |
| `Unknown template "<valor>".` | El ID o número no existe. | Revisa con `plazbot agent templates --list`. |
| `Missing business details for the "<id>" template.` | Sin terminal y faltan datos del negocio. El hint lista los flags que faltan. | Pasa los flags indicados, por ejemplo `--address` y `--contact-phone`. |
| `This action needs confirmation and there is no interactive terminal.` | Sin terminal y sin `--yes`. | Agrega `--yes`. |
| `You are not signed in.` | No hay sesión activa (no aplica con `--json` ni `--list`). | Ejecuta [`plazbot login`](https://developers.plazbot.com/cli/login). |