Construye un Agente en JavaScript

Esta es una versión en español de una charla presentada en MelbJS el 13 de agosto de 2025 sobre cómo construir un agente en JavaScript inspirada en el artículo original How to Build an Agent de Thorsten Ball y el blog de Amp

Enlace al video en YouTube https://www.youtube.com/embed/rEf2-VC2jEI y al repositorio con el código de ejemplo https://github.com/sentience/how-to-build-an-agent-in-javascript

Resumen ejecutivo: la idea central es simple y poderosa. Con unas pocas centenas de líneas de código en Node.js escrito en TypeScript podemos construir un agente IA capaz de mantener conversación, invocar herramientas y modificar archivos del sistema de forma controlada. Este flujo convierte a un modelo de lenguaje en un agente útil para tareas de desarrollo y automatización.

Conceptos clave: conversación como contexto, herramientas declaradas al modelo, ejecución de herramientas fuera del modelo y retroalimentación de resultados al contexto para continuar la conversación. Es importante entender que los modelos son stateless por defecto por lo que el registro de mensajes actúa como memoria de la conversación.

Implementación paso a paso: crear un cliente para acceder al modelo LLM, por ejemplo Anthropic en Google Vertex, inicializar una clase Agent que gestione la conversación y el ciclo principal de interacción, definir funciones de entrada y salida para el usuario en la interfaz de línea de comandos y mantener un array con la lista de mensajes para enviar al modelo en cada petición.

Chat básico: el agente recoge el mensaje del usuario, lo empaqueta con role user y lo añade al registro de conversación, envía todo el registro al modelo y muestra las respuestas de tipo texto que el modelo devuelve. Este patrón permite mantener el estado de la charla y que el modelo responda con conocimiento del contexto previo.

De chat a agente: para que el modelo pueda interactuar con el entorno hay que definir herramientas. Una herramienta se describe con nombre, descripción y esquema de entrada. Cuando el modelo decide usar una herramienta devuelve un mensaje con tipo tool_use. El receptor humano o el programa ejecutan la herramienta, registran el resultado en la conversación y reenvían todo al modelo. Esto habilita al modelo para modificar el mundo fuera de su ventana de contexto.

Ejemplo de herramienta read_file: define name read_file, descripción breve para indicar que lee contenido de un archivo relativo y un input schema que pide el path. La función asociada en Node.js valida la existencia y devuelve el contenido como texto. El modelo aprende por instrucción cuando debe pedir leer un archivo y puede solicitar read_file con el path deseado.

Ejemplo de herramienta list_files: permite listar directorios. Su input schema acepta un path opcional y la función devuelve listados con marcadores de directorio. El modelo puede así explorar la estructura de un proyecto y luego decidir qué archivos leer o editar.

Control humano: por seguridad conviene introducir un paso de human in the loop para aprobar ejecuciones potencialmente peligrosas. En la demo se reemplaza la función de logging por una petición de consentimiento donde el usuario confirma si autoriza la ejecución de la herramienta. Si no hay consentimiento, el agente informa del rechazo y sigue la conversación.

Ejemplo de herramienta edit_file: con name edit_file y un esquema que pide path, old_str y new_str se permite editar o crear archivos. La función valida que old_str y new_str sean distintos, realiza reemplazos globales o crea el archivo si old_str es vacío y devuelve un resumen de los cambios realizados. Con esta herramienta el agente puede generar o modificar código bajo supervisión.

Flujos prácticos mostrados en la demo: resolver un acertijo guardado en secret-file.txt solicitando a Claude que use read_file, listar el contenido del proyecto con list_files, crear un archivo fizzbuzz.js y ejecutarlo, editar ese archivo para cambiar el rango a 15 y crear un script congrats.js que decodifica un texto rot13. En todos los pasos se ve cómo combinar las tres herramientas con consentimiento humano y la conversación persistente.

Lecciones aprendidas: la arquitectura no requiere magia. Es ingeniería práctica. La clave está en diseñar herramientas con descripciones claras y esquemas robustos, en registrar cada interacción en la conversación y en decidir dónde introducir controles humanos y límites de seguridad. Con aproximadamente 300 a 400 líneas de código se obtiene un agente funcional que puede mejorar la productividad.

Consideraciones de seguridad y gobernanza: limitar el alcance de las herramientas, validar entradas y salidas, exigir consentimiento explícito para operaciones sensibles, registrar auditoría de acciones y aplicar controles de acceso son prácticas recomendadas. Para entornos corporativos es crítico integrar autenticación y políticas de permisos y auditar cambios en el código y en los datos.

Cómo Q2BSTUDIO puede ayudar: en Q2BSTUDIO somos una empresa de desarrollo de software especializada en aplicaciones a medida y software a medida. Ofrecemos servicios integrales de inteligencia artificial para empresas, creación de agentes IA personalizados, integración con servicios cloud AWS y Azure y soluciones de inteligencia de negocio y Power BI. También somos especialistas en ciberseguridad y diseño de flujos con human in the loop para minimizar riesgos operativos.

Nuestros servicios clave: desarrollo de aplicaciones a medida, consultoría de inteligencia artificial y ia para empresas, implementación de agentes IA que interactúan con repositorios y sistemas internos, auditoría y endurecimiento de ciberseguridad, migraciones y despliegue en servicios cloud aws y azure, y dashboards en Power BI para inteligencia de negocio y analítica avanzada.

Por qué integrar agentes IA en su organización: los agentes permiten automatizar tareas repetitivas de desarrollo, análisis de código, generación y edición de archivos, búsquedas contextuales en proyectos y apoyo en decisiones mediante datos. Combinando agentes IA con prácticas de ciberseguridad y gobernanza se puede aumentar productividad sin sacrificar control.

Palabras clave relevantes para posicionamiento: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi. Estas palabras clave aparecen integradas en la descripción de servicios y en los casos de uso para mejorar visibilidad y encontrar soluciones alineadas a las necesidades del cliente.

Llamado a la acción: si quiere explorar cómo un agente IA puede integrarse en sus procesos de desarrollo, auditoría de código o flujos de datos contacte con Q2BSTUDIO para una consultoría inicial. Podemos ayudar a prototipar un agente, definir las herramientas necesarias, implementar controles de seguridad y desplegarlo en AWS o Azure con paneles de Power BI para monitorizar resultados.

Recursos adicionales: código de ejemplo disponible en https://github.com/sentience/how-to-build-an-agent-in-javascript y artículo original en https://ampcode.com/how-to-build-an-agent. Para consultas específicas sobre proyectos empresariales contacte con Q2BSTUDIO y mencione sus objetivos en inteligencia artificial, ciberseguridad o servicios cloud.

Conclusión: construir un agente en JavaScript es accesible, práctico y transformador. Con un diseño correcto de herramientas, un flujo de conversación persistente y controles humanos adecuados se puede crear una asistencia automatizada capaz de leer, listar y editar archivos, automatizar tareas de desarrollo y potenciar la inteligencia de negocio. Q2BSTUDIO acompaña a las empresas en cada paso del camino para sacar partido a estas tecnologías de forma segura y eficaz