VoiceAgentDefinition interface

Pacote:

@azure/ai-projects

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

Extends

AgentDefinition

Propriedades

audio	A configuração do áudio, incluindo formatos de entrada e saída, voz, deteção de curvas, redução de ruído e transcrição. Estes valores são os valores padrão da sessão; um cliente pode sobrescrever campos suportados ao ligar-se.
avatar	Configuração opcional do avatar. Estes valores são os valores padrão da sessão e podem ser ultrapassados durante a ligação.
conversation_engine	O motor que controla a conversa para este agente de voz. Deve ser fornecida exatamente uma desta propriedade e a configuração apoiada pelo modelo (model_type com model). Quando esta propriedade é fornecida, , , , , e tool_choice devem ser omitidas, e greeting.tool_choice não podem ser required, porque o motor detém a lógica da conversa. toolsinstructionsmodelmodel_type A implementação inicial suporta um motor de agente hospedado.
greeting	Saudação opcional de início de sessão. O modo template fala texto renderizado exato; o modo gerado por LLM pede ao modelo de sessão que crie a resposta de abertura e pode usar ferramentas configuradas.
include	Campos adicionais a incluir 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	Definições de resposta intermédia para latência e execução da ferramenta.
kind	O tipo de discriminador para uma 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 usar para este agente. É necessário para model_type um agente de voz apoiado 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 este agente de voz é servido. É necessário para model um agente de voz apoiado por modelo e omitido quando conversation_engine é fornecido. Isto é 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. O valor padrão é ["audio"]. 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 este agente continuam. Um único interruptor de persistência, tudo ou nada, que por defeito é false (safe-safe: desligado por defeito). Quando true, o Foundry mantém toda a conversa — a transcrição/cronologia do evento e áudio bruto. Quando false, nada é mantido e nenhuma conversa surge. Não existe controlo separado de registo de áudio; o áudio é mantido apenas como parte desta mudança. A telemetria de latência/desempenho (por exemplo, tempo até ao primeiro áudio, latência entre tokens, interrupção) é apenas observável (rastreio do cliente / App Insights) e não faz parte do conteúdo da conversa persistente.
structured_inputs	Conjunto de entradas estruturadas que participam na 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 (controlos de sessão geridos por serviços) e toolbox. Ferramentas do lado do servidor como web_search, azure_ai_search, e openapi são fornecidas através de uma caixa de ferramentas em vez de declaradas diretamente.
tool_choice	Como o modelo escolhe ferramentas para respostas geradas. none previne chamadas de ferramenta, auto deixa o modelo decidir, required requer pelo menos uma chamada de ferramenta, e uma função específica ou ferramenta MCP pode ser selecionada com um objeto. O valor padrão é auto.

Propriedades Herdadas

rai_config

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

Detalhes de Propriedade

audio

A configuração do áudio, incluindo formatos de entrada e saída, voz, deteção de curvas, redução de ruído e transcrição. Estes valores são os valores padrão da sessão; um cliente pode sobrescrever campos suportados ao ligar-se.

audio?: VoiceAgentAudioConfig

Valor de Propriedade

VoiceAgentAudioConfig

avatar

Configuração opcional do avatar. Estes valores são os valores padrão da sessão e podem ser ultrapassados durante a ligação.

avatar?: VoiceAgentAvatarConfig

Valor de Propriedade

VoiceAgentAvatarConfig

conversation_engine

O motor que controla a conversa para este agente de voz. Deve ser fornecida exatamente uma desta propriedade e a configuração apoiada pelo modelo (model_type com model). Quando esta propriedade é fornecida, , , , , e tool_choice devem ser omitidas, e greeting.tool_choice não podem ser required, porque o motor detém a lógica da conversa. toolsinstructionsmodelmodel_type A implementação inicial suporta um motor de agente hospedado.

conversation_engine?: VoiceConversationEngineUnion

Valor de Propriedade

VoiceConversationEngineUnion

greeting

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

greeting?: VoiceAgentGreetingConfigUnion

Valor de Propriedade

VoiceAgentGreetingConfigUnion

include

Campos adicionais a incluir nas saídas do serviço.

include?: VoiceAgentSessionIncludeOption[]

Valor de 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 de Propriedade

string

interim_response

Definições de resposta intermédia para latência e execução da ferramenta.

interim_response?: VoiceAgentInterimResponseConfigUnion

Valor de Propriedade

VoiceAgentInterimResponseConfigUnion

kind

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

kind: "voice"

Valor de Propriedade

"voice"

max_output_tokens

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

max_output_tokens?: VoiceAgentMaxOutputTokens

Valor de Propriedade

VoiceAgentMaxOutputTokens

model

O modelo a usar para este agente. É necessário para model_type um agente de voz apoiado por modelo e omitido quando conversation_engine é fornecido. O modelo deve suportar voz em tempo real ou em cascata.

model?: string

Valor de Propriedade

string

model_type

Como o modelo que apoia este agente de voz é servido. É necessário para model um agente de voz apoiado por modelo e omitido quando conversation_engine é fornecido. Isto é independente da arquitetura (em tempo real ou em cascata), que o serviço deriva do modelo selecionado.

model_type?: VoiceModelType

Valor de Propriedade

VoiceModelType

output_modalities

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

output_modalities?: VoiceOutputModality[]

Valor de Propriedade

VoiceOutputModality[]

parallel_tool_calls

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

parallel_tool_calls?: boolean

Valor de Propriedade

boolean

store

Se as conversas com este agente continuam. Um único interruptor de persistência, tudo ou nada, que por defeito é false (safe-safe: desligado por defeito). Quando true, o Foundry mantém toda a conversa — a transcrição/cronologia do evento e áudio bruto. Quando false, nada é mantido e nenhuma conversa surge. Não existe controlo separado de registo de áudio; o áudio é mantido apenas como parte desta mudança. A telemetria de latência/desempenho (por exemplo, tempo até ao primeiro áudio, latência entre tokens, interrupção) é apenas observável (rastreio do cliente / App Insights) e não faz parte do conteúdo da conversa persistente.

store?: boolean

Valor de Propriedade

boolean

structured_inputs

Conjunto de entradas estruturadas que participam na 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 de 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 de 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 (controlos de sessão geridos por serviços) e toolbox. Ferramentas do lado do servidor como web_search, azure_ai_search, e openapi são fornecidas através de uma caixa de ferramentas em vez de declaradas diretamente.

tools?: VoiceAgentToolUnion[]

Valor de Propriedade

VoiceAgentToolUnion[]

tool_choice

Como o modelo escolhe ferramentas para respostas geradas. none previne chamadas de ferramenta, auto deixa o modelo decidir, required requer pelo menos uma chamada de ferramenta, e uma função específica ou ferramenta MCP pode ser selecionada com um objeto. O valor padrão é auto.

tool_choice?: VoiceAgentToolChoice

Valor de Propriedade

VoiceAgentToolChoice

Detalhes da Propriedade Herdada

rai_config

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

rai_config?: RaiConfig

Valor de Propriedade

RaiConfig

Herdado deAgentDefinition.rai_config