# Instrucciones para el agente: Apollo: agente de voz para dispositivos con backend propio

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

- Dificultad: avanzado
- Proyecto: https://github.com/galfrevn/apollo (licencia MIT)
- Guía completa: https://lab.wisd.ai/hub/apollo-voice-devices

---

## Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

---

## Pasos de configuración

### Paso 1: prepara el entorno local

Obtén el código desde [el repo](https://github.com/galfrevn/apollo) y abre su raíz. Comprueba que tienes Bun 1.3.13, la versión fijada en [package.json](https://github.com/galfrevn/apollo/blob/main/package.json), y Node.js ≥22, requerido por Wrangler 4.119.0 en el manifiesto de `apps/agent`. Lee [Setup](https://github.com/galfrevn/apollo/blob/HEAD/documentation/operations/setup.md). Esta primera prueba cubre el backend, no instala el firmware.

### Paso 2: prepara dependencias y variables locales

Comandos de la guía:

```bash
bun install
cp apps/agent/.dev.vars.example apps/agent/.dev.vars
```

Edita el archivo local en privado con `DEVICE_SHARED_SECRET` y `OPENROUTER_API_KEY`. Conserva `MOCK_VOICE=1` para empezar sin voz ni recuperación vectorial reales. No compartas el archivo.

### Paso 3: inicia el backend

```bash
bun run dev
```

Wrangler usa por defecto `http://127.0.0.1:8787`. Sigue el [protocolo](https://github.com/galfrevn/apollo/blob/HEAD/documentation/runtime/protocol.md) y la documentación del firmware antes de conectar el dispositivo.

## Comprobación

La guía enumera esta comprobación del repo:

```bash
bun run check
```

En otra terminal comprueba `http://127.0.0.1:8787/health`: el [código de la ruta](https://github.com/galfrevn/apollo/blob/main/apps/agent/src/index.ts) debe devolver JSON con `ok: true` y `name: "apollo"`. Después carga `DEVICE_SHARED_SECRET` en el entorno privado de esa terminal con el mismo valor que usa `.dev.vars`. Desde la raíz ejecuta el [sondeo oficial](https://github.com/galfrevn/apollo/blob/main/apps/wizard/generator/assets/scripts/probe.ts), adaptando su dirección al backend local:

```bash
bun run apps/wizard/generator/assets/scripts/probe.ts --url ws://127.0.0.1:8787/agents/apollo/desk --token "$DEVICE_SHARED_SECRET" --text "hola"
```

El sondeo envía `hello`, espera `ui_state` y envía `text_input`; debe terminar con `turn_end` y «turn complete». No publiques la salida de diagnóstico ni argumentos con secretos. Esto comprueba un turno de texto y audio simulado; no des por validada la voz real con `MOCK_VOICE=1`. Cuando pases a hardware, comprueba por separado entrada de audio, respuesta y reproducción.

## Si algo falla

`apps/agent/.dev.vars` debe estar junto a `wrangler.jsonc`, no en la raíz: la guía advierte de respuestas 401 si queda en el sitio equivocado. Para voz real revisa las credenciales de ElevenLabs; para Sandbox/Containers verifica Docker. Sigue [Deploy](https://github.com/galfrevn/apollo/blob/HEAD/documentation/operations/deploy.md) antes de publicar nada.