Cómo especificar un agente SDD antes de su implementación

SDD + Agentes: cómo especificar un agente antes de construirlo

Tiempo estimado de lectura: 5 min

Ideas clave

• Especificar antes de construir: define flujos de decisión, límites de herramientas y condiciones de parada antes de programar.
• SDD para agentes ≠ SDD tradicional: los agentes requieren specs que formalicen libertad, herramientas y puntos de escalado humano.
• Tres bloques críticos: topología de decisión, contratos de herramienta con schemas y guardrails cuantificables.
• La spec debe ser ejecutable: tests automatizados, simuladores de fallo y verificación en CI/CD.

 

Introducción

SDD + Agentes: cómo especificar un agente antes de construirlo — dilo antes de teclear. Si no documentas la caja de arena cognitiva del LLM, lo que construyas será frágil, caro y peligroso. La especificación no es burocracia: es la diferencia entre un experimento que explota y un servicio que vive en producción.

En las primeras líneas: especificar un agente significa definir flujos de decisión, límites de herramientas y condiciones de parada antes de escribir una sola línea de código. Hazlo así y reduces bucles infinitos, facturas de API descontroladas y escrituras destructivas en tus bases.

Resumen rápido (lectores con prisa)

Qué es: Una spec agéntica formaliza topología de decisión, contratos de herramientas y condiciones de parada.

Cuándo usarla: Antes de implementar agentes que razonan o que pueden tocar recursos críticos.

Por qué importa: Evita comportamientos estocásticos dañinos, costes inesperados y fallos de integridad de datos.

Cómo se aplica: Define un patrón operativo único, schemas de entrada/salida para cada tool, y guardrails cuantificables con telemetría y pruebas.

Por qué SDD para agentes no es lo mismo que SDD tradicional

En apps CRUD, spec = modelos de datos + endpoints + contratos. Un 404 es un fallo leve. Un agente sin spec puede intentar cien variaciones de la misma consulta SQL, escribir datos corruptos o invocar herramientas fuera de scope. Aquí falla la arquitectura, no el prompt.

Los agentes razonan de forma estocástica. Por eso la spec debe formalizar:

• Qué libertad tiene el agente en cada punto.
• Qué herramientas puede tocar y cómo.
• Cuándo debe pararse y llamar a un humano.

Anthropic recomienda priorizar flujos orquestados sobre autonomía total para casos críticos (ver: Anthropic — Building effective agents). Toma nota: la industria no apuesta por “agentes libres” en producción sin guardrails.

Tres bloques que debe cubrir tu spec agéntica

1) Flujos de decisión: topología y patrón operativo

Decide uno (y solo uno) de estos patrones por caso de uso:

• Enrutamiento semántico: el LLM clasifica intenciones y delega a código determinista.
• Máquina de estados orquestada: el LLM elige transiciones entre nodos predefinidos (n8n, LangGraph, XState).
• Bucle ReAct autónomo: pensamiento-observación-acción libre (solo para experimentos controlados).

No mezcles sin regla. Define explícitamente qué patrón rige cada intent/endpoint y por qué.

2) Límites de herramientas (Tool Boundaries)

Una herramienta para un agente no es un endpoint cualquiera. Tu spec de herramienta debe incluir, al menos:

• Contrato de datos (Zod o JSON Schema). No aceptes “any”.
• Descripciones semánticas por campo: guía al LLM sobre qué producir exactamente.
• Precondiciones de uso: cuándo está permitido invocar la tool.
• Protocolo de fallo: ¿autocorrección (con el error serializado), retry con backoff, usar valor por defecto o abortar y escalar?

Ejemplo mínimo (JSON Schema + fallback):

{
  "name": "createUser",
  "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] },
  "description": "Crea un usuario. email debe ser un correo válido. No inferir dominios.",
  "precondition": "email provisto por usuario",
  "onError": { "strategy": "abort_and_escalate", "max_retries": 0 }
}

Si dejas el onError en blanco, el agente decidirá por su cuenta —y lo hará mal.

3) Guardrails y condiciones de parada

Los guardrails no son sugerencias; son límites numéricos y verificables:

