Agents

Generate an agent

POST /agents:generate

Generates and creates an agent from kind-specific high-level inputs. The generated definition remains fully editable through the standard agent versioning operations.

Query parameters

api-version string required

The API version to use for this operation.

Request Body

The kind-specific inputs for generating and creating an agent.

Content-Type: application/json

kind enum required

The agent kind. Always voice.

voice

name string required

The unique name for the agent to create. Must be a non-empty DNS-like agent name.

model_type string | enum

How the model backing a voice agent is served. This is independent of the architecture (realtime or cascaded), which the service derives from the selected model.

Any of the following:

string

enum

managedself_deployed

model string

Optional model identifier. Required when model_type is self_deployed; optional when model_type is managed or omitted. The service never invents a customer deployment name.

use_case string

An optional authoring use case. An empty string is accepted.

goal string

An optional natural-language description of what the agent should do. When supplied, it seeds the generated instructions.

description string

An optional agent description. The authoring service resolves its fallback when omitted.

tools VoiceAgentTool[]

Optional tools carried through verbatim onto the generated agent (see VoiceAgentTool).

draft boolean

(Preview) When true, the generated voice agent is created as a draft — an editable, unpublished version the caller can review and refine before publishing it via the standard create/version path. The service defaults to false if a value is not specified by the caller, in which case the agent is created and published normally.

Responses

The request has succeeded.

Body

Content-Type: application/json

object enum required

The object type, which is always 'agent'.

agent

id string required

The unique identifier of the agent.

name string required

The name of the agent.

state string | enum required

The operational state of an agent.

Any of the following:

string

enum

enableddisabled

configuration_state string | enum required

The operational state of an agent.

Any of the following:

string

enum

enableddisabled

state_source string | enum

Indicates the source of an agent's operational state. Empty when the state is not derived from a specific source.

Any of the following:

string

enum

agent_instance_identityagent_blueprint

versions AgentObject required

The latest version of the agent.

latest AgentVersionObject required

metadata object | null required

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

[key: string] string

object enum required

The object type, which is always 'agent.version'.

agent.version

id string required

The unique identifier of the agent version.

name string required

The name of the agent. Name can be used to retrieve/update/delete the agent.

version string required

The version identifier of the agent. Agents are immutable and every update creates a new version while keeping the name same.

description string

A human-readable description of the agent.

created_at integer required

definition hosted | prompt | workflow | external | voice required

One of the following:

hosted HostedAgentDefinition

The hosted agent definition.

kind enum required

hosted

cpu string required

The CPU configuration for the hosted agent.

memory string required

The memory configuration for the hosted agent.

environment_variables object

Environment variables to set in the hosted agent container.

[key: string] string

container_configuration ContainerConfiguration

Container-based deployment configuration for a hosted agent.

image string required

The container image for the hosted agent.

registry_connection_id string

The id (or name) of the Foundry project connection that provides the credentials used to authenticate to the private container registry hosting image. The connection abstracts the auth mechanism — for example a managed-identity-federated token exchange, or a username/token secret — so registry credentials are never part of the agent definition. Omit for public images or registries already reachable by the platform's default identity (for example, Azure Container Registry).

protocol_versions ProtocolVersionRecord[]

The protocols that the agent supports for ingress communication. (Preview) Declaring the a2a protocol enables A2A passthrough to the hosted agent and requires Foundry-Features: A2AAgents=V1Preview when creating or modifying the hosted agent definition.

code_configuration CodeConfiguration

Code-based deployment configuration for a hosted agent.

runtime string required

The runtime identifier for code execution (e.g., 'python_3_11', 'python_3_12', 'python_3_13').

entry_point string[] required

The entry point command and arguments for the code execution.

dependency_resolution string | enum required

How package dependencies are resolved at deployment time for a code-based hosted agent.

Any of the following:

string

enum

bundledremote_build

content_hash string

The SHA-256 hex digest of the uploaded code zip. Set by the service from the x-ms-code-zip-sha256 request header; read-only in responses and never accepted in request payloads.

telemetry_config TelemetryConfig

Customer-supplied telemetry configuration for exporting container logs, traces, and metrics.

endpoints TelemetryEndpoint[] required

Customer-supplied telemetry export endpoint configurations.

session_configuration SessionConfiguration

Session defaults applied to sessions created for a hosted agent version.

idle_timeout_seconds integer

The idle duration, in seconds, before a session's sandbox is suspended. When omitted, the server defaults to 900 seconds. Must be between 120 and 14400 seconds (4 hours).

enable_memory_snapshot boolean

Whether this agent version uses memory snapshots. Sessions for a snapshot-enabled version start from a snapshot of the agent's initialized process rather than starting the process from its image. Defaults to false.

prompt PromptAgentDefinition

The prompt agent definition

kind enum required

prompt

harness microsoft_copilot_preview | github_copilot_preview

A managed runtime and agent loop used to execute a prompt agent.

One of the following:

microsoft_copilot_preview MicrosoftCopilotHarness

The Microsoft Copilot managed harness for prompt agents.

