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>
This commit is contained in:
Felipe Arentsen
262
docs/adk-2x-cheatsheet.md
Normal file
262
docs/adk-2x-cheatsheet.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# ADK 2.x Cheatsheet
|
||||
|
||||
Comandos, schemas YAML, gotchas. **Versión pineada del template: `ibm-watsonx-orchestrate==2.1.0`**.
|
||||
|
||||
> `./scripts/check-adk-version.sh` te avisa si hay versión nueva en PyPI.
|
||||
|
||||
## Setup del ADK
|
||||
|
||||
```bash
|
||||
python3.12 -m venv .venv-wxo
|
||||
source .venv-wxo/bin/activate
|
||||
pip install --upgrade "ibm-watsonx-orchestrate==2.1.0"
|
||||
orchestrate --version # debe imprimir 2.1.x
|
||||
```
|
||||
|
||||
## Environments
|
||||
|
||||
```bash
|
||||
# Registrar tenant
|
||||
orchestrate env add -n mi-tenant \
|
||||
--iam-url https://iam.cloud.ibm.com/identity/token \
|
||||
-u "$ORCHESTRATE_API_URL"
|
||||
|
||||
# Activar (pide API key, lo guarda en keyring)
|
||||
orchestrate env activate mi-tenant
|
||||
|
||||
# Listar
|
||||
orchestrate env list
|
||||
|
||||
# Borrar
|
||||
orchestrate env remove -n mi-tenant
|
||||
```
|
||||
|
||||
## Modelos disponibles
|
||||
|
||||
```bash
|
||||
orchestrate models list # todos
|
||||
orchestrate models list | grep gpt-oss # filtro
|
||||
```
|
||||
|
||||
**Preferred para tool-calling:** `groq/openai/gpt-oss-120b`
|
||||
**Fallback:** `meta-llama/llama-3-3-70b-instruct` (con caveat — ver `known-issues.md`)
|
||||
|
||||
## Conexiones
|
||||
|
||||
```bash
|
||||
# Crear
|
||||
orchestrate connections add -a mi_app
|
||||
|
||||
# Configurar tipo (key_value | api_key | bearer | oauth2)
|
||||
# IMPORTANTE: hacerlo en draft Y live
|
||||
orchestrate connections configure -a mi_app --env draft --type team --kind key_value
|
||||
orchestrate connections configure -a mi_app --env live --type team --kind key_value
|
||||
|
||||
# Credenciales
|
||||
orchestrate connections set-credentials -a mi_app --env draft -e "BASE_URL=https://..."
|
||||
orchestrate connections set-credentials -a mi_app --env live -e "BASE_URL=https://..."
|
||||
|
||||
# Para API key con header custom (estilo Dun):
|
||||
orchestrate connections set-credentials -a mi_app --env draft \
|
||||
-e "X_API_KEY=secreto" -e "API_KEY_HEADER=X-Orchestrate-Token"
|
||||
|
||||
# Listar
|
||||
orchestrate connections list
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
### Python `@tool`
|
||||
|
||||
```bash
|
||||
orchestrate tools import -k python \
|
||||
-f wxo/tools/python/mi_tool.py \
|
||||
-r wxo/tools/python/requirements.txt \
|
||||
--app-id mi_app
|
||||
```
|
||||
|
||||
Cada función decorada con `@tool(...)` se descubre y registra. Si tu
|
||||
archivo tiene 6 funciones decoradas → 6 tools.
|
||||
|
||||
### OpenAPI
|
||||
|
||||
```bash
|
||||
orchestrate tools import -k openapi \
|
||||
-f wxo/tools/openapi/mi_spec.yaml \
|
||||
--app-id mi_app
|
||||
```
|
||||
|
||||
Pre-requisitos del spec:
|
||||
- OpenAPI 3.0 o 3.1
|
||||
- `description` per-operation (no solo `summary`)
|
||||
- `security` per-operation (no global)
|
||||
- `servers[0].url` apuntando al host correcto (patch en deploy time)
|
||||
|
||||
### MCP
|
||||
|
||||
```bash
|
||||
orchestrate connections add -a mi_mcp_app
|
||||
orchestrate connections configure -a mi_mcp_app --env draft --type team --kind mcp
|
||||
orchestrate connections set-credentials -a mi_mcp_app --env draft \
|
||||
-e "MCP_SERVER_URL=https://mi-mcp-server.example.com"
|
||||
```
|
||||
|
||||
ADK descubre las tools del MCP server automáticamente.
|
||||
|
||||
## Knowledge bases
|
||||
|
||||
```bash
|
||||
orchestrate knowledge-bases import -f wxo/knowledge_base/mi_kb.kb.yaml
|
||||
orchestrate knowledge-bases list
|
||||
```
|
||||
|
||||
Schema YAML mínimo:
|
||||
```yaml
|
||||
spec_version: v1
|
||||
kind: knowledge_base
|
||||
name: mi_kb
|
||||
description: "..."
|
||||
documents:
|
||||
- "runbooks/runbook-01.txt"
|
||||
- "runbooks/runbook-02.txt"
|
||||
embeddings:
|
||||
model: ibm/slate-125m-english-rtrvr
|
||||
```
|
||||
|
||||
Los paths de `documents` son relativos al directorio del YAML.
|
||||
|
||||
## Agentes
|
||||
|
||||
```bash
|
||||
# Import (al draft env)
|
||||
orchestrate agents import -f wxo/agents/mi_agente.agent.yaml
|
||||
|
||||
# Deploy a live
|
||||
orchestrate agents deploy --name mi_agente --env live
|
||||
|
||||
# Listar
|
||||
orchestrate agents list
|
||||
|
||||
# Test con fixture
|
||||
orchestrate agents test mi_agente --input-file evals/scenarios/test1.json
|
||||
```
|
||||
|
||||
Schema YAML mínimo de un agente:
|
||||
```yaml
|
||||
spec_version: v1
|
||||
kind: native
|
||||
name: mi_agente
|
||||
display_name: "Mi Agente"
|
||||
description: "..."
|
||||
style: react
|
||||
llm: groq/openai/gpt-oss-120b
|
||||
instructions: |
|
||||
Eres ...
|
||||
collaborators: []
|
||||
tools: []
|
||||
knowledge_base: []
|
||||
starter_prompts:
|
||||
is_default_prompts: true
|
||||
prompts: []
|
||||
```
|
||||
|
||||
## Canales
|
||||
|
||||
```bash
|
||||
# Web chat
|
||||
orchestrate channels create webchat \
|
||||
--agent mi_agente \
|
||||
--name "Mi Agente - Web"
|
||||
|
||||
# Listar
|
||||
orchestrate channels list
|
||||
```
|
||||
|
||||
El comando imprime el snippet `<script>` con `agentId` y
|
||||
`agentEnvironmentId`. Anotalos.
|
||||
|
||||
**Paso manual obligatorio después:**
|
||||
> WxO Console → Settings → Embed Security → **Off**
|
||||
|
||||
## Runs API (Plan A — webhook to agent)
|
||||
|
||||
Para que un sistema externo dispare al agente sin pasar por chat:
|
||||
|
||||
```bash
|
||||
# 1. Conseguir IAM bearer token
|
||||
curl -s -X POST "https://iam.cloud.ibm.com/identity/token" \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$ORCHESTRATE_API_KEY" \
|
||||
| jq -r .access_token
|
||||
|
||||
# 2. POST a /v1/orchestrate/runs
|
||||
curl -X POST "$ORCHESTRATE_API_URL/v1/orchestrate/runs" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"agent_id": "<uuid-del-agente-en-live>",
|
||||
"message": "Hubo un evento X en el servicio Y..."
|
||||
}'
|
||||
```
|
||||
|
||||
Ver `cotemar-poc-n1/mocks/dynatrace/webhook.py` para implementación
|
||||
completa (incluye refresh del token, error handling, retry).
|
||||
|
||||
## Webhooks lifecycle (run completion)
|
||||
|
||||
WxO puede llamar a tu backend cuando un run termina. Validá la firma:
|
||||
|
||||
```python
|
||||
# Headers a recibir:
|
||||
# X-Orchestrate-Timestamp
|
||||
# X-Orchestrate-Nonce
|
||||
# X-Orchestrate-Signature
|
||||
|
||||
# HMAC-SHA256(secret, f"{timestamp}.{nonce}.{body}")
|
||||
# Tolerancia 300s sobre timestamp
|
||||
# 408 si stale, 401 si firma mala
|
||||
```
|
||||
|
||||
Ver `wxo/tools/openapi/_webhook_validator.py` template.
|
||||
|
||||
## Evaluaciones (CLI nativa)
|
||||
|
||||
```bash
|
||||
# Test individual
|
||||
orchestrate agents test mi_agente --input-file scenario.json
|
||||
|
||||
# Suite (un .json por scenario)
|
||||
for f in evals/scenarios/*.json; do
|
||||
orchestrate agents test mi_agente --input-file "$f"
|
||||
done
|
||||
```
|
||||
|
||||
Output: respuesta del agente + trace de tool calls.
|
||||
|
||||
## Cleanup
|
||||
|
||||
```bash
|
||||
orchestrate agents remove --name mi_agente
|
||||
orchestrate tools remove --name mi_tool
|
||||
orchestrate knowledge-bases remove --name mi_kb
|
||||
orchestrate connections remove -a mi_app
|
||||
orchestrate channels delete --id <channel-id>
|
||||
```
|
||||
|
||||
El template trae `./scripts/reset-wxo.sh` que hace todo en orden.
|
||||
|
||||
## Gotchas mortales (los que descubrimos pagando)
|
||||
|
||||
| Síntoma | Causa | Fix |
|
||||
|---|---|---|
|
||||
| `kid not found` al deployear a live | Connection no existe en live | `connections configure` en `draft` Y `live` |
|
||||
| `No description provided` al importar OpenAPI | Falta `description` per-operation | Forzar `description = summary or "..."` |
|
||||
| `recursion_limit reached` en runs | >2 tool calls en flow ReAct | Patrón meta-tool |
|
||||
| Agent printea tool calls como texto | Llama 3.3 70B drift después del turno 3 | Cambiar a `gpt-oss-120b` + REGLA #0 en prompt |
|
||||
| Pydantic 422 en tool input | LLM mandó `"123"` cuando schema espera `int` | `@field_validator(mode="before")` con coerción |
|
||||
| `ModuleNotFoundError: wxo.tools._compat` | TRM importa el archivo standalone | Inlinear el shim en cada `tools.py` |
|
||||
| Embed widget queda en "Cargando..." | Embed Security ON en WxO | Settings → Embed Security → Off |
|
||||
| Coolify Traefik 503 | Healthcheck `wget --spider` falla | Usar `wget -qO-` o `curl -sf` |
|
||||
| Traefik default cert en vez de Let's Encrypt | Labels Traefik manuales en compose | Solo `traefik.enable=true` |
|
||||
|
||||
Ver `known-issues.md` para el detalle completo de cada uno.
|
||||
Reference in New Issue
Block a user