Creates a new agent or a new version of an existing agent. Creates a new code-based agent. Uploads the code zip and creates the agent in a single call. The agent name is provided in the x-ms-agent-name header since POST /agents has no name in the URL path. The SHA-256 hex digest of the zip is provided in the x-ms-code-zip-sha256 header for integrity and dedup. The request body is multipart/form-data with a JSON metadata part and a binary code part (part order is irrelevant). Maximum upload size is 250 MB.

A feature flag opt-in required when using preview operations or modifying persisted preview resources.

The unique name that identifies the agent. Max 63 chars, must start and end with alphanumeric, hyphens allowed in the middle.

SHA-256 hex digest of the uploaded code zip. Used for change detection (dedup) and integrity verification.

The API version to use for this operation.

The content multipart request content.

The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent. - Must start and end with alphanumeric characters, - Can contain hyphens in the middle - Must not exceed 63 characters.

The operational state of an agent.

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.

A human-readable description of the agent.

The hosted agent definition.

The CPU configuration for the hosted agent.

The memory configuration for the hosted agent.

Environment variables to set in the hosted agent container.

Container-based deployment configuration for a hosted agent.

The container image for the hosted agent.

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).

The protocols that the agent supports for ingress communication.

Code-based deployment configuration for a hosted agent.

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

The entry point command and arguments for the code execution.

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

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.

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

Customer-supplied telemetry export endpoint configurations.

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

The idle duration, in seconds, before a session's sandbox is suspended. Optional — when unset, the server default of 900 seconds is used. Must be between 120 and 3600 seconds (inclusive).

The prompt agent definition

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

The GitHub Copilot managed harness for prompt agents.

The type of managed harness. Always github_copilot_preview.

The model deployment to use for this agent.

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

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

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.

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.

Configuration options for reasoning models.

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.

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.

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.

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

For function calling, the type is always function.

The name of the function to call.

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

For MCP tools, the type is always mcp.

The label of the MCP server to use.

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

Allowed tool configuration type. Always allowed_tools.

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.

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" } ]

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

For custom tool calling, the type is always custom.

The name of the custom tool to call.

The tool to call. Always programmatic_tool_calling.

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

The tool to call. Always apply_patch.

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

The tool to call. Always shell.

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

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

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

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

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

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

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

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

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

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.

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

The type of response format being defined. Always json_schema.

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

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.

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

Default response format. Used to generate text responses.

The type of response format being defined. Always text.

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.

The type of response format being defined. Always json_object.

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

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

A human-readable description of the input.

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

The JSON schema for the structured input (optional).

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.

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.

The CSDL YAML definition of the workflow.

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.

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.

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.

The kind discriminator for a voice agent definition. Always voice.

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.

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.

An engine that owns conversation handling for a voice agent.

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 support the invocations_ws protocol, Voice Live compatibility, and Bridge Protocol 1.0.

Selects a hosted Foundry agent as the conversation engine.

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

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.

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.

Session-start greeting configuration for a voice agent.

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

The Handlebars text template spoken at session start.

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

The Handlebars prompt that guides the opening turn.

Tool-selection behavior for a voice agent.

For function calling, the type is always function.

The name of the function to call.

For MCP tools, the type is always mcp.

The label of the MCP server to use.

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

Input audio configuration for a voice agent.

Input noise reduction. Set to null to disable.

The input audio noise reduction mode.

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.

Server-side voice activity detection.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

Azure semantic voice activity detection.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

Whether filler words are removed from transcription.

Whether a response is created automatically when speech stops.

Whether user speech may interrupt the agent's response.

BCP-47 language codes used for speech detection.

English-optimized Azure semantic voice activity detection.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

Whether filler words are removed from transcription.

Whether a response is created automatically when speech stops.

Whether user speech may interrupt the agent's response.

Multilingual Azure semantic voice activity detection.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

Whether filler words are removed from transcription.

Whether a response is created automatically when speech stops.

Whether user speech may interrupt the agent's response.

BCP-47 language codes used for speech detection.

OpenAI semantic VAD turn-detection settings.

Optional server-side echo cancellation settings.

The echo cancellation implementation. Always server_echo_cancellation.

The source of reference audio used for echo cancellation.

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

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

The language of the input audio. Supplying the input language in ISO-639-1 (e.g. en) format will improve accuracy and latency.

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

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

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.

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.

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. Additional values may be added over time.

Optional customer custom speech deployment configuration, keyed by locale.

Optional phrase hints that bias recognition toward domain terms.

Output audio configuration for a voice agent. Provider-specific fields are selected by voice_type: - openai: voice and speed. - azure-standard: voice, voice_locale, speed, voice_temperature, custom_lexicon_url, custom_text_normalization_url, prefer_locales, style, pitch, and volume. - azure-custom: all azure-standard fields except style, plus custom_voice_endpoint_id. - azure-personal: all azure-standard fields except style, plus personal_voice_model. - avatar-voice-sync: all azure-standard fields except voice and style, plus personal_voice_model; the voice name is derived from the avatar. - azure-realtime-native: voice and speed. format and output_audio_timestamp_types apply to every voice type.

