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

Chamada de funções em tempo real

Aula 4 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Chamada de funções em tempo real
  2. Declaração de ferramentas na sessão
  3. Fluxo da chamada de função
  4. Implementação do manipulador de funções
  5. Integração no ciclo de eventos
  6. Pontos-chave

Atualização de 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts deixarão de funcionar a 6 de janeiro de 2027 (a substituição indicada é gpt-realtime-2.1-mini, que o guia TTS da OpenAI afirma não ser suportado por /v1/audio/speech: a migração da síntese de fala passa para a Realtime API); gpt-realtime, gpt-4o-realtime e modelos de áudio legados a 20 de janeiro de 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe e /v1/audio/translations a 26 de fevereiro de 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Para voz full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026.

Chamada de funções em tempo real

A chamada de funções na Realtime API permite que o seu agente de voz execute ações concretas durante uma conversa: consultar uma base de dados, fazer um pedido ou verificar um estado. A mecânica é semelhante à da Responses API, mas adaptada ao fluxo de eventos WebSocket.

Declaração de ferramentas na sessão

Declara as ferramentas em session.update, tal como faz com as instruções e a voz. Cada ferramenta é um esquema JSON que descreve os seus parâmetros:

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather for a given city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Name of the city"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit"
                }
            },
            "required": ["city"]
        }
    },
    {
        "type": "function",
        "name": "book_appointment",
        "description": "Book an appointment",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
                "time": {"type": "string", "description": "Time in HH:MM format"},
                "service": {"type": "string", "description": "Type of service"}
            },
            "required": ["date", "time", "service"]
        }
    }
]

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "output_modalities": ["audio"],
        "instructions": "You are a voice assistant. Use the available tools.",
        "audio": {"output": {"voice": "marin"}},
        "tools": tools,
        "tool_choice": "auto"
    }
}))

Fluxo da chamada de função

Quando o modelo decide chamar uma ferramenta, a sequência de eventos é a seguinte:

1

response.function_call_arguments.delta

Os argumentos da função chegam via streaming, bloco a bloco.

2

response.function_call_arguments.done

Os argumentos estão completos. Pode agora executar a função.

3

conversation.item.create (you)

Envia o resultado da função de volta ao modelo.

4

response.create (you)

Solicita ao modelo que continue a sua resposta com o resultado.

Implementação do manipulador de funções

Eis um exemplo completo de tratamento de chamadas de funções:

import json

# Registo de funções disponíveis
async def get_weather(city: str, unit: str = "celsius") -> dict:
    # Chamar uma API de meteorologia real
    return {"city": city, "temperature": 22, "unit": unit, "condition": "sunny"}

async def book_appointment(date: str, time: str, service: str) -> dict:
    # Lógica de marcação
    return {"confirmed": True, "date": date, "time": time, "reference": "RDV-2026-0042"}

FUNCTION_REGISTRY = {
    "get_weather": get_weather,
    "book_appointment": book_appointment,
}

async def handle_function_call(ws, event):
    """Processa uma chamada de função e devolve o resultado."""
    response = event["response"]

    for output in response.get("output", []):
        if output["type"] != "function_call":
            continue

        func_name = output["name"]
        call_id = output["call_id"]
        arguments = json.loads(output["arguments"])

        print(f"Calling function: {func_name}({arguments})")

        # Executar a função
        func = FUNCTION_REGISTRY.get(func_name)
        if func:
            result = await func(**arguments)
        else:
            result = {"error": f"Unknown function: {func_name}"}

        # Enviar o resultado de volta ao modelo
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {
                "type": "function_call_output",
                "call_id": call_id,
                "output": json.dumps(result)
            }
        }))

    # Pedir ao modelo para continuar com o resultado
    await ws.send(json.dumps({
        "type": "response.create"
    }))

Integração no ciclo de eventos

O manipulador de funções integra-se no seu ciclo principal:

async def event_loop(ws):
    """Ciclo principal de processamento de eventos."""
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "response.done":
            response = event["response"]
            # Verificar se o modelo chamou alguma função
            has_function_calls = any(
                o["type"] == "function_call"
                for o in response.get("output", [])
            )
            if has_function_calls:
                await handle_function_call(ws, event)

        elif event_type == "response.output_audio.delta":
            # Reproduzir áudio da resposta
            audio_bytes = base64.b64decode(event["delta"])
            player.write(audio_bytes)

        elif event_type == "error":
            print(f"Error: {event['error']['message']}")

Múltiplas chamadas de funções

O modelo pode decidir chamar várias funções numa única resposta. O campo output de response.done pode conter várias entradas do tipo function_call. Processe todas elas antes de chamar response.create.

Pontos-chave

  • As ferramentas são declaradas em session.update usando um esquema JSON padrão
  • Os argumentos chegam via streaming através de response.function_call_arguments.delta
  • Após a execução, envie o resultado de volta via conversation.item.create com o call_id
  • Chame response.create para que o modelo possa formular a sua resposta de voz com o resultado
  • Trate múltiplas chamadas: o modelo pode invocar várias funções simultaneamente