type enum required

The type of managed harness. Always microsoft_copilot_preview.

microsoft_copilot_preview

github_copilot_preview GitHubCopilotHarness

The legacy GitHub Copilot managed harness retained for compatibility. Use MicrosoftCopilotHarness for new prompt agents.

type enum required

The legacy type of managed harness. Always github_copilot_preview; use microsoft_copilot_preview for new prompt agents.

github_copilot_preview

model string required

The model deployment to use for this agent.

instructions string | null

A system (or developer) message inserted into the model's context.

skills SkillReference[]

The Foundry skills available to this prompt agent. An omitted skill version is resolved and pinned when the agent version is created.

temperature number | null

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both. Defaults to 1.

top_p number | null

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both. Defaults to 1.

reasoning OpenAI.Reasoning | null

Configuration options for reasoning models.

mode string | enum

Any of the following:

string

enum

standardpro

effort string | enum | null

Constrains effort on reasoning for reasoning models. Currently supported values are none, minimal, low, medium, high, xhigh, and max. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not all reasoning models support every value. See the reasoning guide for model-specific support.

Any of the following:

string

enum

noneminimallowmediumhighxhighmax

summary enum

autoconcisedetailed

context enum

autocurrent_turnall_turns

generate_summary enum

autoconcisedetailed

tools OpenAI.Tool[]

An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter.

tool_choice string | OpenAI.ToolChoiceParam

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

Any of the following:

string

One of the following:

function OpenAI.ToolChoiceFunction

Use this option to force the model to call a specific function.

type enum required

For function calling, the type is always function.

function

name string required

The name of the function to call.

mcp OpenAI.ToolChoiceMCP

Use this option to force the model to call a specific tool on a remote MCP server.

type enum required

For MCP tools, the type is always mcp.

mcp

server_label string required

The label of the MCP server to use.

name string | null

allowed_tools OpenAI.ToolChoiceAllowed

Constrains the tools available to the model to a pre-defined set.

type enum required

Allowed tool configuration type. Always allowed_tools.

allowed_tools

mode enum required

Constrains the tools available to the model to a pre-defined set. auto allows the model to pick from among the allowed tools and generate a message. required requires the model to call one or more of the allowed tools.

autorequired

tools object[] required

A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ]

custom OpenAI.ToolChoiceCustom

Use this option to force the model to call a specific custom tool.

type enum required

For custom tool calling, the type is always custom.

custom

name string required

The name of the custom tool to call.

programmatic_tool_calling OpenAI.SpecificProgrammaticToolCallingParam

type enum required

The tool to call. Always programmatic_tool_calling.

programmatic_tool_calling

apply_patch OpenAI.SpecificApplyPatchParam

Forces the model to call the apply_patch tool when executing a tool call.

type enum required

The tool to call. Always apply_patch.

apply_patch

shell OpenAI.SpecificFunctionShellParam

Forces the model to call the shell tool when a tool call is required.

type enum required

The tool to call. Always shell.

shell

file_search OpenAI.ToolChoiceFileSearch

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

file_search

web_search_preview OpenAI.ToolChoiceWebSearchPreview

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

web_search_preview

computer_use_preview OpenAI.ToolChoiceComputerUsePreview

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

computer_use_preview

web_search_preview_2025_03_11 OpenAI.ToolChoiceWebSearchPreview20250311

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

web_search_preview_2025_03_11

image_generation OpenAI.ToolChoiceImageGeneration

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

image_generation

code_interpreter OpenAI.ToolChoiceCodeInterpreter

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

code_interpreter

computer OpenAI.ToolChoiceComputer

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

computer

computer_use OpenAI.ToolChoiceComputerUse

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type enum required

computer_use

text PromptAgentDefinitionTextOptions

Configuration options for a text response from the model. Can be plain text or structured JSON data.

format json_schema | text | json_object

An object specifying the format that the model must output. Configuring { "type": "json_schema" } enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide. The default format is { "type": "text" } with no additional options. Not recommended for gpt-4o and newer models:* Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.

One of the following:

json_schema OpenAI.TextResponseFormatJsonSchema

JSON Schema response format. Used to generate structured JSON responses. Learn more about Structured Outputs.

type enum required

The type of response format being defined. Always json_schema.

json_schema

description string

A description of what the response format is for, used by the model to determine how to respond in the format.

name string required

The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

schema OpenAI.ResponseFormatJsonSchemaSchema required

The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.

strict boolean | null

text OpenAI.TextResponseFormatConfigurationResponseFormatText

Default response format. Used to generate text responses.

type enum required

The type of response format being defined. Always text.

text

json_object OpenAI.TextResponseFormatConfigurationResponseFormatJsonObject

JSON object response format. An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

type enum required

The type of response format being defined. Always json_object.

json_object

structured_inputs object

Set of structured inputs that can participate in prompt template substitution or tool argument bindings.

[key: string] StructuredInputDefinition

An structured input that can participate in prompt template substitutions and tool argument binding.

description string

A human-readable description of the input.

default_value StructuredInputDefinition