The voice name or identifier. Applies to openai, azure-standard, azure-custom, azure-personal, and azure-realtime-native. It does not apply to avatar-voice-sync, which derives the voice name from the avatar.

The voice implementation. Additional values may be added over time.

The enforced BCP-47 output locale. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The numeric output speed multiplier. Applies to all known voice_type values and defaults to 1.

The voice variation temperature. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The URL of a custom pronunciation lexicon. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The URL of a custom text-normalization configuration. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

Preferred BCP-47 locales for multilingual synthesis. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The voice speaking style. Applies only when voice_type is azure-standard.

The voice pitch adjustment. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The voice volume adjustment. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The Azure custom-voice deployment endpoint identifier. Applies only when voice_type is azure-custom.

The Azure personal or avatar voice model. Applies only when voice_type is azure-personal or avatar-voice-sync.

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

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

The maximum output-token count or the literal inf.

Additional fields to include in service outputs.

Fields shared by interim-response configurations.

A static interim response selected from configured text.

Candidate text values for the interim response.

An interim response generated by a language model.

The model used to generate interim responses.

Optional instructions for generating interim responses.

The maximum completion-token count for an interim response.

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

The avatar type.

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

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

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

The transport used to deliver the avatar video stream.

The avatar model identifier.

Avatar video encoder and presentation settings.

The target video bitrate in bits per second.

The rectangular crop applied to avatar video.

The avatar video resolution.

The avatar video background.

Avatar placement and motion settings.

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

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-selection behavior for a voice agent.

For function calling, the type is always function.

The name of the function to call.

For MCP tools, the type is always mcp.

The label of the MCP server to use.

Whether the model may call multiple tools in parallel.

Set of structured inputs that participate in prompt template substitution, rendered per session before the live session starts.

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

A human-readable description of the input.

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

The JSON schema for the structured input (optional).

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.

Configuration for sibling Foundry text agents that a voice agent may consult.

The sibling Foundry text agents, in the same project, that this voice agent may consult.

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.

The ID of the managed blueprint

The type of digital worker.

(Preview) Whether this agent version is a draft (candidate) rather than a release. The service defaults to false if a value is not specified by the caller. Draft versions are recorded but excluded from default 'latest' resolution and are not auto-promoted.

Per-protocol configuration for the agent endpoint.

Configuration specific to the activity protocol.

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

The access boundaries for the activity protocol.

Configuration specific to the responses protocol.

Configuration specific to the A2A protocol.

Configuration specific to the MCP protocol.

Configuration specific to the invocations protocol.

Configuration specific to the WebSocket-based invocations protocol.

The authorization schemes supported by the agent endpoint

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

The version of the agent card.

The description of the agent card.

The set of skills that an agent can perform.

JSON metadata including description and hosted definition.

The code zip file (max 250 MB).

The object type, which is always 'agent'.

The unique identifier of the agent.

The name of the agent.

The operational state of an agent.

The operational state of an agent.

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

The latest version of the agent.

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.

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

The unique identifier of the agent version.

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

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

A human-readable description of the agent.

The hosted agent definition.

The CPU configuration for the hosted agent.

The memory configuration for the hosted agent.

Environment variables to set in the hosted agent container.

Container-based deployment configuration for a hosted agent.

The container image for the hosted agent.

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).

The protocols that the agent supports for ingress communication.

Code-based deployment configuration for a hosted agent.

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

The entry point command and arguments for the code execution.

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

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.

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

Customer-supplied telemetry export endpoint configurations.

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

The idle duration, in seconds, before a session's sandbox is suspended. Optional — when unset, the server default of 900 seconds is used. Must be between 120 and 3600 seconds (inclusive).

The prompt agent definition

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

The GitHub Copilot managed harness for prompt agents.

The type of managed harness. Always github_copilot_preview.

The model deployment to use for this agent.

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

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

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.

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.

Configuration options for reasoning models.

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.

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.

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.

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

For function calling, the type is always function.

The name of the function to call.

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

For MCP tools, the type is always mcp.

The label of the MCP server to use.

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

Allowed tool configuration type. Always allowed_tools.

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.

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" } ]

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

For custom tool calling, the type is always custom.

The name of the custom tool to call.

The tool to call. Always programmatic_tool_calling.

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

The tool to call. Always apply_patch.

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

The tool to call. Always shell.

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

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

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

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

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

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

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

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

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

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.

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

The type of response format being defined. Always json_schema.

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

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.

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

Default response format. Used to generate text responses.

The type of response format being defined. Always text.

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.

The type of response format being defined. Always json_object.

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

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

A human-readable description of the input.

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

The JSON schema for the structured input (optional).

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.

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.

The CSDL YAML definition of the workflow.

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.

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.

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.

The kind discriminator for a voice agent definition. Always voice.

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.

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.

An engine that owns conversation handling for a voice agent.

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 support the invocations_ws protocol, Voice Live compatibility, and Bridge Protocol 1.0.

Selects a hosted Foundry agent as the conversation engine.

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

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.

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.

Session-start greeting configuration for a voice agent.

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

The Handlebars text template spoken at session start.

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

The Handlebars prompt that guides the opening turn.

