Développement d'outils personnalisés pour Pi Agent
Enregistrez des outils personnalisés via Extension, permettant à l'IA d'appeler les fonctions que vous écrivez pour accomplir des tâches spécifiques.
Bases de l'enregistrement des outils
Utilisationpi.registerTool()Enregistrez un outil appelable par l'IA :
Exemple
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";
// Définir une liste de tâches (stockage en mémoire)
let todos: string[] = [];
export default function (pi: ExtensionAPI) {
// Restaurer l'état depuis la session au démarrage
pi.on("session_start", async (_event, ctx) => {
todos = [];
for (const entry of ctx.sessionManager.getBranch()) {
if (entry.type === "message"
&& entry.message.role === "toolResult"
&& entry.message.toolName === "todo") {
todos = entry.message.details?.todos ?? [];
}
}
});
pi.registerTool({
name: "todo",
label: Liste de tâches,
description: Gérer la liste de tâches du projet,
// Brève description, affichée dans la section Outils disponibles du prompt système
promptSnippet: Gérer les tâches du projet : list liste, add ajoute, done termine,
// Consignes d'utilisation, ajoutées à la section Guidelines du prompt système
promptGuidelines: [
Utilisez l'outil todo pour la planification des tâches ; ne modifiez pas directement les fichiers todo,
],
parameters: Type.Object({
// StringEnum garantit la compatibilité avec l'API Google
action: StringEnum(["list", "add", "done"] as const),
text: Type.Optional(Type.String({
description: Lors de l'ajout : description de l'élément. Lors de la complétion : numéro ou description de l'élément
})),
}),
// Rétrocompatible avec l'ancien format de paramètre
prepareArguments(args) {
if (!args || typeof args !== "object") return args;
const input = args as { action?: string; oldAction?: string };
// Associer les anciens champs aux nouveaux champs
if (typeof input.oldAction === "string"
&& input.action === undefined) {
return { ...input, action: input.oldAction };
}
return args;
},
async execute(toolCallId, params, signal, onUpdate, ctx) {
if (signal?.aborted) {
return {
content: [{ type: "text", text: Opération annulée }]
};
}
// Envoyer une mise à jour de progression
onUpdate?.({
content: [{ type: "text", text:`Traitement: ${params.action}` }],
});
switch (params.action) {
case "list":
return {
content: [{
type: "text",
text: todos.length === 0
? La liste de tâches est vide
: todos.map((t, i) => `${i + 1}. ${t}`).join("\n"),
}],
details: { todos: [...todos] },
};
case "add":
if (!params.text) {
throw new Error(L'opération d'ajout nécessite un paramètre texte);
}
todos.push(params.text);
// Le 5e paramètre ctx est le contexte d'extension ; ici, nous l'utilisons pour afficher une notification dans le terminal
ctx.ui.notify(`Tâche ajoutée : ${params.text}`, "info");
return {
content: [{
type: "text",
text:`Ajouté: ${params.text}(total ${todos.length}élément(s))`,
}],
details: { todos: [...todos] },
};
case "done":
if (!params.text) {
throw new Error(L'opération done nécessite un paramètre text);
}
const idx = todos.findIndex(
t => t.includes(params.text!)
);
if (idx === -1) {
return {
content: [{
type: "text",
text:`Aucun élément correspondant trouvé: ${params.text}`
}],
details: { todos: [...todos] },
};
}
const removed = todos.splice(idx, 1)[0];
return {
content: [{
type: "text",
text:`Terminé: ${removed}(restant ${todos.length}élément(s))`,
}],
details: { todos: [...todos] },
};
default:
throw new Error(Opération inconnue);
}
},
});
}
Une fois enregistrée, l'IA décide de manière autonome quand appeler l'outil todo en fonction de description et promptSnippet.
Par exemple, lorsque l'utilisateur dit « Ajouter la rédaction du rapport hebdomadaire à ma liste de tâches », l'IA effectuera l'appel suivant :
tool_call: todo
{
"action": "add",
"text": "写周报"
}
Une fois execute exécuté, le texte renvoyé à l'IA est le suivant :
待办已新增:写周报(共 1 项)
Après avoir reçu ce résultat, l'IA confirme à l'utilisateur en langage naturel, par exemple « Ajout de 'la rédaction du rapport hebdomadaire' à la liste de tâches ; actuellement 1 élément au total. »
Outre la reconstruction de l'état à partir des détails dans toolResult, il existe un autre chemin pour la persistance entre les redémarrages :pi.appendEntry()。
Il écrit des entrées personnalisées directement dans le fichier de session ; combinées àpi.registerEntryRenderer(), elles peuvent également être rendues dans l'historique de la conversation.
Les entrées personnalisées n'entrent pas dans le contexte du LLM, donc elles ne consomment pas de tokens.
Mais elles sont enregistrées avec la session et conservées dans la branche /tree.
Explication de la définition d'un outil
L'objet de configuration registerTool contient les champs suivants, dont name, parameters et execute constituent le cœur.
| Champ | Type | Requis | Description |
|---|---|---|---|
| name | string | Oui | Identifiant unique de l'outil ; l'IA l'appelle par ce nom |
| label | string | Oui | Nom d'affichage de l'outil |
| description | string | Oui | Description de la fonction de l'outil ; l'IA l'utilise pour décider quand utiliser l'outil |
| parameters | Schéma TypeBox | Oui | Définition de type des paramètres de l’outil |
| promptSnippet | string | non | Résumé en une ligne dans la section Outils disponibles |
| promptGuidelines | string[] | non | Instructions ajoutées à la section Guidelines du prompt système |
| prepareArguments | fonction | non | Transforme les paramètres avant la validation du schéma, utilisé pour la compatibilité avec les anciens formats |
| execute | fonction async | Oui | La logique d’exécution réelle de l’outil |
Chaque instruction dans promptGuidelines doit indiquerexplicitement le nom de l’outil。
N’écrivez pas « when using this tool... » ; écrivez plutôt « when using my_tool... », car l’IA ne peut pas déterminer à quel outil « this » fait référence.
Fonction execute expliquée
La fonction execute reçoit les paramètres suivants :
| Paramètre | Type | Description |
|---|---|---|
| toolCallId | string | Identifiant unique de l'appel d'outil |
| params | T générique | Objet de paramètre validé par Schema |
| signal | AbortSignal | undefined | Signal d'annulation, déclenché lorsque l'utilisateur appuie sur Échap |
| onUpdate | fonction | Fonction de rappel pour l'envoi de mises à jour de progression |
| ctx | ExtensionContext | Contexte d'extension, fournissant l'interface utilisateur, la session et d'autres capacités |
Format de la valeur de retour :
Exemple
return {
// Contenu envoyé au LLM (obligatoire)
content: [{ type: "text", text: Opération terminée }],
// Données de détail personnalisées, utilisées pour la reconstruction de l'état et le rendu (facultatif)
details: { result: "..." },
// Statistiques d'utilisation pour les appels LLM imbriqués (facultatif)
usage: nestedModelUsage,
// Indicateur de terminaison : lorsque tous les outils du même lot renvoient terminate
// Ignore les appels LLM suivants (facultatif)
terminate: true,
};
Pour marquer l'exécution d'un outil comme échouée, utilisezthrow new Error(), ne tentez pas de définir l'indicateur d'erreur dans la valeur de retour.
Ce n'est qu'en lançant une exception que vous pouvez définir isError sur true et informer le LLM qu'une erreur s'est produite.
StringEnum et sécurité des types
UtilisezStringEnumau lieu de Type.Union/Type.Literal pour définir des paramètres d'énumération :
Exemple
import { StringEnum } from "@earendil-works/pi-ai";
// Correct : compatible avec l'API Google
parameters: Type.Object({
action: StringEnum(["list", "add", "done"] as const),
})
// Incorrect : non compatible avec l'API Google
parameters: Type.Object({
action: Type.Union([
Type.Literal("list"),
Type.Literal("add"),
Type.Literal("done"),
]),
})
File d'attente de sécurité de modification de fichiers
Si votre outil modifie des fichiers, utilisezwithFileMutationQueue()pour participer à la file d'attente de modification de fichiers :
Exemple
import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";
// L'extrait suivant se trouve à l'intérieur de la fonction execute de registerTool
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
// Résoudre le chemin en un chemin absolu
const absolutePath = resolve(ctx.cwd, params.path);
return withFileMutationQueue(absolutePath, async () => {
// S'assurer que le répertoire existe
await mkdir(dirname(absolutePath), { recursive: true });
// Lire le contenu actuel
const current = await readFile(absolutePath, "utf8");
// Appliquer la modification
const next = current.replace(params.oldText, params.newText);
// Réécrire dans le fichier
await writeFile(absolutePath, next, "utf8");
return {
content: [{ type: "text", text:`Mis à jour ${params.path}` }],
details: {},
};
});
}
La file d'attente de modification de fichier garantit que les modifications concurrentes d'un même fichier ne s'écrasent pas mutuellement — lorsque l'outil d'édition intégré et votre outil personnalisé modifient le même fichier en même temps, ils s'exécutent dans une file d'attente.
Troncature de la sortie
La sortie de l'outil doit être tronquée pour éviter de remplir la fenêtre de contexte du LLM. Les limites intégrées sont 50KB (environ 10,000 tokens) et 2000 lignes :
Exemple
import {
truncateHead,
formatSize,
DEFAULT_MAX_BYTES,
DEFAULT_MAX_LINES,
} from "@earendil-works/pi-coding-agent";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
// L'extrait suivant se trouve à l'intérieur de la fonction execute de registerTool
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
// Lire un vrai fichier pour obtenir le texte à renvoyer
const output = await readFile(resolve(ctx.cwd, params.file), "utf8");
// Conserver la partie initiale (adaptée à la lecture de fichiers, aux résultats de recherche)
const truncation = truncateHead(output, {
maxLines: DEFAULT_MAX_LINES,
maxBytes: DEFAULT_MAX_BYTES,
});
let result = truncation.content;
// Ajouter une ligne de note en cas de troncature, afin que l'IA sache que le contenu est incomplet
if (truncation.truncated) {
result += `\n\n[Sortie tronquée : ${truncation.outputLines}/`;
result += `${truncation.totalLines}lignes`;
result += `(${formatSize(truncation.outputBytes)}/`;
result += `${formatSize(truncation.totalBytes)})]`;
}
return {
content: [{ type: "text", text: result }],
};
}
Pour un fichier journal volumineux qui dépasse les limites, le texte renvoyé par l'outil inclura une note de troncature à la fin :
[2026-08-31 10:02:11] server started on port 3000 [2026-08-31 10:02:12] GET / 200 12ms [2026-08-31 10:02:12] GET /static/app.js 200 4ms ... [输出已截断:2000/8642 行(49.9KB/210.3KB)]
La troncature n'est pas facultative。
Une sortie d'outil surdimensionnée peut provoquer un débordement de contexte, des échecs de compression et une dégradation des performances du modèle. Tronquez toujours la sortie des outils.
Remplacement des outils intégrés
Vous pouvez remplacer les outils intégrés en enregistrant des outils portant le même nom (read, bash, powershell, edit, write, grep, find, ls).
$ pi -e ./tool-override.ts
Ci-dessous, registerTool est utilisé pour remplacer l'outil read intégré, en ajoutant une entrée de journal pour chaque lecture de fichier :
Exemple
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
export default function (pi: ExtensionAPI) {
// Remplacer en utilisant le même nom que l'outil intégré ; ici, nous ajoutons uniquement la journalisation à read
pi.registerTool({
name: "read",
label: "Lire le fichier",
description: "Lire le contenu du fichier et journaliser l'accès dans le terminal",
parameters: Type.Object({
path: Type.String({ description: "Le chemin du fichier à lire" }),
}),
async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
const absolutePath = resolve(ctx.cwd, params.path);
const text = await readFile(absolutePath, "utf8");
// Capacité supplémentaire : enregistrer un journal d'accès
console.log(`[read] ${params.path}(${text.length}caractères)`);
// Conserver la structure de retour cohérente avec le read intégré
return {
content: [{ type: "text", text }],
};
},
});
}
Après avoir chargé cette extension, l'IA affichera une ligne de journal [read] dans le terminal chaque fois qu'elle lit un fichier.
Lors d'une surcharge, les renderers (renderCall/renderResult) sont hérités par emplacement—si vous omettez renderCall, le renderCall intégré sera quand même utilisé.
Cela vous permet d'ajouter de la journalisation ou un contrôle des permissions aux outils intégrés sans réécrire l'interface utilisateur.
Mais pour promptSnippet et promptGuidelines, ilsne seront pashérités des outils intégrés ; ils doivent être définis explicitement.
Il existe une autre contrainte plus subtile : votre implémentation doit correspondre exactement à la forme du résultat de l'outil intégré, y compris le champ details.
Prenons read comme exemple : les paramètres d'entrée doivent prendre en charge deux paramètres facultatifs, offset et limit, afin que l'IA puisse obtenir le contenu attendu lors de la lecture de fichiers volumineux de manière paginée.
Les details dans la valeur de retour doivent aussi correspondre à la forme ReadToolDetails du read intégré ; sinon, le rendu de l'interface utilisateur manquera d'informations et le suivi de l'état de session en sera également affecté.
L'exemple d'extension de journalisation ci-dessus est uniquement à titre de démonstration. Lorsque vous surchargez officiellement le read intégré, veuillez compléter les paramètres et les details conformément à l'implémentation intégrée.
Autres extensions