The default value for the input if no run-time value is provided.

schema object

The JSON schema for the structured input (optional).

required boolean

Whether the input property is required when the agent is invoked. The service defaults to false if a value is not specified by the caller.

workflow WorkflowAgentDefinition

The workflow agent definition. Microsoft Foundry is retiring workflows on December 1, 2026. If you're looking to build new workflows, use Microsoft Agent Framework. To migrate existing workflows, see the Migration guide.

kind enum required

workflow

workflow string

The CSDL YAML definition of the workflow.

external ExternalAgentDefinition

The external agent definition. Represents a third-party agent hosted outside Foundry (for example, on GCP or AWS). Registration is metadata-only: Foundry records the agent definition to light up observability experiences (traces, evaluations) over customer-emitted OpenTelemetry data.

kind enum required

external

otel_agent_id string

The OpenTelemetry agent identifier used to attribute customer-emitted spans to this Foundry agent. Spans must include the attribute gen_ai.agent.id = <otel_agent_id> to appear under this registration. Defaults to the top-level agent name when omitted. Provide an explicit value only for migration scenarios where the running external agent already emits a stable id that differs from the Foundry agent name. The resolved value is always echoed on read.

voice realtime | live

Shared voice-agent settings; protocol-specific fields remain flat on each subtype. Creates and updates produce immutable versions. Each version selects its own protocol, so a new version can switch between Realtime and Live.

One of the following:

realtime VoiceAgentDefinition

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.

sub_protocol enum required

Selects the Realtime protocol.

realtime

model_type string | enum

How the model backing a voice agent is served. This is independent of the architecture (realtime or cascaded), which the service derives from the selected model.

Any of the following:

string

enum

managedself_deployed

model string

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.

conversation_engine hosted_agent

An engine that owns conversation handling for a voice agent.

One of the following:

hosted_agent VoiceHostedAgentConversationEngine

A closed reference to the hosted text agent that owns conversation handling for a voice agent. The hosted agent is resolved within the same project and must declare voice_conversation_engine version 1.0.0. Voice Live connects through the dedicated voice-conversation-engine endpoint using the existing Bridge Protocol 1.0 wire semantics; the Bridge message version is independent of the container protocol version and the Hosted Agents API version v1. Declaring invocations_ws is optional and does not substitute for voice_conversation_engine.

type enum required

Selects a hosted Foundry agent as the conversation engine.

hosted_agent

name string required

The non-empty DNS-like name of the target hosted text agent in the same project.

version string

The target agent version. Omit this property to select the latest version when the voice session starts. When supplied, use a positive integer or draft-{positive-unix-timestamp} whose numeric component fits in a signed 64-bit integer.

greeting template | llm_generated

Session-start greeting configuration for a voice agent.

One of the following:

template VoiceAgentTemplateGreetingConfig

A deterministic greeting rendered with the voice agent's structured inputs and synthesized without model-authored generation.

type enum required

template

text string required

The Handlebars text template spoken at session start.

llm_generated VoiceAgentLlmGeneratedGreetingConfig

A greeting authored by the session model from a scoped opening-turn prompt.

type enum required

llm_generated

prompt string required

The Handlebars prompt that guides the opening turn.

tool_choice enum | OpenAI.ToolChoiceFunction | OpenAI.ToolChoiceMCP

Tool-selection behavior for a voice agent.

One of the following:

enum

noneautorequired

type enum required

For function calling, the type is always function.

function

name string required

The name of the function to call.

type enum required

For MCP tools, the type is always mcp.

mcp

server_label string required

The label of the MCP server to use.

name string | null

audio VoiceAgentAudioConfig

The audio configuration for a voice agent. These values are session defaults and may be overridden when connecting.

input VoiceAgentAudioInputConfig

Input audio configuration for a voice agent.

format audio/pcm | audio/pcmu | audio/pcma

One of the following:

audio/pcm OpenAI.RealtimeAudioFormatsAudioPcm

type enum required

audio/pcm

rate enum

24000

audio/pcmu OpenAI.RealtimeAudioFormatsAudioPcmu

type enum required

audio/pcmu

audio/pcma OpenAI.RealtimeAudioFormatsAudioPcma

type enum required

audio/pcma

noise_reduction VoiceAgentNoiseReduction | null

Input noise reduction. Set to null to disable.

type string | enum required

The input audio noise reduction mode. - azure_deep_noise_suppression_headset: Azure headset-optimized noise suppression for local voice activity detection. Optimized for low-sample-rate audio, including 8 kHz telephony audio. Enhances detection audio without changing the audio used for recognition. The mode is not restricted to headset devices. - azure_personal_noise_suppression: Azure personalized noise suppression for local voice activity detection. Starts with headset suppression and personalizes detection after automatic speaker enrollment. Recognition audio is unchanged; headset suppression remains active when personalization is unavailable.

Any of the following:

string

enum

near_fieldfar_fieldazure_deep_noise_suppressionazure_deep_noise_suppression_headsetazure_personal_noise_suppression

