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>
2.3 KiB
Guía conversacional
Cómo guiar la conversación con el usuario en la Fase 1 de la skill.
Apertura
"Genial, vamos a arrancar una solución WxO nueva. Primero necesito entender el caso. ¿Para qué cliente o caso de uso es?"
Preguntas en cascada
1. Cliente / Caso
-
Si menciona un cliente FIT existente:
"¿Querés que traiga contexto de la ficha del cliente en Outline y deals activos de HubSpot? Puedo invocar la skill
consulta-fichas." -
Si menciona un caso de uso técnico ("mesa N1", "QA testing", etc.):
"Ok, ¿es similar a alguno que hayamos hecho? (Cotemar = mesa N1, Dun = QA copilot). Si tenés transcripción, email, RFP o diagrama, mandalo."
-
Si es vago:
"Para diseñar la arquitectura necesito saber: (a) qué le pide el usuario al agente, (b) qué sistemas externos necesita tocar, (c) qué procedimiento debe seguir. Si tenés un caso concreto, contámelo paso a paso."
2. Dominios
Después de oír el caso, decir lo que vos VES:
"Por lo que me contás identifico estos dominios:
- [X] — porque mencionaste [evidencia]
- [Y] — porque [evidencia]
¿Falta alguno? ¿Alguno sobra?"
3. Sistemas externos
"Qué sistemas tocaría cada dominio?
- ¿Son sistemas reales (AD, ServiceNow, SAP, Dynatrace) que ya existen?
- ¿O vamos a mockear todo para un PoC?
- ¿Hay backend propio que ya tenemos que extender?"
4. Stack web
"Para la capa web hay dos happy-paths:
- FastAPI + HTMX (SSR) — perfecto para demos, control planes, paneles operativos
- FastAPI + React + Vite — para apps productivas con varios usuarios
¿Cuál te encaja?"
5. Confirmación
Antes de empezar a generar:
"Resumiendo:
- Cliente: X
- Topología: 1 orchestrator + N specialists
- Agentes: [lista con nombres]
- Tools: [Python para mocks, OpenAPI para backend Y]
- Web: HTMX
- Runbooks: [lista]
¿Avanzo con esto? ¿Querés cambiar algo?"
Cuándo NO seguir
Detenerse y pedir más contexto si:
- No queda claro qué le pide el usuario al agente
- No queda claro qué sistemas externos hay
- La topología propuesta tiene un agente con >10 tools (split)
- El orchestrator necesitaría tools de remediación (rediseñar)
- Hay >5 dominios y el usuario no quiere multi-capa (advertir consecuencias)