Tool-selection behavior for a voice agent.

For function calling, the type is always function.

The name of the function to call.

For MCP tools, the type is always mcp.

The label of the MCP server to use.

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

Input audio configuration for a voice agent.

Input noise reduction. Set to null to disable.

The input audio noise reduction mode.

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.

Server-side voice activity detection.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

Azure semantic voice activity detection.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

Whether filler words are removed from transcription.

Whether a response is created automatically when speech stops.

Whether user speech may interrupt the agent's response.

BCP-47 language codes used for speech detection.

English-optimized Azure semantic voice activity detection.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

Whether filler words are removed from transcription.

Whether a response is created automatically when speech stops.

Whether user speech may interrupt the agent's response.

Multilingual Azure semantic voice activity detection.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

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

The semantic end-of-utterance detection model.

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

A duration encoded as an integer number of milliseconds.

A duration encoded as an integer number of milliseconds.

Whether filler words are removed from transcription.

Whether a response is created automatically when speech stops.

Whether user speech may interrupt the agent's response.

BCP-47 language codes used for speech detection.

OpenAI semantic VAD turn-detection settings.

Optional server-side echo cancellation settings.

The echo cancellation implementation. Always server_echo_cancellation.

The source of reference audio used for echo cancellation.

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

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

The language of the input audio. Supplying the input language in ISO-639-1 (e.g. en) format will improve accuracy and latency.

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

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

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.

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.

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. Additional values may be added over time.

Optional customer custom speech deployment configuration, keyed by locale.

Optional phrase hints that bias recognition toward domain terms.

Output audio configuration for a voice agent. Provider-specific fields are selected by voice_type: - openai: voice and speed. - azure-standard: voice, voice_locale, speed, voice_temperature, custom_lexicon_url, custom_text_normalization_url, prefer_locales, style, pitch, and volume. - azure-custom: all azure-standard fields except style, plus custom_voice_endpoint_id. - azure-personal: all azure-standard fields except style, plus personal_voice_model. - avatar-voice-sync: all azure-standard fields except voice and style, plus personal_voice_model; the voice name is derived from the avatar. - azure-realtime-native: voice and speed. format and output_audio_timestamp_types apply to every voice type.

The voice name or identifier. Applies to openai, azure-standard, azure-custom, azure-personal, and azure-realtime-native. It does not apply to avatar-voice-sync, which derives the voice name from the avatar.

The voice implementation. Additional values may be added over time.

The enforced BCP-47 output locale. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The numeric output speed multiplier. Applies to all known voice_type values and defaults to 1.

The voice variation temperature. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The URL of a custom pronunciation lexicon. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The URL of a custom text-normalization configuration. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

Preferred BCP-47 locales for multilingual synthesis. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The voice speaking style. Applies only when voice_type is azure-standard.

The voice pitch adjustment. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The voice volume adjustment. Applies to azure-standard, azure-custom, azure-personal, and avatar-voice-sync.

The Azure custom-voice deployment endpoint identifier. Applies only when voice_type is azure-custom.

The Azure personal or avatar voice model. Applies only when voice_type is azure-personal or avatar-voice-sync.

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

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

The maximum output-token count or the literal inf.

Additional fields to include in service outputs.

Fields shared by interim-response configurations.

A static interim response selected from configured text.

Candidate text values for the interim response.

An interim response generated by a language model.

The model used to generate interim responses.

Optional instructions for generating interim responses.

The maximum completion-token count for an interim response.

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

The avatar type.

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

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

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

The transport used to deliver the avatar video stream.

The avatar model identifier.

Avatar video encoder and presentation settings.

The target video bitrate in bits per second.

The rectangular crop applied to avatar video.

The avatar video resolution.

The avatar video background.

Avatar placement and motion settings.

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

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-selection behavior for a voice agent.

For function calling, the type is always function.

The name of the function to call.

For MCP tools, the type is always mcp.

The label of the MCP server to use.

Whether the model may call multiple tools in parallel.

Set of structured inputs that participate in prompt template substitution, rendered per session before the live session starts.

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

A human-readable description of the input.

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

The JSON schema for the structured input (optional).

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.

Configuration for sibling Foundry text agents that a voice agent may consult.

The sibling Foundry text agents, in the same project, that this voice agent may consult.

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.

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.

The provisioning status of an agent version.

The principal ID of the agent instance

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

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

The principal ID of the agent instance

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

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

The ID of the managed blueprint

The unique GUID identifier of the agent.

Per-protocol configuration for the agent endpoint.

Configuration specific to the activity protocol.

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

The access boundaries for the activity protocol.

Configuration specific to the responses protocol.

Configuration specific to the A2A protocol.

Configuration specific to the MCP protocol.

Configuration specific to the invocations protocol.

Configuration specific to the WebSocket-based invocations protocol.

The authorization schemes supported by the agent endpoint

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

The type of digital worker.

The principal ID of the agent instance

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

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

The principal ID of the agent instance

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

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

The ID of the managed blueprint

The version of the agent card.

The description of the agent card.

The set of skills that an agent can perform.

The public explanation for this block.

The public continuation instruction.

The public explanation for this block.

The public continuation instruction.