Turn (end-of-speech) detection. Server-side turn detection is enabled by default; set to null to disable it, in which case the client must trigger responses manually.

One of the following:

server_vad VoiceAgentServerVadTurnDetection

Server-side voice activity detection.

threshold number

prefix_padding_ms integer

silence_duration_ms integer

create_response boolean

interrupt_response boolean

idle_timeout_ms integer | null

type enum required

server_vad

speech_duration_ms integer

A duration encoded as an integer number of milliseconds.

end_of_utterance_detection VoiceAgentEndOfUtteranceDetection | null

Semantic end-of-utterance detection configuration. Set to null to disable it.

model string | enum required

The semantic end-of-utterance detection model.

Any of the following:

string

enum

semantic_detection_v1semantic_detection_v1_ensemantic_detection_v1_multilingualsmart_end_of_turn_detection

threshold_level string | enum

The sensitivity threshold for semantic end-of-utterance detection.

Any of the following:

string

enum

lowmediumhighdefault

timeout_ms integer

A duration encoded as an integer number of milliseconds.

azure_semantic_vad VoiceAgentAzureSemanticVadTurnDetection

Azure semantic voice activity detection.

type enum required

azure_semantic_vad

threshold number

Activation threshold for voice activity detection, from 0 to 1.

prefix_padding_ms integer

A duration encoded as an integer number of milliseconds.

silence_duration_ms integer

A duration encoded as an integer number of milliseconds.

idle_timeout_ms integer

A duration encoded as an integer number of milliseconds.

end_of_utterance_detection VoiceAgentEndOfUtteranceDetection | null

Semantic end-of-utterance detection configuration. Set to null to disable it.

model string | enum required

The semantic end-of-utterance detection model.

Any of the following:

string

enum

semantic_detection_v1semantic_detection_v1_ensemantic_detection_v1_multilingualsmart_end_of_turn_detection

threshold_level string | enum

The sensitivity threshold for semantic end-of-utterance detection.

Any of the following:

string

enum

lowmediumhighdefault

timeout_ms integer

A duration encoded as an integer number of milliseconds.

speech_duration_ms integer

A duration encoded as an integer number of milliseconds.

remove_filler_words boolean

Whether filler words are removed from transcription.

create_response boolean

Whether a response is created automatically when speech stops.

interrupt_response boolean

Whether user speech may interrupt the agent's response.

languages string[]

BCP-47 language codes used for speech detection.

azure_semantic_vad_en VoiceAgentAzureSemanticVadEnTurnDetection

English-optimized Azure semantic voice activity detection.

type enum required

azure_semantic_vad_en

threshold number

Activation threshold for voice activity detection, from 0 to 1.

prefix_padding_ms integer

A duration encoded as an integer number of milliseconds.

silence_duration_ms integer

A duration encoded as an integer number of milliseconds.

idle_timeout_ms integer

A duration encoded as an integer number of milliseconds.

end_of_utterance_detection VoiceAgentEndOfUtteranceDetection | null

Semantic end-of-utterance detection configuration. Set to null to disable it.

model string | enum required

The semantic end-of-utterance detection model.

Any of the following:

string

enum

semantic_detection_v1semantic_detection_v1_ensemantic_detection_v1_multilingualsmart_end_of_turn_detection

threshold_level string | enum

The sensitivity threshold for semantic end-of-utterance detection.

Any of the following:

string

enum

lowmediumhighdefault

timeout_ms integer

A duration encoded as an integer number of milliseconds.

speech_duration_ms integer

A duration encoded as an integer number of milliseconds.

remove_filler_words boolean

Whether filler words are removed from transcription.

create_response boolean

Whether a response is created automatically when speech stops.

interrupt_response boolean

Whether user speech may interrupt the agent's response.

azure_semantic_vad_multilingual VoiceAgentAzureSemanticVadMultilingualTurnDetection

Multilingual Azure semantic voice activity detection.

type enum required

azure_semantic_vad_multilingual

threshold number

Activation threshold for voice activity detection, from 0 to 1.

prefix_padding_ms integer

A duration encoded as an integer number of milliseconds.

silence_duration_ms integer

A duration encoded as an integer number of milliseconds.

idle_timeout_ms integer

A duration encoded as an integer number of milliseconds.

end_of_utterance_detection VoiceAgentEndOfUtteranceDetection | null

Semantic end-of-utterance detection configuration. Set to null to disable it.

model string | enum required

The semantic end-of-utterance detection model.

Any of the following:

string

enum

semantic_detection_v1semantic_detection_v1_ensemantic_detection_v1_multilingualsmart_end_of_turn_detection

threshold_level string | enum

The sensitivity threshold for semantic end-of-utterance detection.

Any of the following:

string

enum

lowmediumhighdefault

timeout_ms integer

A duration encoded as an integer number of milliseconds.

speech_duration_ms integer

A duration encoded as an integer number of milliseconds.

remove_filler_words boolean

Whether filler words are removed from transcription.

create_response boolean

Whether a response is created automatically when speech stops.

interrupt_response boolean

Whether user speech may interrupt the agent's response.

