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:
-
Definir ferramentas: especifique as ferramentas disponíveis com seus parâmetros no evento promptStart
-
O usuário fala: o usuário faz uma solicitação que requer uma ferramenta (como “Como está o tempo em Seattle?”)
-
Invocação da ferramenta: o Nova 2 Sonic reconhece a necessidade e envia um evento toolUse
-
Ferramenta de execução: sua aplicação executa a ferramenta e retorna os resultados
-
Geração de resposta: o Nova 2 Sonic incorpora os resultados em sua resposta falada
O seguinte diagrama ilustra como a ferramenta funciona:
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
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"] } } } }
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": "<prompt-id>", "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:
-
toolUseID: identificador único para esta invocação de ferramenta -
ToolName: o nome da ferramenta a ser executada
-
Content: string JSON contendo parâmetros extraídos da solicitação do usuário
-
SessionID: identificador da sessão atual
-
Role: definido como “TOOL” para eventos de uso de ferramenta
Exemplo de evento de uso de ferramenta
{ "event": { "toolUse": { "completionId": "<completion-id>", "content": "{\"location\": \"Seattle\", \"units\": \"fahrenheit\"}", "contentId": "<content-id>", "promptName": "<prompt-id>", "role": "TOOL", "sessionId": "<session-id>", "toolName": "get_weather", "toolUseId": "<tool-use-id>" } } }
Processamento de etapas
-
Receber o evento toolUse do Nova 2 Sonic
-
Extrair o nome da ferramenta e os parâmetros do evento
-
Executar a lógica da sua ferramenta (chamada de API, consulta ao banco de dados etc.)
-
Retornar o resultado usando um evento toolResult
Exemplo de evento ToolResult
{ "event": { "toolResult": { "promptName": "<prompt-id>", "contentName": "<content-id>", "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).
