La mayoría de las demos de IA se quedan en texto. En producción, tu agente debe hacer cosas de verdad, como marcar con estrella un repositorio, crear incidencias o etiquetar pull requests, siempre de forma segura, con trazabilidad y acceso de mínimos privilegios. En esta guía verás un montaje 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. En Q2BSTUDIO, especialistas en aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure y servicios inteligencia de negocio con power bi, usamos este patrón a diario para llevar la ia para empresas a producción con agentes IA robustos. Si buscas una agencia con foco en resultados, descubre cómo aceleramos tus casos de uso de IA en inteligencia artificial.
Qué vas a construir: formularás una solicitud al agente como Star tobySolutions barra stream2peer, el modelo devolverá una llamada a herramienta estructurada con nombre de función y argumentos JSON, tu servidor la ejecutará mediante el SDK de ACI usando la cuenta de GitHub enlazada del usuario y obtendrás un resultado limpio y auditable con registro.
Arquitectura resumida: Gaia procesa la intención y propone una tool call; tu backend valida, registra y delega en ACI la ejecución real contra GitHub u otras integraciones; ACI gestiona OAuth, permisos finos y auditoría para mantener el principio de mínimo privilegio.
Requisitos previos: Python 3.10 o superior, clave y dominio de Gaia compatibles con OpenAI, Gaia toolkit para gestionar tus nodos, y una cuenta en ACI.dev con un proyecto y agente por defecto, la app GITHUB configurada, tu cuenta de GitHub enlazada vía OAuth, el agente autorizado a usar GITHUB y la clave API del agente para el SDK.
Configuración única en ACI: crea o entra en tu proyecto y agente en la plataforma, configura la app GITHUB en el App Store de ACI, enlaza tu cuenta de GitHub y elige un linked account owner id por ejemplo tobySolutions que usarás en el código, permite que el agente use GITHUB en Allowed Apps y copia la clave API del agente para tu backend.
Entorno de variables: crea un archivo .env en la raíz con estas claves. Para Gaia define GAIA_BASE_URL igual a la url de tu dominio Gaia con sufijo v1 y GAIA_API_KEY. Para ACI define ACI_API_KEY con la clave del agente y ACI_OWNER_ID con el owner id usado al enlazar la cuenta de GitHub.
Instalación de dependencias: actualiza pip y añade openai, python guion dotenv y aci. Alternativamente, usa uv pip para instalar los mismos paquetes. En algunos entornos el paquete se publica como aci y no aci guion sdk. Recuerda usar Python 3.10 o superior.
Ejemplo mínimo funcional. Objetivo: indicarle al modelo que existe la función de GITHUB para dar estrella a un repositorio, dejar que proponga la llamada a herramienta y ejecutarla con ACI. Paso 1 descubre el esquema de la función desde ACI con el identificador GITHUB__STAR_REPOSITORY. Paso 2 invoca chat completions del cliente OpenAI apuntando al endpoint de Gaia con un modelo con capacidad de tools como Llama guion 3 guion Groq guion 8B guion Tool, pasando en tools el esquema devuelto por ACI y, para una demo, forzando tool_choice igual a required. Paso 3 lee la tool_call devuelta por el modelo, parsea los arguments JSON, aplica guardrails por ejemplo permitir solo owner tobySolutions y ejecuta aci punto handle_function_call con el nombre de función, los argumentos y linked_account_owner_id igual a tu ACI_OWNER_ID. Imprime el resultado para auditar.
Ejecución: lanza python main punto py. Flujo esperado: el LLM devuelve una tool call con name GITHUB__STAR_REPOSITORY y arguments con owner tobySolutions y repo stream2peer, tu servidor llama a aci punto handle_function_call con el owner id enlazado, GitHub marca con estrella el repositorio y recibes un payload de éxito registrable.
Por qué funciona este patrón. Descubrir obtienes de ACI el esquema exacto de la función y lo pasas al modelo. Restringir el modelo solo puede llamar a lo que tú expones. Ejecutar las credenciales viven en tu backend y el modelo nunca ve tokens. Auditar puedes registrar cada invocación y aplicar allowlists de organización y repositorio, así como límites de tasa y políticas.
Más allá de dar estrella. Descubre y expón más funciones como GITHUB__CREATE_ISSUE o GITHUB__COMMENT_ON_PR, añade sus definiciones a la lista de tools y usa tool_choice en auto. Tu servidor mantiene la misma ruta de ejecución pasando la tool call seleccionada a aci punto handle_function_call, con los mismos controles y auditoría.
Solución de problemas. Si el modelo no genera tool call, asegúrate de incluir el esquema en tools y, en demos, mantén tool_choice en required. Si ves errores de permisos, confirma que la app GITHUB está configurada, la cuenta está enlazada y el agente tiene GITHUB en Allowed Apps. Si el owner no coincide, revisa que linked_account_owner_id sea exactamente el elegido al enlazar la cuenta por ejemplo tobySolutions. Si hay problemas al instalar paquetes, usa aci, actualiza pip y verifica la versión de Python.
Nota MCP. Si construyes una pila basada en MCP, expón las herramientas de ACI a través de un servidor MCP para que cualquier cliente compatible incluso los que trabajan contra Gaia pueda descubrir y llamarlas. La capa de ejecución permanece en ACI, manteniendo seguridad, auditoría y mínimos privilegios.
Cierre. Ya dispones de un patrón claro para convertir la intención de un LLM en acciones reales usando Gaia para la inferencia y ACI.dev para la ejecución. Cambia la función y conserva la forma, y tu agente podrá abrir issues, etiquetar PRs o publicar en Slack de forma segura y auditable. En Q2BSTUDIO te ayudamos a llevar agentes IA a producción integrados con tus procesos, desde automatización de flujos hasta cuadros de mando con power bi, y a orquestarlos en nubes híbridas con servicios cloud aws y azure. Si quieres impulsar tu roadmap de automatización de procesos con IA, descubre cómo lo abordamos en automatización de procesos.