languages string[]

BCP-47 language codes used for speech detection.

semantic_vad VoiceAgentSemanticVadTurnDetection

OpenAI semantic VAD turn-detection settings.

eagerness enum

lowmediumhighauto

create_response boolean

interrupt_response boolean

type enum required

semantic_vad

echo_cancellation VoiceAgentEchoCancellation | null

Optional server-side echo cancellation settings.

type enum required

The echo cancellation implementation. Always server_echo_cancellation.

server_echo_cancellation

reference_source enum

The source of reference audio used for echo cancellation.

serverclient

channels integer

The number of input channels. Use two interleaved channels when reference_source is client.

transcription VoiceAgentInputTranscription | null

Asynchronous input-audio transcription. Set to null to disable transcription.

language string

The language of the input audio. Supplying the input language in ISO-639-1 (e.g. en) format will improve accuracy and latency. Optional for other transcription models; required and must be nonempty when model is azure-speech-streaming (such as en-US; comma-separated locales are supported).

languages string[]

Possible languages of the input audio, in ISO-639-1 format. Supported by gpt-transcribe and gpt-live-transcribe.

keywords string[]

Words or phrases to guide transcription of the input audio. Supported by gpt-transcribe and gpt-live-transcribe.

prompt string

An optional text to guide the model's style or continue a previous audio segment. For whisper-1, the prompt is a list of keywords. For gpt-4o-transcribe models (excluding gpt-4o-transcribe-diarize), the prompt is a free text string, for example "expect words related to technology". Prompt is not supported with gpt-realtime-whisper in GA Realtime sessions.

delay enum

Controls how long the model waits before emitting transcription text. Higher values can improve transcription accuracy at the cost of latency. Only supported with gpt-realtime-whisper in GA Realtime sessions.

minimallowmediumhighxhigh

model string | enum required

The input-audio transcription model identifier. This is a model name, not a Foundry deployment name. Mirrors the transcription models supported by the managed voice backend, covering the OpenAI Realtime transcription models plus the Azure and MAI models. azure-speech-streaming is supported for cascaded text-model conversations only (not realtime speech-to-speech models), requires a nonempty language such as en-US (comma-separated locales are supported), and supports custom_speech, phrase_list, and profanity_filter. Additional values may be added over time.

Any of the following:

string

enum

whisper-1gpt-realtime-whispergpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarizegpt-transcribegpt-live-transcribemai-transcribeazure-speechazure-speech-streaming

custom_speech object

Optional customer custom speech deployment configuration, keyed by locale.

[key: string] string

phrase_list string[]

Optional phrase hints that bias recognition toward domain terms.

profanity_filter string | enum

The supported input-transcript profanity filtering modes.

Any of the following:

string

enum

maskedunfilteredremoved

output VoiceAgentAudioOutputConfig

Output audio configuration for a voice agent. Extends the voice configuration with the session-level format and output_audio_timestamp_types settings, which apply to every voice type.

format audio/pcm | audio/pcmu | audio/pcma

One of the following:

audio/pcm OpenAI.RealtimeAudioFormatsAudioPcm

type enum required

audio/pcm

rate enum

24000

audio/pcmu OpenAI.RealtimeAudioFormatsAudioPcmu

type enum required

audio/pcmu

audio/pcma OpenAI.RealtimeAudioFormatsAudioPcma

type enum required

audio/pcma

output_audio_timestamp_types enum[]

Timestamp kinds to include with output audio. Applies to every voice_type.

soundscape VoiceAgentSoundscapeConfig

Agent-owned background ambience and event cues. Each omitted track is disabled. The service rejects unknown fields; custom uploads, URLs, and inline audio are not supported.

background VoiceAgentSoundscapeTrackConfig

A soundscape track with its own audio source and playback volume.

source VoiceAgentSoundscapeSourceConfig required

A packaged sound selected from the service-managed catalogue. The service rejects unknown source fields and discriminator values.

type enum required

The audio source type. Always built_in.

built_in

name enum required

The packaged sounds accepted by a built-in soundscape source.

officecall_centerbusy_streetpeople_talkingstreet_and_metro_stationding1ding2

gain number

Linear playback gain from 0 to 1, independent of agent speech volume. If omitted, the service defaults to 1. A value of 0 mutes this track.

working VoiceAgentSoundscapeWorkingTrackConfig

A working-loop track with a delay measured from the first pending non-call-control tool.

source VoiceAgentSoundscapeSourceConfig required

A packaged sound selected from the service-managed catalogue. The service rejects unknown source fields and discriminator values.

type enum required

The audio source type. Always built_in.

built_in

name enum required

The packaged sounds accepted by a built-in soundscape source.

officecall_centerbusy_streetpeople_talkingstreet_and_metro_stationding1ding2

gain number

Linear playback gain from 0 to 1, independent of agent speech volume. If omitted, the service defaults to 1. A value of 0 mutes this track.

delay_ms integer

The delay in milliseconds before working audio starts, from 0 to 10000. If omitted, the service defaults to 1000 milliseconds. This delays only working audio, not tool execution, and is valid only on the working track.

