Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Chamada de funções por voz

Aula 13 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Executar funções numa conversa por voz
  2. Declarar uma função
  3. Receber e gerir uma chamada de função
  4. Chamadas de funções em paralelo
  5. Boas práticas
  6. Pontos-chave

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.

1

O agente identifica a necessidade

O utilizador diz algo que exige uma chamada de função. O agente gera os argumentos.

2

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.

3

Envia o resultado de volta

Envie `conversation.item.create` com o tipo `function_call_output` e o `call_id`.

4

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 é:

  1. Resolver todas as funções antes de responder
  2. Submeter todos os resultados, com um conversation.item.create por resultado
  3. Enviar um único response.create no 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.update com um esquema JSON para os seus parâmetros.
  • O resultado deve ser enviado de volta através de conversation.item.create com type: "function_call_output".
  • Envie sempre response.create após submeter os resultados.
  • Para chamadas em paralelo, aguarde por todos os resultados antes de enviar um único response.create.