En esta página
Un ejemplo de código recordado puede hacer que actualizar un cliente parezca sencillo. En este caso ilustrativo, un agente redacta uno de memoria. El nombre del método es plausible. Los campos resultan familiares. El entorno de prueba acepta la solicitud. El contrato real del proveedor cambió después de escribirse el ejemplo.
El fallo empezó antes de la llamada. El agente utilizó la memoria donde necesitaba una fuente actual.
Una charla sobre agentes y API cambiantes defiende recuperar el fragmento exacto que responde a la tarea. El principio es especialmente útil en integraciones, donde la definición de una API es un contrato en movimiento y no una lectura de fondo.
Una llamada plausible no es un contrato
Los modelos grandes aprenden de código, documentación y conversaciones creados en distintas fechas. Esos ejemplos pueden seguir siendo útiles para la estructura y las convenciones. No establecen qué acepta hoy un proveedor, en la versión utilizada por una aplicación y en la cuenta conectada a la sincronización.
La guía de Shopify sobre versiones de API documenta publicaciones trimestrales y notas de cambios específicas de cada versión. Una persona desarrolladora puede elegir una versión con soporte del proveedor y leer los cambios relevantes antes de actualizar. La versión incluida en la solicitud importa más que el recuerdo del modelo sobre «la API de Shopify».
La referencia de Brevo para crear contactos añade otra capa: los atributos personalizados deben existir en la cuenta y los valores que no coinciden con el tipo declarado pueden ignorarse. Un esquema genérico de API no puede decirle al agente qué atributos creó esta cuenta concreta. Eso exige una consulta o validación limitada a la cuenta.
El contrato actual tiene al menos dos partes: la operación publicada por el proveedor y los objetos configurados en la cuenta. El agente necesita ambas cuando la tarea depende de ambas.
La versión y el ámbito de la cuenta deben acompañar la respuesta recuperada. Una descripción correcta para una versión de API puede ser errónea para otra. Un nombre de atributo correcto en una cuenta de Brevo quizá no exista en la siguiente. Incluye la versión elegida y el identificador de la cuenta en los datos de prueba; haz fallar el test si alguno no se conoce. El asistente no debe resolver esa ambigüedad adivinando a partir de un ejemplo parecido.
Recupera la pequeña parte que necesitas
Una mala solución sería pegar diez mil definiciones de operaciones en cada turno del agente. El modelo tendría más texto que buscar, más fragmentos obsoletos que confundir y menos espacio para la tarea real. Pregunta por la operación que mueve este registro y las restricciones que determinan si tiene éxito.
Para actualizar un contacto, el material útil podría incluir la ruta de la operación, los campos permitidos, el identificador obligatorio, las reglas de tipo de atributos y la versión actual de la API. Entrega al agente esos fragmentos con sus URL de origen. Deja lo demás disponible para otra pregunta.
La guía de Tajo sobre la API de Brevo puede ayudar a orientarse en el proveedor. Antes de usar una llamada concreta en código de producción, debe confirmarla la referencia oficial. Quien lee necesita una fuente que pueda volver a abrir cuando cambie el proveedor.
Un repositorio puede hacer esto repetible. Registra la versión fijada, la huella de la especificación guardada y la fecha en que se comprobó. Una huella distinta no demuestra un cambio incompatible; indica qué hay que comparar. Un modelo puede resumir la diferencia pertinente. Aun así, las pruebas deben ejecutar las operaciones de las que depende una sincronización funcional.
Trata la solicitud generada como una hipótesis con tres comprobaciones. Primera: ¿coincide con la operación oficial y la versión fijada? Segunda: ¿contiene la cuenta conectada los objetos que la solicitud supone? Tercera: ¿deja una ejecución limitada el estado esperado? Una comprobación del esquema responde a la primera, una consulta de la cuenta a la segunda y una lectura después de escribir a la tercera. Ninguna sustituye las otras dos.
- Operación del proveedor versión · campos
Qué acepta la API publicada
- Cuenta conectada atributo · tipo
Qué existe en esta cuenta
- Ejecución limitada escritura · lectura
Qué cambió realmente
No confundas recuperación con prueba de ejecución
Una objeción razonable es: «La documentación oficial puede ir por detrás del servicio real». Puede ocurrir. Leerla es necesario, pero no suficiente. Una prueba de contrato debe enviar una solicitud limitada mediante el mismo código cliente y comprobar la respuesta y el estado del destino. Si el servicio se comporta de otra manera, registra la discrepancia y delimita la operación afectada.
Un agente también debe detenerse si el contrato es ambiguo. Una correspondencia adivinada y aplicada a muchos contactos cuesta más que revisar una definición de campo. La guía para integrar varias herramientas empresariales empieza identificando la fuente de verdad de cada objeto de datos; la vigencia de la API aplica la misma disciplina a las operaciones que transportan ese objeto.
El coste es mantener referencias y pruebas actuales. La alternativa es pagar la misma suposición obsoleta en cada registro que toque la sincronización.
El modelo puede recordar la idea. Debe leer el contrato y comprobar la cuenta que va a cambiar.
Esto no tiene por qué volver lenta cada interacción. Guarda temporalmente el fragmento concreto con su versión y el esquema de la cuenta hasta que ocurra un evento de invalidación conocido o llegue un momento elegido para actualizar. Conserva la fuente y la fecha de consulta con la decisión. Así, el coste de leer de nuevo se paga cuando el contrato puede haber cambiado, no en cada fila de una sincronización ya aprobada.
Preguntas frecuentes
¿Por qué puede equivocarse un asistente de IA sobre una API?
Su entrenamiento y los ejemplos guardados pueden preceder al esquema, versión o configuración actual de una cuenta del proveedor. Hay que consultar el contrato oficial vigente para la operación concreta.
¿Fijar una versión de API resuelve el problema?
Estabiliza el contrato durante un periodo, pero las versiones envejecen y la configuración de la cuenta también importa. Sigue la versión con soporte del proveedor y lee las notas al actualizarla.
¿Qué debe recuperar un agente?
La definición concreta de la operación, sus campos obligatorios y las notas de versión pertinentes, con enlace y fecha. No cargues todo el catálogo del proveedor para responder sobre una sola llamada.