opening VoiceAgentSoundscapeTrackConfig

A soundscape track with its own audio source and playback volume.

source VoiceAgentSoundscapeSourceConfig required

A packaged sound selected from the service-managed catalogue. The service rejects unknown source fields and discriminator values.

type enum required

The audio source type. Always built_in.

built_in

name enum required

The packaged sounds accepted by a built-in soundscape source.

officecall_centerbusy_streetpeople_talkingstreet_and_metro_stationding1ding2

gain number

Linear playback gain from 0 to 1, independent of agent speech volume. If omitted, the service defaults to 1. A value of 0 mutes this track.

transfer VoiceAgentSoundscapeTrackConfig

A soundscape track with its own audio source and playback volume.

source VoiceAgentSoundscapeSourceConfig required

A packaged sound selected from the service-managed catalogue. The service rejects unknown source fields and discriminator values.

type enum required

The audio source type. Always built_in.

built_in

name enum required

The packaged sounds accepted by a built-in soundscape source.

officecall_centerbusy_streetpeople_talkingstreet_and_metro_stationding1ding2

gain number

Linear playback gain from 0 to 1, independent of agent speech volume. If omitted, the service defaults to 1. A value of 0 mutes this track.

closing VoiceAgentSoundscapeTrackConfig

A soundscape track with its own audio source and playback volume.

source VoiceAgentSoundscapeSourceConfig required

A packaged sound selected from the service-managed catalogue. The service rejects unknown source fields and discriminator values.

type enum required

The audio source type. Always built_in.

built_in

name enum required

The packaged sounds accepted by a built-in soundscape source.

officecall_centerbusy_streetpeople_talkingstreet_and_metro_stationding1ding2

gain number

Linear playback gain from 0 to 1, independent of agent speech volume. If omitted, the service defaults to 1. A value of 0 mutes this track.

output_modalities VoiceOutputModality[]

The output modalities the agent produces. Defaults to ["audio"]. animation and avatar are available when an avatar is configured.

max_output_tokens integer | enum

The maximum output-token count or the literal inf.

Any of the following:

integer

enum

inf

include enum[]

Additional fields to include in service outputs.

interim_response static_interim_response | llm_interim_response

Fields shared by interim-response configurations.

One of the following:

static_interim_response VoiceAgentStaticInterimResponseConfig

A static interim response selected from configured text.

type enum required

static_interim_response

texts string[]

Candidate text values for the interim response.

llm_interim_response VoiceAgentLlmInterimResponseConfig

An interim response generated by a language model.

type enum required

llm_interim_response

model string

The model used to generate interim responses.

instructions string

Optional instructions for generating interim responses.

max_completion_tokens integer

The maximum completion-token count for an interim response.

avatar VoiceAgentAvatarConfig

Avatar configuration for a voice agent. These values are session defaults and may be overridden when connecting.

type string | enum required

The avatar type.

Any of the following:

string

enum

video_avatarphoto_avatar

character string required

The avatar character identifier, e.g. 'lisa'.

style string

The avatar style, e.g. 'casual-sitting'.

customized boolean

Whether the avatar is a customer-customized avatar. Defaults to false.

output_protocol string | enum

The transport used to deliver the avatar video stream.

Any of the following:

string

enum

webrtcwebsocket

model string

The avatar model identifier.

video VoiceAgentAvatarVideoParams

Avatar video encoder and presentation settings.

bitrate integer

The target video bitrate in bits per second.

crop VoiceAgentAvatarVideoCrop

The rectangular crop applied to avatar video.

bottom_right integer[] required

top_left integer[] required

resolution VoiceAgentAvatarVideoResolution

The avatar video resolution.

width integer required

height integer required

background VoiceAgentAvatarVideoBackground

The avatar video background.

image_url string

color string

gop_size integer

scene VoiceAgentAvatarScene

Avatar placement and motion settings.

zoom number

position_x number

position_y number

rotation_x number

rotation_y number

rotation_z number

amplitude number

output_audit_audio boolean

Whether audit audio is emitted with avatar output. Defaults to false.

tools VoiceAgentTool[]

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.

tool_choice enum | OpenAI.ToolChoiceFunction | OpenAI.ToolChoiceMCP

Tool-selection behavior for a voice agent.

One of the following:

enum

noneautorequired

type enum required

For function calling, the type is always function.

function

name string required

The name of the function to call.

type enum required

For MCP tools, the type is always mcp.

mcp

server_label string required

The label of the MCP server to use.

name string | null

parallel_tool_calls boolean

Whether the model may call multiple tools in parallel.

subagent_config delegate | inline

Configuration for delegated background specialists or inline voice subagents. For compatibility with existing delegate configurations, the service treats an omitted subagent_type as delegate.

One of the following:

delegate VoiceAgentDelegateSubagentConfig

Configuration for referenced Foundry agents invoked as delegated background specialists.

subagent_type enum required

The subagent mode for delegated background specialists.

delegate

subagents VoiceAgentSubagent[] required

