VoiceAgentDefinition Class

Definition

Namespace:

Azure.AI.Projects.Agents

Assembly:

Azure.AI.Projects.Agents.dll

Package:

Azure.AI.Projects.Agents v3.0.0-beta.3

Source:

VoiceAgentDefinition.cs

The voice agent definition. Its configuration (model, instructions, audio, tools, and optional avatar) drives a managed speech-to-speech experience. Establish realtime voice sessions through GET /agents/{agent_name}/endpoint/protocols/voice. Every create or update produces a new immutable version.

public class VoiceAgentDefinition : Azure.AI.Projects.Agents.ProjectsAgentDefinition, System.ClientModel.Primitives.IJsonModel<Azure.AI.Projects.Agents.VoiceAgentDefinition>, System.ClientModel.Primitives.IPersistableModel<Azure.AI.Projects.Agents.VoiceAgentDefinition>

type VoiceAgentDefinition = class
    inherit ProjectsAgentDefinition
    interface IJsonModel<VoiceAgentDefinition>
    interface IPersistableModel<VoiceAgentDefinition>

Public Class VoiceAgentDefinition
Inherits ProjectsAgentDefinition
Implements IJsonModel(Of VoiceAgentDefinition), IPersistableModel(Of VoiceAgentDefinition)

Inheritance

Object

ProjectsAgentDefinition

VoiceAgentDefinition

Implements

IJsonModel<VoiceAgentDefinition> IPersistableModel<VoiceAgentDefinition> IPersistableModel<T>

Constructors

Name	Description
VoiceAgentDefinition()	Initializes a new instance of VoiceAgentDefinition.

Properties

Name	Description
Audio	The audio configuration, including input and output formats, voice, turn detection, noise reduction, and transcription. These values are session defaults; a client may override supported fields when connecting.
Avatar	Optional avatar configuration. These values are session defaults and may be overridden when connecting.
ContentFilterConfiguration	Configuration for Responsible AI (RAI) content filtering and safety features. (Inherited from ProjectsAgentDefinition)
ConversationEngine	The engine that owns conversation handling for this voice agent. Exactly one of this property and the model-backed configuration (model_type with model) must be provided. When this property is provided, model_type, model, instructions, tools, and tool_choice must be omitted, and greeting.tool_choice cannot be required, because the engine owns the conversation logic. The initial implementation supports a hosted-agent engine.
Greeting	Optional session-start greeting. Template mode speaks exact rendered text; LLM-generated mode asks the session model to author the opening response and may use configured tools.
Include	Additional fields to include in service outputs.
Instructions	A system (or developer) message inserted into the model's context. Supports template substitution via structured_inputs, rendered per session before the live session starts.
InterimResponse	Interim-response settings for latency and tool execution.
MaxOutputTokens	The maximum output-token count for one response. To assign an object to this property use FromObjectAsJson<T>(T, JsonSerializerOptions). To assign an already formatted json string to this property use FromString(String). <remarks> Supported types: Int32. "inf". </remarks> Examples: BinaryData.FromObjectAsJson("foo"). : Creates a payload of "foo". BinaryData.FromString("\"foo\""). : Creates a payload of "foo". BinaryData.FromObjectAsJson(new { key = "value" }). : Creates a payload of { "key": "value" }. BinaryData.FromString("{\"key\": \"value\"}"). : Creates a payload of { "key": "value" }.
Model	The model to use for this agent. Required with model_type for a model-backed voice agent and omitted when conversation_engine is provided. The model must support realtime or cascaded voice.
ModelType	How the model backing this voice agent is served. Required with model for a model-backed voice agent and omitted when conversation_engine is provided. This is independent of the architecture (realtime or cascaded), which the service derives from the selected model.
OutputModalities	The output modalities the agent produces. Defaults to ["audio"]. animation and avatar are available when an avatar is configured.
ParallelToolCalls	Whether the model may call multiple tools in parallel.
Store	Whether conversations with this agent are persisted. A single, all-or-nothing persistence switch that defaults to false (privacy-safe: off by default). When true, Foundry persists the full conversation — the transcript/event timeline and raw audio. When false, nothing is persisted and no conversation is surfaced. There is no separate audio-logging control; audio is persisted only as part of this switch. Latency/performance telemetry (e.g. time-to-first-audio, inter-token latency, interruption) is observability-only (customer trace / App Insights) and is not part of the persisted conversation content.
StructuredInputs	Set of structured inputs that participate in prompt template substitution, rendered per session before the live session starts.
SubagentConfig	Optional configuration for sibling Foundry text agents that this voice agent may consult as background specialists.
ToolChoice	How the model chooses tools for generated responses. none prevents tool calls, auto lets the model decide, required requires at least one tool call, and a specific function or MCP tool can be selected with an object. Defaults to auto. To assign an object to this property use FromObjectAsJson<T>(T, JsonSerializerOptions). To assign an already formatted json string to this property use FromString(String). <remarks> Supported types: "none". "auto". "required". OpenAI.Realtime.RealtimeCustomFunctionToolChoice. OpenAI.Realtime.RealtimeCustomMcpToolChoice. </remarks> Examples: BinaryData.FromObjectAsJson("foo"). : Creates a payload of "foo". BinaryData.FromString("\"foo\""). : Creates a payload of "foo". BinaryData.FromObjectAsJson(new { key = "value" }). : Creates a payload of { "key": "value" }. BinaryData.FromString("{\"key\": \"value\"}"). : Creates a payload of { "key": "value" }.
Tools	The tools the voice agent may use. Supported tool kinds are function (executed by the client), mcp, system (service-managed session controls), and toolbox. Server-side tools such as web_search, azure_ai_search, and openapi are provided through a toolbox rather than declared directly.

Methods

Name	Description
JsonModelCreateCore(Utf8JsonReader, ModelReaderWriterOptions)
JsonModelWriteCore(Utf8JsonWriter, ModelReaderWriterOptions)
PersistableModelCreateCore(BinaryData, ModelReaderWriterOptions)
PersistableModelWriteCore(ModelReaderWriterOptions)

Explicit Interface Implementations

Name	Description
IJsonModel<ProjectsAgentDefinition>.Create(Utf8JsonReader, ModelReaderWriterOptions)	(Inherited from ProjectsAgentDefinition)
IJsonModel<ProjectsAgentDefinition>.Write(Utf8JsonWriter, ModelReaderWriterOptions)	(Inherited from ProjectsAgentDefinition)
IJsonModel<VoiceAgentDefinition>.Create(Utf8JsonReader, ModelReaderWriterOptions)
IJsonModel<VoiceAgentDefinition>.Write(Utf8JsonWriter, ModelReaderWriterOptions)
IPersistableModel<ProjectsAgentDefinition>.Create(BinaryData, ModelReaderWriterOptions)	(Inherited from ProjectsAgentDefinition)
IPersistableModel<ProjectsAgentDefinition>.GetFormatFromOptions(ModelReaderWriterOptions)	(Inherited from ProjectsAgentDefinition)
IPersistableModel<ProjectsAgentDefinition>.Write(ModelReaderWriterOptions)	(Inherited from ProjectsAgentDefinition)
IPersistableModel<VoiceAgentDefinition>.Create(BinaryData, ModelReaderWriterOptions)
IPersistableModel<VoiceAgentDefinition>.GetFormatFromOptions(ModelReaderWriterOptions)
IPersistableModel<VoiceAgentDefinition>.Write(ModelReaderWriterOptions)