# 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: ![Fluxo de conversa que demonstra a configuração do cliente, o tratamento de eventos de uso de ferramentas com Amazon Bedrock Agents e Nova S2S, e as etapas de geração da transcrição.](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. + Sempre responda às chamadas de ferramentas: o Nova 2 Sonic espera um evento toolResult após cada evento toolUse enviado. Se a aplicação não responder, mesmo quando ocorrer um erro, o modelo entrará em um estado de espera, causando um comportamento sem resposta ou uma saída inesperada. Sempre envie um evento toolResult em resposta, mesmo que ele contenha uma mensagem de erro ou sinalize que a sessão está terminando. + 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).