The sibling Foundry text agents, in the same project, that this Voice Agent may consult.

inline VoiceAgentInlineSubagentConfig

Configuration for inline voice subagents that may become active through Handoff.

subagent_type enum required

The subagent mode for inline voice subagents.

inline

subagents InlineVoiceSubagent[] required

Inline voice subagents owned and versioned with the parent Voice Agent. $entrypoint must be first, followed by at least one specialist and at most 31 additional subagents. Each subagent declares its outgoing handoff_conditions; condition identifiers and the 128-condition limit apply across the entire Agent.

handoff_policy VoiceAgentHandoffPolicy

Session-wide limits shared by all handoff conditions in one Voice Agent session.

max_transfers integer

The maximum number of successfully completed handoffs in one session, from 1 through 100. If omitted, the service defaults to 16.

max_attempts integer

The maximum number of attempted handoffs, from 1 through 100. If omitted, the service uses max_transfers. The service requires this value to be greater than or equal to max_transfers.

post_call VoiceAgentPostCallConfig

Post-call delivery configuration.

destinations VoiceAgentPostCallDestination[] required

The destinations to notify.

include VoiceAgentPostCallIncludeOption[]

Additional content to include in each delivery. The transcript is always delivered; add audio to also deliver a URL to the merged call recording.

live VoiceAgentLiveDefinition

The Live voice agent definition. Its configuration (model, instructions, audio, and delegation) drives a managed speech-to-speech experience using a Foundry GPT Live deployment. Establish Live voice sessions through GET /agents/{agent_name}/endpoint/protocols/voice/live/sessions. Every create or update produces a new immutable version.

sub_protocol enum required

Selects the Live protocol.

live

model_type enum required

Uses a Foundry model deployment.

self_deployed

model string required

The GPT Live deployment name.

greeting VoiceAgentTemplateGreetingConfig

A deterministic greeting rendered with the voice agent's structured inputs and synthesized without model-authored generation.

type enum required

template

text string required

The Handlebars text template spoken at session start.

audio OpenAI.LiveInitialSessionAudioParam

Startup audio configuration. Only primary WebSockets accept audio.format; WebRTC and SIP negotiate their media format. Voice and format are immutable after startup.

format audio/pcm | audio/pcmu | audio/pcma

Audio encoding and sample rate for audio sent and received over a Live WebSocket connection. WebRTC and SIP negotiate their media format separately.

One of the following:

audio/pcm OpenAI.LiveSessionAudioFormatPCMParam

Raw, mono 16-bit little-endian PCM audio for a Live WebSocket connection.

type enum required

The audio encoding. Always audio/pcm.

audio/pcm

rate enum required

Audio sample rate in hertz. Live WebSocket PCM audio supports 16000 or 24000 Hz.

1600024000

audio/pcmu OpenAI.LiveSessionAudioFormatPCMUParam

Raw, mono G.711 μ-law audio for a Live WebSocket connection.

type enum required

The audio encoding. Always audio/pcmu.

audio/pcmu

rate integer required

audio/pcma OpenAI.LiveSessionAudioFormatPCMAParam

Raw, mono G.711 A-law audio for a Live WebSocket connection.

type enum required

The audio encoding. Always audio/pcma.

audio/pcma

rate integer required

output OpenAI.LiveInitialSessionAudioOutputParam

Settings for speech generated by the Live model. Choose the voice before starting the session.

voice string | enum | OpenAI.LiveCustomVoiceParam

The voice used for Live speech, as a built-in voice name or a custom voice object containing its ID. Defaults to marin and cannot change after startup.

One of the following:

string

enum

alloyashballadbeaconbossabrisecedarcindercoraldeltaechoflitzgleamharemajunimarinmeridianniranoeulnuriquartzripplesageshidashimmersillagestonetempoversevesperwillow

id string required

delegation client | responses | foundry_managed_agent

Who handles delegated work for a Live voice agent.

One of the following:

client VoiceAgentLiveClientDelegation

Delegates work to the application using native client delegation.

acknowledgement_delay_ms integer

type enum required

client

responses VoiceAgentLiveResponsesDelegation

Delegates work to a Responses backend using native Responses settings.

acknowledgement_delay_ms integer

responses OpenAI.LiveResponsesDelegationSettingsInputParam required

Model, prompt, and tool settings for tasks delegated by the Live session to a Responses backend.

model string required

The model used for server-owned Responses delegations.

instructions string | null

max_output_tokens integer | null

service_tier enum

autodefaultfast_tier_temp_pilotflexpriorityultrafast

reasoning OpenAI.LiveDelegationReasoningInputParam | null

Reasoning options for Responses requests made on behalf of the Live session.

effort enum

noneminimallowmediumhighxhigh

summary enum

concisedetailedauto

text OpenAI.LiveDelegationTextInputParam | null

Text generation options for the Live session’s Responses backend.

verbosity enum

lowmediumhigh

Tools available to the Responses backend while it handles tasks delegated by the Live model.

Controls which tool the Responses backend uses when handling a task delegated by the Live model.

