# Consulta única

> plazbot studio ask: ejecuta una consulta de Studio y sale, ideal para scripts y CI

Fuente: https://developers.plazbot.com/cli/studio/ask/

### 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
plazbot 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
# Listar los agentes del workspace
plazbot studio ask "List my agents"

# Diagnosticar un agente
plazbot studio ask "Diagnose this agent and report issues" -a age_AbcDef123

# Chunks crudos para scripts
plazbot 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
$ plazbot studio ask "List my agents"

▸ Listing agents…
✓ Agents listed
You have 3 agents in this workspace:

- Ventas WA (age_AbcDef123) - active, WhatsApp
- Soporte L1 (age_GhiJkl456) - active, Webchat
- Reservas (age_MnoPqr789) - inactive
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)`.

> **Nota:** Cada llamada es una conversación nueva, sin historial. Para trabajar en varios turnos usa la [sesión interactiva](https://developers.plazbot.com/cli/studio/repl), 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
{"type":"tool_call","tool_name":"list_agents","tool_args":{}}
{"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"}]}}}
{"type":"text","content":"You have 3 agents "}
{"type":"text","content":"in this workspace:\n\n- Ventas WA ..."}
{"type":"usage","input_tokens":3412,"output_tokens":156}
{"type":"done"}
```

Solo los nombres de los agentes con `jq`:

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

```text
Ventas WA
Soporte L1
Reservas
```

Solo el texto de la respuesta, unido:

```bash
plazbot 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
plazbot 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
- name: Diagnose production agent
env:
  PLAZBOT_API_KEY: ${{ secrets.PLAZBOT_API_KEY }}
  PLAZBOT_WORKSPACE_ID: ${{ secrets.PLAZBOT_WORKSPACE_ID }}
  PLAZBOT_ZONE: LA
run: |
  npm install -g plazbot-cli
  plazbot studio ask "Diagnose this agent" -a age_AbcDef123 --json > diagnose.ndjson
  jq 'select(.type=="tool_result" and .tool_name=="diagnose_agent") | .tool_result.data.issues' diagnose.ndjson
```

> **Tip:** 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](https://developers.plazbot.com/cli/studio/errores).