CUGA : comment créer des agents IA en un seul fichier sans tout coder

POURQUOI CUGA EST-IL DIFFÉRENT DES AUTRES OUTILS ?

La plupart des applications utilisant des agents IA commencent par une semaine de réglages avant même que l'agent ne fasse quelque chose d'utile. Il faut choisir un framework, configurer un client de modèle, écrire des adaptateurs d'outils, construire un système pour afficher l'état dans une interface, et pendant ce temps, on n'a même pas encore décidé à quoi servira l'agent. La partie intéressante arrive toujours en dernier.

CUGA inverse cette logique. Ce harness (cadre de travail léger) open source d'IBM s'occupe pour vous de la planification, de la boucle d'exécution, des appels d'outils et de la gestion de l'état. Il ne reste plus qu'à définir les outils que l'agent peut utiliser et ce que vous voulez qu'il fasse. Pour montrer concrètement ce que cela donne, IBM a créé cuga-apps : deux douzaines d'applications fonctionnelles, chacune contenue dans un seul fichier FastAPI, utilisant un seul CugaAgent. Ces exemples vont du recommandeur de films à un conseiller en architecture IBM Cloud. Ils sont là pour être lus et copiés, et vous pouvez explorer la galerie en ligne.

CE QUE CUGA ÉCONOMISE DE LA CORVÉE DE CODAGE

La question légitime à se poser sur tout outil dans ce domaine est : qu'est-ce qu'il m'évite d'écrire ? Pour CUGA, la réponse est claire : tout l'orchestration autour d'un modèle que vous devriez sinon reconstruire à chaque fois.

CUGA planifie avant d'agir, puis exécute en combinant des appels d'outils et la génération de code (CodeAct). Sur une tâche longue de vingt étapes, ce qui fait échouer la plupart des agents, c'est la perte de la trace des résultats intermédiaires et la recalculer (souvent de manière incorrecte) à l'étape suivante. CUGA conserve cet état et effectue une étape de réflexion qui peut détecter un mauvais appel et replanifier au lieu de continuer aveuglément. C'est ce mécanisme qui lui a permis de figurer en tête des benchmarks comme AppWorld et WebArena, plutôt que d'être un outil à ajuster manuellement.

Vous définissez aussi le compromis coût/latence directement depuis la configuration, sans toucher au code : modes de raisonnement Rapide, Équilibré et Précis, avec l'exécution de code dans le bac à sable de votre choix (local, Docker/Podman, ou E2B cloud). Le même agent, différents paramètres. Ce réglage compte plus qu'il n'y paraît. La plupart des harness supposent qu'un modèle de pointe se trouve en dessous et comptent sur lui pour récupérer lorsque le plan déraille. CUGA fait ce travail lui-même. La planification, l'étape de réflexion, le suivi des variables qui maintient une longue exécution sur la bonne voie : c'est le harness qui porte cette charge à la place du modèle. C'est ce qui permet à un modèle plus petit et open source de tenir la route là où il ne le ferait normalement pas. C'est pourquoi les applications hébergées tournent sur gpt-oss-120b plutôt que sur une API de modèle de pointe.

Aucune des pièces individuelles n'est unique à CUGA. Ce qui est différent, c'est qu'elles sont pré-assemblées, donc vous les configurez au lieu de les assembler vous-même. L'API que vous utilisez est minimaliste : construisez un CugaAgent avec une liste d'outils et une instruction système, puis attendez agent.invoke(.). Tout ce qui se trouve sous cette ligne fait partie du harness.

TOUT CE QUE VOUS DEVEZ ÉCRIRE : UN OUTIL ET UNE CONSIGNE

