fit-boilerplate-wox/docs/adk-2x-cheatsheet.md

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