Ferramenta de editor de texto

Ferramenta de edição de texto

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Claude pode usar uma ferramenta de editor de texto com esquema Anthropic para visualizar e modificar arquivos de texto, ajudando você a depurar, corrigir e melhorar seu código ou outros documentos de texto. Isso permite que Claude interaja diretamente com seus arquivos, fornecendo assistência prática em vez de apenas sugerir mudanças.

Para suporte de modelo, consulte a Referência de ferramentas.

Quando usar a ferramenta de editor de texto

Alguns exemplos de quando usar a ferramenta de editor de texto são:

Depuração de código: Peça ao Claude para identificar e corrigir bugs em seu código, desde erros de sintaxe até problemas de lógica.
Refatoração de código: Deixe Claude melhorar a estrutura, legibilidade e desempenho do seu código através de edições direcionadas.
Geração de documentação: Peça ao Claude para adicionar docstrings, comentários ou arquivos README ao seu código.
Criação de testes: Peça ao Claude para criar testes unitários para seu código com base em sua compreensão da implementação.

Use a ferramenta de editor de texto

Forneça a ferramenta de editor de texto (nomeada str_replace_based_edit_tool) ao Claude usando a API de Mensagens.

Você pode opcionalmente especificar um parâmetro max_characters para controlar o truncamento ao visualizar arquivos grandes.

max_characters é compatível apenas com text_editor_20250728 e versões posteriores da ferramenta de editor de texto.

A ferramenta de editor de texto pode ser usada da seguinte forma:

Comandos da ferramenta de editor de texto

A ferramenta de editor de texto suporta vários comandos para visualizar e modificar arquivos:

view

O comando view permite que Claude examine o conteúdo de um arquivo ou liste o conteúdo de um diretório. Ele pode ler o arquivo inteiro ou um intervalo específico de linhas.

Parâmetros:

command: Deve ser "view"
path: O caminho para o arquivo ou diretório a visualizar
view_range (opcional): Uma matriz de dois inteiros especificando os números de linha inicial e final a visualizar. Os números de linha são indexados a partir de 1, e -1 para a linha final significa ler até o final do arquivo. Este parâmetro se aplica apenas ao visualizar arquivos, não diretórios.

str_replace

O comando str_replace permite que Claude substitua uma string específica em um arquivo por uma nova string. Isso é usado para fazer edições precisas.

Parâmetros:

command: Deve ser "str_replace"
path: O caminho para o arquivo a modificar
old_str: O texto a substituir (deve corresponder exatamente, incluindo espaços em branco e indentação)
new_str: O novo texto a inserir no lugar do texto antigo

create

O comando create permite que Claude crie um novo arquivo com conteúdo especificado.

Parâmetros:

command: Deve ser "create"
path: O caminho onde o novo arquivo deve ser criado
file_text: O conteúdo a escrever no novo arquivo

insert

O comando insert permite que Claude insira texto em um local específico em um arquivo.

Parâmetros:

command: Deve ser "insert"
path: O caminho para o arquivo a modificar
insert_line: O número da linha após a qual inserir o texto (0 para o início do arquivo)
insert_text: O texto a inserir

Exemplo: Corrigindo um erro de sintaxe com a ferramenta editor de texto

Este exemplo demonstra como Claude usa a ferramenta editor de texto para corrigir um erro de sintaxe em um arquivo Python.

Primeiro, sua aplicação fornece a Claude a ferramenta editor de texto e um prompt para corrigir um erro de sintaxe:

Claude usa a ferramenta editor de texto primeiro para visualizar o arquivo:

Output

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-4-7",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

Sua aplicação deve então ler o arquivo e retornar seu conteúdo a Claude:

Números de linha

No exemplo acima, o resultado da ferramenta view inclui o conteúdo do arquivo com números de linha adicionados a cada linha (por exemplo, "1: def is_prime(n):"). Os números de linha não são obrigatórios, mas são essenciais para usar com sucesso o parâmetro view_range para examinar seções específicas de arquivos e o parâmetro insert_line para adicionar conteúdo em locais precisos.

