ADR / 014

Exponer las capacidades del agente como contratos de herramienta acotados, no como API de sistema en bruto

Cada herramienta declara propósito, entrada, salida, permisos, precondiciones, efecto, fallo y reversibilidad, y los impone en código, para que el prompt no sea la última línea de defensa.

Patrón de referencia

Elaborado de forma independiente. No contiene detalles de implementación, nombres internos ni cifras de ningún empleador o cliente.

01Contexto

Un agente piloto usaba un usuario de integración con acceso general a la API del CRM. Podía leer y escribir cualquier objeto al que llegara la integración. Las salvaguardas vivían en el prompt de sistema. Un cambio de prompt durante las pruebas le permitió actualizar etapas de oportunidad que solo debía leer.

02Factores de decisión

  1. F01

    Mínimo privilegio para un actor que razona de forma probabilística

  2. F02

    Reglas impuestas donde no se pueden sortear con argumentos

  3. F03

    Idempotencia ante reintentos y peticiones duplicadas

  4. F04

    Capacidades que se puedan revisar y probar

03Opciones consideradas

Opciones consideradas: cuándo sería cada una la elección adecuada, qué cuesta y el veredicto con estas premisas
OpciónEncaja cuandoCoste / contrapartidaVeredicto
Acceso general a la API con salvaguardas en el promptPrototipos con datos sintéticosEl prompt es el único control; una edición amplía la autoridadDescartada
Acceso de solo lectura; las personas hacen todas las escriturasEl agente solo asiste y nunca prepara borradores en un sistemaSin borradores; valor limitadoSegún el contexto
Un pequeño catálogo de herramientas específicas con contratos impuestosAgentes que preparan borradores o actúan en sistemas de registroHerramientas que diseñar, versionar y probarElegida

Cada opción es la adecuada con ciertas premisas. El veredicto se refiere al contexto descrito arriba.

04Decisión

Exponer solo herramientas específicas de la tarea. Cada una tiene un contrato (propósito, entrada y salida tipadas, permisos, precondiciones, efecto, comportamiento ante fallos y reversibilidad) que la propia herramienta impone: los borradores no pueden convertirse en registros, los mensajes no pueden enviarse sin una referencia de aprobación y los ID de petición duplicados devuelven el resultado existente. Las capacidades con consecuencias (aprobación de descuentos, creación de clientes en el ERP, fusión de cuentas) no son herramientas. Las herramientas se ejecutan con la visibilidad del usuario que hace la petición, y cada llamada queda registrada en la traza.

05Consecuencias

Lo que esta elección cambia en el resto del sistema.

  1. Autoridad

    La autoridad se puede revisar leyendo el catálogo de herramientas.

  2. Seguridad

    Los cambios de prompt no pueden ampliar lo que el agente puede hacer.

  3. Idempotencia

    Los reintentos y las peticiones duplicadas son seguros por construcción.

  4. Cambio y releases

    Añadir una capacidad es una decisión de diseño con contrato, no un cambio de configuración.

06Cuándo revisarla

La decisión se sostiene mientras se mantenga su contexto. Hay que cuestionarla cuando:

01

La plataforma ofrece de forma nativa permisos de agente granulares y exigibles.

02

El agente solo lee y resume.

07Dónde se aplica esta decisión

La decisión explica por qué se eligió este camino; cada caso muestra cómo forma parte de una arquitectura más amplia.

  1. Caso de IA / 01Diseñar una preparación con IA basada en evidencias para las decisiones comercialesUna sola arquitectura para antes de una visita a cliente y antes de una revisión de cuenta: contexto gobernado ensamblado de forma determinista, un contrato de contexto por fuente, cada afirmación tipada y citada, herramientas de solo lectura acotadas, un comportamiento explícito cuando el contexto está obsoleto, es contradictorio o falta—y la decisión, en manos de una persona.IA y Flujos AgénticosRevenue OperationsDatos e IntegracionesCaso de arquitectura · 12 min
  2. Caso de IA / 02Diseñar una entrada asistida por IA para el trabajo comercial no estructuradoUn punto de entrada comercial compartido convertido en trabajo estructurado y con responsable: una taxonomía escrita antes que el modelo, la intención mixta descompuesta en elementos de trabajo que comparten una misma referencia de origen, entidades ofrecidas como candidatos respaldados por evidencia, responsables y relojes operativos asignados por reglas deterministas, revisión situada donde la ambigüedad pasa a tener consecuencias—y ningún compromiso externo sin una persona.IA y Flujos AgénticosArquitectura de ProcesosAutomatizaciónCaso de arquitectura · 11 min
  3. Caso de IA / 03Diseñar una gestión de datos asistida por IA sin trasladar la autoridad sobre los datos maestrosIA que hace más rápidos a los data stewards sin convertirse en el data steward: candidatos encontrados, ordenados por impacto y explicados con evidencia y diferencias; una cola del data steward gobernada; identidad, fusión y clasificación con consecuencias decididas por personas que responden de ellas; decisiones aceptadas que ejecutan los propios procesos del sistema; y resultados que mejoran la evaluación y las reglas, nunca los permisos del modelo.IA y Flujos AgénticosDatos e IntegracionesArquitectura de Sistemas y CRMCaso de arquitectura · 10 min
  4. Caso de IA / 08Rediseñar el procesamiento de RFQ con IA sin trasladar la autoridad comercial al agenteUn rediseño del modelo operativo del procesamiento de RFQ: qué trabajo necesita razonamiento, cuál es una regla determinista y cuál conlleva autoridad de negocio; después, un agente que prepara las solicitudes con evidencias y nunca las confirma.IA y Flujos AgénticosArquitectura de ProcesosArquitectura de Sistemas y CRMCaso de arquitectura · 9 min

Decisiones de las que depende o a las que condiciona.

  1. ADR / 013Conceder autoridad al agente por acción y consecuencia, nunca por confianzaClasificar cada acción que un agente podría realizar (leer, recomendar, preparar un borrador, ejecutar, aprobación humana o prohibida) según su consecuencia y reversibilidad. La confianza cambia cómo se presenta el trabajo, no quién puede comprometerlo.Patrón propuestoIA · Autoridad · Gobierno