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

# Acciones

> Guia completa para activar acciones del Agente de IA.

### Configuracion de las Acciones del Agentes IA

Este documento describe como se puede agregar en el archivo `agent.config.json`, acciones que se pueden ejecutar en el Agente de IA, como por ejemplo:

* Apagar un agente de IA.
* Asignar una etapa al contacto.
* Asignar una etiqueta al contacto.
* Asignar una segmentacion al contacto.
* Asignar un agente humano al contacto.
* Marcar como resuelto.
* Gestionar eventos (citas, reuniones, etc.).

<Card title="Github" icon="github" href="https://github.com/plazbot/plazbot-sdk-examples">
  Puedes descargar nuestro repositorio de ejemplo para crear tus agentes.
</Card>

### Estructura

<Tip>
  Las acciones se pueden agregar en el archivo `agent.config.json`, para que el Agente de IA pueda ejecutar las acciones. Estas pueden agregar de forma independiente o agregar un campo `action` dentro de un servicio.
</Tip>

```json theme={null}
{
  "actions":[
    {
      "intent": "conversar_humano",
      "reference": "Informacion cuando un usuario quiere hablar con un Agente humano.",
      "tags": ["conversacion", "humano", "agente"],
      "enabled": true,
      "requiredFields": [],
      "responseMessage": "Por favor, espera un momento mientras te conectamos con un agente humano.",
      "responseJson": false,
      "responseExact": true,
      "action": [
          {
            "type": "action.asign",
            "value": "k@gmail.com"
          },
          {
            "type": "action.stage",
            "value": "agendado"
          },
          {
            "type": "action.agentShutDown",
            "value": "true"
          },
          {
            "type": "action.segmentation",
            "value": "segmentacion1"
          },
          {
            "type": "action.tag",
            "value": "pendiente"
          }
      ]
    }
  ]
}
```

### Campos de la Accion

| Campo             | Tipo      | Descripcion                                                                                                                                |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `intent`          | string    | Identificador unico de la intencion de la action. (por ejemplo, `"conversar_humano"`).                                                     |
| `reference`       | string    | Frase corta y descriptiva que ayuda a la IA a entender cuando debe activarse esta action.                                                  |
| `tags`            | string\[] | Etiquetas para complementar la `reference` con contexto adicional.                                                                         |
| `enabled`         | boolean   | Indica si la action esta activa (`true`) o no (`false`).                                                                                   |
| `requiredFields`  | array     | Campos que el agente debe recopilar del usuario antes de ejecutar la accion. Funciona igual que en los servicios.                          |
| `responseMessage` | string    | Mensaje que el agente devuelve al usuario tras ejecutar la action. Soporta variables: `{{variable}}`, `{variable}`, `@variable`.           |
| `responseJson`    | boolean   | Si la action debe devolver un JSON (`true`) o texto plano (`false`). Solo aplica en orquestador clasico.                                   |
| `responseExact`   | boolean   | Si el `responseMessage` se envia **exactamente** al usuario sin reformulacion del LLM. Solo aplica en modo Tool Calling. Default: `false`. |
| `action`          | array     | Arreglo de objetos con `type` y `value` que definen las acciones a ejecutar.                                                               |

### Tipos de Accion

| Tipo                   | Descripcion                                                             |
| ---------------------- | ----------------------------------------------------------------------- |
| `action.asign`         | Asigna un agente humano al contacto. El `value` es el email del agente. |
| `action.stage`         | Asigna una etapa al contacto.                                           |
| `action.agentShutDown` | Apaga el agente de IA para el contacto. El `value` debe ser `"true"`.   |
| `action.segmentation`  | Asigna una segmentacion al contacto.                                    |
| `action.tag`           | Asigna una etiqueta al contacto.                                        |
| `action.solved`        | Marca la conversacion como resuelta. El `value` debe ser `"true"`.      |
| `action.event.add`     | Crea un nuevo evento/cita en el calendario.                             |
| `action.event.update`  | Actualiza un evento existente.                                          |
| `action.event.delete`  | Elimina un evento.                                                      |
| `action.event.list`    | Lista los eventos disponibles.                                          |
| `action.event.confirm` | Confirma un evento pendiente.                                           |
| `action.event.cancel`  | Cancela un evento existente.                                            |