Concrètement, cela signifie des outils interchangeables (OpenAPI, MCP, et fonctions LangChain s'intègrent tous de la même manière), une planification à long terme avec gestion des variables et auto-correction (le mécanisme derrière la #1 sur AppWorld de juillet 2025 à février 2026 et WebArena de février 2025 à septembre 2025), des garde-fous déclaratifs, une délégation multi-agents via A2A, un RAG alimenté par Docling, et un changement de fournisseur d'IA avec une seule variable d'environnement (pip install cuga, puis OpenAI, watsonx, Ollama, etc.). Chaque élément est quelque chose que vous devriez sinon construire vous-même. Le premier mot du nom fait le travail : Configurable ; les parties difficiles sont gérées, donc votre travail se limite à la tâche.

CRÉER UN AGENT DE A À Z : L'EXEMPLE DU CONSEILLER IBM CLOUD

Voici l'application IBM Cloud Advisor : un agent qui recommande des services réels d'IBM Cloud pour une architecture. L'ensemble tient dans un seul fichier : un main.py contenant la fabrique de l'agent, les outils et la consigne système, plus une petite interface utilisateur.

def make_agent():
    from cuga import CugaAgent
    from llm import createllm

    return CugaAgent(
        model=create_llm(
            provider=os.getenv("LLM_PROVIDER"),
            model=os.getenv("LLM_MODEL"),
        ),
        tools=maketools(),
        specialinstructions=SYSTEM,
        cugafolder=str(DIR / ".cuga"),
    )

Quatre arguments seulement. Le modèle provient d'une petite fabrique (create_llm) qui parle à OpenAI, Anthropic, watsonx, LiteLLM ou Ollama selon une variable d'environnement. Rien dans le code de l'application ne sait quel modèle se cache derrière. Le cuga_folder est l'endroit où l'application conserve son état et ses politiques. Les deux arguments qui portent l'application sont tools et special_instructions.

Voici comment sont définis les outils :

def maketools():
    from langchain_core.tools import tool

    @tool
    def searchibmcatalog(query: str) -> str:
        """Search the IBM Cloud Global Catalog for real IBM Cloud services.
        Always call this before recommending services to verify they exist."""
        .  # hits the catalog API, returns JSON

    from mcpbridge import load_tools
    webtools = loadtools(["web"])

    return [searchibmcatalog, *web_tools]

On retrouve ici un motif qui se répète dans toutes les applications : une séparation entre les outils MCP et les outils intégrés. Les capacités génériques et sans état proviennent de serveurs MCP partagés ; load_tools(["web"]) importe la recherche web sans que vous ayez à héberger quoi que ce soit. Tout ce qui est spécifique à cette application est défini directement comme une fonction Python normale, comme searchibmcatalog, dont la docstring est ce que l'agent lit pour décider quand l'appeler. Vous écrivez l'outil qui vous appartient et empruntez le reste.

La consigne système de l'application conseillère cloud indique à l'agent de rechercher dans le catalogue avant de nommer un service, de recommander trois à sept services avec le rôle de chacun dans la conception, et de ne jamais inventer de noms de services. Cette dernière règle est cruciale : un agent recommandant des services IBM Cloud qui n'existent pas est pire que pas d'agent du tout, donc la consigne force chaque recommandation à passer par une recherche dans le catalogue d'abord. Les consignes écrites comme des étapes ordonnées avec des règles explicites du type "ne pas inventer" fonctionnent ; les consignes écrites comme des personas partent dans tous les sens.

Voilà l'application. Un outil, une procédure, quatre lignes de constructeur. Les routes FastAPI autour sont du code web ordinaire : le navigateur envoie une question à /ask, et le panneau en direct interroge un endpoint /session/{thread_id} pour obtenir l'état. Il n'y a pas de base de données ; l'état est un dictionnaire Python par thread_id que seul l'agent écrit, via ses outils. Dès que l'agent appelle un outil en cours d'exécution, le panneau se redessine. L'interface n'est pas une seconde copie de la logique ; c'est une vue sur l'état que l'agent a modifié.

LA CONVENTION QUI FAIT TOUTE LA DIFFÉRENCE : LES ENVELOPPES DE RÉPONSE

Un détail est facile à négliger et s'avère pourtant essentiel : chaque outil intégré retourne la même petite enveloppe. Une réponse réussie ressemble à {