# Crear agente

> Crea un agente de IA con un asistente interactivo o desde un archivo JSON.

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

### Crear agente

Crea un agente de IA de dos formas: sin argumentos abre un asistente interactivo de 8 pasos; con la ruta de un archivo JSON crea el agente directamente desde esa configuración (ideal para scripts y CI).

```bash
plazbot agent create [configPath] [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `configPath` | (posicional) | No | Ruta a un archivo JSON con la configuración. Si se omite, se abre el asistente interactivo. |
| JSON | `--json` | No | Imprime el agente creado como JSON (`{"id","name"}`). Por defecto: `false`. |

### Ejemplos

```bash
# Abrir el asistente interactivo
plazbot agent create

# Crear desde un archivo JSON
plazbot agent create ./agent.json

# Crear desde un archivo y capturar el nuevo ID (scripts)
plazbot agent create ./agent.json --json | jq -r '.id'
```

## Asistente interactivo

El asistente necesita una terminal interactiva. Cada paso propone valores por defecto que aceptas con Enter.

| Paso | Qué pregunta |
|------|--------------|
| 1/8 Basic information | Nombre (obligatorio), descripción, system prompt (por defecto `You are a friendly and professional virtual assistant.`), memoria de conversación: cuántos mensajes anteriores lee el agente, de 3 a 20 (por defecto 5), y color (`blue`, `green`, `orange`, `gray`, `white`). |
| 2/8 Personality and instructions | Tono (Professional, Friendly, Formal, Casual, Technical, Empathetic), estilo (Concise, Detailed, Conversational, Direct), personalidad, objetivo, idioma de respuesta (Spanish, English, Portuguese, French) y si usa emojis. |
| 3/8 Agent identity | Nombre del personaje (por defecto el nombre del agente), rol (por defecto `Virtual assistant`) y si habla en primera persona. |
| 4/8 Fallback messages | Mensajes para cuando no tiene respuesta, cuando falla un servicio externo y cuando no entiende. Los valores por defecto están en el idioma elegido en el paso 2. |
| 5/8 Tool Calling | Si activa Tool Calling (por defecto sí). Si lo activas, puedes agregar servicios (llamadas a APIs) y acciones con las mismas preguntas que [`plazbot agent tools`](https://developers.plazbot.com/cli/agent/tools). |
| 6/8 AI provider | Si usa tu propio proveedor de IA. Si respondes que sí: proveedor (OpenAI, Anthropic (Claude), Google (Gemini)), modelo y API token. Se guarda con temperatura 0.7 y 4096 tokens máximos; ajústalos luego con [`plazbot agent ai-config`](https://developers.plazbot.com/cli/agent/ai-config). Si respondes que no, usa la IA por defecto de la plataforma. |
| 7/8 Connect a channel | Si conectas un canal ahora (WhatsApp, WhatsApp Business, Instagram, Messenger, Telegram). Puedes elegir una integración existente del workspace o generar un enlace de conexión; el CLI espera la conexión (Enter para omitir) y activa la integración. |
| 8/8 Conversation examples | Ejemplos de conversación (mensaje del cliente y respuesta del agente) para guiar al agente. |

Al final muestra una vista previa y pide confirmación:

```text
Configuration preview
────────────────────────────────────────
Name: Sofia
Prompt: Eres una asesora comercial de Acme...
Memory: 5 messages
Language: Spanish
Tool Calling: Enabled
Services: 1
Actions: 2
AI provider: Platform default (Plazbot)
Channels: Not connected

? Create the agent with this configuration? (Y/n)
```

Si respondes que no, se imprime `Aborted.` y el comando termina con código 1.

Los modelos disponibles en el paso 6 son los mismos de [`ai-config`](https://developers.plazbot.com/cli/agent/ai-config). Modelo por defecto: `gpt-4o` (OpenAI), `claude-sonnet-4-6` (Claude), `gemini-2.5-pro` (Gemini).

## Desde un archivo JSON

El archivo debe contener un objeto JSON con la configuración del agente. Los campos obligatorios del schema son `name`, `prompt`, `zone` y `buffer` (entero de 3 a 20).

```json
{
"name": "Sofia",
"description": "Asistente de atención al cliente",
"prompt": "Eres una asistente amable que ayuda a los clientes de Acme.",
"zone": "LA",
"buffer": 5,
"color": "blue",
"question": "¿Cómo te podemos ayudar?",
"timezone": "America/Lima",
"person": {
  "name": "Sofia",
  "role": "Asistente de atención al cliente",
  "speaksInFirstPerson": true,
  "isHuman": false
},
"instructions": {
  "tone": "amigable",
  "style": "conversacional",
  "language": "Espanol",
  "emojis": true
},
"useToolCalling": false
}
```

> **Tip:** Valida el archivo antes de crearlo con [`plazbot agent validate ./agent.json`](https://developers.plazbot.com/cli/agent/validate). Para partir de un agente existente, usa [`plazbot agent export`](https://developers.plazbot.com/cli/agent/export); para partir de una plantilla, [`plazbot agent templates --json`](https://developers.plazbot.com/cli/agent/templates).

### Resultado

```text
Creating agent from file
────────────────────────────────────────
{ ...contenido del archivo... }
✔ Agent created successfully

Agent details
────────────────────────────────────────
ID: age_AbcDef123
Name: Sofia
Tool Calling: Disabled

Next steps:
  plazbot agent chat age_AbcDef123       # test it in the terminal
  plazbot agent get age_AbcDef123        # review the configuration
```

### Salida JSON

```json
{
"id": "age_AbcDef123",
"name": "Sofia"
}
```

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `The agent wizard needs an interactive terminal.` | Se ejecutó sin archivo en CI, un pipe o con `--json`. | Pasa un archivo: `plazbot agent create ./agent.json`. |
| `Could not read the config file: ...` | La ruta no existe o no se puede leer. | Revisa la ruta del archivo. |
| `The config file is not valid JSON: ...` | El archivo tiene un error de sintaxis. | Revísalo con `plazbot agent validate ./agent.json`. |
| `The config file must contain a JSON object.` | El archivo contiene un arreglo u otro valor. | El archivo debe ser un objeto `{ ... }`. |
| `The API rejected the agent configuration:` seguido de una lista numerada | La API validó el schema y encontró errores (uno por línea). | Corrige los campos indicados; revisa con `plazbot agent validate`. |
| `You are not signed in.` | No hay sesión activa. | Ejecuta [`plazbot login`](https://developers.plazbot.com/cli/login). |