L'outil text editor

Claude connaît un outil d’édition de texte dont Anthropic fournit le schéma : vous n’avez pas à le décrire. Il lui permet de lire des fichiers et des dossiers, de remplacer un passage, de créer un fichier ou d’insérer des lignes, comme un développeur dans son éditeur. Le schéma vient d’Anthropic ; l’exécution reste à votre charge.

Un outil défini par Anthropic

C’est le troisième mode de la leçon 22 : Anthropic publie le type d’outil, votre code exécute les actions. L’intérêt est la fiabilité : selon la documentation d’Anthropic, Claude a été entraîné sur un grand nombre d’utilisations réussies de ces outils, et les appelle plus sûrement qu’un outil maison équivalent.

Sur Bedrock, ces outils suivent le format de l’API Messages d’Anthropic. Avec l’API Converse, la documentation AWS les fait passer par additionalModelRequestFields, le champ des paramètres propres à un modèle, et non par toolConfig. Les demandes de Claude reviennent, elles, sous forme de blocs toolUse ordinaires.

Déclarer l’outil

def chat(messages, system=None, tools=None, tool_choice=None, text_editor=None):
    params = {"modelId": model_id, "messages": messages}
    if system:
        params["system"] = [{"text": system}]
    if tools:
        params["toolConfig"] = {"tools": tools}
        if tool_choice:
            params["toolConfig"]["toolChoice"] = {"tool": {"name": tool_choice}}
    if text_editor:
        params["additionalModelRequestFields"] = {
            "tools": [{"type": text_editor, "name": "str_replace_based_edit_tool"}]
        }

    response = client.converse(**params)
    parts = response["output"]["message"]["content"]
    return {
        "parts": parts,
        "stop_reason": response["stopReason"],
        "text": "\n".join(part["text"] for part in parts if "text" in part),
    }

La version text_editor_20250728, avec le nom str_replace_based_edit_tool, vaut pour les modèles Claude 4 et suivants ; la fiche AWS de Claude Haiku 5.5 la liste, sans en-tête bêta. La version antérieure, text_editor_20250124, s’appelait str_replace_editor ; la documentation AWS précise que les modèles récents la refusent. Nos outils maison, eux, restent déclarés dans toolConfig, à côté.

Selon la documentation d’Anthropic, l’outil ajoute environ 974 tokens d’entrée à chaque requête sur les modèles Claude 4.7 et suivants. Un paramètre facultatif, max_characters, demande à votre code de tronquer l’affichage des gros fichiers.

Les quatre commandes

La commande undo_edit n’existait que dans la version antérieure : pour revenir en arrière, c’est à votre application de garder des copies.

L’exécution vous revient

Claude demande par exemple {"command": "view", "path": "main.py"}. Votre code lit le fichier et renvoie son contenu. Voici une implémentation minimale de deux commandes :

from pathlib import Path

ROOT = Path("projet").resolve()


def safe_path(path):
    p = (ROOT / path).resolve()
    if not p.is_relative_to(ROOT):
        raise ValueError(f"chemin hors du dossier de travail : {path}")
    return p


def text_editor(command, path, **params):
    p = safe_path(path)
    if command == "view":
        if p.is_dir():
            return "\n".join(sorted(child.name for child in p.iterdir()))
        if not p.exists():
            raise ValueError(f"fichier introuvable : {path}")
        lines = p.read_text(encoding="utf-8").splitlines()
        start, end = params.get("view_range", [1, -1])
        end = len(lines) if end == -1 else end
        return "\n".join(f"{n}: {line}" for n, line in enumerate(lines[start - 1:end], start))
    if command == "str_replace":
        text = p.read_text(encoding="utf-8")
        count = text.count(params["old_str"])
        if count != 1:
            raise ValueError(f"old_str trouvé {count} fois : il doit l'être exactement une fois")
        p.write_text(text.replace(params["old_str"], params["new_str"]), encoding="utf-8")
        return "Remplacement effectué."
    raise ValueError(f"commande non prise en charge : {command}")


TOOLS["str_replace_based_edit_tool"] = text_editor

Le cours officiel aiguille les commandes dans run_tool vers une classe TextEditorTool fournie dans son notebook ; ici, une fonction branchée dans TOOLS fait le même travail. Les numéros de ligne ajoutés par view permettent à Claude d’utiliser correctement view_range et insert_line.

Reste à transmettre l’option à chat depuis la boucle de la leçon 28 :

def run_conversation(messages, tools, max_turns=10, **options):
    for _ in range(max_turns):
        result = chat(messages, tools=tools, **options)
        add_assistant_message(messages, result["parts"])
        if result["text"]:
            print(result["text"])
        if result["stop_reason"] != "tool_use":
            return messages
        add_user_message(messages, run_tools(result["parts"]))
    raise RuntimeError(f"Pas de réponse finale après {max_turns} tours")


messages = []
add_user_message(messages, "Décris en une phrase le code du fichier main.py.")
run_conversation(messages, tools, text_editor="text_editor_20250728")

Claude demande view sur main.py, votre code renvoie le contenu, et Claude répond par sa description.

Les précautions

La documentation d’Anthropic insiste sur quatre points, que l’implémentation ci-dessus applique en partie :

1. Limiter l’accès au dossier de travail : safe_path refuse tout chemin qui en sort, comme ../../etc/passwd.
2. Garder des copies des fichiers avant de les modifier.
3. Exiger une correspondance unique pour str_replace, pour ne jamais modifier le mauvais passage.
4. Renvoyer des erreurs claires, qui repartent vers Claude avec le statut error.

À vous de jouer

Compléter l’éditeur. Ajoutez les commandes create et insert, ainsi qu’une copie de sauvegarde avant chaque modification. Créez un dossier projet avec un main.py, puis demandez : « Ajoute dans main.py une fonction qui calcule pi à la cinquième décimale, puis crée test.py pour la tester. » Suivez dans l’historique les commandes demandées.

Sources officielles : The text editor tool (Claude Academy) · Computer use et Anthropic Claude tool use (documentation AWS) · Text editor tool (documentation Claude)

Points clés à retenir

• Le type d’outil vient d’Anthropic, l’exécution reste à votre charge.
• Avec Converse, l’outil passe par additionalModelRequestFields ; ses demandes reviennent en blocs toolUse.
• text_editor_20250728 et le nom str_replace_based_edit_tool valent pour les modèles actuels.
• Quatre commandes : view, str_replace, create, insert.
• Limitez les chemins au dossier de travail, gardez des copies, exigez une correspondance unique.