Consulta única

plazbot studio ask envía un solo mensaje a Studio, imprime la respuesta y sale. No abre el chat ni necesita una terminal interactiva, así que sirve para scripts, cron y CI. plazbot studio -m "<mensaje>" es un alias y acepta las mismas opciones (incluido --json).

bash

01plazbot studio ask <message> [options]

Parámetros

Parámetro	Flag	Requerido	Descripción
Mensaje	`<message>`	Sí	Lo que le pides a Studio. Entre comillas. No puede estar vacío
Agente	`-a, --agent-id <id>`	No	Agente que se usa como contexto
JSON	`--json`	No	Imprime los chunks del stream como NDJSON (un objeto JSON por línea). Por defecto: `false`

Ejemplos

bash

01# Listar los agentes del workspace
02plazbot studio ask "List my agents"
03 
04# Diagnosticar un agente
05plazbot studio ask "Diagnose this agent and report issues" -a age_AbcDef123
06 
07# Chunks crudos para scripts
08plazbot studio ask "List my agents" --json

Resultado

La respuesta va a stdout; los pasos de herramientas, los tokens y los errores van a stderr. Así puedes redirigir solo la respuesta (> respuesta.txt).

text

01$ plazbot studio ask "List my agents"
02 
03  ▸ Listing agents…
04  ✓ Agents listed
05You have 3 agents in this workspace:
06 
07- Ventas WA (age_AbcDef123) - active, WhatsApp
08- Soporte L1 (age_GhiJkl456) - active, Webchat
09- Reservas (age_MnoPqr789) - inactive
10  tokens: 3412 in / 156 out

Si un paso falla se ve como ✗ Could not load agent — <motivo>. Si Studio no devuelve texto se imprime (no text response).

Cada llamada es una conversación nueva, sin historial. Para trabajar en varios turnos usa la sesión interactiva, o incluye todo el contexto en el mensaje.

Salida JSON

Con --json, stdout lleva un chunk por línea, tal como llega del stream. Tipos posibles:

`type`	Campos
`text`	`content`: fragmento de texto de la respuesta
`tool_call`	`tool_name`, `tool_args` (opcional)
`tool_result`	`tool_name`, `tool_result`: `{ success, tool, type, data, message, error }`
`usage`	`input_tokens`, `output_tokens`
`error`	`error`: mensaje
`done`	sin campos

El resultado de cada herramienta viene anidado en tool_result. Su type indica qué trae data: agent_list (data.agents), agent_loaded (data.agent), agent_config (data.config), diagnostic (data.summary, data.issues), whatsapp_link, instagram_link o messenger_link.

json

01{"type":"tool_call","tool_name":"list_agents","tool_args":{}}
02{"type":"tool_result","tool_name":"list_agents","tool_result":{"success":true,"tool":"list_agents","type":"agent_list","data":{"total":3,"query":null,"agents":[{"id":"age_AbcDef123","name":"Ventas WA","description":"Ventas por WhatsApp","enable":true,"channels":["whatsapp"],"hasSource":true,"hasVoice":false,"version":"1.0","updatedAt":"2026-10-01T15:20:11Z"}]}}}
03{"type":"text","content":"You have 3 agents "}
04{"type":"text","content":"in this workspace:\n\n- Ventas WA ..."}
05{"type":"usage","input_tokens":3412,"output_tokens":156}
06{"type":"done"}

Solo los nombres de los agentes con jq:

bash

01plazbot studio ask "List my agents" --json \
02  | jq -r 'select(.type=="tool_result" and .tool_name=="list_agents") | .tool_result.data.agents[].name'

text

01Ventas WA
02Soporte L1
03Reservas

Solo el texto de la respuesta, unido:

bash

01plazbot studio ask "List my agents" --json | jq -j 'select(.type=="text") | .content'

En modo --json, si el stream trae un chunk error, ese chunk sale en stdout y además se escribe en stderr {"error":{"message":"...","code":"studio_error"}}. Los demás errores (sesión, HTTP, red) salen en stderr como {"error":{"message","code","hint"}}.

Códigos de salida

Código	Caso
`0`	Respuesta completa
`1`	Cualquier error: sin sesión, mensaje vacío, HTTP (401, 403, 429, 5xx), red, o un chunk `error` en el stream
`130`	Cancelado con `Ctrl+C` (imprime `Cancelled.` en `stderr`)

bash

01plazbot studio ask "Diagnose this agent" -a age_AbcDef123 || echo "Falló con código $?"

Uso en CI

Con variables de entorno no necesitas plazbot login:

yaml

01- name: Diagnose production agent
02  env:
03    PLAZBOT_API_KEY: ${{ secrets.PLAZBOT_API_KEY }}
04    PLAZBOT_WORKSPACE_ID: ${{ secrets.PLAZBOT_WORKSPACE_ID }}
05    PLAZBOT_ZONE: LA
06  run: |
07    npm install -g plazbot-cli
08    plazbot studio ask "Diagnose this agent" -a age_AbcDef123 --json > diagnose.ndjson
09    jq 'select(.type=="tool_result" and .tool_name=="diagnose_agent") | .tool_result.data.issues' diagnose.ndjson

Con PLAZBOT_API_KEY / PLAZBOT_WORKSPACE_ID, define también PLAZBOT_USER_ID (opcional) para que los agentes creados o guardados por Studio queden atribuidos a un usuario.

Errores comunes

Mensaje	Causa	Solución
`The message is empty.`	El mensaje está vacío o solo tiene espacios	`plazbot studio ask "List my agents"`
`You are not signed in.`	No hay sesión ni variables de entorno	`plazbot login`, o define `PLAZBOT_API_KEY` y `PLAZBOT_WORKSPACE_ID`
`Your session is invalid or expired.`	Token vencido o revocado (401)	`plazbot login`
`You do not have permission for this workspace.`	El workspace no es accesible con tu usuario (403)	Revisa el workspace activo con `plazbot whoami` o el valor de `-w`
`Too many requests.`	Límite de peticiones (429)	Espera unos segundos y reintenta
`Plazbot Studio error (HTTP 502).`	Error temporal del backend	Reintenta en unos segundos
`Could not reach the Plazbot API.`	Sin conexión, DNS o proxy	Revisa tu conexión a internet

Ver todos en Errores comunes.