Claude identifica o erro de sintaxe e usa o comando str_replace para corrigi-lo:

Output

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-4-7",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "str_replace",
        "path": "primes.py",
        "old_str": "    for num in range(2, limit + 1)",
        "new_str": "    for num in range(2, limit + 1):"
      }
    }
  ]
}

Sua aplicação deve então fazer a edição e retornar o resultado:

Por fim, Claude fornece uma explicação completa da correção:

Output

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-4-7",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit."
    }
  ]
}

Implementar a ferramenta editor de texto

A ferramenta editor de texto é implementada como uma ferramenta sem esquema. Ao usar esta ferramenta, você não precisa fornecer um esquema de entrada como com outras ferramentas; o esquema é incorporado no modelo de Claude e não pode ser modificado.

O tipo de ferramenta é type: "text_editor_20250728" para modelos Claude 4.

Ao implementar a ferramenta editor de texto, tenha em mente:

Segurança: A ferramenta tem acesso ao seu sistema de arquivos local, portanto implemente medidas de segurança apropriadas.
Backup: Sempre crie backups antes de permitir edições em arquivos importantes.
Validação: Valide todas as entradas para evitar alterações não intencionais.
Correspondência única: Certifique-se de que as substituições correspondam exatamente a um local para evitar edições não intencionais.

Lidar com erros

Ao usar a ferramenta editor de texto, vários erros podem ocorrer. Aqui está orientação sobre como lidar com eles:

Seguir as melhores práticas de implementação

Preços e uso de tokens

The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using.

In addition to the base tokens, the following additional input tokens are needed for the text editor tool:

Tool	Additional input tokens
`text_editor_20250429` (Claude 4.x)	700 tokens

Para informações mais detalhadas sobre preços de ferramentas, consulte Preços de uso de ferramentas.

Integrar a ferramenta editor de texto com outras ferramentas

A ferramenta editor de texto pode ser usada junto com outras ferramentas Claude. Ao combinar ferramentas, certifique-se de:

Corresponder a versão da ferramenta com o modelo que você está usando
Contabilizar o uso de tokens adicional para todas as ferramentas incluídas em sua solicitação

Registro de alterações

Data	Versão	Alterações
28 de julho de 2025	`text_editor_20250728`	Lançamento de uma ferramenta editor de texto atualizada que corrige alguns problemas e adiciona um parâmetro `max_characters` opcional. É idêntica a `text_editor_20250429` de outra forma.
29 de abril de 2025	`text_editor_20250429`	Lançamento da ferramenta editor de texto para Claude 4. Esta versão remove o comando `undo_edit` mas mantém todas as outras capacidades. O nome da ferramenta foi atualizado para refletir sua arquitetura baseada em str_replace.
13 de março de 2025	`text_editor_20250124`	Introdução da documentação da ferramenta editor de texto independente. Esta versão é otimizada para Claude Sonnet 3.7 mas tem capacidades idênticas à versão anterior.
22 de outubro de 2024	`text_editor_20241022`	Lançamento inicial da ferramenta editor de texto com Claude Sonnet 3.5 (). Fornece capacidades para visualizar, criar e editar arquivos através dos comandos , , , e .

Próximos passos

Aqui estão algumas ideias de como usar a ferramenta editor de texto de formas mais convenientes e poderosas:

Integrar com seu fluxo de trabalho de desenvolvimento: Construa a ferramenta editor de texto em suas ferramentas de desenvolvimento ou IDE
Criar um sistema de revisão de código: Tenha Claude revisar seu código e fazer melhorias
Construir um assistente de depuração: Crie um sistema onde Claude possa ajudá-lo a diagnosticar e corrigir problemas em seu código
Implementar conversão de formato de arquivo: Deixe Claude ajudá-lo a converter arquivos de um formato para outro
Automatizar documentação: Configure fluxos de trabalho para Claude documentar automaticamente seu código

A ferramenta editor de texto permite que Claude trabalhe diretamente com sua base de código, suportando fluxos de trabalho desde depuração até documentação automatizada.

Visão geral de uso de ferramentas

