Comment piloter mini-me depuis un programme

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# Comment piloter mini-me depuis un programme

Ce guide montre comment utiliser un agent mini-me depuis votre propre code Go, Kotlin ou Node.js : lui poser des questions, recevoir ses réponses en stream, annuler un tour, et décider quels outils il peut lancer. Il suppose que vous avez déjà un fichier d'agent qui fonctionne (voir [Créer un agent avec `mm init`](create-an-agent.md)) et le binaire `mm`.

Votre programme lance `mm -acp` comme processus enfant et lui parle par ACP, le protocole qu'utilisent les éditeurs comme Zed. Rien ne change dans mm : tout fichier d'agent fonctionne, avec ses outils, ses hooks, ses serveurs MCP et ses autres agents.

## Étapes

1. Rendez `mm` accessible : dans le PATH, ou désigné par `MM_BIN=/chemin/vers/mm`.
2. Choisissez le client de votre langage et ajoutez-le à votre projet :
   - **Go** : le module `minime` de [`demo.acp.sdk/go/`](../../../demo.acp.sdk/go/README.fr.md). Tant qu'il n'est pas publié, faites-le pointer depuis votre `go.mod` :
     ```bash
     go mod edit -require=minime@v0.0.0 -replace=minime=../chemin/vers/demo.acp.sdk/go
     go mod tidy
     ```
   - **Kotlin** (JDK ≥ 21) : le build Gradle de [`demo.acp.sdk/kotlin/`](../../../demo.acp.sdk/kotlin/README.fr.md). Tant qu'il n'est pas publié, incluez-le depuis votre `settings.gradle.kts` avec `includeBuild("../chemin/vers/demo.acp.sdk/kotlin")`, puis déclarez la dépendance `minime:minime:0.1.0` (plus un backend SLF4J comme `org.slf4j:slf4j-nop`, pour les logs du SDK).
   - **Node.js** (≥ 20), deux clients avec la même API :
     - [`demo.acp.sdk/nodejs/`](../../../demo.acp.sdk/nodejs/README.fr.md) : copiez `lib/minime.js`, qui n'a aucune dépendance ;
     - [`demo.acp.sdk/nodejs-sdk/`](../../../demo.acp.sdk/nodejs-sdk/README.fr.md) : construit sur le SDK ACP officiel `@agentclientprotocol/sdk` ; `npm install ../chemin/vers/demo.acp.sdk/nodejs-sdk`, puis `import { Agent } from "minime-sdk"`.
3. Démarrez un agent sur votre fichier d'agent, posez une question, puis fermez-le :
   ```go
   agent, err := minime.Start(ctx, minime.Options{Config: "agent.yaml"})
   if err != nil {
   	log.Fatal(err)
   }
   defer agent.Close()

   res, err := agent.Complete(ctx, "What is in this folder?")
   ```
   ```kotlin
   Agent.start(Options(config = "agent.yaml")).use { agent ->
       val result = agent.complete("What is in this folder?")
   }
   ```
   ```js
   import { Agent } from "./lib/minime.js"; // ou "minime-sdk"

   const agent = await Agent.start({ config: "agent.yaml" });
   const { text } = await agent.complete("What is in this folder?");
   await agent.close();
   ```
4. Pour afficher la réponse au fil de l'eau, utilisez plutôt la forme stream (`agent.Stream(ctx, prompt)` en Go, le flow `agent.stream(prompt)` en Kotlin, `agent.stream(prompt)` en Node.js) et affichez les événements de texte.
5. Si votre fichier d'agent contient `yolo: false`, donnez un callback de permission, sinon chaque appel d'outil est refusé :
   ```go
   minime.Options{
   	Config: "agent.yaml",
   	OnPermission: func(_ context.Context, call minime.ToolCall) minime.Decision {
   		if call.Kind == "read" {
   			return minime.Allow
   		}
   		return minime.Reject
   	},
   }
   ```
   ```kotlin
   Options(config = "agent.yaml", onPermission = { call -> if (call.kind == "read") Decision.Allow else Decision.Reject })
   ```
   ```js
   Agent.start({ config: "agent.yaml", onPermission: (call) => call.toolKind === "read" });
   ```

## Variantes

- **Pour arrêter un tour trop long**, annulez-le : en Go, annulez le `ctx` que vous avez passé (par exemple avec `context.WithTimeout`) ; en Kotlin, appelez `agent.cancel()` depuis une autre coroutine ; en Node.js, passez `{ signal }` d'un `AbortController`. Le tour se termine avec `stopReason: "cancelled"` et le texte déjà reçu. mm retire la question inachevée de la conversation.
- **Pour repartir d'une conversation vierge** sans relancer mm, appelez `Reset(ctx)` (Go) ou `reset()` (Kotlin, Node.js).
- **Pour travailler sur plusieurs choses en parallèle**, démarrez plusieurs agents : chacun est son propre processus mm et ne traite qu'un tour à la fois.
- **Pour exécuter les outils dans un autre répertoire** que celui de votre programme, renseignez `Cwd` (Go) ou `cwd` (Kotlin, Node.js).
- **Pour voir ce que mm écrit dans ses logs** (bannière, avertissements, lignes `[acp]`), renseignez `OnStderr` (Go) ou `onStderr` (Kotlin, Node.js).

## Voir aussi

- Toutes les options, événements et erreurs de chaque client : [Go](../../../demo.acp.sdk/go/README.fr.md), [Kotlin](../../../demo.acp.sdk/kotlin/README.fr.md), [Node.js](../../../demo.acp.sdk/nodejs/README.fr.md), [Node.js avec le SDK ACP](../../../demo.acp.sdk/nodejs-sdk/README.fr.md).
- Les messages ACP derrière les clients : [`demo.acp.sdk/README.fr.md`](../../../demo.acp.sdk/README.fr.md).
- Confirmer les appels d'outils dans mm lui-même : [Confirmer les appels d'outils](confirm-tool-calls.md).