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

Ferramentas e chamada de funções em voz

Aula 5 de 14 Atualizada a 29 de julho de 2026 Intermediario
Nesta página
  1. Um agente que age, não apenas fala
  2. Os cinco tipos de ferramentas
  3. O ciclo completo de chamada de função
  4. Quando várias funções são acionadas simultaneamente
  5. Restrições específicas da voz
  6. Pontos-chave

Um agente que age, não apenas fala

Um assistente de voz limitado à conversa esbarra rapidamente num muro: responde educadamente a «Onde está a minha encomenda?» sem saber nada. O verdadeiro valor do Agente de Voz reside na sua capacidade de agir no meio de uma conversa (consultar uma base de dados, executar uma pesquisa na Web, chamar uma API empresarial, aceder a um servidor MCP) e ler o resultado como se nada tivesse acontecido.

Os cinco tipos de ferramentas

A pesquisa na Web, na sua forma mais simples, não requer parâmetros:

{ "type": "web_search" }

O agente pesquisa então na Web em tempo real, o que cobre questões factuais, notícias e quaisquer dados que mudam com demasiada frequência para estarem num prompt.

A pesquisa no X funciona da mesma forma, com a opção de a limitar a certas contas:

{
  "type": "x_search",
  "allowed_x_handles": ["corsen_ai"]
}

O parâmetro allowed_x_handles é opcional, mas altera a natureza da ferramenta. Sem ele, o agente pesquisa toda a plataforma; com ele, o agente torna-se num porta-voz que cita apenas as suas publicações oficiais.

A pesquisa de ficheiros consulta coleções de documentos vetorizados, como os seus manuais, procedimentos e documentação de produtos:

{
  "type": "file_search",
  "vector_store_ids": ["vs_abc123"],
  "max_num_results": 10
}

As funções personalizadas abrem a porta aos seus próprios sistemas. Este é o tipo de ferramenta que mais utilizará, pelo que vale a pena declará-la com cuidado:

{
  "type": "function",
  "name": "check_order",
  "description": "Checks the status of a customer order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_number": {
        "type": "string",
        "description": "The order number, in the format CMD-XXXX"
      }
    },
    "required": ["order_number"]
  }
}

Pode ligar um CRM, um ERP, um calendário ou uma base de dados interna da mesma forma. Por fim, os servidores MCP dão acesso a ferramentas normalizadas através do Model Context Protocol, para não ter de reescrever uma integração para cada serviço:

{
  "type": "mcp",
  "server_url": "https://mcp.example.com/sse",
  "server_label": "My MCP server"
}

O ciclo completo de chamada de função

Quando o agente decide chamar uma função, não a executa: pede-lhe que o faça, e a sua aplicação realiza o trabalho. Os argumentos chegam primeiro em fluxo contínuo através de response.function_call_arguments.delta. Em seguida, o evento response.function_call_arguments.done marca o fim do pedido e fornece o call_id juntamente com os argumentos completos. Cabe-lhe executar a função e devolver o resultado como um conversation.item.create do tipo function_call_output:

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\": \"shipped\", \"delivery_date\": \"2026-04-05\"}"
  }
}

Um último passo é essencial e é aquele que as pessoas esquecem: envie response.create para que o agente integre o resultado na sua resposta falada. Sem isso, o resultado chega à conversa, mas nada acontece. O utilizador ouve silêncio e você procura o erro no sítio errado.

Quando várias funções são acionadas simultaneamente

O modelo pode muito bem decidir chamar duas ou três funções de uma vez, por exemplo, para verificar uma encomenda e consultar o calendário de entregas. Recebe então vários eventos function_call_arguments.done, cada um com o seu próprio call_id. Execute-os todos, em paralelo se possível para que as latências não se somem, submeta cada resultado no seu próprio conversation.item.create e envie um único response.create no final. Um response.create por função desencadearia tantas respostas de voz concorrentes e o agente começaria a falar por cima de si mesmo.

// Receive and run all the functions
const results = await Promise.all(
  pendingCalls.map(call => executeFunction(call))
);

// Submit all the results
for (const result of results) {
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "function_call_output",
      call_id: result.callId,
      output: JSON.stringify(result.data)
    }
  }));
}

// Trigger the response
ws.send(JSON.stringify({ type: "response.create" }));

Restrições específicas da voz

O que passa despercebido numa interface de texto torna-se gritante na fala, começando pelo tempo. Ninguém espera mais de três a cinco segundos no meio de uma conversa. Além disso, os utilizadores pensam que a linha caiu e começam a falar. Se a sua função consultar um sistema lento, faça o agente dizer uma frase de espera durante a chamada em vez de deixar um silêncio morto.

O tamanho dos resultados importa tanto quanto o tempo. O agente tem de resumir em voz alta tudo o que lhe der, e uma lista de quarenta encomendas produzirá quer um recital interminável quer um resumo grosseiro. Devolva dados estruturados, mas limite-os ao essencial. Cuide também da descrição de cada função, pois é a única coisa em que o modelo se baseia para escolher: uma descrição vaga como «gerencia encomendas» fá-lo hesitar ou escolher a ferramenta errada. E preveja falhas. Quando uma função falha, devolva uma mensagem de erro explícita em output em vez de nada, caso contrário o agente improvisará uma resposta sem saber que a chamada falhou.

Pontos-chave

  • O Agente de Voz suporta cinco tipos de ferramentas: pesquisa na Web, pesquisa no X, pesquisa de ficheiros, funções e MCP
  • Uma chamada de função passa por quatro etapas: receber os argumentos, executar a função, devolver o resultado e acionar a resposta
  • Chamadas paralelas são possíveis: execute tudo, submeta tudo e envie depois um único response.create
  • Em voz, o tempo de resposta da função é crítico: aponte para menos de 3 segundos