VoiceAgentDefinition interface

Pacote:

@azure/ai-projects

A definição de agente de voz. Sua configuração (modelo, instruções, áudio, ferramentas e avatar opcional) impulsiona uma experiência gerenciada de fala para fala. Estabeleça sessões de voz em tempo real através GET /agents/{agent_name}/endpoint/protocols/voicede . Cada criação ou atualização gera uma nova versão imutável.

Extends

AgentDefinition

Propriedades

audio	A configuração do áudio, incluindo formatos de entrada e saída, voz, detecção de giro, redução de ruído e transcrição. Esses valores são os padrões da sessão; um cliente pode sobrescrever campos suportados ao conectar.
avatar	Configuração opcional do avatar. Esses valores são os padrões da sessão e podem ser sobrescritos ao conectar.
conversation_engine	O motor responsável pelo gerenciamento de conversas para esse agente de voz. Exatamente uma dessa propriedade e a configuração suportada pelo modelo (model_type com model) devem ser fornecidas. Quando essa propriedade é fornecida, , , , , e tool_choice devem ser omitidas, e greeting.tool_choice não podem ser required, porque a engine é dona da lógica de conversa. toolsinstructionsmodelmodel_type A implementação inicial suporta um motor de agente hospedado.
greeting	Saudação opcional para início de sessão. O modo template fala texto renderizado exato; o modo gerado por LLM pede ao modelo de sessão que autorize a resposta de abertura e pode usar ferramentas configuradas.
include	Campos adicionais a serem incluídos nas saídas do serviço.
instructions	Uma mensagem do sistema (ou desenvolvedor) inserida no contexto do modelo. Suporta substituição de templates via structured_inputs, renderizado por sessão antes do início da sessão ao vivo.
interim_response	Configurações de resposta intermediária para latência e execução de ferramentas.
kind	O tipo de discriminador para a definição de agente de voz. Sempre voice.
max_output_tokens	A contagem máxima de tokens de saída para uma resposta.
model	O modelo a ser usado para esse agente. Exigido com model_type para um agente de voz respaldado por modelo e omitido quando conversation_engine fornecido. O modelo deve suportar voz em tempo real ou em cascata.
model_type	Como o modelo que apoia esse agente de voz é servido. Exigido com model para um agente de voz respaldado por modelo e omitido quando conversation_engine fornecido. Isso é independente da arquitetura (em tempo real ou em cascata), que o serviço deriva do modelo selecionado.
output_modalities	As modalidades de saída que o agente produz. Usa ["audio"] como padrão. animation e avatar estão disponíveis quando um avatar é configurado.
parallel_tool_calls	Se o modelo pode chamar múltiplas ferramentas em paralelo.
store	Se as conversas com esse agente continuam a ser mantidas. Um único interruptor de persistência tudo ou nada que por padrão é false (seguro para privacidade: desligado por padrão). Quando true, o Foundry mantém toda a conversa — a transcrição/linha do tempo do evento e o áudio bruto. Quando false, nada é persistido e nenhuma conversa surge. Não há controle separado de registro de áudio; o áudio é mantido apenas como parte dessa troca. Telemetria de latência/desempenho (por exemplo, tempo até o primeiro áudio, latência entre tokens, interrupção) é apenas observabilidade (rastreamento do cliente / App Insights) e não faz parte do conteúdo persistente da conversa.
structured_inputs	Conjunto de entradas estruturadas que participam da substituição de templates de prompt, renderizadas por sessão antes do início da sessão ao vivo.
subagent_config	Configuração opcional para agentes de texto irmãos da Foundry que este agente de voz pode consultar como especialistas em segundo plano.
tools	As ferramentas que o agente de voz pode usar. Os tipos de ferramentas suportados são function (executados pelo cliente), mcp, system (controles de sessão gerenciados por serviços) e toolbox. Ferramentas do lado do servidor como web_search, azure_ai_search, e openapi são fornecidas por meio de uma caixa de ferramentas, em vez de declaradas diretamente.
tool_choice	Como o modelo escolhe ferramentas para respostas geradas. none impede chamadas de ferramenta, auto permite que o modelo decida, required requer pelo menos uma chamada de ferramenta, e uma função específica ou ferramenta MCP pode ser selecionada com um objeto. Usa auto como padrão.

Propriedades herdadas

rai_config

Configuração para filtragem de conteúdo e recursos de segurança de IA Responsável (RAI).

Detalhes da propriedade

audio

A configuração do áudio, incluindo formatos de entrada e saída, voz, detecção de giro, redução de ruído e transcrição. Esses valores são os padrões da sessão; um cliente pode sobrescrever campos suportados ao conectar.

audio?: VoiceAgentAudioConfig

Valor da propriedade

VoiceAgentAudioConfig

avatar

Configuração opcional do avatar. Esses valores são os padrões da sessão e podem ser sobrescritos ao conectar.

avatar?: VoiceAgentAvatarConfig

Valor da propriedade

VoiceAgentAvatarConfig

conversation_engine

