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

// Chemin du fichier : ~/.pi/agent/extensions/todo-tool.ts
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.

ChampTypeRequisDescription
namestringOuiIdentifiant unique de l'outil ; l'IA l'appelle par ce nom
labelstringOuiNom d'affichage de l'outil
descriptionstringOuiDescription de la fonction de l'outil ; l'IA l'utilise pour décider quand utiliser l'outil
parametersSchéma TypeBoxOuiDéfinition de type des paramètres de l’outil
promptSnippetstringnonRésumé en une ligne dans la section Outils disponibles
promptGuidelinesstring[]nonInstructions ajoutées à la section Guidelines du prompt système
prepareArgumentsfonctionnonTransforme les paramètres avant la validation du schéma, utilisé pour la compatibilité avec les anciens formats
executefonction asyncOuiLa 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ètreTypeDescription
toolCallIdstringIdentifiant unique de l'appel d'outil
paramsT génériqueObjet de paramètre validé par Schema
signalAbortSignal | undefinedSignal d'annulation, déclenché lorsque l'utilisateur appuie sur Échap
onUpdatefonctionFonction de rappel pour l'envoi de mises à jour de progression
ctxExtensionContextContexte d'extension, fournissant l'interface utilisateur, la session et d'autres capacités

Format de la valeur de retour :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/todo-tool.ts (valeur de retour de la fonction execute)
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

// Chemin du fichier : ~/.pi/agent/extensions/todo-tool.ts (champ parameters)
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

// Chemin du fichier : ~/.pi/agent/extensions/note-edit.ts
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

// Chemin du fichier : ~/.pi/agent/extensions/read-log.ts
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

// Chemin du fichier : ~/.pi/agent/extensions/read-logger.ts
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