Chamada de funções por voz
Nesta página
Executar funções numa conversa por voz
A chamada de funções por voz permite que o seu agente desencadeie ações reais durante uma conversa: consultar uma base de dados, efetuar uma encomenda, enviar um e-mail ou chamar uma API externa. O agente decide quando chamar uma função com base no que o utilizador diz.
O agente identifica a necessidade
O utilizador diz algo que exige uma chamada de função. O agente gera os argumentos.
A sua aplicação executa a função
Recebe os argumentos através do evento `function_call_arguments.done` e executa a sua lógica de negócio.
Envia o resultado de volta
Envie `conversation.item.create` com o tipo `function_call_output` e o `call_id`.
O agente continua a conversa
Envie `response.create` para que o agente integre o resultado na sua resposta falada.
Declarar uma função
Declara as funções no array tools de session.update:
{
"type": "session.update",
"session": {
"tools": [
{
"type": "function",
"name": "get_balance",
"description": "Gets the balance of a customer's bank account",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Customer ID"
}
},
"required": ["client_id"]
}
}
]
}
}
Receber e gerir uma chamada de função
Quando o agente decide chamar uma função, recebe os argumentos sob a forma de fluxo (stream) e, de seguida, todos de uma vez:
let functionArgs = "";
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "response.function_call_arguments.delta":
functionArgs += event.delta;
break;
case "response.function_call_arguments.done":
const args = JSON.parse(event.arguments);
const callId = event.call_id;
const functionName = event.name;
// Executar a função
handleFunctionCall(functionName, args, callId);
break;
}
});
async function handleFunctionCall(name, args, callId) {
let result;
switch (name) {
case "get_balance":
result = await getBalance(args.client_id);
break;
default:
result = { error: "Unknown function" };
}
// Enviar o resultado de volta
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Pedir ao agente para continuar
ws.send(JSON.stringify({
type: "response.create"
}));
}
Chamadas de funções em paralelo
O agente pode decidir chamar várias funções simultaneamente. Nesse caso, recebe vários eventos function_call_arguments.done. A regra é:
- Resolver todas as funções antes de responder
- Submeter todos os resultados, com um
conversation.item.createpor resultado - Enviar um único
response.createno final
const pendingCalls = new Map();
let expectedCalls = 0;
case "response.function_call_arguments.done":
const result = await executeFunction(event.name, event.arguments);
pendingCalls.set(event.call_id, result);
if (pendingCalls.size === expectedCalls) {
// Todas as funções foram resolvidas
for (const [callId, output] of pendingCalls) {
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(output)
}
}));
}
// Um único response.create para todas as saídas
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Boas práticas
- Descrições claras: a qualidade das descrições das suas funções determina quando o agente as utiliza.
- Execução rápida: uma função que demore mais de 2 ou 3 segundos cria um silêncio constrangedor.
- Gestão de erros: devolva uma mensagem de erro legível em vez de uma exceção técnica.
- Confirmação falada: para ações sensíveis (pagamentos, eliminações), peça ao utilizador que confirme antes de as executar.
Pontos-chave
- A chamada de funções por voz segue um ciclo de quatro etapas: deteção, execução, devolução do resultado e continuação.
- Declara as funções em
session.updatecom um esquema JSON para os seus parâmetros. - O resultado deve ser enviado de volta através de
conversation.item.createcomtype: "function_call_output". - Envie sempre
response.createapós submeter os resultados. - Para chamadas em paralelo, aguarde por todos os resultados antes de enviar um único
response.create.