La mayoría de las demos de IA se quedan en el texto. En producción, tu agente debe hacer cosas de forma segura, con trazabilidad y acceso de mínimos privilegios: marcar con estrella un repositorio, crear incidencias, etiquetar pull requests y más, todo con auditoría y sin exponer credenciales.
En esta guía verás un flujo de extremo a extremo donde un LLM alojado en Gaia propone una llamada de herramienta y ACI.dev la ejecuta contra GitHub en nombre del usuario, manteniendo control, seguridad y registro.
Qué construirás: un flujo donde el usuario pide que se marque con estrella el repositorio tobySolutions slash stream2peer, el modelo devuelve una llamada de herramienta estructurada con nombre de función y argumentos en JSON, tu servidor la ejecuta con el SDK de ACI usando la cuenta de GitHub vinculada del usuario y obtienes un resultado limpio y auditable.
Arquitectura en una frase: el cliente envía la intención al LLM de Gaia junto con los esquemas de funciones disponibles, el LLM propone una tool call, y tu backend invoca ACI.dev para ejecutar la acción real sobre GitHub usando el owner vinculado mediante OAuth.
Requisitos previos: Python 3.10 o superior; clave de API y dominio de Gaia compatibles con la API de OpenAI; toolkit de Gaia para levantar y gestionar tus nodos locales; cuenta en ACI.dev con proyecto y agente por defecto, app GITHUB configurada, cuenta de GitHub vinculada por OAuth, GITHUB añadido en allowed apps del agente y una API key del agente para usar con el SDK de ACI.
Configuración única en la plataforma ACI: entra en tu proyecto y agente en platform punto aci punto dev; configura la app GITHUB desde App Store; vincula tu cuenta de GitHub iniciando el flujo OAuth y elige un linked account owner id que recordarás en el código; autoriza a tu agente a usar GITHUB en Project Settings; copia la API key del agente.
Variables de entorno recomendadas en un archivo punto env: GAIA_BASE_URL con la URL de tu dominio Gaia terminando en v1, GAIA_API_KEY con tu clave de Gaia, ACI_API_KEY con la clave del agente de ACI y ACI_OWNER_ID con el owner id seleccionado al vincular la cuenta de GitHub.
Dependencias a instalar con pip o uv pip: openai, python-dotenv y aci. En algunos entornos el paquete se publica como aci y requiere Python 3.10 o superior, por lo que conviene actualizar pip antes de instalar.
Ejemplo mínimo de trabajo explicado: primero descubre el esquema de la función en ACI, por ejemplo GITHUB__STAR_REPOSITORY, para obtener el nombre de la función y la estructura de los argumentos; después envía un chat completion al modelo de Gaia con mensajes y la definición de la herramienta en tools para que el modelo proponga una tool call; al recibir la respuesta, extrae el nombre de la función y los argumentos, aplica guardrails como limitar el owner permitido a tu organización y, por último, delega la ejecución real en ACI mediante handle_function_call pasando el linked_account_owner_id. El resultado será una confirmación de GitHub con la operación completada o un error manejable.
Flujo esperado en producción: el LLM devuelve una llamada a GITHUB__STAR_REPOSITORY con owner y repo; tu servidor llama a ACI con esos argumentos y el owner vinculado; GitHub marca el repositorio con estrella y recibes un payload de éxito que puedes registrar para auditoría.
Por qué funciona este patrón: descubrir el esquema exacto desde ACI evita desalineaciones; restringir las herramientas garantiza que el modelo solo puede llamar a lo que tú expongas; ejecutar en backend mantiene los tokens fuera del alcance del modelo; y auditar te permite registrar cada invocación y aplicar listas de permitidos por organización o repositorio.
Cómo ir más allá de star repo: descubre y expón más funciones de ACI como GITHUB__CREATE_ISSUE para crear incidencias o GITHUB__COMMENT_ON_PR para comentar en pull requests; tu backend no cambia, solo enruta la tool call seleccionada a handle_function_call y conserva las mismas políticas de seguridad y auditoría.
Resolución de problemas habitual: si no se genera tool call, asegúrate de incluir el esquema en tools y, para demos, fuerza tool_choice en required; si aparecen errores de permisos, verifica que la app GITHUB está configurada, la cuenta está vinculada y el agente tiene permitido GITHUB; si falla por owner incorrecto, revisa que linked_account_owner_id coincide con el elegido al vincular; si hay problemas de instalación, usa el paquete aci con Python 3.10 o superior y actualiza pip.
Nota MCP para stacks modernos: si trabajas con el protocolo MCP, expón las herramientas de ACI mediante un servidor MCP para que cualquier cliente compatible, incluido uno que utilice Gaia, pueda descubrirlas y llamarlas. La capa de ejecución sigue siendo ACI, por lo que heredas el mismo control de permisos, auditoría y trazabilidad.
En Q2BSTUDIO, empresa de desarrollo de software, impulsamos soluciones de aplicaciones a medida y software a medida integrando agentes IA con flujos seguros de ejecución sobre plataformas como ACI y orquestando modelos en Gaia. Diseñamos arquitecturas productivas con principios de least privilege, gestión de secretos y observabilidad, y llevamos la ia para empresas desde el prototipo hasta la operación continua.
Nuestros servicios incluyen inteligencia artificial aplicada, ciberseguridad y pentesting, servicios cloud aws y azure, automatización de procesos, servicios inteligencia de negocio con power bi, además de consultoría de integración y MLOps. Si quieres acelerar tu roadmap de agentes IA con casos de uso reales, descubre cómo trabajamos en inteligencia artificial y cómo estandarizamos flujos y aprobaciones con automatización de procesos.
Resumen accionable: publica tus funciones operativas en ACI, descubre sus esquemas desde tu backend, provee esas herramientas al LLM de Gaia, aplica guardrails por organización o repositorio, ejecuta con linked_account_owner_id y registra cada llamada para auditoría. Cambia la función, conserva el patrón y tu agente podrá abrir issues, etiquetar PRs, comentar cambios o notificar en Slack de manera segura y trazable.