One of the following:

enum

autononerequired

type enum required

The tool to call. Always function.

function

name string required

The name of the function tool to call.

type enum required

The tool to call. Always mcp.

mcp

server_label string required

The label of the MCP server to call.

name string | null

type enum required

The tool to call. Always file_search.

file_search

type enum required

The tool to call. Always web_search.

web_search

type enum required

The tool to call. Always web_search_preview.

web_search_preview

type enum required

The tool to call. Always image_generation.

image_generation

type enum required

The tool to call. Always computer.

computer

type enum required

The tool to call. Always code_interpreter.

code_interpreter

type enum required

The tool to call. Always programmatic_tool_calling.

programmatic_tool_calling

type enum required

The tool to call. Always shell.

shell

type enum required

The tool to call. Always custom.

custom

name string required

The name of the custom tool to call.

type enum required

The tool to call. Always apply_patch.

apply_patch

type enum required

The tool choice type. Always allowed_tools.

allowed_tools

The tools that the delegated Responses model may call.

mode enum

noneautorequired

parallel_tool_calls boolean | null

type enum required

responses

foundry_managed_agent VoiceAgentLiveManagedAgentDelegation

Delegates to a same-project prompt agent using native client delegation. Requires [thinking] and/or [commentary] output sections.

type enum required

Canonical delegation type; legacy managed_prompt_agent values are returned as foundry_managed_agent.

foundry_managed_agent

agent_name string required

Name of a prompt agent in the same project.

agent_version string

Agent version, pinned per connection. Omit to select the active version.

draft boolean

Whether this agent version is a draft (candidate) rather than a release. Draft versions are recorded but excluded from default 'latest' resolution and are not auto-promoted. Defaults to false.

status enum

The provisioning status of an agent version.

creatingactivefaileddeletingdeleted

instance_identity AgentIdentity

principal_id string required

The principal ID of the agent instance

client_id string required

The client ID of the agent instance. Also referred to as the instance ID

status string | enum

The status of an agent identity, applicable to both the agent instance identity and the agent blueprint.

Any of the following:

string

enum

activedisabled

blueprint AgentIdentity

principal_id string required

The principal ID of the agent instance

client_id string required

The client ID of the agent instance. Also referred to as the instance ID

status string | enum

The status of an agent identity, applicable to both the agent instance identity and the agent blueprint.

Any of the following:

string

enum

activedisabled

blueprint_reference ManagedAgentIdentityBlueprint

One of the following:

ManagedAgentIdentityBlueprint ManagedAgentIdentityBlueprintReference

type enum required

ManagedAgentIdentityBlueprint

blueprint_id string required

The ID of the managed blueprint

agent_guid string

The unique GUID identifier of the agent.

agent_endpoint AgentEndpointConfig

version_selector VersionSelector

version_selection_rules VersionSelectionRule[] required

protocol_configuration ProtocolConfiguration

Per-protocol configuration for the agent endpoint.

activity ActivityProtocolConfiguration

Configuration specific to the activity protocol.

enable_m365_public_endpoint boolean

Whether to enable the M365 public endpoint for the activity protocol.

access_boundaries ActivityProtocolAccessBoundary[]

The access boundaries for the activity protocol.

responses ResponsesProtocolConfiguration

Configuration specific to the responses protocol.

a2a A2AProtocolConfiguration

Configuration specific to the A2A protocol.

mcp McpProtocolConfiguration

Configuration specific to the MCP protocol.

invocations InvocationsProtocolConfiguration

Configuration specific to the invocations protocol.

invocations_ws InvocationsWsProtocolConfiguration

Configuration specific to the WebSocket-based invocations protocol.

authorization_schemes AgentEndpointAuthorizationScheme[]

The authorization schemes supported by the agent endpoint

publish_approval_status string | enum

The Microsoft Agent Certification review status of the Microsoft 365 store title published for an agent.

Any of the following:

string

enum

not_publishedpendingapprovedrejectedno_approval_needed

digital_worker_type string | enum

The type of digital worker.

Any of the following:

string

enum

m365

instance_identity AgentIdentity

principal_id string required

The principal ID of the agent instance

client_id string required

The client ID of the agent instance. Also referred to as the instance ID

status string | enum

The status of an agent identity, applicable to both the agent instance identity and the agent blueprint.

Any of the following:

string

enum

activedisabled

blueprint AgentIdentity

principal_id string required

The principal ID of the agent instance

client_id string required

The client ID of the agent instance. Also referred to as the instance ID

status string | enum

The status of an agent identity, applicable to both the agent instance identity and the agent blueprint.

Any of the following:

string

enum

activedisabled

blueprint_reference ManagedAgentIdentityBlueprint

One of the following:

ManagedAgentIdentityBlueprint ManagedAgentIdentityBlueprintReference

type enum required

ManagedAgentIdentityBlueprint

blueprint_id string required

The ID of the managed blueprint

agent_card AgentCard

version string required

The version of the agent card.

description string

The description of the agent card.

skills AgentCardSkill[] required

The set of skills that an agent can perform.