b089c2ef18
Boilerplate completo para construir soluciones agénticas sobre IBM watsonx Orchestrate (ADK 2.x) con una capa web encima. Destilado de cotemar-poc-n1 y dun-casos-prueba. Incluye: - 11 docs (best practices, architecture patterns, ADK cheatsheet, observability, tool authoring, deployment, RUNBOOK, DEPLOY_TO_NEW_WOX, known-issues con 16 errores reales y fix, eval strategy, INDEX) - 13 templates WxO (orchestrator/specialist/single-meta agents, 3 connections, KB + runbook, observable_tool decorator, coercion helpers, Python tools, OpenAPI spec, backend filter endpoint, webhook validator HMAC, MCP connection) - 6 scripts (deploy idempotente con fallback ADK, undeploy, reset, check-adk-version, new-specialist scaffold, eval-agents runner) - 4 eval pieces (linter de best practices, runner, smoke-test, direct backend probe) + scenario templates - 8 subagentes Claude (.claude/agents/) — wxo-architect, wxo-agent-author, wxo-tool-author, runbook-author, mock-builder, backend-tool-builder, eval-author, web-layer-builder - Skill bundle fit-wxo-bootstrap/ (SKILL.md + 3 templates) listo para copiar a ~/.claude/skills/ - Web layer default FastAPI+HTMX con vista timeline observable + endpoint receptor de trazas - Docker compose Coolify-ready (healthcheck wget -qO-, sin labels Traefik, network split internal:true) - CI Gitea workflow con lint + smoke Best practices enforced por evals/lint_wxo_yaml.py: - A1: máx 10 tools por agente - A3: orchestrator sin tools de remediación - A6: agente sin propósito (react sin tools ni KB) - T1: @observable_tool obligatorio, no @tool directo - T3: _compat shim inline en tools.py - D1: docker-compose sin wget --spider - I-005: OpenAPI con description per-operation - I-009: sin labels Traefik manuales Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
219 lines
5.1 KiB
Markdown
219 lines
5.1 KiB
Markdown
# Deploy to a New WxO Tenant — Cold Start Playbook
|
|
|
|
Cuando arrancás esta solución en un tenant WxO **completamente nuevo**
|
|
(otro cliente, otro environment, fresh start), seguí este playbook
|
|
literal. Es el camino más corto desde "tengo credenciales" a "demo
|
|
funcionando".
|
|
|
|
---
|
|
|
|
## Step 0 — Pre-requisitos
|
|
|
|
- [ ] IBM Cloud account del cliente con WxO instance provisionada
|
|
- [ ] API key del tenant
|
|
- [ ] Coolify (u otro host Docker) accesible
|
|
- [ ] Dominio público con DNS apuntando al host
|
|
- [ ] Acceso a Gitea/repo para clonar el código
|
|
|
|
---
|
|
|
|
## Step 1 — Provisionar el ADK localmente
|
|
|
|
```bash
|
|
python3.12 -m venv .venv-wxo
|
|
source .venv-wxo/bin/activate
|
|
pip install --upgrade "ibm-watsonx-orchestrate==2.1.0"
|
|
orchestrate --version # 2.1.x
|
|
```
|
|
|
|
Verificá que el modelo esté disponible:
|
|
|
|
```bash
|
|
orchestrate env add -n nuevo-tenant \
|
|
--iam-url https://iam.cloud.ibm.com/identity/token \
|
|
-u "$ORCHESTRATE_API_URL"
|
|
orchestrate env activate nuevo-tenant
|
|
|
|
orchestrate models list | grep gpt-oss-120b
|
|
```
|
|
|
|
Si no aparece `gpt-oss-120b`, editá los YAMLs en `wxo/agents/` y poné
|
|
`meta-llama/llama-3-3-70b-instruct` (con la advertencia de I-002).
|
|
|
|
---
|
|
|
|
## Step 2 — Secretos
|
|
|
|
Crear `.env` desde `.env.example`:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
nano .env
|
|
```
|
|
|
|
Llenar:
|
|
- `ORCHESTRATE_API_URL`
|
|
- `ORCHESTRATE_API_KEY`
|
|
- `WATSONX_API_KEY` (si vas a usar Plan A)
|
|
- `PUBLIC_HOST`
|
|
- (Coolify) `COOLIFY_API_URL`, `COOLIFY_API_TOKEN`
|
|
|
|
---
|
|
|
|
## Step 3 — Deploy del backend / mocks
|
|
|
|
Si tu solución incluye un backend propio o mocks:
|
|
|
|
```bash
|
|
# Coolify: crear app desde el git repo, configurar env vars, deploy
|
|
# O localmente:
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Verificá que el `PUBLIC_HOST/health` responde 200:
|
|
|
|
```bash
|
|
curl -sf "https://$PUBLIC_HOST/health"
|
|
```
|
|
|
|
Si da 503 → Traefik exclude por healthcheck. Issue I-008.
|
|
Si da default cert → labels manuales en compose. Issue I-009.
|
|
|
|
---
|
|
|
|
## Step 4 — Deploy del stack WxO
|
|
|
|
```bash
|
|
PUBLIC_HOST=mi-cliente.fitlabs.dev ./scripts/deploy-wxo.sh
|
|
```
|
|
|
|
El script:
|
|
1. Crea las connections (draft + live)
|
|
2. Importa los tools
|
|
3. Importa las KBs
|
|
4. Importa los agentes en orden (specialists primero)
|
|
5. Hace `deploy --env live` de cada uno
|
|
6. Crea el canal webchat
|
|
|
|
Si falla a mitad de camino:
|
|
- Re-corré el script (es idempotente)
|
|
- Si persiste, ver `docs/known-issues.md`
|
|
|
|
---
|
|
|
|
## Step 5 — Capturar IDs
|
|
|
|
```bash
|
|
orchestrate agents list
|
|
```
|
|
|
|
Buscá tu orchestrator en el env `live`, capturá:
|
|
- `agent_id` (UUID)
|
|
- `environment_id` (UUID)
|
|
|
|
Ponelos en:
|
|
- `web/.../templates/index.html` (o donde esté tu landing): `agentId` y `agentEnvironmentId`
|
|
- `.env`: `WXO_AGENT_ID`
|
|
- Coolify panel: `WXO_AGENT_ID` env var
|
|
|
|
Commit + redeploy de la landing.
|
|
|
|
---
|
|
|
|
## Step 6 — Embed Security OFF (manual, UI)
|
|
|
|
**Esto es manual. No hay API.**
|
|
|
|
1. WxO Console → Settings
|
|
2. Embed Security → **Off**
|
|
3. Confirmar
|
|
|
|
Sin esto, el widget de chat queda en "Cargando..." para siempre.
|
|
Issue I-007.
|
|
|
|
---
|
|
|
|
## Step 7 — Smoke test
|
|
|
|
```bash
|
|
./evals/smoke-test.sh
|
|
```
|
|
|
|
Si pasa, validá manualmente:
|
|
|
|
```bash
|
|
# Abrir el chat
|
|
open "https://$PUBLIC_HOST/"
|
|
```
|
|
|
|
Tirale al chat tu primer scenario. Verifica que:
|
|
1. El agente responde
|
|
2. El tool se llama (mirá `docker logs <web>` para ver las trazas)
|
|
3. El resultado final aparece en la UI (kanban / control plane / lo que sea)
|
|
|
|
---
|
|
|
|
## Step 8 — Direct backend probe (diagnóstico)
|
|
|
|
Si el chat funciona pero ves errores, ejecutá:
|
|
|
|
```bash
|
|
./evals/direct-backend-probe.sh
|
|
```
|
|
|
|
Esto llama tu backend directamente con curl + el token de WxO. Sirve
|
|
para aislar:
|
|
- **200 OK con error de lógica** → el backend está bien, el problema
|
|
está en la conversación con el agente
|
|
- **401/403** → problema de auth / connection / credentials
|
|
- **502/504** → problema de red entre WxO y tu backend (firewall, DNS,
|
|
Cloud Run cold start, etc.)
|
|
|
|
---
|
|
|
|
## Step 9 — Activar Plan A (webhook → Runs API)
|
|
|
|
Si tu solución tiene auto-trigger desde un sistema externo:
|
|
|
|
1. Capturá el `WXO_AGENT_ID` (paso 5)
|
|
2. Asegurate que `WATSONX_API_KEY` está en `.env`
|
|
3. Re-deployá el backend/mocks (`docker compose up -d --force-recreate`)
|
|
4. Probá disparando un evento desde el sistema externo
|
|
5. Mirá los logs: debería ver `→ POST /v1/orchestrate/runs ... 200`
|
|
|
|
Issue I-011 si los env vars no se actualizan: `restart` no relee `.env`,
|
|
usar `--force-recreate`.
|
|
|
|
---
|
|
|
|
## Step 10 — Set up monitoring básico
|
|
|
|
- Coolify alerta por email si el container reinicia >3 veces en 5 min
|
|
- Healthcheck endpoint custom si necesitás
|
|
- Logs accesibles desde Coolify panel
|
|
- `./evals/smoke-test.sh` corriendo nightly desde CI
|
|
|
|
---
|
|
|
|
## Checklist final
|
|
|
|
- [ ] Step 0 — Pre-reqs listos
|
|
- [ ] Step 1 — ADK provisionado + modelo disponible
|
|
- [ ] Step 2 — `.env` completo
|
|
- [ ] Step 3 — Backend/mocks responden 200 en /health
|
|
- [ ] Step 4 — `./scripts/deploy-wxo.sh` sin errores
|
|
- [ ] Step 5 — IDs capturados y propagados
|
|
- [ ] Step 6 — Embed Security OFF
|
|
- [ ] Step 7 — Smoke test pasa
|
|
- [ ] Step 8 — Direct probe responde 200
|
|
- [ ] Step 9 — (si aplica) Plan A funciona
|
|
- [ ] Step 10 — Monitoring básico
|
|
|
|
Cuando los 10 estén ✅, estás listo para demo.
|
|
|
|
---
|
|
|
|
## Si algo se rompió en producción
|
|
|
|
Ver `docs/RUNBOOK.md` para recovery procedures.
|