• Max Steps: 5–10 iteraciones razonables por sesión antes de forzar cierre.
• Retries por herramienta: típicamente 1–3, con backoff y registro.
• Presupuesto operativo: tokens máximos por ejecución y tiempo máximo (p. ej. 30s wall clock).
• Reglas de escalado humano: por ejemplo, tres fallos consecutivos de la misma tool o confianza del modelo < 0.6 → escalar.

Documenta esos números en la spec. Implanta telemetría que lo verifique en tiempo real.

Ingeniería práctica: plantilla rápida para tu spec agéntica

Un documento mínimo y accionable debe contener:

1. Directiva principal (system prompt base, objetivo inmutable).
2. Fronteras negativas (anti-prompts: qué nunca debe hacer el agente).
3. Contrato de memoria (qué guarda la memoria episódica y qué va a la semántica, p. ej. pgvector).
4. Matriz de herramientas (schema, descripciones, precondiciones, fallback).
5. Criterios de interrupción y política de escalado humano.
6. Tests de comportamiento (simulaciones de fallo: error DB, timeout API, input malicioso).

Incluye URLs en la spec para APIs críticas, contratos de datos y documentación de seguridad. Un equipo debe poder reproducir el flujo completo sin leer código.

Trade‑offs y decisiones reales

– Ventana de contexto gigante vs memoria estructurada: ventajas teóricas hay, pero en producción la memoria estructurada gana por latencia, coste y precisión (ver problema “lost in the middle”: arXiv:2307.03172).

– Autonomía vs auditabilidad: cuanto más autónomo, menos auditable. Para negocios, prioriza auditabilidad.

– Retry agresivo vs abort + humano: lo primero puede romper tu DB; lo segundo ralentiza workflows pero salva integridad.

Cierre operativo: de la spec al CI/CD

La spec no es un PDF muerto. Debe formar parte del pipeline:

• Tests automatizados que validen precondiciones y fallbacks.
• Simuladores que reproduzcan errores de herramientas.
• Guardrails chequeados en staging y alertas de telemetría en producción.

Si tu spec no se puede testear automáticamente, no es spec: es promesa. Y las promesas no pagan facturas.

Define la caja de arena antes de soltar los músculos del agente. Es la única manera de que tus agentes actúen con intención, no con catástrofe.

Dominicode Labs

Para equipos que implementan pipelines y simuladores de fallo como parte de la spec, una referencia práctica y recursos complementarios están disponibles en Dominicode Labs. Considéralo como un recurso adicional para integrar tests y telemetría en tu CI/CD.

 

FAQ

• ¿Por qué no vale con un buen prompt para controlar un agente?
• ¿Qué es un contrato de herramienta y por qué usar JSON Schema?
• ¿Cuántas iteraciones (Max Steps) son razonables?
• ¿Cómo debo manejar fallos recurrentes de una herramienta?
• ¿Qué pruebas automatizadas son mínimas para una spec agéntica?
• ¿Dónde documentar la política de escalado humano?

¿Por qué no vale con un buen prompt para controlar un agente?

Un prompt no formaliza contratos ni límites verificables. Los agentes razonan de forma estocástica; sin schemas, precondiciones y guardrails numéricos, el prompt será frágil frente a inputs inesperados.

¿Qué es un contrato de herramienta y por qué usar JSON Schema?

Un contrato de herramienta define tipos, formatos y campos requeridos. JSON Schema o Zod son formalismos que permiten validar entradas/salidas de forma determinista y evitar “any” que produzca comportamiento impredecible.

¿Cuántas iteraciones (Max Steps) son razonables?

La guía práctica sugiere entre 5 y 10 iteraciones por sesión antes de forzar cierre. Ese rango reduce bucles infinitos y consumo excesivo de recursos.

¿Cómo debo manejar fallos recurrentes de una herramienta?

Define un protocolo de fallo en la spec: retries limitados con backoff, registro y una estrategia de escalado (por ejemplo, abort_and_escalate tras N retries). No dejes el comportamiento en blanco.

¿Qué pruebas automatizadas son mínimas para una spec agéntica?

Al menos: validación de precondiciones, simuladores de fallo de tools (DB error, timeout), y tests que verifiquen que los guardrails se activan (Max Steps, budget, retries).

¿Dónde documentar la política de escalado humano?

La política de escalado debe estar en la spec principal, con reglas verificables (ej. tres fallos consecutivos de la misma tool o confianza < 0.6 → escalado) y enlaces a contactos/runbooks en tu repositorio de operaciones.