# Uso de ferramentas (chamada de função) com o Amazon Nova
**nota**
Esta documentação é para o Amazon Nova versão 1. Para obter informações sobre o uso de ferramentas com o Amazon Nova 2, acesse [Como usar ferramentas (chamada de função)](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html).
As ferramentas são uma forma de fornecer funcionalidade externa ao Amazon Nova, como uma chamada de API ou uma função de código. Esta seção abordará como você pode definir e integrar ferramentas ao trabalhar com modelos do Amazon Nova.
O uso de ferramentas envolve três etapas de alto nível:
+ **Consulta do usuário**: você define as ferramentas que o Amazon Nova pode usar fornecendo um esquema JSON que descreve a funcionalidade e os requisitos de entrada de cada ferramenta.
+ **Seleção de ferramentas**: quando um usuário envia uma mensagem, o Amazon Nova a analisa para determinar se uma ferramenta é necessária para gerar uma resposta. Isso é conhecido como escolha `Auto` de ferramentas. Consulte [Escolher uma ferramenta](https://docs.aws.amazon.com/nova/latest/userguide/tool-choice.html) para obter mais informações. Se o Amazon Nova identificar uma ferramenta adequada, ele “chamará a ferramenta” e retornará o nome da ferramenta e os parâmetros a serem usados.
Você, como desenvolvedor, é responsável por executar a ferramenta com base na solicitação do modelo. Isso significa que você precisa escrever o código que invoca a funcionalidade da ferramenta e processa os parâmetros de entrada fornecidos pelo modelo.
**nota**
Como todas as respostas de LLM, é possível que o Amazon Nova alucine uma chamada de ferramenta. É sua responsabilidade, do desenvolvedor, validar se a ferramenta existe, se as entradas estão formatadas corretamente e se as permissões apropriadas já estão em vigor.
+ **Retornar resultados**: depois de executar a ferramenta, você deve enviar os resultados de volta para o Amazon Nova em um formato estruturado. Os formatos válidos incluem JSON ou uma combinação de texto e imagens. Isso permite que o Amazon Nova incorpore a saída da ferramenta na resposta final ao usuário.
Se houver algum erro durante a execução da ferramenta, você poderá indicar isso na resposta da ferramenta ao Amazon Nova, permitindo que o Amazon Nova ajuste sua resposta adequadamente.
Considere um exemplo simples de uma ferramenta de calculadora:
------
#### [ User query ]
A primeira etapa no fluxo de trabalho de chamada da ferramenta é a consulta do usuário ao Amazon Nova para obter o resultado de uma equação matemática: 10 vezes 5. Essa consulta é enviada como um prompt para o Amazon Nova junto com uma especificação de ferramenta que representa a calculadora.
```
user_query = "10*5"
messages = [{
"role": "user",
"content": [{"text": user_query}]
}]
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator", # Name of the tool
"description": "A calculator tool that can execute a math equation", # Concise description of the tool
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": { # The name of the parameter
"type": "string", # parameter type: string/int/etc
"description": "The full equation to evaluate" # Helpful description of the parameter
}
},
"required": [ # List of all required parameters
"equation"
]
}
}
}
}
]
}
```
------
#### [ Tool selection ]
O Amazon Nova usa o contexto da ferramenta junto com o prompt do usuário para determinar a ferramenta necessária para uso e a configuração necessária. Isso é retornado como parte da resposta da API.
```
{
"toolUse": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"name": "calculator",
"input": {
"equation": "10*5"
}
}
}
```
A aplicação é responsável por executar a ferramenta e armazenar o resultado.
```
def calculator(equation: str):
return eval(equation)
tool_result = calculator("10*5")
```
------
#### [ Return results ]
Para retornar o resultado da ferramenta ao Amazon Nova, o resultado da ferramenta é incluído em uma nova solicitação de API. Observe que o ID de uso da ferramenta é consistente com o retornado pelo Amazon Nova na resposta anterior.
```
{
"toolResult": {
"toolUseId": "tooluse_u7XTryCSReawd9lXwljzHQ",
"content": [
{
"json": {
"result": "50"
}
}
],
"status": "success"
}
}
```
+ O Amazon Nova usará o contexto completo das mensagens, incluindo a consulta inicial do usuário, o uso da ferramenta e o resultado da ferramenta para determinar a resposta final para o usuário. Nesse caso, o Amazon Nova responderá ao usuário que “10 vezes 5 é 50”.
------
O Amazon Nova permite o uso de ferramentas nas APIs Invoke e Converse. No entanto, para uma ampla gama de recursos, recomendamos o uso da [API Converse](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use-inference-call.html) e usaremos exemplos com essa API conforme avançarmos.
**Topics**
+ [Definir uma ferramenta](tool-use-definition.md)
+ [Invocar uma ferramenta](tool-use-invocation.md)
+ [Escolher uma ferramenta](tool-choice.md)
+ [Retornar resultados da ferramenta](tool-use-results.md)
+ [Uso de ferramentas integradas](tool-built-in.md)
+ [Informar um erro](tool-use-error.md)
+ [Referências adicionais](#tool-use-resources)
## Referências adicionais
1. [Usar uma ferramenta para completar uma resposta](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)
1. [Criar agentes de IA com o Amazon Nova](agents.md)
1. [Práticas recomendadas para criação de prompts de compreensão de texto](prompting-text-understanding.md)
1. [Solucionar problemas de chamadas de ferramentas](prompting-tool-troubleshooting.md)