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

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

# 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

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

# 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

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

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

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

orchestrate knowledge-bases import -f wxo/knowledge_base/mi_kb.kb.yaml
orchestrate knowledge-bases list

Schema YAML mínimo:

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

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

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

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

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

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

# 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

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.