Pular para o conteúdo principal

Visão Geral do Uso de Ferramentas

O AI Cockpit Reasoning implementa um sistema de ferramentas sofisticado que permite que os modelos de IA interajam com seu ambiente de desenvolvimento de maneira controlada e segura. Este documento explica como as ferramentas funcionam, quando são chamadas e como são gerenciadas.

Conceitos Principais​

Grupos de Ferramentas​

As ferramentas são organizadas em grupos lógicos com base em sua funcionalidade:

CategoriaPropósitoFerramentasUso Comum
Grupo de LeituraLeitura e pesquisa no sistema de arquivosread_file, search_files, list_files, list_code_definition_namesExploração e análise de código
Grupo de EdiçãoModificações no sistema de arquivosapply_diff, write_to_fileAlterações de código e manipulação de arquivos
Grupo de NavegadorAutomação da Webbrowser_actionTeste e interação na Web
Grupo de ComandoExecução de comandos do sistemaexecute_commandExecução de scripts, compilação de projetos
Grupo MCPIntegração de ferramentas externasuse_mcp_tool, access_mcp_resourceFuncionalidade especializada através de servidores externos
Grupo de Fluxo de TrabalhoGerenciamento de modo e tarefaswitch_mode, new_task, ask_followup_question, attempt_completion, update_todo_listTroca de contexto e organização de tarefas

Ferramentas Sempre Disponíveis​

Certas ferramentas são acessíveis independentemente do modo atual:

Ferramentas Disponíveis​

Ferramentas de Leitura​

Estas ferramentas ajudam o AI Cockpit Reasoning a entender seu código e projeto:

Ferramentas de Edição​

Estas ferramentas ajudam o AI Cockpit Reasoning a fazer alterações em seu código:

  • apply_diff - Faz alterações precisas e cirúrgicas em seu código
  • write_to_file - Cria novos arquivos ou reescreve completamente os existentes

Ferramentas de Navegador​

Estas ferramentas ajudam o AI Cockpit Reasoning a interagir com aplicativos da web:

Ferramentas de Comando​

Estas ferramentas ajudam o AI Cockpit Reasoning a executar comandos:

Ferramentas MCP​

Estas ferramentas ajudam o AI Cockpit Reasoning a se conectar com serviços externos:

Ferramentas de Fluxo de Trabalho​

Estas ferramentas ajudam a gerenciar a conversa e o fluxo de tarefas:

Mecanismo de Chamada de Ferramenta​

Quando as Ferramentas São Chamadas​

As ferramentas são invocadas sob condições específicas:

  1. Requisitos Diretos da Tarefa

    • Quando ações específicas são necessárias para concluir uma tarefa, conforme decidido pelo LLM
    • Em resposta às solicitações do usuário
    • Durante fluxos de trabalho automatizados

  2. Disponibilidade Baseada no Modo

    • Diferentes modos habilitam diferentes conjuntos de ferramentas
    • As trocas de modo podem acionar alterações na disponibilidade de ferramentas
    • Algumas ferramentas são restritas a modos específicos

  3. Chamadas Dependentes do Contexto

    • Com base no estado atual do espaço de trabalho
    • Em resposta a eventos do sistema
    • Durante o tratamento e recuperação de erros

Processo de Decisão​

O sistema usa um processo de várias etapas para determinar a disponibilidade da ferramenta:

  1. Validação do Modo

    isToolAllowedForMode(
        tool: string,
        modeSlug: string,
        customModes: ModeConfig[],
        toolRequirements?: Record<string, boolean>,
        toolParams?: Record<string, any>
    )

  2. Verificação de Requisitos

    • Verificação da capacidade do sistema
    • Disponibilidade de recursos
    • Validação de permissão

  3. Validação de Parâmetros

    • Presença de parâmetros obrigatórios
    • Verificação do tipo de parâmetro
    • Validação de valor

Implementação Técnica​

Processamento de Chamada de Ferramenta​

  1. Inicialização

    • O nome e os parâmetros da ferramenta são validados
    • A compatibilidade do modo é verificada
    • Os requisitos são verificados

  2. Execução

    const toolCall = {
        type: "tool_call",
        name: chunk.name,
        arguments: chunk.input,
        callId: chunk.callId
    }

  3. Manuseio de Resultados

    • Determinação de sucesso/falha
    • Formatação do resultado
    • Tratamento de erros

    Segurança e Permissões​

  4. Controle de Acesso

    • Restrições do sistema de arquivos
    • Limitações de execução de comandos
    • Controles de acesso à rede

  5. Camadas de Validação

    • Validação específica da ferramenta
    • Restrições baseadas no modo
    • Verificações no nível do sistema

Integração de Modo​

Acesso a Ferramentas Baseado no Modo​

As ferramentas são disponibilizadas com base no modo atual:

  • Modo Código: Acesso total às ferramentas do sistema de arquivos, capacidades de edição de código, execução de comandos
  • Modo Pergunta: Limitado a ferramentas de leitura, capacidades de coleta de informações, sem modificações no sistema de arquivos
  • Modo Arquiteto: Ferramentas focadas em design, capacidades de documentação, direitos de execução limitados
  • Modos Personalizados: Podem ser configurados com acesso a ferramentas específicas para fluxos de trabalho especializados

Troca de Modo​

  1. Processo

    • Preservação do estado do modo atual
    • Atualizações de disponibilidade de ferramentas
    • Troca de contexto

  2. Impacto nas Ferramentas

    • Alterações no conjunto de ferramentas
    • Ajustes de permissão
    • Preservação de contexto

Melhores Práticas​

Diretrizes de Uso de Ferramentas​

  1. Eficiência

    • Use a ferramenta mais específica para a tarefa
    • Evite chamadas de ferramentas redundantes
    • Agrupe operações quando possível

  2. Segurança

    • Valide as entradas antes das chamadas de ferramentas
    • Use as permissões mínimas necessárias
    • Siga as melhores práticas de segurança

  3. Tratamento de Erros

    • Implemente a verificação de erros adequada
    • Forneça mensagens de erro significativas
    • Lide com falhas de forma elegante

Padrões Comuns​

  1. Coleta de Informações

    [ask_followup_question](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files)

  2. Modificação de Código

    [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion)

  3. Gerenciamento de Tarefas

    [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command)

  4. Acompanhamento do Progresso

    [update_todo_list](/features/tools/update-todo-list) → [execute_command](/features/tools/execute-command) → [update_todo_list](/features/tools/update-todo-list)

Tratamento e Recuperação de Erros​

Tipos de Erro​

  1. Erros Específicos da Ferramenta

    • Falhas na validação de parâmetros
    • Erros de execução
    • Problemas de acesso a recursos

  2. Erros do Sistema

    • Permissão negada
    • Recurso indisponível
    • Falhas de rede

  3. Erros de Contexto

    • Modo inválido para a ferramenta
    • Requisitos ausentes
    • Inconsistências de estado

Estratégias de Recuperação​

  1. Recuperação Automática

    • Mecanismos de repetição
    • Opções de fallback
    • Restauração de estado

  2. Intervenção do Usuário

    • Notificações de erro
    • Sugestões de recuperação
    • Opções de intervenção manual