Glossário
76 termos de “Tool calling de agentes: fazendo agentes agirem de verdade”. Passe o cursor sobre a primeira ocorrência na lição para ver a definição.
| Termo | Definição | Fonte |
|---|---|---|
| ferramenta | No contexto de um agente, uma ferramenta é uma capacidade concreta que o modelo pode solicitar durante a conversa; o programa host a registra e a executa, transformando o modelo de algo que apenas conversa em algo que pode agir. | Define tools — Claude API |
| programa host | O programa host é o código que de fato recebe a requisição de chamada de ferramenta do modelo, executa a operação e passa o resultado de volta ao modelo — por exemplo, o Claude Code ou um script de agente que você mesmo escreve. | How tool use works — Claude API |
| search_files | Um nome de ferramenta de exemplo usado ao longo do curso, representando a classe de definições concretas de ferramenta que 'buscam arquivos do projeto por alguma condição'. | Define tools — Claude API |
| name | Um campo obrigatório na definição de uma ferramenta; é o identificador que o modelo escreve quando escolhe uma ferramenta, e precisa corresponder exatamente ao nome dado no momento da chamada. | Define tools — Claude API |
| description | Um campo obrigatório na definição de uma ferramenta; declara em texto simples o que a ferramenta faz, quando usá-la e como ela se comporta, e é a única base legível que o modelo tem ao escolher uma ferramenta. | Define tools — Claude API |
| input_schema | Um campo obrigatório na definição de uma ferramenta; é um JSON Schema que especifica a forma que os parâmetros devem assumir quando a ferramenta é chamada. | Define tools — Claude API |
| client tools | Ferramentas que o aplicativo host é responsável por executar ele mesmo; o modelo apenas gera a requisição de chamada, enquanto o código de execução real roda do lado do host. | Tool use with Claude — Overview |
| server tools | Ferramentas que os servidores da Anthropic executam em seu nome, em oposição às client tools cuja lógica de execução o aplicativo host precisa implementar ele mesmo. | Tool use with Claude — Overview |
| dados estruturados | A requisição de chamada de ferramenta do modelo volta como um pedaço de dados estruturados (não uma instrução em linguagem natural), carregando o nome da ferramenta e os parâmetros para o programa host interpretar e executar. | How tool use works — Claude API |
| required | Um campo no JSON Schema que lista os nomes de parâmetro que uma chamada de ferramenta precisa fornecer; uma chamada sem esses parâmetros é tratada como entrada inválida. | Define tools — Claude API |
| Claude Code | O exemplo concreto do curso do conceito de 'programa host' — ele próprio um produto de agente que solicita chamadas a muitas ferramentas (ler arquivos, buscar código, rodar comandos e assim por diante). | Tools reference — Claude Code Docs |
| tools | Um campo transportado na requisição enviada ao modelo; é um manifesto de ferramentas listando quais o modelo pode solicitar nesta conversa e quais parâmetros cada uma precisa. | Define tools — Claude API |
| stop_reason | Um campo na resposta do modelo explicando por que o modelo parou de falar desta vez — os valores incluem tool_use, end_turn e outros — e é apenas um sinal, não um registro de execução. | Tool use with Claude — Overview |
| tool_result | Um tipo de bloco de conteúdo na mensagem enviada de volta ao modelo; carrega o resultado finalizado de uma execução de ferramenta e corresponde ao seu bloco tool_use via tool_use_id. | Handle tool calls — Claude API |
| tool_use_id | Um campo em um bloco tool_result que precisa corresponder exatamente ao id do seu bloco tool_use correspondente; o modelo o usa para parear cada resultado com sua requisição. | Handle tool calls — Claude API |
| is_error | Um campo opcional em um bloco tool_result marcando se a própria execução desta ferramenta falhou; definido como true, diz ao modelo que esta chamada esbarrou em um problema. | Handle tool calls — Claude API |
| finish_reason | O nome do campo que corresponde a stop_reason nas APIs compatíveis com OpenAI; o valor tool_calls significa que o modelo está solicitando uma chamada de ferramenta. | Tool Use — LM Studio Docs (OpenAI-compatible API) |
| messages | O campo de array na requisição que carrega o histórico da conversa; a resposta de cada turno precisa ser anexada a ele literalmente, incluindo a resposta tool_use do modelo e o tool_result seguinte. | How tool use works — Claude API |
| end_turn | Um valor de stop_reason significando que o modelo terminou de falar neste turno, não precisa de mais chamadas de ferramenta, e seu conteúdo pode ser entregue ao usuário. | Tool use with Claude — Overview |
| bloco tool_use | O tipo de bloco de conteúdo no array content da resposta do modelo que representa uma requisição de chamada de ferramenta; é completo apenas quando carrega todos os três campos id, name e input. | Handle tool calls — Claude API |
| ida e volta | O ciclo completo de uma chamada de ferramenta: o modelo emite uma requisição, o host a executa, o resultado é enviado de volta e o modelo produz sua próxima resposta. | How tool use works — Claude API |
| laço | A forma do lado do host de lidar com chamadas de ferramenta de múltiplos turnos: enquanto stop_reason ainda for tool_use, continue executando ferramentas, enviando resultados de volta e solicitando novamente, até que vire end_turn. | How tool use works — Claude API |
| dependência de dados | Dentro de um lote de chamadas de ferramenta paralelas, quando o parâmetro de uma chamada deveria em teoria ser igual ao valor de retorno de outra chamada — um valor que ainda não existe no momento em que o lote é gerado. | Parallel tool use — Claude API |
| disable_parallel_tool_use | Uma configuração no objeto tool_choice da requisição; definida como true, o modelo chama no máximo uma ferramenta por resposta, usada para apertar o comportamento quando dependências de chamadas paralelas ainda não foram resolvidas. | Parallel tool use — Claude API |
| raio de impacto | O alcance de dano que uma chamada de ferramenta pode causar quando dá errado; é o critério central para classificar as cinco categorias de ferramenta. | Configure the sandboxed Bash tool - Claude Code Docs |
| read_file | O nome de exemplo do curso para a categoria de ferramenta de leitura; seu parâmetro típico é um caminho de arquivo, e retorna o conteúdo do arquivo. | Tools reference — Claude Code Docs |
| write_file | O nome de exemplo do curso para a categoria de ferramenta de escrita; seus parâmetros típicos são um caminho e conteúdo, e uma vez que roda, sobrescreve o arquivo original e geralmente não pode ser desfeito. | Tools reference — Claude Code Docs |
| bash | O nome de exemplo do curso para a categoria de ferramenta de execução; seu parâmetro é uma string de comando aberta que pode rodar qualquer comando de shell. | Configure the sandboxed Bash tool - Claude Code Docs |
| search_code | O nome de exemplo do curso para a categoria de ferramenta de busca; seus parâmetros típicos incluem pattern e max_results, e retorna uma lista de locais de correspondência em vez de conteúdos de arquivo inteiros. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| send_slack_message | O nome de exemplo do curso para a categoria de ferramenta de chamada de API externa; seus parâmetros típicos são um canal e texto, e chamá-la atravessa a rede até um serviço que você não controla. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| command | O campo de parâmetro central de uma ferramenta da categoria de execução (como bash); é essencialmente um script de shell aberto cuja capacidade não está delimitada pela estrutura do schema. | Configure the sandboxed Bash tool - Claude Code Docs |
| max_results | Um parâmetro comum em ferramentas da categoria de busca; limita quantas correspondências voltam em uma chamada, evitando uma sobrecarga de resultados que estoura o contexto. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| assimetria entre ferramentas de leitura e ferramentas de escrita | Ferramentas de leitura e escrita têm formas de chamada parecidas, mas uma leitura errada pode apenas ser lida de novo enquanto uma escrita errada frequentemente não pode ser desfeita — suas consequências de risco não são equivalentes. | Tools reference — Claude Code Docs |
| retry_after | Um campo que uma ferramenta de API externa pode retornar em falha, dizendo ao modelo quanto tempo esperar antes de tentar de novo — um exemplo concreto de 'informação de falha deveria carregar pistas acionáveis'. | Tools - Model Context Protocol |
| total_matches | Um campo no resultado retornado da ferramenta search_code dando o número total de acertos, deixando o modelo julgar se os resultados estão completos ou se a busca deveria ser estreitada. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| code_search_grep | O nome de ferramenta de busca reescrito no exemplo de comparação do curso; sua descrição declara claramente que busca por conteúdo e nomeia code_search_glob como a ferramenta para usar para encontrar arquivos por nome. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| code_search_glob | A ferramenta de busca de nome de arquivo pareada com code_search_grep; o curso a usa para mostrar que nomear a ferramenta alternativa em uma descrição reduz marcadamente as chances do modelo de escolher a ferramenta errada. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| enum | Uma palavra-chave do JSON Schema que estreita o valor de um parâmetro a uma de um conjunto listado de opções; é uma restrição real que rejeita entrada inválida, não apenas uma nota. | Creating your first schema - JSON Schema |
| additionalProperties: false | Uma configuração de input_schema de nível superior exigindo que o objeto de entrada carregue apenas chaves declaradas em properties, fechando a brecha onde o modelo inventa campos extras que escorregam para o código a jusante. | Strict tool use — Claude API |
| modo strict | Com strict: true definido em uma definição de ferramenta, a plataforma restringe a amostragem do modelo de modo que o input gerado corresponda estritamente ao input_schema, e parâmetros inválidos nunca são gerados em primeiro lugar. | Strict tool use — Claude API |
| namespacing | A prática de prefixar nomes de ferramenta com o serviço (como github_, slack_), de modo que conforme as ferramentas crescem o modelo pode primeiro descartar opções irrelevantes por prefixo. | How to implement tool use - Claude Platform Docs |
| github_list_prs | O exemplo do curso de um nome de ferramenta com namespace; o prefixo github_ marca a ferramenta como pertencente ao serviço GitHub, ajudando o modelo a distingui-la de operações de mesmo nome em outros serviços. | How to implement tool use - Claude Platform Docs |
| slack_send_message | Outro dos exemplos de nome de ferramenta com namespace do curso; o prefixo slack_ a marca como pertencente ao serviço Slack, distinguindo-a de outras ferramentas de envio de mensagem. | How to implement tool use - Claude Platform Docs |
| title | Um campo descritivo no JSON Schema usado para dar a um parâmetro um título legível; como description, apenas explica e não impõe nenhuma restrição de imposição. | Creating your first schema - JSON Schema |
| MCP | Um protocolo definindo como clientes e serviços de ferramenta interagem; o curso cita sua exigência explícita de que mensagens de erro sejam expostas ao modelo para que ele possa se autocorrigir. | Tools - Model Context Protocol |
| 55K tokens | Um número de exemplo da equipe de engenharia da Anthropic: as definições de 58 ferramentas podem ocupar aproximadamente 55 mil tokens de contexto, ilustrando o impacto real da contagem de ferramentas na sobrecarga de contexto. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| 134 mil tokens | Um exemplo mais extremo que o curso cita, mostrando que conforme a contagem de ferramentas continua crescendo, o contexto consumido apenas por definições de ferramenta pode inchar para uma escala muito significativa. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| file_type | Um campo de parâmetro de exemplo que o curso usa para mostrar que uma descrição não é uma restrição; com apenas uma descrição o modelo pode preenchê-lo arbitrariamente, e apenas enum de fato o estreita. | Creating your first schema - JSON Schema |
| granularidade | Quão finamente as responsabilidades de uma ferramenta são divididas; o curso enfatiza que granularidade não é nem melhor grossa nem melhor fina — divida por função primeiro, depois controle chances de escolha errada com namespacing e descrições. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| prompt injection | Um ataque onde instruções são escondidas em conteúdo que o agente vai eventualmente ler (uma issue, uma página web), então o agente confunde aquele texto com uma nova instrução que precisa obedecer. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| allow | Um dos três níveis de regra de permissão; aplica-se a operações somente leitura, sem efeitos colaterais, que podem ser repetidas sem deixar rastro, e é auto-aprovado sem confirmação humana. | Configure permissions - Claude Code Docs |
| ask | Um dos três níveis de regra de permissão; aplica-se a operações com efeitos colaterais que são reversíveis e cujo raio de impacto fica dentro do repositório local, e requer confirmação humana antes de rodar. | Configure permissions - Claude Code Docs |
| deny | Um dos três níveis de regra de permissão; aplica-se a operações irreversíveis ou cujo raio de impacto alcança além do local, recusando execução, e é avaliado antes de ask e allow. | Configure permissions - Claude Code Docs |
| Read(./.env) | Um exemplo concreto de regra de permissão do curso, pondo a operação de ler o arquivo .env diretamente na lista deny para manter conteúdos secretos fora do contexto da conversa. | Configure permissions - Claude Code Docs |
| Bash(git push:*) | Um exemplo de regra de permissão do curso; a forma Tool(especificador) mapeia diretamente para o nome de ferramenta exato e escopo de chamada que o host expõe ao modelo. | Configure permissions - Claude Code Docs |
| excessive agency | Categoria de risco da OWASP para uma ação danosa sendo acionada por uma saída de modelo inesperada, ambígua ou manipulada que nunca deveria ter acontecido. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| Funcionalidade excessiva | Uma causa-raiz de excessive agency: uma ferramenta única veste muitos chapéus (digamos, pode tanto ler a caixa de entrada quanto enviar e-mail), então uma chamada ruim tem seu raio de impacto ampliado. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| Permissões excessivas | Uma causa-raiz de excessive agency: a própria ferramenta faz uma coisa, mas o acesso que lhe é concedido vai além do que a tarefa de fato precisa. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| Autonomia excessiva | Uma causa-raiz de excessive agency: um agente roda muitos passos seguidos sem verificação humana no meio, então quando um problema é notado uma ação irreversível pode já ter rodado. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| lethal trifecta | A combinação de risco formada quando acesso a dados privados, exposição a conteúdo não confiável e capacidade de se comunicar externamente estão todos presentes de uma vez, dando à prompt injection um caminho para carregar dados para fora. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| human-in-the-loop | Uma das mitigações da OWASP para excessive agency: ações de alto impacto precisam ser aprovadas por um humano antes de serem tomadas. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| sandbox | Um mecanismo de isolamento em nível de SO que impõe isolamento de sistema de arquivos e de rede independentemente do julgamento do modelo, então o dano fica contido mesmo que prompt injection tenha sucesso. | Configure the sandboxed Bash tool - Claude Code Docs |
| TOOLS | O objeto único no exemplo do curso onde os campos de schema de cada ferramenta e seu handler de execução real vivem em uma tabela, impedindo que os dois lados se separem. | Define tools — Claude API |
| toolSchemas | A lista de parâmetro tools derivada da tabela TOOLS e enviada ao modelo; contém apenas name/description/input_schema, não o handler. | Define tools — Claude API |
| toolHandlers | A tabela de busca em tempo de execução derivada da tabela TOOLS, mapeando cada nome de ferramenta para a função que de fato a roda. | How tool use works — Claude API |
| github_repo_info | A terceira ferramenta de exemplo que o curso implementa; consulta informação básica sobre um repositório público do GitHub e é a única ferramenta que envia dados para fora do projeto. | How to implement tool use - Claude Platform Docs |
| SAFE_NAME | A expressão regular no código do curso usada para validar o formato dos parâmetros owner/repo, prevenindo que uma string arbitrária seja enviada à rede externa. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| MAX_TURNS | O limite de iterações definido no laço de execução do curso, prevenindo que o modelo solicite infinitamente chamadas de ferramenta de modo que o laço nunca termine. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| PROJECT_ROOT | A constante no código do curso para o diretório raiz do projeto; read_file e search_files ambos a usam para uma verificação de fronteira de caminho para prevenir acesso a arquivos fora do projeto. | Configure the sandboxed Bash tool - Claude Code Docs |
| recentCalls | O array no código do curso que registra as assinaturas das últimas poucas chamadas de ferramenta, usado para detectar o padrão de 'a mesma ferramenta com os mesmos argumentos chamada três vezes seguidas'. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| GITHUB_TOKEN | Uma credencial opcional lida de uma variável de ambiente, usada para aumentar o limite de taxa ao chamar a API do GitHub; a chamada também funciona anonimamente sem ela. | Configure permissions - Claude Code Docs |
| válvula de segurança | O termo coletivo do curso para o conjunto de proteções adicionadas ao laço de execução — MAX_TURNS, detecção de chamada repetida e as verificações internas de caminho e formato das ferramentas — cada uma parando um cenário de descontrole diferente. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| function walk(dir) | A função de percorrer diretório que o próprio código do curso implementa, usada dentro de searchFiles para listar arquivos recursivamente em vez de delegar para grep no shell. | Configure the sandboxed Bash tool - Claude Code Docs |
| JSON Schema | A especificação usada para definir o input_schema de uma ferramenta; seus title/description declaram intenção e não adicionam restrições, enquanto palavras-chave como enum e required de fato validam valores. | Creating your first schema - JSON Schema |
| amostragem restrita por gramática | A técnica por trás do modo strict: a plataforma restringe a amostragem de token do modelo a saídas válidas segundo o schema, então as entradas de ferramenta geradas sempre correspondem ao JSON Schema. | Strict tool use — Claude API |
| tool_choice | O objeto de requisição que controla como o modelo seleciona ferramentas; definir disable_parallel_tool_use: true nele (quando type é auto) faz o modelo chamar no máximo uma ferramenta por resposta. | Parallel tool use — Claude API |