Este tópico descreve o fluxo de interação multimodal em tempo real entre o servidor e o cliente.
Endpoints de conexão
Modelos compatíveis: qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime e qwen3.5-omni-flash-realtime.
- China (Pequim)
- Singapura
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime{WorkspaceId} pelo ID do workspace da região e model pelo nome do modelo a chamar. Para autenticação e preparação antes da conexão, consulte Acesso por WebSocket.
Fluxo de conexão
Modo VAD
Para ativar o modo VAD, defina o parâmetro session.turn_detection do evento do cliente como "server_vad". Nesse modo, o servidor executa a Detecção de Atividade de Voz (VAD) no áudio recebido e responde ao identificar fala. Esta é a configuração padrão, ideal para cenários em que o cliente envia áudio continuamente ao servidor.
- O servidor envia o evento
input_audio_buffer.speech_startedao detectar o início da fala. - O cliente pode adicionar áudio ao buffer a qualquer momento enviando um evento
input_audio_buffer.append. - O servidor envia o evento
input_audio_buffer.speech_stoppedao detectar o fim da fala. - O servidor confirma o buffer de áudio de entrada enviando um evento
input_audio_buffer.committed. - O servidor envia um evento
conversation.item.createdcontendo o item de mensagem do usuário criado a partir do buffer de áudio.
Fluxo de chamada de ferramenta
No modo VAD, quando uma resposta gerada pelo servidor exige uma chamada de ferramenta, ocorre o seguinte fluxo de interação:
- Após detectar o fim da fala e gerar uma resposta, o servidor determina que uma chamada de ferramenta é necessária.
- O servidor envia um evento
response.function_call_arguments.deltacom dados incrementais dos argumentos da chamada de ferramenta. - O servidor envia um evento
response.function_call_arguments.donepara indicar que todos os argumentos da chamada de ferramenta foram enviados. - O cliente executa a chamada de ferramenta e obtém o resultado.
- O cliente envia um evento
conversation.item.createcontendo o resultado da chamada de ferramenta. - O servidor gera automaticamente uma resposta com base no resultado da chamada de ferramenta.
Modo Manual
Para ativar o modo Manual, defina o parâmetro session.turn_detection do evento do cliente como null. Nessa configuração, o cliente solicita uma resposta do servidor enviando explicitamente os eventos input_audio_buffer.commit e response.create. Esse modo é adequado para cenários de "pressionar para falar", como o envio de mensagens de voz em aplicativos de chat.
- O cliente pode adicionar áudio ao buffer enviando um evento
input_audio_buffer.append. - O cliente confirma o buffer de áudio de entrada enviando um evento
input_audio_buffer.commit. Essa confirmação cria um novo item de mensagem do usuário na conversa. - O servidor responde enviando um evento
input_audio_buffer.committed. - O cliente envia um evento
response.createpara acionar o modelo e gerar a resposta final. - O servidor responde enviando um evento
conversation.item.created.
Fluxo de chamada de ferramenta
- Após o cliente enviar um evento
response.create, o servidor gera uma resposta e detecta a necessidade de uma chamada de ferramenta. - O servidor envia um evento
response.function_call_arguments.deltacontendo dados incrementais dos argumentos da chamada de ferramenta. - O servidor envia um evento
response.function_call_arguments.donepara sinalizar que a transferência dos argumentos da chamada de ferramenta foi concluída. - O cliente executa a chamada de ferramenta e obtém o resultado.
- O cliente envia o resultado da chamada de ferramenta utilizando um evento
conversation.item.create. - O cliente envia um evento
response.createpara acionar o modelo e gerar a resposta final. - O servidor gera uma resposta baseada no resultado da chamada de ferramenta e a envia ao cliente por meio de eventos
response.audio.deltaouresponse.text.delta.
Chamadas de ferramentas MCP
Este fluxo se aplica ao Qwen3.8-Omni-Flash-Realtime nos modos VAD e Manual.
Function Calling e MCP podem ser configurados juntos em session.tools. Não podem ser usados com a busca na Web (enable_search). O Model Studio não cobra uma taxa adicional pelas chamadas de ferramentas MCP. A inferência do modelo continua sujeita aos preços do modelo.
Descoberta de ferramentas
Após o cliente configurar servidores MCP com session.update, o serviço Realtime descobre suas ferramentas de forma assíncrona:

opt indica execução quando uma condição é atendida; alt indica ramificações alternativas escolhidas por condição; par indica processamento paralelo.
- Envie
session.updatecom entradas MCP emsession.tools. - Trate
mcp_list_tools.in_progress, que pode chegar antes desession.updated.session.updatedconfirma a aceitação da configuração, não a disponibilidade das ferramentas. - O serviço descobre as ferramentas. Ele envia
conversation.item.createdcom um itemmcp_list_tools, seguido demcp_list_tools.completedoumcp_list_tools.failedcom o mesmoitem_id. O item contém as ferramentas filtradas finais ou um erro.
response.create podem continuar durante a descoberta, mas apenas Responses criadas após a conclusão da descoberta podem usar as ferramentas correspondentes.
Chamadas MCP e continuação
Quando o modelo seleciona uma ferramenta MCP, o serviço Realtime executa a chamada. Se for necessária aprovação, o cliente deve primeiro responder à solicitação de aprovação:

- O servidor cria um item
mcp_callporresponse.output_item.added. - Concatene zero ou mais fragmentos
response.mcp_call_arguments.delta. Considere a string JSON completa emresponse.mcp_call_arguments.donecomo referência definitiva. - Quando houver necessidade de aprovação, trate
conversation.item.createdcomitem.type="mcp_approval_request". Decida se a chamada será permitida e responda comconversation.item.create,item.type="mcp_approval_response", oitem.idexato da aprovação e o booleanoapprove. A aprovação é obrigatória por padrão. - Chamadas aprovadas ou configuradas para dispensar aprovação emitem
response.mcp_call.in_progress. O serviço executa a chamada MCP e emiteresponse.mcp_call.completedouresponse.mcp_call.failed. A rejeição ou o fim do tempo limite de aprovação emitefailedsem executar a chamada. - Processe
response.output_item.donepara obter o item final da chamada. Oresponse.doneda Response que contém a chamada chega após todos os itens MCP dessa Response atingirem um estado terminal. Seuresponse.outputinclui os estados finais: chamadas bem-sucedidas têmcompletedeoutput; chamadas que falham têmfailedeerror. - Para gerar uma resposta do modelo a partir dos resultados MCP, envie um único
response.createapós oresponse.doneda Response que contém a chamada. Não inclua resultados MCP: eles já estão na conversa. Não use o fluxo manual de retornofunction_call_outputpara essas chamadas MCP executadas pelo servidor.
Limites de uso
As seguintes restrições MCP padrão se aplicam a cada sessão:
| Item | Valor padrão |
|---|---|
| Servidores MCP | 8 |
| Ferramentas MCP | 128 |
| Tempo limite de descoberta de ferramentas | 30 segundos |
| Tempo limite de aprovação | 60 segundos |
| Tempo limite de execução de ferramentas | 30 segundos |
| Tamanho de uma resposta de saída | 2 MB |
| Tamanho acumulado dos resultados das ferramentas | 8 MB |
| Número acumulado de chamadas de ferramentas | 256 |