turbo-editors/turbo-js · talk-to-an-agent.md

⑂ v1.0.1

talk-to-an-agent.md · 177 lines · 11.9 KBmarkdown    Blame HistoryRaw
   1# Dialoguer avec un agent de code depuis l'éditeur
3Ce guide montre comment pointer Turbo JS vers un agent qui parle l'[Agent Client Protocol](https://agentclientprotocol.com), ouvrir une fenêtre dessus, et tenir une conversation sur le code en cours d'édition. Il suppose que Turbo JS est déjà lancé dans un projet.
5Turbo JS est un **client** ACP. Il lance l'agent comme processus fils et lui parle en JSON-RPC sur son entrée et sa sortie standard — le même montage que Zed, donc un agent qui fonctionne là-bas fonctionne ici.
7## Déclarer un agent à l'éditeur
9Les agents sont listés dans `acp.toml`. Choisissez **Agent ▸ Create agents file** et l'éditeur écrit un fichier de départ dans `.turbo-js/acp.toml`, puis l'ouvre.
11Un agent, c'est un bloc `[[agent]]` :
14
15name    = "Bob (llama.cpp)"
16command = "docker"
17args    = ["agent", "serve", "acp", ".turbo-js/agent.yaml"]
18env     = { TELEMETRY_ENABLED = "false" }
21`name` est ce qu'affiche le menu Agent et le nom de la fenêtre. `command` et `args` disent comment démarrer l'agent. C'est tout — le fichier est relu à chaque ouverture de fenêtre, donc on ne redémarre jamais l'éditeur pour essayer une modification.
23Listez-en autant que vous voulez. Chacun devient une ligne du menu, et chaque fenêtre ouverte depuis cette ligne est un processus distinct avec sa propre conversation.
25## Placer la configuration de l'agent à côté
27La plupart des agents ont leur propre fichier de configuration, et `.turbo-js/` est un endroit raisonnable pour le garder afin qu'il voyage avec le projet. Pour `docker agent`, l'enregistrer sous `.turbo-js/agent.yaml` correspond aux `args` ci-dessus :
30
31  llamacpp:
32    api_type: openai_chatcompletions
33    base_url: http://localhost:8080/v1
36
37    provider: llamacpp
38    model: JetBrains/Mellum2-12B-A2.5B-Instruct-GGUF-Q4_K_M:Q4_K_M
39    temperature: 0.7
40    provider_opts:
41      context_size: 262144
45    model: mellum2
46    description: A helpful AI assistant running on a local llama.cpp server
47    instruction: |
48      You name is Bob 🤓, you are a knowledgeable code assistant.
49      Be helpful, accurate, and concise in your responses.
50      You have access to the local filesystem and shell: use these tools
51    toolsets:
52      - type: filesystem
53      - type: shell
56## Ouvrir une fenêtre dessus
58Appuyez sur `Alt-A`, ou choisissez **Agent** dans la barre de menus, puis l'agent par son nom.
60Une fenêtre s'ouvre, coupée en deux : la conversation en haut, une zone de saisie en bas. L'agent est démarré à l'ouverture de la fenêtre et arrêté à sa fermeture.
63┌ Bob (llama.cpp) ───────────────────────────────[■]┐
65│   Que fait buildMenus ?                           │
67│ ‣ Shell  ls -1 src/                      ✓ fini   │
71│   Elle assemble la barre de menus. Sa forme :     │
73│   ```javascript                                   │
74│   export function buildMenus(app) {               │
75│     return new MenuBar(...app.allMenus());        │
78├───────────────────────────────────────────────────┤
80└───────────────────────────────────────────────────┘
83Le code que l'agent envoie dans un bloc délimité est coloré par les mêmes analyseurs que l'éditeur utilise pour les fichiers : une réponse en JavaScript est colorée comme du JavaScript, une réponse en shell comme du shell. Un bloc annonçant un langage que l'éditeur ne colore pas est laissé brut plutôt que deviné.
85## Tenir la conversation
87| Touche | Effet |
88| --- | --- |
89| `Entrée` | Envoyer ce qui est saisi |
90| `Alt-Entrée` | Passer à la ligne au lieu d'envoyer |
91| `Tab` | Passer de la conversation à la zone de saisie, et retour |
92| `PgUp` `PgDn` | Faire défiler la conversation d'un écran |
93| `Échap` | Arrêter le tour en cours |
94| `Ctrl-W` | Fermer la fenêtre, et arrêter l'agent avec elle |
96Pendant que l'agent répond, sa réponse s'affiche au fil de l'écriture plutôt que d'un bloc, et la règle entre les deux zones fait tourner un indicateur à côté du mot *thinking*. `Échap` l'interrompt — l'agent reçoit l'ordre de s'arrêter, et ce qu'il avait déjà dit reste dans la fenêtre.
98## Utiliser les commandes propres à l'agent
100Certains agents répondent à des commandes — `/compact`, `/web`, `/plan` — et disent à l'éditeur lesquelles. Tapez `/` comme premier caractère de la zone de saisie et la liste s'ouvre par-dessus la conversation : chaque commande, ce qu'elle fait, et entre chevrons ce qu'elle attend après son nom.
102Continuez à taper pour la réduire, `↑` `↓` pour vous déplacer, puis `Tab` pour compléter. Une commande qui attend quelque chose est complétée avec une espace après elle, prête à recevoir la suite ; appuyez sur `Entrée` quand la ligne dit ce que vous voulez. Si rien n'apparaît quand vous tapez `/`, l'agent n'a annoncé aucune commande — **Agent ▸ Agent status** le dit — et `/` n'est qu'un caractère.
104## Désigner un fichier à l'agent
106Tapez `@` n'importe où dans la zone de saisie et les fichiers du projet apparaissent. Tapez quelques lettres du nom du fichier pour réduire la liste, `Tab` pour prendre celui en surbrillance :
109> explique ce que fait @src/menus.js
112Quand vous appuyez sur `Entrée`, l'agent reçoit le **fichier**, et pas seulement son nom : son texte quand l'agent accepte le contexte incorporé, un lien vers lui sinon. Si le fichier est ouvert dans l'éditeur avec des modifications non enregistrées, c'est votre version non enregistrée qui part. La ligne reste dans la conversation telle que vous l'avez tapée.
114Plusieurs fichiers dans une invite, c'est plusieurs `@`. Un mot qui commence par `@` mais n'est pas un fichier — une adresse électronique — est laissé en texte.
116## Récupérer un morceau de la conversation
118Appuyez sur `Tab` pour placer le curseur dans la conversation. La règle change et annonce ce que font désormais les touches.
120| Touche | Effet |
121| --- | --- |
122| `↑` `↓` `PgUp` `PgDn` | Déplacer le curseur dans ce qui a été dit |
123| `Shift-↑` `Shift-↓` | Sélectionner des lignes entières |
124| Glisser à la souris | Pareil, à la main |
125| `Ctrl-C` | Copier |
126| `Échap` | Abandonner la sélection |
127| `Tab` | Revenir à la zone de saisie |
129**Sans rien de sélectionné, `Ctrl-C` copie le bloc sur lequel est le curseur** — un bloc de code délimité, un paragraphe, la sortie d'un outil — sans le libellé de l'interlocuteur au-dessus ni la phrase qui suit. C'est presque toujours ce que vous vouliez, et cela évite de le sélectionner à la main.
131Ce qui est copié va dans **deux** presse-papiers : celui de l'éditeur, pour que `Shift-Ins` le colle dans un fichier ouvert ici, et celui du système, pour que `Ctrl-V` le colle n'importe où ailleurs. L'indentation d'affichage de la conversation est retirée, donc le code collé arrive collé à la marge.
133La moitié « système » passe par votre terminal (une séquence d'échappement nommée OSC 52). La plupart des terminaux la gèrent ; quelques-uns la refusent par sécurité, et certains demandent de l'activer. Si `Ctrl-V` ailleurs ne donne rien, c'est là qu'il faut regarder — le presse-papiers de l'éditeur contient le texte dans tous les cas.
135## Répondre quand l'agent demande la permission
137Un agent doté d'un outil shell ou d'un outil de fichiers demande avant de s'en servir. Une boîte de dialogue nomme l'outil et la commande exacte, et propose les choix que l'agent lui-même a proposés — d'ordinaire *Autoriser*, *Autoriser et retenir mon choix*, et *Passer*.
140┌────────── Bob (llama.cpp) veut lancer ──────────┐
145│    [ Autoriser ] [ Toujours ]  [ Passer ]       │
146└─────────────────────────────────────────────────┘
149*Toujours* est retenu par l'agent, pas par l'éditeur : ce que cela couvre et combien de temps cela dure sont l'affaire de l'agent. Échap équivaut à *Passer*.
151Rien ne s'exécute avant votre réponse. Un agent en attente d'une boîte de permission est simplement bloqué, et c'est bien le but.
153## Laisser l'agent voir ce qui n'est pas encore enregistré
155L'éditeur offre à l'agent son propre système de fichiers : quand l'agent lit un fichier que vous avez ouvert avec des modifications non enregistrées, il reçoit **le texte du tampon**, pas le texte plus ancien du disque. C'est généralement ce qu'on veut — vous posez une question sur la modification que vous venez de faire.
157Quand l'agent écrit un fichier, la modification arrive dans le tampon et la fenêtre est marquée modifiée : vous pouvez la lire, l'annuler avec `Ctrl-Z`, ou l'enregistrer avec `F2`. Un fichier que vous n'avez pas ouvert est lu et écrit directement sur le disque.
159## Faire tourner plusieurs agents à la fois
161Chaque fenêtre est son propre processus et sa propre conversation. Ouvrir deux fois le même agent donne deux sessions indépendantes, et ouvrir deux agents différents permet de mettre côte à côte un modèle local rapide et un modèle lent et soigneux — **Window ▸ Tile** les dispose.
163Quitter l'éditeur arrête tous les agents.
165## Variantes
167- **Vous voulez que l'agent tourne ailleurs qu'à la racine du projet.** Ajoutez `cwd = "backend"` à son bloc. Le chemin est relatif au projet, et c'est à la fois l'endroit où le processus démarre et le dossier de travail annoncé à l'agent.
168- **L'agent a besoin d'un identifiant.** Mettez-le dans `env`, ou comptez sur sa présence dans l'environnement depuis lequel vous lancez l'éditeur — l'agent en hérite.
169- **Les commandes de l'agent n'apparaissent pas quand vous tapez `/`.** Ouvrez **Agent ▸ Agent status** avec la fenêtre devant. S'il ne liste aucune commande, l'agent n'en a annoncé aucune — ou les a annoncées dans une forme que cet éditeur n'a pas su lire, auquel cas la boîte nomme la mise à jour et l'erreur de décodage. Pour voir exactement ce qui est passé sur le fil, lancez l'éditeur avec `TURBO_ACP_TRACE=/tmp/acp.log` et lisez le fichier : `->` est ce que l'éditeur a envoyé, `<-` ce que l'agent a répondu.
170- **L'agent ne démarre pas.** **Agent ▸ Agent status** liste ce qui a été lu dans `acp.toml`, la ligne de commande obtenue pour chaque agent, et l'erreur de tout ce qui n'a pas démarré. Ce que l'agent écrit sur sa sortie d'erreur y figure aussi, et c'est là qu'un point d'accès de modèle mal configuré se signale.
171- **Vous gardez le même agent dans tous les projets.** Mettez le bloc `[[agent]]` dans `~/.config/turbo-js/acp.toml`. Le fichier du projet est lu ensuite, et un agent du même `name` y remplace le vôtre.
173## Voir aussi
175- Chaque clé du fichier, et la part exacte du protocole implémentée : [référence Agents et ACP](../reference/acp.md)
176- Pourquoi un agent est une fenêtre et non un panneau, et pourquoi les permissions sont modales : [Fenêtres agent](../explanation/agent-windows.md)
177- Le protocole lui-même : [agentclientprotocol.com](https://agentclientprotocol.com)

📦 Turbo JS 91999d1 k33g 12h ago	1	# Dialoguer avec un agent de code depuis l'éditeur
	2
	3	Ce guide montre comment pointer Turbo JS vers un agent qui parle l'[Agent Client Protocol](https://agentclientprotocol.com), ouvrir une fenêtre dessus, et tenir une conversation sur le code en cours d'édition. Il suppose que Turbo JS est déjà lancé dans un projet.
	4
	5	Turbo JS est un client ACP. Il lance l'agent comme processus fils et lui parle en JSON-RPC sur son entrée et sa sortie standard — le même montage que Zed, donc un agent qui fonctionne là-bas fonctionne ici.
	6
	7	## Déclarer un agent à l'éditeur
	8
	9	Les agents sont listés dans `acp.toml`. Choisissez Agent ▸ Create agents file et l'éditeur écrit un fichier de départ dans `.turbo-js/acp.toml`, puis l'ouvre.
	10
	11	Un agent, c'est un bloc `[[agent]]` :
	12
	13	```toml
	14	[[agent]]
	15	name = "Bob (llama.cpp)"
	16	command = "docker"
	17	args = ["agent", "serve", "acp", ".turbo-js/agent.yaml"]
	18	env = { TELEMETRY_ENABLED = "false" }
	19	```
	20
	21	`name` est ce qu'affiche le menu Agent et le nom de la fenêtre. `command` et `args` disent comment démarrer l'agent. C'est tout — le fichier est relu à chaque ouverture de fenêtre, donc on ne redémarre jamais l'éditeur pour essayer une modification.
	22
	23	Listez-en autant que vous voulez. Chacun devient une ligne du menu, et chaque fenêtre ouverte depuis cette ligne est un processus distinct avec sa propre conversation.
	24
	25	## Placer la configuration de l'agent à côté
	26
	27	La plupart des agents ont leur propre fichier de configuration, et `.turbo-js/` est un endroit raisonnable pour le garder afin qu'il voyage avec le projet. Pour `docker agent`, l'enregistrer sous `.turbo-js/agent.yaml` correspond aux `args` ci-dessus :
	28
	29	```yaml
	30	providers:
	31	llamacpp:
	32	api_type: openai_chatcompletions
	33	base_url: http://localhost:8080/v1
	34
	35	models:
	36	mellum2:
	37	provider: llamacpp
	38	model: JetBrains/Mellum2-12B-A2.5B-Instruct-GGUF-Q4_K_M:Q4_K_M
	39	temperature: 0.7
	40	provider_opts:
	41	context_size: 262144
	42
	43	agents:
	44	root:
	45	model: mellum2
	46	description: A helpful AI assistant running on a local llama.cpp server
	47	instruction: \|
	48	You name is Bob 🤓, you are a knowledgeable code assistant.
	49	Be helpful, accurate, and concise in your responses.
	50	You have access to the local filesystem and shell: use these tools
	51	toolsets:
	52	- type: filesystem
	53	- type: shell
	54	```
	55
	56	## Ouvrir une fenêtre dessus
	57
	58	Appuyez sur `Alt-A`, ou choisissez Agent dans la barre de menus, puis l'agent par son nom.
	59
	60	Une fenêtre s'ouvre, coupée en deux : la conversation en haut, une zone de saisie en bas. L'agent est démarré à l'ouverture de la fenêtre et arrêté à sa fermeture.
	61
	62	```
	63	┌ Bob (llama.cpp) ───────────────────────────────[■]┐
	64	│ ‣ Vous │
