# Configuração de ferramentas O Amazon Nova 2 Sonic é compatível com o uso de ferramentas (também conhecidas como chamada de função), permitindo que o modelo solicite informações ou ações externas durante conversas, como chamadas de API, consultas a banco de dados ou funções de código personalizadas. Isso permite que seu assistente de voz execute ações, recupere informações e se integre a serviços externos com base nas solicitações do usuário. O Nova 2 Sonic apresenta chamada assíncrona de ferramentas, permitindo que a IA continue conversando naturalmente enquanto as ferramentas são executadas em segundo plano, criando uma experiência de usuário mais fluida e responsiva. Confira abaixo as etapas simplificadas de como usar as ferramentas: 1. Definir ferramentas: especifique as ferramentas disponíveis com seus parâmetros no evento promptStart 1. O usuário fala: o usuário faz uma solicitação que requer uma ferramenta (como “Como está o tempo em Seattle?”) 1. Invocação da ferramenta: o Nova 2 Sonic reconhece a necessidade e envia um evento toolUse 1. Ferramenta de execução: sua aplicação executa a ferramenta e retorna os resultados 1. Geração de resposta: o Nova 2 Sonic incorpora os resultados em sua resposta falada O seguinte diagrama ilustra como a ferramenta funciona: ![](http://docs.aws.amazon.com/pt_br/nova/latest/nova2-userguide/images/How-tool-use-works_5.png) ## Definição de ferramentas As ferramentas são definidas usando um esquema JSON que descreve sua finalidade, parâmetros e entradas esperadas. Confira os componentes e as explicações da definição de ferramentas: + Nome: um identificador único para a ferramenta (use snake\_case) + Descrição: explicação clara do que a ferramenta faz; ajuda a IA a decidir quando usá-la + InputSchema: um esquema JSON que define os parâmetros que a ferramenta aceita + Propriedades: parâmetros individuais com tipos e descrições + Obrigatório: matriz de nomes de parâmetros que devem ser fornecidos ### Exemplo de definição de ferramentas Confira uma definição simples de ferramenta de clima ``` { "toolSpec": { "name": "get_weather", "description": "Get current weather information for a specific location", "inputSchema": { "json": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or zip code" }, "units": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature units" } }, "required": ["location"] } } } } ``` ### Configuração de ferramentas no PromptStart A configuração da ferramenta é passada para o Nova 2 Sonic no evento `promptStart`, juntamente com as configurações de saída de áudio e texto: ``` { "event": { "promptStart": { "promptName": "", "textOutputConfiguration": { "mediaType": "text/plain" }, "audioOutputConfiguration": { "mediaType": "audio/lpcm", "sampleRateHertz": 16000, "sampleSizeBits": 16, "channelCount": 1, "voiceId": "matthew", "encoding": "base64", "audioType": "SPEECH" }, "toolUseOutputConfiguration": { "mediaType": "application/json" }, "toolConfiguration": { "tools": [ { "toolSpec": { "name": "get_weather", "description": "Get current weather information for a specific location", "inputSchema": { "json": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or zip code" }, "units": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "Temperature units" } }, "required": ["location"] } } } } ], "toolChoice": { "auto": {} } } } } } ``` ## Parâmetros de escolha de ferramentas O Nova 2 Sonic é compatível com três parâmetros de escolha de ferramentas para controlar quando e quais ferramentas são usadas. Especifique o parâmetro toolChoice na configuração da ferramenta: + Auto (padrão): o modelo decide se alguma ferramenta é necessária e pode chamar várias ferramentas, se necessário. Oferece a máxima flexibilidade. + Any: garante que pelo menos uma das ferramentas disponíveis seja chamada no início da geração da resposta, permitindo que o modelo selecione a mais adequada. Útil quando você tem várias bases de conhecimentos ou ferramentas e deseja garantir que uma seja usada. + Tool: força uma ferramenta específica designada a ser chamada exatamente uma vez no início da resposta. Por exemplo, se você especificar uma ferramenta de base de conhecimentos, o modelo a consultará antes de responder, independentemente de achar que a ferramenta é necessária. **Exemplos de escolha de ferramentas** Auto (padrão) ``` "toolChoice": {     "auto": {} } ``` Qualquer uma: ``` "toolChoice": { "any": {} } ``` Ferramenta específica: ``` "toolChoice": { "tool": { "name": "get_weather" } } ``` ## Eventos de uso da ferramenta de recebimento e processamento Quando o Amazon Nova 2 Sonic determina que uma ferramenta é necessária, ele envia um evento `toolUse` contendo: 1. `toolUseID`: identificador único para esta invocação de ferramenta 1. ToolName: o nome da ferramenta a ser executada 1. Content: string JSON contendo parâmetros extraídos da solicitação do usuário 1. SessionID: identificador da sessão atual 1. Role: definido como “TOOL” para eventos de uso de ferramenta Exemplo de evento de uso de ferramenta ``` { "event": { "toolUse": { "completionId": "", "content": "{\"location\": \"Seattle\", \"units\": \"fahrenheit\"}", "contentId": "", "promptName": "", "role": "TOOL", "sessionId": "", "toolName": "get_weather", "toolUseId": "" } } } ``` Processamento de etapas 1. Receber o evento toolUse do Nova 2 Sonic 1. Extrair o nome da ferramenta e os parâmetros do evento 1. Executar a lógica da sua ferramenta (chamada de API, consulta ao banco de dados etc.) 1. Retornar o resultado usando um evento toolResult Exemplo de evento ToolResult ``` { "event": { "toolResult": { "promptName": "", "contentName": "", "content": "{\"temperature\": 72, \"condition\": \"sunny\", \"humidity\": 45}" } } } ``` ## Práticas recomendadas + Descrições claras: escreva descrições detalhadas das ferramentas para ajudar o Nova 2 Sonic a entender quando usar cada ferramenta. + Validar parâmetros: sempre valide os parâmetros da ferramenta antes da execução para evitar erros. Defina os parâmetros da ferramenta usando o esquema JSON adequado com tipos de dados estruturados (como enumerações, números ou booleanos) em vez de strings abertas, sempre que possível. + Tratamento de erros: retorne mensagens de erro significativas em eventos toolResult quando as ferramentas falharem. + Execução assíncrona: aproveite a chamada assíncrona de ferramentas para manter o fluxo da conversa. + Nomenclatura de ferramentas: use nomes descritivos e orientados à ação (como get\_weather, search\_database, send\_email).