<Note>
  Las acciones de tipo `action.event.*` requieren que el agente tenga configurado un calendario. Cuando se configuran acciones de eventos, el sistema inyecta automaticamente una herramienta de **consulta de disponibilidad** (`check_availability`) para que el agente pueda verificar horarios libres antes de agendar.
</Note>

### Asignar un agente humano

```json theme={null}
 {
    "type": "action.asign",
    "value": "k@gmail.com"
}
```

### Asignar una etapa

```json theme={null}
 {
    "type": "action.stage",
    "value": "agendado"
}
```

### Apagar un agente de IA

```json theme={null}
{
    "type": "action.agentShutDown",
    "value": "true"
}
```

### Asignar una segmentacion

```json theme={null}
{
    "type": "action.segmentation",
    "value": "segmentacion1"
}
```

### Asignar una etiqueta

```json theme={null}
{
    "type": "action.tag",
    "value": "pendiente"
}
```

### Marcar como resuelto

```json theme={null}
{
    "type": "action.solved",
    "value": "true"
}
```

### Campos Requeridos en Acciones

Las acciones tambien soportan `requiredFields`, que funcionan de la misma forma que en los servicios. Esto es util cuando la accion necesita datos del usuario antes de ejecutarse (por ejemplo, una fecha para agendar un evento).

```json theme={null}
{
  "intent": "agendar_cita",
  "reference": "El usuario quiere agendar una cita o reunion",
  "enabled": true,
  "requiredFields": [
    {
      "name": "fecha",
      "description": "Fecha deseada para la cita",
      "promptHint": "Cual es la fecha que prefieres para la cita?",
      "type": "datetime"
    },
    {
      "name": "nombre_cliente",
      "description": "Nombre del cliente",
      "type": "string"
    }
  ],
  "responseMessage": "Listo {{nombre_cliente}}, tu cita ha sido agendada para el {{fecha}}.",
  "responseExact": true,
  "action": [
    {
      "type": "action.event.add",
      "value": "cita"
    }
  ]
}
```

#### Comportamiento de Respuesta

**Modo Tool Calling (`useToolCalling: true`):**

Con `responseExact: true`:

```json theme={null}
{
  "responseExact": true,
  "responseMessage": "He transferido tu conversacion al equipo de soporte."
}
```

* Ejecuta las acciones
* Envia el `responseMessage` **exacto** al usuario (con variables sustituidas)
* El LLM no reformula el mensaje

Con `responseExact: false` (default):

```json theme={null}
{
  "responseExact": false,
  "responseMessage": ""
}
```

* Ejecuta las acciones
* El LLM genera una respuesta natural basada en el resultado
* Mas inteligente y conversacional

**Modo Clasico (`useToolCalling: false`):**

`responseJson: false`:

```json theme={null}
{
  "responseJson": false,
  "responseMessage": "Solicitud procesada correctamente."
}
```

* Ejecuta las acciones
* Responde con mensaje fijo
* Util para confirmaciones simples

`responseJson: true`:

```json theme={null}
{
  "responseJson": true,
  "responseMessage": "Proceso completado"
}
```

* Ejecuta las acciones
* Responde con JSON estructurado
* Ideal para integraciones con APIs/webhooks

### TypeScript

```typescript theme={null}
import type { AgentAction, AgentActionItem, ActionType } from 'plazbot';
```

### Consideraciones

El `action` tambien se puede agregar dentro de un servicio, para que se ejecute cuando se active el servicio como un campo mas adicional. En caso de que se agregue dentro de un servicio, se debe agregar el campo `action` dentro del servicio y solo ejecutara las acciones y no analizara el mensaje del usuario ya que las referencias ya se encuentran en el servicio.