Por qué elegimos input() en lugar de run()

Elegir el nombre correcto para un método de una API parece un detalle menor, pero en Q2BSTUDIO entendemos que esas decisiones definen la experiencia de usuario. Al diseñar una API para agentes IA encontramos un dilema sencillo en apariencia: cómo llamar al método principal para interactuar con un agente. La elección afectaría la primera impresión de todos los usuarios, desde desarrolladores que crean software a medida hasta equipos que integran soluciones de inteligencia artificial en sus procesos.

El problema con run Fue tentador seguir la convención de la industria y exponer agent.run(prompt). Parecía lógico, un agente ejecuta tareas, no obstante el feedback fue contundente: la palabra run genera fricción cognitiva. Los usuarios tenían que traducir su intención natural, quiero preguntar algo al agente, a un término técnico, tengo que ejecutar o correr el agente. Esa fricción pequeñísima se multiplicaba miles de veces al día entre nuestros usuarios de soluciones de aplicaciones a medida y servicios cloud aws y azure.

El proceso de investigación Observamos cómo abordaban la API nuevos usuarios sin leer documentación. Primeros intentos de usuarios novatos 40% probaron agent.input() 18% probaron agent.ask() 15% probaron agent.chat() 12% probaron agent.run() 8% probaron agent.process() 7% otras variaciones El dato fue claro: la gente piensa en términos de lo que ELLOS hacen, no de lo que hace el sistema. Prefieren dar entrada, pedir, chatear, no ejecutar procesos.

Evaluación de alternativas 1. agent.chat(prompt) Conversacional y amigable pero implica conversación con estado y puede ser engañoso para llamadas estateless. No todos los agentes charlan, algunos calculan o analizan. 2. agent.ask(prompt) Natural para preguntas y respuestas pero limitante, no todas las interacciones son preguntas y suena raro para comandos como pedir borrar un archivo. 3. agent.prompt(prompt) Exacto técnicamente pero confunde por el uso del mismo término prompt, resulta demasiado técnico para principiantes. 4. agent.process(prompt) Describe lo que ocurre internamente pero es jerga técnica, los usuarios no piensan en procesar algo. 5. agent.invoke(prompt) Sonido profesional pero intimida a quienes empiezan y recuerda a terminología enterprise. 6. agent.input(prompt) Coincide con el modelo mental del usuario, válido para todo tipo de interacción, es autoexplicativo y suena más cercano. 7. agent.run(prompt) Convención de la industria pero obliga a traducir mentalmente la intención y sugiere ejecución de código más que intercambio informacional.

La prueba de sentido común Aplicamos una heurística sencilla: un familiar no técnico podría adivinar la función. Claro para cualquiera agent.input(Translate this to Spanish: Hello) Confuso para no desarrolladores agent.run(Translate this to Spanish: Hello) agent.invoke(Translate this to Spanish: Hello) Input aprobó la prueba. Run e invoke no.

Principio más profundo: perspectiva del usuario vs perspectiva del sistema Esta decisión evidenció una regla básica de diseño API: diseñar desde la perspectiva del usuario, no desde cómo funciona el sistema. Perspectiva del sistema El agente recibe prompt El agente procesa el prompt El agente ejecuta inferencia El agente llama herramientas El agente devuelve respuesta Perspectiva del usuario Yo doy entrada Yo recibo salida La perspectiva del usuario es más simple, más clara y más intuitiva, y eso mejora la adopción tanto en proyectos de software a medida como en integraciones de inteligencia artificial y agentes IA.

La implementación fue trivial El cambio real fue una línea de código pero con impacto enorme. Antes class Agent: def run(self, prompt: str) -> str: return self._process(prompt) Después class Agent: def input(self, prompt: str) -> str: return self._process(prompt) Ese gesto sencillo mejoró la claridad sin sacrificar nada técnico.

Medición del éxito Tras el cambio notamos mejoras cuantificables 60% menos preguntas sobre como usar el agente en nuestros canales de soporte Tasa de éxito en la primera llamada subió de 67% a 89% Tiempo hasta la primera llamada correcta disminuyó 40% Consultas a la documentación sobre uso básico bajaron 55% Estos resultados avalaron la inversión en diseñar para la mentalidad del usuario.

Lecciones aprendidas 1. Cuestiona las convenciones de la industria. Que todos usen run no implica que sea lo más claro. 2. Los datos vencen a la opinión. Teníamos preferencia por run pero el comportamiento de los usuarios nos corrigió. 3. Palabras pequeñas, gran impacto. Un cambio de tres letras transformó la experiencia de desarrolladores que crean aplicaciones a medida y equipos que usan IA para empresas. 4. Diseña para modelos mentales. Alinea la API con cómo piensa el usuario, no con la arquitectura interna. 5. La mejor API casi no necesita documentación. Si la gente adivina, has acertado con el nombre.

Efectos colaterales Esta elección permeó nuestra filosofía de diseño: agent.input( ... ) en lugar de agent.run() agent.history.summary() en lugar de agent.get_execution_log() agent.tools = [...] en lugar de agent.register_capabilities() Adoptamos una postura centrada en experiencia de usuario que aplicamos en servicios como ciberseguridad, pentesting y servicios cloud aws y azure y en productos de inteligencia de negocio y power bi.

Por qué Q2BSTUDIO eligió input en lugar de run En Q2BSTUDIO, empresa especializada en desarrollo de software, aplicaciones a medida, inteligencia artificial, ciberseguridad y servicios cloud, creemos que la tecnología debe adaptarse a las personas. Elegir input comunica a desarrolladores y a equipos no técnicos que interactuar con un agente es tan simple como dar entrada y recibir salida. Esa decisión refleja nuestro enfoque en la creación de soluciones de software a medida y en la integración de agentes IA pensando en usabilidad y eficiencia. Si buscas soluciones de aplicaciones a medida o quieres acompañamiento en proyectos de inteligencia artificial y ia para empresas, en Q2BSTUDIO unimos experiencia técnica y diseño centrado en usuario.

Reflexión final La próxima vez que nombres un método en una API pregúntate desde qué perspectiva lo haces, desde la del sistema o desde la del usuario. Esa sola decisión puede transformar la experiencia de adopción y reducir fricción en proyectos que implican agentes IA, automatización de procesos, servicios de inteligencia de negocio y soluciones cloud. En Q2BSTUDIO diseñamos APIs para que los desarrolladores olviden que están usando una API y se concentren en crear valor, ya sea mediante software a medida, integraciones con Power BI o despliegues seguros en AWS y Azure.