Herramientas del agente

Herramientas (Tool Calling)

Gestiona las herramientas del agente: servicios (llamadas a tus APIs) y acciones (etiquetar, cambiar fase, derivar a un humano, agendar eventos, enviar archivos...). Sin flags abre un menú interactivo; con --list o --json solo imprime las herramientas configuradas.

bash

01plazbot agent tools <agentId> [options]

Parámetros

Parámetro	Flag	Requerido	Descripción
`agentId`	(posicional)	Sí	ID del agente, por ejemplo `age_AbcDef123`.
Listar	`--list`	No	Imprime los servicios y acciones actuales y termina, sin preguntas.
JSON	`--json`	No	Imprime las herramientas como JSON (implica `--list`). Por defecto: `false`.

Ejemplos

bash

01# Abrir el menú interactivo
02plazbot agent tools age_AbcDef123
03 
04# Ver los servicios y acciones configurados
05plazbot agent tools age_AbcDef123 --list
06 
07# Exportar servicios y acciones en JSON (headers secretos enmascarados)
08plazbot agent tools age_AbcDef123 --list --json

Primero muestra las herramientas actuales y luego ofrece:

Opción	Qué hace
`List services and actions`	Vuelve a mostrar las tablas de servicios y acciones.
`Add service (API call)`	Agrega un servicio (ver preguntas abajo).
`Add action`	Agrega una acción (ver tipos abajo).
`Remove service` / `Remove action`	Permite marcar varios elementos y pide confirmación antes de quitarlos. Deshabilitado si no hay ninguno.
`Enable Tool Calling` / `Disable Tool Calling`	Activa o desactiva Tool Calling en el agente.
`Exit`	Sale del menú.

Cada cambio se guarda en el momento. Si agregas una herramienta con Tool Calling desactivado, el CLI pregunta si quieres activarlo; nunca lo activa sin preguntar. Si ya existe un servicio o acción con el mismo nombre, no se guarda nada.

Preguntas al agregar un servicio

Nombre o intent (por ejemplo check_order_status).
Cuándo debe usarlo el agente (descripción o palabras clave).
Método HTTP: GET, POST, PUT, PATCH o DELETE.
URL del endpoint (http o https; puede incluir {{campo}}).
Campos requeridos (opcional): datos que el agente debe pedir al usuario antes de llamar. Cada campo tiene nombre, tipo (string, number, integer, boolean, date, datetime, email, phone), descripción y una pista para la IA.
Headers HTTP (opcional), por ejemplo Authorization. Deja el nombre vacío para terminar.
Plantilla de body JSON (solo POST, PUT y PATCH): un objeto JSON donde {{campo}} se reemplaza con los campos requeridos, por ejemplo {"orderId":"{{orderId}}"}.
Mensaje de respuesta (opcional).

Tipos de acción

Grupo	Tipo	Etiqueta en el CLI	Valor que pide
Contact	`action.asign`	Assign agent	ID de usuario o email del agente
Contact	`action.unassign`	Unassign agent	—
Contact	`action.stage`	Set stage	ID de la fase
Contact	`action.stage.remove`	Remove stage	—
Contact	`action.segmentation`	Set segmentation	ID de la segmentación
Contact	`action.segmentation.remove`	Remove segmentation	—
Contact	`action.tag`	Add tag	ID de la etiqueta
Contact	`action.tag.remove`	Remove tag	ID de la etiqueta
Contact	`action.solved`	Mark chat as resolved	—
Contact	`action.agentShutDown`	Hand off to human agent (turns the AI agent off)	—
Contact	`action.secuence`	Assign sequence	ID de la secuencia
Contact	`action.worker`	Run worker	ID del worker
Events	`action.event.add`	Schedule event	—
Events	`action.event.update`	Reschedule event	—
Events	`action.event.delete`	Delete event	—
Events	`action.event.list`	List events	—
Events	`action.event.confirm`	Confirm event	—
Events	`action.event.cancel`	Cancel event	—
Files	`action.send.image`	Send image	URL de la imagen
Files	`action.send.file`	Send file	URL del archivo

Al agregar una acción se pide: nombre o intent (por ejemplo talk_to_human), cuándo usarla, tipo, valor (si el tipo lo requiere), campos requeridos opcionales y mensaje de respuesta.

Resultado

text

01  Tool Calling - Sales Plazbot
02  ────────────────────────────────────────
03  Status: Enabled
04 
05  Services - API calls (1)
06  ────────────────────────────────────────
07┌────────────────────┬────────┬────────────────────────────────────────────┬──────────┐
08│ Intent             │ Method │ Endpoint                                   │ Status   │
09├────────────────────┼────────┼────────────────────────────────────────────┼──────────┤
10│ check_order_status │ GET    │ https://api.example.com/orders/{{orderId}} │ ● active │
11└────────────────────┴────────┴────────────────────────────────────────────┴──────────┘
12 
13  Actions (1)
14  ────────────────────────────────────────
15┌───────────────┬──────────────────────────────────────────────────┬──────────┐
16│ Intent        │ Type                                             │ Status   │
17├───────────────┼──────────────────────────────────────────────────┼──────────┤
18│ talk_to_human │ Hand off to human agent (turns the AI agent off) │ ● active │
19└───────────────┴──────────────────────────────────────────────────┴──────────┘

Si Tool Calling está desactivado y hay herramientas, se muestra Tool Calling is disabled, so the agent will not use these tools.

Salida JSON

json

01{
02  "id": "age_AbcDef123",
03  "name": "Sales Plazbot",
04  "useToolCalling": true,
05  "services": [
06    {
07      "intent": "check_order_status",
08      "reference": "Cuando el cliente pregunta por su pedido",
09      "method": "GET",
10      "endpoint": "https://api.example.com/orders/{{orderId}}",
11      "enabled": true,
12      "requiredFields": [{ "name": "orderId", "type": "string" }],
13      "headers": { "Authorization": "Bear…x9Zq" }
14    }
15  ],
16  "actions": [
17    {
18      "intent": "talk_to_human",
19      "reference": "Cuando el cliente pide hablar con una persona",
20      "enabled": true,
21      "actions": [
22        { "type": "action.agentShutDown", "label": "Hand off to human agent (turns the AI agent off)", "value": "" }
23      ]
24    }
25  ]
26}

Los headers cuyo nombre contiene auth, token, key, secret, password o cookie se enmascaran.

Para ediciones masivas, exporta el agente con plazbot agent export, edita services y actions en el JSON y aplícalo con plazbot agent update.

Errores comunes

Mensaje	Causa	Solución
`The tools menu needs an interactive terminal.`	Sin `--list`/`--json` y sin terminal (CI, pipes).	Usa `plazbot agent tools age_AbcDef123 --list --json`.
`A service named "<intent>" already exists. Nothing was saved.`	Ya hay un servicio (o acción) con ese nombre.	Usa otro nombre o quita el existente.
`Agent "age_AbcDef123" was not found in workspace ...`	El ID no existe en el workspace activo.	Revisa con `plazbot agent list`.
`You are not signed in.`	No hay sesión activa.	Ejecuta `plazbot login`.