65	│ Que fait buildMenus ? │
66	│ │
67	│ ‣ Shell ls -1 src/ ✓ fini │
68	│ menus.js │
69	│ │
70	│ ‣ Bob │
71	│ Elle assemble la barre de menus. Sa forme : │
72	│ │
73	│ ```javascript │
74	│ export function buildMenus(app) { │
75	│ return new MenuBar(...app.allMenus()); │
76	│ } │
77	│ ``` │
78	├───────────────────────────────────────────────────┤
79	│ > _ │
80	└───────────────────────────────────────────────────┘
81	```
82
83	Le code que l'agent envoie dans un bloc délimité est coloré par les mêmes analyseurs que l'éditeur utilise pour les fichiers : une réponse en JavaScript est colorée comme du JavaScript, une réponse en shell comme du shell. Un bloc annonçant un langage que l'éditeur ne colore pas est laissé brut plutôt que deviné.
84
85	## Tenir la conversation
86
87	\| Touche \| Effet \|
88	\| --- \| --- \|
89	\| `Entrée` \| Envoyer ce qui est saisi \|
90	\| `Alt-Entrée` \| Passer à la ligne au lieu d'envoyer \|
91	\| `Tab` \| Passer de la conversation à la zone de saisie, et retour \|
92	\| `PgUp` `PgDn` \| Faire défiler la conversation d'un écran \|
93	\| `Échap` \| Arrêter le tour en cours \|
94	\| `Ctrl-W` \| Fermer la fenêtre, et arrêter l'agent avec elle \|
95
96	Pendant que l'agent répond, sa réponse s'affiche au fil de l'écriture plutôt que d'un bloc, et la règle entre les deux zones fait tourner un indicateur à côté du mot thinking. `Échap` l'interrompt — l'agent reçoit l'ordre de s'arrêter, et ce qu'il avait déjà dit reste dans la fenêtre.
97
98	## Utiliser les commandes propres à l'agent
99
100	Certains agents répondent à des commandes — `/compact`, `/web`, `/plan` — et disent à l'éditeur lesquelles. Tapez `/` comme premier caractère de la zone de saisie et la liste s'ouvre par-dessus la conversation : chaque commande, ce qu'elle fait, et entre chevrons ce qu'elle attend après son nom.
101
102	Continuez à taper pour la réduire, `↑` `↓` pour vous déplacer, puis `Tab` pour compléter. Une commande qui attend quelque chose est complétée avec une espace après elle, prête à recevoir la suite ; appuyez sur `Entrée` quand la ligne dit ce que vous voulez. Si rien n'apparaît quand vous tapez `/`, l'agent n'a annoncé aucune commande — Agent ▸ Agent status le dit — et `/` n'est qu'un caractère.
103
104	## Désigner un fichier à l'agent
105
106	Tapez `@` n'importe où dans la zone de saisie et les fichiers du projet apparaissent. Tapez quelques lettres du nom du fichier pour réduire la liste, `Tab` pour prendre celui en surbrillance :
107
108	```
109	> explique ce que fait @src/menus.js
110	```
111
112	Quand vous appuyez sur `Entrée`, l'agent reçoit le fichier, et pas seulement son nom : son texte quand l'agent accepte le contexte incorporé, un lien vers lui sinon. Si le fichier est ouvert dans l'éditeur avec des modifications non enregistrées, c'est votre version non enregistrée qui part. La ligne reste dans la conversation telle que vous l'avez tapée.
113
114	Plusieurs fichiers dans une invite, c'est plusieurs `@`. Un mot qui commence par `@` mais n'est pas un fichier — une adresse électronique — est laissé en texte.
115
116	## Récupérer un morceau de la conversation
117
118	Appuyez sur `Tab` pour placer le curseur dans la conversation. La règle change et annonce ce que font désormais les touches.
119
120	\| Touche \| Effet \|
121	\| --- \| --- \|
122	\| `↑` `↓` `PgUp` `PgDn` \| Déplacer le curseur dans ce qui a été dit \|
123	\| `Shift-↑` `Shift-↓` \| Sélectionner des lignes entières \|
124	\| Glisser à la souris \| Pareil, à la main \|
125	\| `Ctrl-C` \| Copier \|
126	\| `Échap` \| Abandonner la sélection \|
127	\| `Tab` \| Revenir à la zone de saisie \|
128
129	Sans rien de sélectionné, `Ctrl-C` copie le bloc sur lequel est le curseur — un bloc de code délimité, un paragraphe, la sortie d'un outil — sans le libellé de l'interlocuteur au-dessus ni la phrase qui suit. C'est presque toujours ce que vous vouliez, et cela évite de le sélectionner à la main.
130
131	Ce qui est copié va dans deux presse-papiers : celui de l'éditeur, pour que `Shift-Ins` le colle dans un fichier ouvert ici, et celui du système, pour que `Ctrl-V` le colle n'importe où ailleurs. L'indentation d'affichage de la conversation est retirée, donc le code collé arrive collé à la marge.
132
133	La moitié « système » passe par votre terminal (une séquence d'échappement nommée OSC 52). La plupart des terminaux la gèrent ; quelques-uns la refusent par sécurité, et certains demandent de l'activer. Si `Ctrl-V` ailleurs ne donne rien, c'est là qu'il faut regarder — le presse-papiers de l'éditeur contient le texte dans tous les cas.
134
135	## Répondre quand l'agent demande la permission
136
137	Un agent doté d'un outil shell ou d'un outil de fichiers demande avant de s'en servir. Une boîte de dialogue nomme l'outil et la commande exacte, et propose les choix que l'agent lui-même a proposés — d'ordinaire Autoriser, Autoriser et retenir mon choix, et Passer.
138
139	```
140	┌────────── Bob (llama.cpp) veut lancer ──────────┐
141	│ │
142	│ Shell │
143	│ ls -1 │
144	│ │
145	│ [ Autoriser ] [ Toujours ] [ Passer ] │
146	└─────────────────────────────────────────────────┘
147	```
148
149	Toujours est retenu par l'agent, pas par l'éditeur : ce que cela couvre et combien de temps cela dure sont l'affaire de l'agent. Échap équivaut à Passer.
150
151	Rien ne s'exécute avant votre réponse. Un agent en attente d'une boîte de permission est simplement bloqué, et c'est bien le but.
152
153	## Laisser l'agent voir ce qui n'est pas encore enregistré
154
155	L'éditeur offre à l'agent son propre système de fichiers : quand l'agent lit un fichier que vous avez ouvert avec des modifications non enregistrées, il reçoit le texte du tampon, pas le texte plus ancien du disque. C'est généralement ce qu'on veut — vous posez une question sur la modification que vous venez de faire.
156
157	Quand l'agent écrit un fichier, la modification arrive dans le tampon et la fenêtre est marquée modifiée : vous pouvez la lire, l'annuler avec `Ctrl-Z`, ou l'enregistrer avec `F2`. Un fichier que vous n'avez pas ouvert est lu et écrit directement sur le disque.
158
159	## Faire tourner plusieurs agents à la fois
160
161	Chaque fenêtre est son propre processus et sa propre conversation. Ouvrir deux fois le même agent donne deux sessions indépendantes, et ouvrir deux agents différents permet de mettre côte à côte un modèle local rapide et un modèle lent et soigneux — Window ▸ Tile les dispose.
162
163	Quitter l'éditeur arrête tous les agents.
164
165	## Variantes
166
167	- Vous voulez que l'agent tourne ailleurs qu'à la racine du projet. Ajoutez `cwd = "backend"` à son bloc. Le chemin est relatif au projet, et c'est à la fois l'endroit où le processus démarre et le dossier de travail annoncé à l'agent.
168	- L'agent a besoin d'un identifiant. Mettez-le dans `env`, ou comptez sur sa présence dans l'environnement depuis lequel vous lancez l'éditeur — l'agent en hérite.
169	- Les commandes de l'agent n'apparaissent pas quand vous tapez `/`. Ouvrez Agent ▸ Agent status avec la fenêtre devant. S'il ne liste aucune commande, l'agent n'en a annoncé aucune — ou les a annoncées dans une forme que cet éditeur n'a pas su lire, auquel cas la boîte nomme la mise à jour et l'erreur de décodage. Pour voir exactement ce qui est passé sur le fil, lancez l'éditeur avec `TURBO_ACP_TRACE=/tmp/acp.log` et lisez le fichier : `->` est ce que l'éditeur a envoyé, `<-` ce que l'agent a répondu.
170	- L'agent ne démarre pas. Agent ▸ Agent status liste ce qui a été lu dans `acp.toml`, la ligne de commande obtenue pour chaque agent, et l'erreur de tout ce qui n'a pas démarré. Ce que l'agent écrit sur sa sortie d'erreur y figure aussi, et c'est là qu'un point d'accès de modèle mal configuré se signale.
171	- Vous gardez le même agent dans tous les projets. Mettez le bloc `[[agent]]` dans `~/.config/turbo-js/acp.toml`. Le fichier du projet est lu ensuite, et un agent du même `name` y remplace le vôtre.
172
173	## Voir aussi
174
175	- Chaque clé du fichier, et la part exacte du protocole implémentée : [référence Agents et ACP](../reference/acp.md)
176	- Pourquoi un agent est une fenêtre et non un panneau, et pourquoi les permissions sont modales : [Fenêtres agent](../explanation/agent-windows.md)
177	- Le protocole lui-même : [agentclientprotocol.com](https://agentclientprotocol.com)