farentsen/fit-boilerplate-wox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
fit-boilerplate-wox/docs/DEPLOY_TO_NEW_WOX.md
Felipe Arentsen b089c2ef18
Some checks failed
CI — Lint + Evals / lint (push) Has been cancelled
Details
CI — Lint + Evals / smoke (push) Has been cancelled
Details
feat: v1 — boilerplate WxO + web 
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>
2026-05-16 14:59:44 +00:00

5.1 KiB
Raw Permalink Blame History

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

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:

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:

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:

# 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:

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

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

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

./evals/smoke-test.sh

Si pasa, validá manualmente:

# 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á:

./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.

Reference in New Issue View Git Blame Copy Permalink