LLM + Java, responsabilités distinctes

La clé de l'intégration d'un agent à un système existant : laisser suffisamment de liberté au LLM mais lui mettre des contraintes avec des outils bien pensés.

Vraiment 3 fichiers

Pas de Maven. On utilise jBang pour gérer les dépendances et exécuter notre fichier .java.

Ce que fait l'agent

Pattern ReAct

LangChain4j gère la boucle outil ↔ LLM automatiquement. Le modèle itère jusqu'à trouver le bon prix.
2 outils : previewItem pour simuler un item sans le valider, finalizeItem pour le retourner à l'utilisateur.

ItemMerchantAgent.java (CLI)

Interface en ligne de commande avec JLine. Lit la requête et le budget, puis appelle l'agent.

private int run() throws IOException {

    Terminal terminal = TerminalBuilder.builder()
        .provider("FFM").system(true).build();
    Prompter prompter = PrompterFactory.create(terminal);

    // Prompts typés : texte libre + entier
    PromptBuilder builder = prompter.newBuilder();
    builder.createInputPrompt()
           .message("Your request").name("request").addPrompt()
           .createNumberPrompt()
           .message("Your budget in gold pieces")
           .allowDecimals(false).name("budget").addPrompt();

    /* ellipse : utiliser le prompter Jline pour récupérer request et budget */

    // Appel de l'agent avec le budget dans le prompt
    // et comme paramètre d'invocation
    String prompt = request + "
Budget : " + budget;
    Result<String> resp = agent.createItem(prompt,
        new InvocationParameters(Map.of("budget", Integer.valueOf(budget))));

    /* ellipse : affichage du résultat */
}

Agent.java (le service IA)

LangChain4j construit l'agent en quelques lignes.

// Langchain4j va construire une implémentation de cette interface
interface InnerAgent {
    Result createItem(
            @UserMessage String prompt, InvocationParameters parameters);
}

// constructor
public Agent(
        String modelUrl, String modelName, String apiKey) {
    this.model = OpenAiChatModel.builder()
            .baseUrl(modelUrl)     // http://localhost:8080/v1
            .modelName(modelName)  // "qwen"
            .apiKey(apiKey)      // "dummy"
            .build();

    this.agent = AiServices.builder(InnerAgent.class)
            .chatModel(model)
            .systemMessage(systemPrompt)     // rôle + workflow
            .tools(new ItemSystemTools())    // @Tool auto-découverts
            .maxSequentialToolsInvocations(10)   // cap la boucle
            .afterToolExecution(this::logTools)  // logging
            .chatMemory(
                    MessageWindowChatMemory.builder()
                            .maxMessages(30).build())
            .build();
}

ItemSystemTools.java (le moteur d'items)

Implémente un système d'objets (armes et armures) simple que l'on pourrait retrouver dans un jeu vidéo. La formule de prix et les seuils de rareté sont déterministes. Le LLM ne peut donc inventer que des objets qui sont compatibles avec le moteur de jeu. Et les prix sont toujours cohérents.

// types d'objets et stats de base
public enum Prototype {
    //          weapon   atk  spd  def  basePrice
    DAGGER(true, 6, 10, 0, 60),
    SWORD(true, 12, 6, 2, 120),
    AXE(true, 16, 2, 0, 140),
    CHESTPLATE(false, 0, -2, 14, 160),
    // ...12 prototypes au total
}

// Rareté = ratio bonus-gold / basePrice
// UNCOMMON ≥ 20 %  ·  RARE ≥ 60 %  ·  EPIC ≥ 120 %
record RarityThresholds(double uncommon, double rare, double epic) {
    static RarityThresholds defaults() {
        return new RarityThresholds(0.20, 0.60, 1.20);
    }
}

private ComputedItem computeItem(
        Prototype proto, int atkBonus, int spdBonus, int defBonus) {
    //calcule l'item final, permet d'appliquer les contraintes du moteurs de jeu
    //exemple : pas d'attaque sur une armure
}

ItemSystemTools.java suite (les outils de l'agent)

Le pont LLM ↔ Java. Ces méthodes peuvent être appelées par le modèle, le code est exécuté et le retour est transmis au LLM. LangChain4j lit la signature des méthodes annotées @Tool pour générer les schémas JSON qui seront utilisés dans l'API du LLM.

@Tool("""
    Preview an item without finalizing it. Returns price,     rarity, and stat breakdown. Call repeatedly with adjusted     bonuses until the buy price fits the user's budget""")
public String previewItem(
        Prototype prototype,
        @P("Greater than 0") int atkBonus,
        @P("Greater than 0") int spdBonus,
        @P("Greater than 0") int defBonus,
        InvocationParameters parameters) {

  int budget = parameters.get("budget");   // budget depuis les métadonnées
  ComputedItem item = computeItem(prototype, atkBonus, spdBonus, defBonus);
  Rarity rarity = deriveRarity(item.totalDelta(), prototype.basePrice);
  int price = prototype.basePrice + item.totalDelta();

  // Retourne une prévisualisation au format texte pour le LLM.
  // On utilise la variable budget pour indiquer dans la réponse
  // au LLM si le budget est respecté.
  return formatPreview(prototype, rarity, price, budget);
}

Le system prompt : donner un rôle au LLM

La personnalité et le workflow sont dictés dans un text block Java assemblé à l'initialisation.

String systemPrompt = """
    You are a Dungeon Master playing the role of the
    Weapon and Armor Merchant. The user will ask for
    a weapon or armor to buy with a specific budget.
    You must invent an item for them.

    Workflow to follow:
      1. Call previewItem() with a Prototype enum value
         and chosen bonuses : get price + rarity feedback
         WITHOUT committing.
      2. Adjust bonuses and call previewItem() again until
         the result fits the budget / power target.
      3. Call finalizeItem() with the same configuration.

    Try to get as close as possible to the budget to
    propose the most powerful item possible.
    You must call finalizeItem() with your proposed item.

    Base item prototypes to choose from :
    """ + ItemSystemTools.Prototype.summarize();
    // → "DAGGER : ATK 6, SPD 10 SWORD : ATK 12, SPD 6, DEF 2"

LLM local : exemple avec Llama.cpp

Le service LangChain4j utilisé est compatible avec l'API OpenAI. La plupart des moteurs d'inférence locaux (Llama.cpp, LM Studio, Ollama) implémente cette API.

# llm.properties
baseUrl=http://localhost:8080/v1
modelName=qwen
apiKey=dummy

Illustrer les items : génération d'image

Une fois l'item finalisé, on peut générer son illustration. La cohérence visuelle entre les items repose sur un prompt de base fixe qui définit le style graphique, on y concatène simplement le nom et la description de l'item généré.

Exemple de prompt

Cuirasse of the Grey Lands, Chestplate. Made of steel grayed by northern storms, it absorbs blows without flinching.
Line art sprite for a medieval fantasy RPG video game, clean and precise black ink outlines with no anti-aliasing, consistent stroke weight of 2px for outer contours and 1px for inner details, rendered on a transparent background, top-down 3/4 oblique perspective slightly facing the viewer, single directional light source from the upper-left at 45° producing hard cel-shaded shadows with flat color fills using a limited palette of rich jewel tones, deep emerald greens, royal purples, warm amber, aged parchment beige, avoiding pure white in favor of warm cream, with 2 shading levels per color zone (base tone and one shadow pass 30% darker with a slightly cooler hue), medieval fantasy aesthetic with hand-forged iron, worn leather and arcane ornamental details, style consistent with classic JRPG illustrated sprites, isolated subject centered in frame with no background.

Ce qu'on retient