O motor responsável pelo gerenciamento de conversas para esse agente de voz. Exatamente uma dessa propriedade e a configuração suportada pelo modelo (model_type com model) devem ser fornecidas. Quando essa propriedade é fornecida, , , , , e tool_choice devem ser omitidas, e greeting.tool_choice não podem ser required, porque a engine é dona da lógica de conversa. toolsinstructionsmodelmodel_type A implementação inicial suporta um motor de agente hospedado.

conversation_engine?: VoiceConversationEngineUnion

Valor da propriedade

VoiceConversationEngineUnion

greeting

Saudação opcional para início de sessão. O modo template fala texto renderizado exato; o modo gerado por LLM pede ao modelo de sessão que autorize a resposta de abertura e pode usar ferramentas configuradas.

greeting?: VoiceAgentGreetingConfigUnion

Valor da propriedade

VoiceAgentGreetingConfigUnion

include

Campos adicionais a serem incluídos nas saídas do serviço.

include?: VoiceAgentSessionIncludeOption[]

Valor da propriedade

VoiceAgentSessionIncludeOption[]

instructions

Uma mensagem do sistema (ou desenvolvedor) inserida no contexto do modelo. Suporta substituição de templates via structured_inputs, renderizado por sessão antes do início da sessão ao vivo.

instructions?: string

Valor da propriedade

string

interim_response

Configurações de resposta intermediária para latência e execução de ferramentas.

interim_response?: VoiceAgentInterimResponseConfigUnion

Valor da propriedade

VoiceAgentInterimResponseConfigUnion

kind

O tipo de discriminador para a definição de agente de voz. Sempre voice.

kind: "voice"

Valor da propriedade

"voice"

max_output_tokens

A contagem máxima de tokens de saída para uma resposta.

max_output_tokens?: VoiceAgentMaxOutputTokens

Valor da propriedade

VoiceAgentMaxOutputTokens

model

O modelo a ser usado para esse agente. Exigido com model_type para um agente de voz respaldado por modelo e omitido quando conversation_engine fornecido. O modelo deve suportar voz em tempo real ou em cascata.

model?: string

Valor da propriedade

string

model_type

Como o modelo que apoia esse agente de voz é servido. Exigido com model para um agente de voz respaldado por modelo e omitido quando conversation_engine fornecido. Isso é independente da arquitetura (em tempo real ou em cascata), que o serviço deriva do modelo selecionado.

model_type?: VoiceModelType

Valor da propriedade

VoiceModelType

output_modalities

As modalidades de saída que o agente produz. Usa ["audio"] como padrão. animation e avatar estão disponíveis quando um avatar é configurado.

output_modalities?: VoiceOutputModality[]

Valor da propriedade

VoiceOutputModality[]

parallel_tool_calls

Se o modelo pode chamar múltiplas ferramentas em paralelo.

parallel_tool_calls?: boolean

Valor da propriedade

boolean

store

Se as conversas com esse agente continuam a ser mantidas. Um único interruptor de persistência tudo ou nada que por padrão é false (seguro para privacidade: desligado por padrão). Quando true, o Foundry mantém toda a conversa — a transcrição/linha do tempo do evento e o áudio bruto. Quando false, nada é persistido e nenhuma conversa surge. Não há controle separado de registro de áudio; o áudio é mantido apenas como parte dessa troca. Telemetria de latência/desempenho (por exemplo, tempo até o primeiro áudio, latência entre tokens, interrupção) é apenas observabilidade (rastreamento do cliente / App Insights) e não faz parte do conteúdo persistente da conversa.

store?: boolean

Valor da propriedade

boolean

structured_inputs

Conjunto de entradas estruturadas que participam da substituição de templates de prompt, renderizadas por sessão antes do início da sessão ao vivo.

structured_inputs?: Record<string, StructuredInputDefinition>

Valor da propriedade

Record<string, StructuredInputDefinition>

subagent_config

Configuração opcional para agentes de texto irmãos da Foundry que este agente de voz pode consultar como especialistas em segundo plano.

subagent_config?: VoiceAgentSubagentConfig

Valor da propriedade

VoiceAgentSubagentConfig

tools

As ferramentas que o agente de voz pode usar. Os tipos de ferramentas suportados são function (executados pelo cliente), mcp, system (controles de sessão gerenciados por serviços) e toolbox. Ferramentas do lado do servidor como web_search, azure_ai_search, e openapi são fornecidas por meio de uma caixa de ferramentas, em vez de declaradas diretamente.

tools?: VoiceAgentToolUnion[]

Valor da propriedade

VoiceAgentToolUnion[]

tool_choice

Como o modelo escolhe ferramentas para respostas geradas. none impede chamadas de ferramenta, auto permite que o modelo decida, required requer pelo menos uma chamada de ferramenta, e uma função específica ou ferramenta MCP pode ser selecionada com um objeto. Usa auto como padrão.

tool_choice?: VoiceAgentToolChoice

Valor da propriedade

VoiceAgentToolChoice

Detalhes das propriedades herdadas

rai_config

Configuração para filtragem de conteúdo e recursos de segurança de IA Responsável (RAI).

rai_config?: RaiConfig

Valor da propriedade

RaiConfig

Herdado deAgentDefinition.rai_config