Aprenda como implementar fluxos de trabalho de ferramentas para uso com Claude.

Ferramenta Bash

Execute comandos shell com Claude.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?",
        }
    ],
)

print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        {
            "role": "user",
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?",
        }
    ],
)

print(response)

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        {
            "role": "user",
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue.",
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "name": "str_replace_based_edit_tool",
                    "input": {"command": "view", "path": "primes.py"},
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "content": '1: def is_prime(n):\n2:     """Check if a number is prime."""\n3:     if n <= 1:\n4:         return False\n5:     if n <= 3:\n6:         return True\n7:     if n % 2 == 0 or n % 3 == 0:\n8:         return False\n9:     i = 5\n10:     while i * i <= n:\n11:         if n % i == 0 or n % (i + 2) == 0:\n12:             return False\n13:         i += 6\n14:     return True\n15: \n16: def get_primes(limit):\n17:     """Generate a list of prime numbers up to the given limit."""\n18:     primes = []\n19:     for num in range(2, limit + 1)\n20:         if is_prime(num):\n21:             primes.append(num)\n22:     return primes\n23: \n24: def main():\n25:     """Main function to demonstrate prime number generation."""\n26:     limit = 100\n27:     prime_list = get_primes(limit)\n28:     print(f"Prime numbers up to {limit}:")\n29:     print(prime_list)\n30:     print(f"Found {len(prime_list)} prime numbers.")\n31: \n32: if __name__ == "__main__":\n33:     main()',
                }
            ],
        },
    ],
)

print(response)

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        # Previous messages...
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you.",
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "name": "str_replace_based_edit_tool",
                    "input": {
                        "command": "str_replace",
                        "path": "primes.py",
                        "old_str": "    for num in range(2, limit + 1)",
                        "new_str": "    for num in range(2, limit + 1):",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "content": "Successfully replaced text at exactly one location.",
                }
            ],
        },
    ],
)

print(response)

Inicializar sua implementação do editor
Crie funções auxiliares para lidar com operações de arquivo como leitura, escrita e modificação de arquivos. Considere implementar funcionalidade de backup para recuperação de erros.

Lidar com chamadas da ferramenta editor

Crie uma função que processe chamadas de ferramenta de Claude com base no tipo de comando:

def handle_editor_tool(tool_call):
    input_params = tool_call.input
    command = input_params.get("command", "")
    file_path = input_params.get("path", "")

    if command == "view":
        # Read and return file contents
        pass
    elif command == "str_replace":
        # Replace text in file
        pass
    elif command == "create":
        # Create new file
        pass
    elif command == "insert":
        # Insert text at location
        pass

Implementar medidas de segurança
Adicione validação e verificações de segurança:
- Validar caminhos de arquivo para evitar travessia de diretório
- Criar backups antes de fazer alterações
- Lidar com erros adequadamente
- Implementar verificações de permissões

Processar respostas de Claude

Extrair e lidar com chamadas de ferramenta das respostas de Claude:

# Process tool use in Claude's response
for content in response.content:
    if content.type == "tool_use":
        # Execute the tool based on command
        result = handle_editor_tool(content)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

view

create

str_replace

insert

undo_edit

Quando usar a ferramenta de editor de texto

Use a ferramenta de editor de texto

Comandos da ferramenta de editor de texto

view

Exemplos de comandos view

str_replace

Exemplo de comando str_replace

create

Exemplo de comando create

insert

Exemplo de comando insert

Exemplo: Corrigindo um erro de sintaxe com a ferramenta editor de texto

Implementar a ferramenta editor de texto

Lidar com erros

Arquivo não encontrado

Múltiplas correspondências para substituição

Seguir as melhores práticas de implementação

Fornecer contexto claro

Ser explícito sobre caminhos de arquivo

Criar backups antes de editar

Preços e uso de tokens

Integrar a ferramenta editor de texto com outras ferramentas

Registro de alterações

Próximos passos

Nenhuma correspondência para substituição

Erros de permissão

Lidar com substituição de texto única com cuidado

Verificar alterações