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

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `api-version` | `string` | Yes | The API version to use for this operation. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Foundry-Features` | `enum` | Yes | A feature flag opt-in required when using preview operations or modifying persisted preview resources. _Constant:_ `VoiceAgents=V1Preview` |

## Request Body

Content-Type: `application/json` *(required)*

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | The agent kind. Always `voice`. _Constant:_ `voice` |
| `name` | `string` | Yes | The unique name for the agent to create. Must be a non-empty DNS-like agent name. |
| `model_type` | `enum` | No | 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. _Enum:_ `managed`, `self_deployed` |
| `model` | `string` | No | 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` | No | An optional authoring use case. An empty string is accepted. |
| `goal` | `string` | No | An optional natural-language description of what the agent should do. When supplied, it seeds the generated instructions. |
| `description` | `string` | No | An optional agent description. The authoring service resolves its fallback when omitted. |
| `tools` | `(VoiceAgentFunctionTool \| VoiceAgentMcpTool \| VoiceAgentSystemTool \| VoiceAgentToolboxTool)[]` | No | Optional tools carried through verbatim onto the generated agent (see `VoiceAgentTool`). |
| `draft` | `boolean` | No | (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. _Default:_ `false` |

### `tools` — `(VoiceAgentFunctionTool | VoiceAgentMcpTool | VoiceAgentSystemTool | VoiceAgentToolboxTool)[]`

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

**One of the following:**

#### `function` — `function (VoiceAgentFunctionTool)`

A native function tool executed by the client.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `function` |
| `description` | `string` | No | The description of the function, including guidance on when and how to call it, and guidance about what to tell the user when calling (if anything). |
| `parameters` | `OpenAI.RealtimeFunctionToolParameters` | No |  |
| `name` | `string` | Yes | The function name. |

#### `mcp` — `mcp (VoiceAgentMcpTool)`

An MCP tool available to a voice agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `mcp` |
| `server_label` | `string` | Yes | A label for this MCP server, used to identify it in tool calls. |
| `authorization` | `string` | No | An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. |
| `server_description` | `string` | No | Optional description of the MCP server, used to provide more context. |
| `headers` | `object \| null` | No |  |
| `allowed_tools` | `string[] \| OpenAI.MCPToolFilter \| null` | No |  |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |
| `require_approval` | `OpenAI.MCPToolRequireApproval \| enum \| null` | No | _Default:_ `"always"` _Enum:_ `always`, `never` |
| `defer_loading` | `boolean` | No | Whether this MCP tool is deferred and discovered via tool search. |
| `project_connection_id` | `string` | No | The connection ID in the project for the MCP server. The connection stores authentication and other connection details needed to connect to the MCP server. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `server_url` | `string` | No | The URL for the MCP server. _Format:_ `uri` |
| `response_scheduling` | `enum` | No | When a tool invocation creates a follow-up response. Additional values may be added over time. _Enum:_ `silent`, `when_idle`, `interrupt`, `skip_if_busy` |

##### `allowed_tools` — `string[] | OpenAI.MCPToolFilter | null`

**One of the following:**

###### `string[]` — `string[]`

Type: `string[]`

###### `OpenAI.MCPToolFilter` — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

###### `null` — `null`

| Type | Description |
|------|-------------|
| `null` | — |

##### `require_approval` — `OpenAI.MCPToolRequireApproval | enum | null`

**One of the following:**

###### `OpenAI.MCPToolRequireApproval` — `OpenAI.MCPToolRequireApproval`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `always` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |
| `never` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |

- **`always`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`never`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

###### `enum` — `enum`

| Type | Description |
|------|-------------|
| `enum` | _Enum:_ `always`, `never` |

###### `null` — `null`

| Type | Description |
|------|-------------|
| `null` | — |

#### `system` — `system (VoiceAgentSystemTool)`

A service-managed control that acts on the active voice session without customer code or external authentication.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `system`. _Constant:_ `system` |
| `name` | `enum` | Yes | A service-managed voice-session control action. Known values are stable; additional values may be added over time. _Constant:_ `end_conversation` |
| `description` | `string` | No | An optional description of the system tool. |

#### `toolbox` — `toolbox (VoiceAgentToolboxTool)`

A reference to a Foundry toolbox, which is a versioned bundle of tools executed through its MCP endpoint.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `toolbox`. _Constant:_ `toolbox` |
| `toolbox_name` | `string` | Yes | The name of the toolbox to attach. |
| `toolbox_version` | `string` | Yes | The immutable version of the toolbox to attach. |
| `response_scheduling` | `enum` | No | When a tool invocation creates a follow-up response. Additional values may be added over time. _Enum:_ `silent`, `when_idle`, `interrupt`, `skip_if_busy` |

## Responses

### 200 — The request has succeeded.

Content-Type: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | `enum` | Yes | The object type, which is always 'agent'. _Constant:_ `agent` |
| `id` | `string` | Yes | The unique identifier of the agent. |
| `name` | `string` | Yes | The name of the agent. |
| `state` | `enum` | Yes | The operational state of an agent. _Enum:_ `enabled`, `disabled` |
| `configuration_state` | `enum` | Yes | The operational state of an agent. _Enum:_ `enabled`, `disabled` |
| `state_source` | `enum` | No | Indicates the source of an agent's operational state. Empty when the state is not derived from a specific source. _Enum:_ `agent_instance_identity`, `agent_blueprint` |
| `versions` | `object` | Yes | The latest version of the agent. |
| `agent_endpoint` | `AgentEndpointConfig` | No |  |
| `digital_worker_type` | `enum` | No | The type of digital worker. _Constant:_ `m365` |
| `instance_identity` | `AgentIdentity` | No |  |
| `blueprint` | `AgentIdentity` | No |  |
| `blueprint_reference` | `ManagedAgentIdentityBlueprintReference` | No |  |
| `agent_card` | `AgentCard` | No |  |

#### `versions` — `object`

The latest version of the agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `latest` | `AgentVersionObject` | Yes |  |

##### `latest` — `AgentVersionObject`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `metadata` | `object \| null` | Yes | 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. |
| `object` | `enum` | Yes | The object type, which is always 'agent.version'. _Constant:_ `agent.version` |
| `id` | `string` | Yes | The unique identifier of the agent version. |
| `name` | `string` | Yes | The name of the agent. Name can be used to retrieve/update/delete the agent. |
| `version` | `string` | Yes | The version identifier of the agent. Agents are immutable and every update creates a new version while keeping the name same. |
| `description` | `string` | No | A human-readable description of the agent. |
| `created_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `definition` | `HostedAgentDefinition \| PromptAgentDefinition \| WorkflowAgentDefinition \| ExternalAgentDefinition \| VoiceAgentDefinition` | Yes |  |
| `draft` | `boolean` | No | 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. _Default:_ `false` |
| `status` | `AgentVersionStatus` | No | The provisioning status of an agent version. _Enum:_ `creating`, `active`, `failed`, `deleting`, `deleted` |
| `instance_identity` | `AgentIdentity` | No |  |
| `blueprint` | `AgentIdentity` | No |  |
| `blueprint_reference` | `ManagedAgentIdentityBlueprintReference` | No |  |
| `agent_guid` | `string` | No | The unique GUID identifier of the agent. |

###### `definition` — `HostedAgentDefinition | PromptAgentDefinition | WorkflowAgentDefinition | ExternalAgentDefinition | VoiceAgentDefinition`

**One of the following:**

- **`hosted`** — `hosted (HostedAgentDefinition)`

The hosted agent definition.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | _Constant:_ `hosted` |
| `rai_config` | `RaiConfig` | No | Configuration for Responsible AI (RAI) content filtering and safety features. |
| `cpu` | `string` | Yes | The CPU configuration for the hosted agent. |
| `memory` | `string` | Yes | The memory configuration for the hosted agent. |
| `environment_variables` | `object` | No | Environment variables to set in the hosted agent container. |
| `container_configuration` | `ContainerConfiguration` | No | Container-based deployment configuration for a hosted agent. |
| `protocol_versions` | `ProtocolVersionRecord[]` | No | The protocols that the agent supports for ingress communication. |
| `code_configuration` | `CodeConfiguration` | No | Code-based deployment configuration for a hosted agent. |
| `telemetry_config` | `TelemetryConfig` | No | Customer-supplied telemetry configuration for exporting container logs, traces, and metrics. |
| `session_configuration` | `SessionConfiguration` | No | Session defaults applied to sessions created for a hosted agent version. |

- **`rai_config`** — `RaiConfig`

Configuration for Responsible AI (RAI) content filtering and safety features.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rai_policy_name` | `string` | Yes | The name of the RAI policy to apply. |
| `invocations_moderation` | `RaiInvocationModeration` | No | Declares where request/response text lives so content-safety guardrails can extract it. |

- **`invocations_moderation`** — `RaiInvocationModeration`

Declares where request/response text lives so content-safety guardrails can extract it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `output_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `response_mode` | `enum` | Yes | Author-declared response shape for the invocations protocol. _Enum:_ `non_streaming`, `streaming`, `both` |
| `input_paths` | `string[]` | No | Path(s) to user text in the REQUEST body. Required when input_content_type is `json`. |
| `output_paths` | `string[]` | No | Path(s) to agent text in a NON-STREAMING response body. Required when response_mode is non_streaming/both and output_content_type is `json`. |
| `stream_selectors` | `RaiSseTextSelector[]` | No | One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`. |

- **`stream_selectors`** — `RaiSseTextSelector[]`

One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`.

**Array of** `RaiSseTextSelector`**:**

An SSE event-type to text-field selector for streaming invocation output.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `event_type` | `string` | Yes | The SSE event `type` value that carries text. |
| `text_field` | `string` | No | The field on a matched event holding the text delta. When omitted, the service defaults to `delta`. _Default:_ `"delta"` |

- **`container_configuration`** — `ContainerConfiguration`

Container-based deployment configuration for a hosted agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `image` | `string` | Yes | The container image for the hosted agent. |
| `registry_connection_id` | `string` | No | 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.

**Array of** `ProtocolVersionRecord`**:**

A record mapping for a single protocol and its version.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `protocol` | `enum` | Yes | _Enum:_ `activity`, `responses`, `a2a`, `mcp`, `invocations`, `voice`, `invocations_ws` |
| `version` | `string` | Yes | The version string for the protocol, e.g. 'v0.1.1'. |

- **`code_configuration`** — `CodeConfiguration`

Code-based deployment configuration for a hosted agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `runtime` | `string` | Yes | The runtime identifier for code execution (e.g., 'python_3_11', 'python_3_12', 'python_3_13'). |
| `entry_point` | `string[]` | Yes | The entry point command and arguments for the code execution. |
| `dependency_resolution` | `enum` | Yes | How package dependencies are resolved at deployment time for a code-based hosted agent. _Enum:_ `bundled`, `remote_build` |
| `content_hash` | `string` | No | 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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `endpoints` | `OtlpTelemetryEndpoint[]` | Yes | Customer-supplied telemetry export endpoint configurations. |

- **`endpoints`** — `OtlpTelemetryEndpoint[]`

Customer-supplied telemetry export endpoint configurations.

**One of the following:**

- **`OTLP`** — `OTLP (OtlpTelemetryEndpoint)`

An OTLP (OpenTelemetry Protocol) telemetry export endpoint.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | The endpoint kind, always 'OTLP' for OpenTelemetry Protocol endpoints. _Constant:_ `OTLP` |
| `data` | `enum[]` | Yes | Data types to export to this endpoint. Use an empty array to export no data. _Enum:_ `ContainerStdoutStderr`, `ContainerOtel`, `Metrics` |
| `auth` | `HeaderTelemetryEndpointAuth` | No | Authentication configuration for a telemetry endpoint. |
| `endpoint` | `string` | Yes | The OTLP collector endpoint URL. |
| `protocol` | `enum` | Yes | The transport protocol for telemetry export. _Enum:_ `Http`, `Grpc` |

- **`auth`** — `HeaderTelemetryEndpointAuth`

Authentication configuration for a telemetry endpoint.

**One of the following:**

- **`header`** — `header (HeaderTelemetryEndpointAuth)`

Header-based secret authentication for a telemetry endpoint. The resolved secret value is injected as an HTTP header.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The authentication type, always 'header' for header-based secret authentication. _Constant:_ `header` |
| `header_name` | `string` | Yes | The name of the HTTP header to inject the secret value into. |
| `secret_id` | `string` | Yes | The identifier of the secret store or connection. |
| `secret_key` | `string` | Yes | The key within the secret to retrieve the authentication value. |

- **`session_configuration`** — `SessionConfiguration`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `idle_timeout_seconds` | `integer` | No | 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). _Default:_ `900` _Format:_ `int32` |

- **`prompt`** — `prompt (PromptAgentDefinition)`

The prompt agent definition

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | _Constant:_ `prompt` |
| `rai_config` | `RaiConfig` | No | Configuration for Responsible AI (RAI) content filtering and safety features. |
| `harness` | `GitHubCopilotHarness` | No | A managed runtime and agent loop used to execute a prompt agent. |
| `model` | `string` | Yes | The model deployment to use for this agent. |
| `instructions` | `string \| null` | No | A system (or developer) message inserted into the model's context. |
| `skills` | `SkillReference[]` | No | 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` | No | 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`. _Default:_ `1` |
| `top_p` | `number \| null` | No | 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`. _Default:_ `1` |
| `reasoning` | `OpenAI.Reasoning \| null` | No |  |
| `tools` | `(GitHubCopilotToolsetPreview \| BingGroundingTool \| MicrosoftFabricPreviewTool \| SharepointPreviewTool \| AzureAISearchTool \| OpenApiTool \| BingCustomSearchPreviewTool \| BrowserAutomationPreviewTool \| BrowserAutomationTool \| AzureFunctionTool \| CaptureStructuredOutputsTool \| A2APreviewTool \| A2ATool \| WorkIQPreviewTool \| FabricIQPreviewTool \| WebIQPreviewTool \| MemorySearchPreviewTool \| OpenAI.MCPTool \| OpenAI.CodeInterpreterTool \| OpenAI.FunctionTool \| OpenAI.FileSearchTool \| OpenAI.ComputerUsePreviewTool \| OpenAI.WebSearchTool \| OpenAI.ProgrammaticToolCallingParam \| OpenAI.ImageGenTool \| OpenAI.LocalShellToolParam \| OpenAI.FunctionShellToolParam \| OpenAI.CustomToolParam \| OpenAI.WebSearchPreviewTool \| OpenAI.ApplyPatchToolParam \| OpenAI.ComputerTool \| OpenAI.NamespaceToolParam \| OpenAI.ToolSearchToolParam)[]` | No | 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.ToolChoiceFunction \| OpenAI.ToolChoiceMCP \| OpenAI.ToolChoiceAllowed \| OpenAI.ToolChoiceCustom \| OpenAI.SpecificProgrammaticToolCallingParam \| OpenAI.SpecificApplyPatchParam \| OpenAI.SpecificFunctionShellParam \| OpenAI.ToolChoiceFileSearch \| OpenAI.ToolChoiceWebSearchPreview \| OpenAI.ToolChoiceComputerUsePreview \| OpenAI.ToolChoiceWebSearchPreview20250311 \| OpenAI.ToolChoiceImageGeneration \| OpenAI.ToolChoiceCodeInterpreter \| OpenAI.ToolChoiceComputer \| OpenAI.ToolChoiceComputerUse` | No | 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. |
| `text` | `PromptAgentDefinitionTextOptions` | No | Configuration options for a text response from the model. Can be plain text or structured JSON data. |
| `structured_inputs` | `object` | No | Set of structured inputs that can participate in prompt template substitution or tool argument bindings. |

- **`rai_config`** — `RaiConfig`

Configuration for Responsible AI (RAI) content filtering and safety features.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rai_policy_name` | `string` | Yes | The name of the RAI policy to apply. |
| `invocations_moderation` | `RaiInvocationModeration` | No | Declares where request/response text lives so content-safety guardrails can extract it. |

- **`invocations_moderation`** — `RaiInvocationModeration`

Declares where request/response text lives so content-safety guardrails can extract it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `output_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `response_mode` | `enum` | Yes | Author-declared response shape for the invocations protocol. _Enum:_ `non_streaming`, `streaming`, `both` |
| `input_paths` | `string[]` | No | Path(s) to user text in the REQUEST body. Required when input_content_type is `json`. |
| `output_paths` | `string[]` | No | Path(s) to agent text in a NON-STREAMING response body. Required when response_mode is non_streaming/both and output_content_type is `json`. |
| `stream_selectors` | `RaiSseTextSelector[]` | No | One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`. |

- **`stream_selectors`** — `RaiSseTextSelector[]`

One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`.

**Array of** `RaiSseTextSelector`**:**

An SSE event-type to text-field selector for streaming invocation output.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `event_type` | `string` | Yes | The SSE event `type` value that carries text. |
| `text_field` | `string` | No | The field on a matched event holding the text delta. When omitted, the service defaults to `delta`. _Default:_ `"delta"` |

- **`harness`** — `GitHubCopilotHarness`

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

**One of the following:**

- **`github_copilot_preview`** — `github_copilot_preview (GitHubCopilotHarness)`

The GitHub Copilot managed harness for prompt agents.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of managed harness. Always `github_copilot_preview`. _Constant:_ `github_copilot_preview` |

- **`skills`** — `SkillReference[]`

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

**Array of** `SkillReference`**:**

A reference to a versioned Foundry skill.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `SkillName` | Yes | A skill name following the agentskills.io spec: lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen or contain consecutive hyphens. |
| `version` | `string` | No | The skill version. If omitted, the current default version is resolved and pinned when the agent version is created. |

- **`reasoning`** — `OpenAI.Reasoning | null`

**One of the following:**

- **`OpenAI.Reasoning`** — `OpenAI.Reasoning`

Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `mode` | `enum` | No | _Enum:_ `standard`, `pro` |
| `effort` | `enum \| null` | No | _Enum:_ `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
| `summary` | `enum` | No | _Enum:_ `auto`, `concise`, `detailed` |
| `context` | `enum` | No | _Enum:_ `auto`, `current_turn`, `all_turns` |
| `generate_summary` | `enum` | No | _Enum:_ `auto`, `concise`, `detailed` |

- **`effort`** — `enum | null`

**One of the following:**

- **`OpenAI.ReasoningEffort`** — `enum`

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](https://platform.openai.com/docs/guides/reasoning) for model-specific support.

| Type | Description |
|------|-------------|
| `enum` | 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](https://platform.openai.com/docs/guides/reasoning) for model-specific support. _Enum:_ `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`tools`** — `(GitHubCopilotToolsetPreview | BingGroundingTool | MicrosoftFabricPreviewTool | SharepointPreviewTool | AzureAISearchTool | OpenApiTool | BingCustomSearchPreviewTool | BrowserAutomationPreviewTool | BrowserAutomationTool | AzureFunctionTool | CaptureStructuredOutputsTool | A2APreviewTool | A2ATool | WorkIQPreviewTool | FabricIQPreviewTool | WebIQPreviewTool | MemorySearchPreviewTool | OpenAI.MCPTool | OpenAI.CodeInterpreterTool | OpenAI.FunctionTool | OpenAI.FileSearchTool | OpenAI.ComputerUsePreviewTool | OpenAI.WebSearchTool | OpenAI.ProgrammaticToolCallingParam | OpenAI.ImageGenTool | OpenAI.LocalShellToolParam | OpenAI.FunctionShellToolParam | OpenAI.CustomToolParam | OpenAI.WebSearchPreviewTool | OpenAI.ApplyPatchToolParam | OpenAI.ComputerTool | OpenAI.NamespaceToolParam | OpenAI.ToolSearchToolParam)[]`

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.

**One of the following:**

- **`github_copilot_toolset_preview`** — `github_copilot_toolset_preview (GitHubCopilotToolsetPreview)`

Configuration overrides for GitHub Copilot built-in tools.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the toolset. Always `github_copilot_toolset_preview`. _Constant:_ `github_copilot_toolset_preview` |
| `default_config` | `GitHubCopilotToolsetDefaultConfig` | No | The default enablement setting for GitHub Copilot built-in tools. |
| `configs` | `GitHubCopilotToolsetConfig[]` | No | Per-tool configuration overrides. Duplicate built-in tool names are not allowed. |

- **`default_config`** — `GitHubCopilotToolsetDefaultConfig`

The default enablement setting for GitHub Copilot built-in tools.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `enabled` | `boolean` | No | Whether built-in tools are enabled by default. Defaults to true. _Default:_ `true` |

- **`configs`** — `GitHubCopilotToolsetConfig[]`

Per-tool configuration overrides. Duplicate built-in tool names are not allowed.

**Array of** `GitHubCopilotToolsetConfig`**:**

An enablement override for a GitHub Copilot built-in tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `GitHubCopilotBuiltInTool` | Yes | A customer-configurable GitHub Copilot built-in tool. _Enum:_ `filesystem_read`, `filesystem_write`, `shell`, `web`, `subagents` |
| `enabled` | `boolean` | No | Whether the built-in tool is enabled. If omitted, the toolset default applies. |

- **`bing_grounding`** — `bing_grounding (BingGroundingTool)`

The input definition information for a bing grounding search tool as used to configure an agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'bing_grounding'. _Constant:_ `bing_grounding` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `bing_grounding` | `BingGroundingSearchToolParameters` | Yes | The bing grounding search tool parameters. |

- **`bing_grounding`** — `BingGroundingSearchToolParameters`

The bing grounding search tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `search_configurations` | `BingGroundingSearchConfiguration[]` | Yes | The search configurations attached to this tool. There can be a maximum of 1 search configuration resource attached to the tool. |

- **`search_configurations`** — `BingGroundingSearchConfiguration[]`

The search configurations attached to this tool. There can be a maximum of 1 search configuration resource attached to the tool.

**Array of** `BingGroundingSearchConfiguration`**:**

Search configuration for Bing Grounding

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | Project connection id for grounding with bing search |
| `market` | `string` | No | The market where the results come from. |
| `set_lang` | `string` | No | The language to use for user interface strings when calling Bing API. |
| `count` | `integer` | No | The number of search results to return in the bing api response _Format:_ `int64` |
| `freshness` | `string` | No | Filter search results by a specific time range. See [accepted values here](https://learn.microsoft.com/bing/search-apis/bing-web-search/reference/query-parameters). |

- **`fabric_dataagent_preview`** — `fabric_dataagent_preview (MicrosoftFabricPreviewTool)`

The input definition information for a Microsoft Fabric tool as used to configure an agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'fabric_dataagent_preview'. _Constant:_ `fabric_dataagent_preview` |
| `fabric_dataagent_preview` | `FabricDataAgentToolParameters` | Yes | The fabric data agent tool parameters. |

- **`fabric_dataagent_preview`** — `FabricDataAgentToolParameters`

The fabric data agent tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connections` | `ToolProjectConnection[]` | No | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

- **`project_connections`** — `ToolProjectConnection[]`

The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool.

**Array of** `ToolProjectConnection`**:**

A project connection resource.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | A project connection in a ToolProjectConnectionList attached to this tool. |

- **`sharepoint_grounding_preview`** — `sharepoint_grounding_preview (SharepointPreviewTool)`

The input definition information for a sharepoint tool as used to configure an agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'sharepoint_grounding_preview'. _Constant:_ `sharepoint_grounding_preview` |
| `sharepoint_grounding_preview` | `SharepointGroundingToolParameters` | Yes | The sharepoint grounding tool parameters. |

- **`sharepoint_grounding_preview`** — `SharepointGroundingToolParameters`

The sharepoint grounding tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connections` | `ToolProjectConnection[]` | No | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

- **`project_connections`** — `ToolProjectConnection[]`

The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool.

**Array of** `ToolProjectConnection`**:**

A project connection resource.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | A project connection in a ToolProjectConnectionList attached to this tool. |

- **`azure_ai_search`** — `azure_ai_search (AzureAISearchTool)`

The input definition information for an Azure AI search tool as used to configure an agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'azure_ai_search'. _Constant:_ `azure_ai_search` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `azure_ai_search` | `AzureAISearchToolResource` | Yes | A set of index resources used by the `azure_ai_search` tool. |

- **`azure_ai_search`** — `AzureAISearchToolResource`

A set of index resources used by the `azure_ai_search` tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `indexes` | `AISearchIndexResource[]` | Yes | The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent. |

- **`indexes`** — `AISearchIndexResource[]`

The indices attached to this agent. There can be a maximum of 1 index resource attached to the agent.

**Array of** `AISearchIndexResource`**:**

A AI Search Index resource.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | No | An index connection ID in an IndexResource attached to this agent. |
| `index_name` | `string` | No | The name of an index in an IndexResource attached to this agent. |
| `query_type` | `enum` | No | Available query types for Azure AI Search tool. _Enum:_ `simple`, `semantic`, `vector`, `vector_simple_hybrid`, `vector_semantic_hybrid` |
| `top_k` | `integer` | No | Number of documents to retrieve from search and present to the model. _Format:_ `int32` |
| `filter` | `string` | No | filter string for search resource. [Learn more here](https://learn.microsoft.com/azure/search/search-filters). |
| `index_asset_id` | `string` | No | Index asset id for search resource. |

- **`openapi`** — `openapi (OpenApiTool)`

The input definition information for an OpenAPI tool as used to configure an agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'openapi'. _Constant:_ `openapi` |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `openapi` | `OpenApiFunctionDefinition` | Yes | The input definition information for an openapi function. |

- **`openapi`** — `OpenApiFunctionDefinition`

The input definition information for an openapi function.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | The name of the function to be called. |
| `description` | `string` | No | A description of what the function does, used by the model to choose when and how to call the function. |
| `spec` | `object` | Yes | The openapi function shape, described as a JSON Schema object. |
| `auth` | `OpenApiAnonymousAuthDetails \| OpenApiProjectConnectionAuthDetails \| OpenApiManagedAuthDetails` | Yes | authentication details for OpenApiFunctionDefinition |
| `default_params` | `string[]` | No | List of OpenAPI spec parameters that will use user-provided defaults |
| `functions` | `object[]` | No | List of function definitions used by OpenApi tool |

- **`auth`** — `OpenApiAnonymousAuthDetails | OpenApiProjectConnectionAuthDetails | OpenApiManagedAuthDetails`

authentication details for OpenApiFunctionDefinition

**One of the following:**

- **`anonymous`** — `anonymous (OpenApiAnonymousAuthDetails)`

Security details for OpenApi anonymous authentication

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'anonymous'. _Constant:_ `anonymous` |

- **`project_connection`** — `project_connection (OpenApiProjectConnectionAuthDetails)`

Security details for OpenApi project connection authentication

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'project_connection'. _Constant:_ `project_connection` |
| `security_scheme` | `OpenApiProjectConnectionSecurityScheme` | Yes | Security scheme for OpenApi managed_identity authentication |

- **`security_scheme`** — `OpenApiProjectConnectionSecurityScheme`

Security scheme for OpenApi managed_identity authentication

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | Project connection id for Project Connection auth type |

- **`managed_identity`** — `managed_identity (OpenApiManagedAuthDetails)`

Security details for OpenApi managed_identity authentication

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'managed_identity'. _Constant:_ `managed_identity` |
| `security_scheme` | `OpenApiManagedSecurityScheme` | Yes | Security scheme for OpenApi managed_identity authentication |

- **`security_scheme`** — `OpenApiManagedSecurityScheme`

Security scheme for OpenApi managed_identity authentication

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `audience` | `string` | Yes | Authentication scope for managed_identity auth type |

- **`functions`** — `object[]`

List of function definitions used by OpenApi tool

**Array of** `object`**:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | The name of the function to be called. |
| `description` | `string` | No | A description of what the function does, used by the model to choose when and how to call the function. |
| `parameters` | `object` | Yes | The parameters the functions accepts, described as a JSON Schema object. |

- **`bing_custom_search_preview`** — `bing_custom_search_preview (BingCustomSearchPreviewTool)`

The input definition information for a Bing custom search tool as used to configure an agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'bing_custom_search_preview'. _Constant:_ `bing_custom_search_preview` |
| `bing_custom_search_preview` | `BingCustomSearchToolParameters` | Yes | The bing custom search tool parameters. |

- **`bing_custom_search_preview`** — `BingCustomSearchToolParameters`

The bing custom search tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `search_configurations` | `BingCustomSearchConfiguration[]` | Yes | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

- **`search_configurations`** — `BingCustomSearchConfiguration[]`

The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool.

**Array of** `BingCustomSearchConfiguration`**:**

A bing custom search configuration.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | Project connection id for grounding with bing search |
| `instance_name` | `string` | Yes | Name of the custom configuration instance given to config. |
| `market` | `string` | No | The market where the results come from. |
| `set_lang` | `string` | No | The language to use for user interface strings when calling Bing API. |
| `count` | `integer` | No | The number of search results to return in the bing api response _Format:_ `int64` |
| `freshness` | `string` | No | Filter search results by a specific time range. See [accepted values here](https://learn.microsoft.com/bing/search-apis/bing-web-search/reference/query-parameters). |

- **`browser_automation_preview`** — `browser_automation_preview (BrowserAutomationPreviewTool)`

The input definition information for a Browser Automation Tool, as used to configure an Agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'browser_automation_preview'. _Constant:_ `browser_automation_preview` |
| `browser_automation_preview` | `BrowserAutomationToolParameters` | Yes | Definition of input parameters for the Browser Automation Tool. |

- **`browser_automation_preview`** — `BrowserAutomationToolParameters`

Definition of input parameters for the Browser Automation Tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `connection` | `BrowserAutomationToolConnectionParameters` | Yes | Definition of input parameters for the connection used by the Browser Automation Tool. |

- **`connection`** — `BrowserAutomationToolConnectionParameters`

Definition of input parameters for the connection used by the Browser Automation Tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | The ID of the project connection to your Azure Playwright resource. |

- **`browser_automation`** — `browser_automation (BrowserAutomationTool)`

The input definition information for a Browser Automation Tool, as used to configure an Agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'browser_automation'. _Constant:_ `browser_automation` |
| `browser_automation` | `BrowserAutomationToolParameters` | Yes | Definition of input parameters for the Browser Automation Tool. |

- **`browser_automation`** — `BrowserAutomationToolParameters`

Definition of input parameters for the Browser Automation Tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `connection` | `BrowserAutomationToolConnectionParameters` | Yes | Definition of input parameters for the connection used by the Browser Automation Tool. |

- **`connection`** — `BrowserAutomationToolConnectionParameters`

Definition of input parameters for the connection used by the Browser Automation Tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | The ID of the project connection to your Azure Playwright resource. |

- **`azure_function`** — `azure_function (AzureFunctionTool)`

The input definition information for an Azure Function Tool, as used to configure an Agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'browser_automation'. _Constant:_ `azure_function` |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `azure_function` | `AzureFunctionDefinition` | Yes | The definition of Azure function. |

- **`azure_function`** — `AzureFunctionDefinition`

The definition of Azure function.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `function` | `object` | Yes | The definition of azure function and its parameters. |
| `input_binding` | `AzureFunctionBinding` | Yes | The structure for keeping storage queue name and URI. |
| `output_binding` | `AzureFunctionBinding` | Yes | The structure for keeping storage queue name and URI. |

- **`function`** — `object`

The definition of azure function and its parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | The name of the function to be called. |
| `description` | `string` | No | A description of what the function does, used by the model to choose when and how to call the function. |
| `parameters` | `object` | Yes | The parameters the functions accepts, described as a JSON Schema object. |

- **`input_binding`** — `AzureFunctionBinding`

The structure for keeping storage queue name and URI.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | The structure for keeping storage queue name and URI. |

- **`storage_queue`** — `AzureFunctionStorageQueue`

The structure for keeping storage queue name and URI.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `queue_service_endpoint` | `string` | Yes | URI to the Azure Storage Queue service allowing you to manipulate a queue. |
| `queue_name` | `string` | Yes | The name of an Azure function storage queue. |

- **`output_binding`** — `AzureFunctionBinding`

The structure for keeping storage queue name and URI.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | The structure for keeping storage queue name and URI. |

- **`storage_queue`** — `AzureFunctionStorageQueue`

The structure for keeping storage queue name and URI.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `queue_service_endpoint` | `string` | Yes | URI to the Azure Storage Queue service allowing you to manipulate a queue. |
| `queue_name` | `string` | Yes | The name of an Azure function storage queue. |

- **`capture_structured_outputs`** — `capture_structured_outputs (CaptureStructuredOutputsTool)`

A tool for capturing structured outputs

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `capture_structured_outputs`. _Constant:_ `capture_structured_outputs` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `outputs` | `StructuredOutputDefinition` | Yes | A structured output that can be produced by the agent. |

- **`outputs`** — `StructuredOutputDefinition`

A structured output that can be produced by the agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | The name of the structured output. |
| `description` | `string` | Yes | A description of the output to emit. Used by the model to determine when to emit the output. |
| `schema` | `object` | Yes | The JSON schema for the structured output. |
| `strict` | `boolean \| null` | Yes | Whether to enforce strict validation. Default `true`. |

- **`a2a_preview`** — `a2a_preview (A2APreviewTool)`

An agent implementing the A2A protocol.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `"a2a_preview`. _Constant:_ `a2a_preview` |
| `base_url` | `string` | No | Base URL of the agent. _Format:_ `uri` |
| `agent_card_path` | `string` | No | The path to the agent card relative to the `base_url`. If not provided, defaults to `/.well-known/agent-card.json` |
| `project_connection_id` | `string` | No | The connection ID in the project for the A2A server. The connection stores authentication and other connection details needed to connect to the A2A server. |
| `send_credentials_for_agent_card` | `boolean` | No | When `true`, Foundry sends its credentials when fetching the remote agent's Agent Card. The service defaults to `false` if a value is not specified by the caller (anonymous fetch). _Default:_ `false` |

- **`a2a`** — `a2a (A2ATool)`

An agent implementing the A2A protocol.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `"a2a"`. _Constant:_ `a2a` |
| `base_url` | `string` | No | Base URL of the agent. _Format:_ `uri` |
| `agent_card_path` | `string` | No | The path to the agent card relative to the `base_url`. If not provided, defaults to `/.well-known/agent-card.json` |
| `project_connection_id` | `string` | No | The connection ID in the project for the A2A server. The connection stores authentication and other connection details needed to connect to the A2A server. |
| `send_credentials_for_agent_card` | `boolean` | No | When `true`, Foundry sends its credentials when fetching the remote agent's Agent Card. The service defaults to `false` if a value is not specified by the caller (anonymous fetch). _Default:_ `false` |
| `a2a_version` | `enum` | Yes | Supported A2A protocol versions. _Constant:_ `1.0` |

- **`work_iq_preview`** — `work_iq_preview (WorkIQPreviewTool)`

A WorkIQ server-side tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'work_iq_preview'. _Constant:_ `work_iq_preview` |
| `project_connection_id` | `string` | Yes | The ID of the WorkIQ project connection. |

- **`fabric_iq_preview`** — `fabric_iq_preview (FabricIQPreviewTool)`

A FabricIQ server-side tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'fabric_iq_preview'. _Constant:_ `fabric_iq_preview` |
| `project_connection_id` | `string` | Yes | The ID of the FabricIQ project connection. |
| `server_label` | `string` | No | (Optional) The label of the FabricIQ MCP server to connect to. |
| `server_url` | `string` | No | (Optional) The URL of the FabricIQ MCP server. If not provided, the URL from the project connection will be used. _Format:_ `uri` |
| `require_approval` | `OpenAI.MCPToolRequireApproval \| string \| null` | No | (Optional) Whether the agent requires approval before executing actions. Default is always. _Default:_ `"always"` |

- **`require_approval`** — `OpenAI.MCPToolRequireApproval | string | null`

(Optional) Whether the agent requires approval before executing actions. Default is always.

**One of the following:**

- **`OpenAI.MCPToolRequireApproval`** — `OpenAI.MCPToolRequireApproval`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `always` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |
| `never` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |

- **`always`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`never`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`string`** — `string`

| Type | Description |
|------|-------------|
| `string` | — |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`web_iq_preview`** — `web_iq_preview (WebIQPreviewTool)`

A WebIQ server-side tool.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The object type, which is always 'web_iq_preview'. _Constant:_ `web_iq_preview` |
| `project_connection_id` | `string` | Yes | The ID of the WebIQ project connection. |
| `server_label` | `string` | No | The label of the WebIQ MCP server to connect to. When omitted, the service defaults to connection name extracted from project_connection_id. |
| `require_approval` | `OpenAI.MCPToolRequireApproval \| string \| null` | No | Whether the agent requires approval before executing actions. When omitted, the service defaults to "always". _Default:_ `"always"` |

- **`require_approval`** — `OpenAI.MCPToolRequireApproval | string | null`

Whether the agent requires approval before executing actions. When omitted, the service defaults to "always".

**One of the following:**

- **`OpenAI.MCPToolRequireApproval`** — `OpenAI.MCPToolRequireApproval`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `always` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |
| `never` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |

- **`always`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`never`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`string`** — `string`

| Type | Description |
|------|-------------|
| `string` | — |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`memory_search_preview`** — `memory_search_preview (MemorySearchPreviewTool)`

A tool for integrating memories into the agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `memory_search_preview`. _Constant:_ `memory_search_preview` |
| `memory_store_name` | `string` | Yes | The name of the memory store to use. |
| `scope` | `string` | Yes | The namespace used to group and isolate memories, such as a user ID. Limits which memories can be retrieved or updated. Use special variable `{{$userId}}` to scope memories to the current signed-in user. |
| `search_options` | `MemorySearchOptions` | No | Memory search options. |
| `update_delay` | `integer` | No | Time to wait before updating memories after inactivity (seconds). Default 300. _Default:_ `300` _Format:_ `int32` |

- **`search_options`** — `MemorySearchOptions`

Memory search options.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `max_memories` | `integer` | No | Maximum number of memory items to return. _Format:_ `int32` |

- **`mcp`** — `mcp (OpenAI.MCPTool)`

Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the MCP tool. Always `mcp`. _Constant:_ `mcp` |
| `server_label` | `string` | Yes | A label for this MCP server, used to identify it in tool calls. |
| `server_url` | `string` | No | The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. _Format:_ `uri` |
| `connector_id` | `enum` | No | Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about service connectors [here](/docs/guides/tools-remote-mcp#connectors). Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` _Enum:_ `connector_dropbox`, `connector_gmail`, `connector_googlecalendar`, `connector_googledrive`, `connector_microsoftteams`, `connector_outlookcalendar`, `connector_outlookemail`, `connector_sharepoint` |
| `tunnel_id` | `string` | No | The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. |
| `authorization` | `string` | No | An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. |
| `server_description` | `string` | No | Optional description of the MCP server, used to provide more context. |
| `headers` | `object \| null` | No |  |
| `allowed_tools` | `string[] \| OpenAI.MCPToolFilter \| null` | No |  |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |
| `require_approval` | `OpenAI.MCPToolRequireApproval \| enum \| null` | No | _Default:_ `"always"` _Enum:_ `always`, `never` |
| `defer_loading` | `boolean` | No | Whether this MCP tool is deferred and discovered via tool search. |
| `project_connection_id` | `string` | No | The connection ID in the project for the MCP server. The connection stores authentication and other connection details needed to connect to the MCP server. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |

- **`allowed_tools`** — `string[] | OpenAI.MCPToolFilter | null`

**One of the following:**

- **`string[]`** — `string[]`

Type: `string[]`

- **`OpenAI.MCPToolFilter`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`require_approval`** — `OpenAI.MCPToolRequireApproval | enum | null`

**One of the following:**

- **`OpenAI.MCPToolRequireApproval`** — `OpenAI.MCPToolRequireApproval`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `always` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |
| `never` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |

- **`always`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`never`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`enum`** — `enum`

| Type | Description |
|------|-------------|
| `enum` | _Enum:_ `always`, `never` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`code_interpreter`** — `code_interpreter (OpenAI.CodeInterpreterTool)`

A tool that runs Python code to help generate a response to a prompt.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the code interpreter tool. Always `code_interpreter`. _Constant:_ `code_interpreter` |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `container` | `string \| OpenAI.AutoCodeInterpreterToolParam` | No | The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting. If not provided, the service assumes auto. |

- **`container`** — `string | OpenAI.AutoCodeInterpreterToolParam`

The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting. If not provided, the service assumes auto.

**One of the following:**

- **`string`** — `string`

| Type | Description |
|------|-------------|
| `string` | — |

- **`OpenAI.AutoCodeInterpreterToolParam`** — `OpenAI.AutoCodeInterpreterToolParam`

Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Always `auto`. _Default:_ `"auto"` _Constant:_ `auto` |
| `file_ids` | `string[]` | No | An optional list of uploaded files to make available to your code. |
| `memory_limit` | `enum` | No | _Enum:_ `1g`, `4g`, `16g`, `64g` |
| `network_policy` | `OpenAI.ContainerNetworkPolicyDisabledParam \| OpenAI.ContainerNetworkPolicyAllowlistParam` | No | Network access policy for the container. |

- **`network_policy`** — `OpenAI.ContainerNetworkPolicyDisabledParam | OpenAI.ContainerNetworkPolicyAllowlistParam`

Network access policy for the container.

**One of the following:**

- **`disabled`** — `disabled (OpenAI.ContainerNetworkPolicyDisabledParam)`

Network access policy for the container.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Disable outbound network access. Always `disabled`. _Constant:_ `disabled` |

- **`allowlist`** — `allowlist (OpenAI.ContainerNetworkPolicyAllowlistParam)`

Network access policy for the container.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Allow outbound network access only to specified domains. Always `allowlist`. _Constant:_ `allowlist` |
| `allowed_domains` | `string[]` | Yes | A list of allowed domains when type is `allowlist`. |

- **`function`** — `function (OpenAI.FunctionTool)`

Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the function tool. Always `function`. _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |
| `async` | `boolean` | No |  |
| `description` | `string \| null` | No |  |
| `parameters` | `object \| null` | Yes |  |
| `output_schema` | `object \| null` | No |  |
| `strict` | `boolean \| null` | Yes |  |
| `defer_loading` | `boolean` | No | Whether this function is deferred and loaded via tool search. |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |

- **`file_search`** — `file_search (OpenAI.FileSearchTool)`

A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the file search tool. Always `file_search`. _Constant:_ `file_search` |
| `vector_store_ids` | `string[]` | Yes | The IDs of the vector stores to search. |
| `max_num_results` | `OpenAI.integer` | No | _Format:_ `int64` |
| `ranking_options` | `OpenAI.RankingOptions` | No |  |
| `filters` | `OpenAI.ComparisonFilter \| OpenAI.CompoundFilter \| null` | No |  |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |

- **`ranking_options`** — `OpenAI.RankingOptions`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ranker` | `OpenAI.RankerVersionType` | No | _Enum:_ `auto`, `default-2024-11-15` |
| `score_threshold` | `OpenAI.numeric` | No | _Format:_ `double` |
| `hybrid_search` | `OpenAI.HybridSearchOptions` | No |  |

- **`hybrid_search`** — `OpenAI.HybridSearchOptions`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `embedding_weight` | `OpenAI.numeric` | Yes | _Format:_ `double` |
| `text_weight` | `OpenAI.numeric` | Yes | _Format:_ `double` |

- **`filters`** — `OpenAI.ComparisonFilter | OpenAI.CompoundFilter | null`

**One of the following:**

- **`OpenAI.Filters`** — `OpenAI.ComparisonFilter | OpenAI.CompoundFilter`

**One of the following:**

- **`OpenAI.ComparisonFilter`** — `OpenAI.ComparisonFilter`

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in _Default:_ `"eq"` _Enum:_ `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| `key` | `string` | Yes | The key to compare against the value. |
| `value` | `string \| OpenAI.numeric \| boolean \| (string \| OpenAI.numeric)[]` | Yes | The value to compare against the attribute key; supports string, number, or boolean types. |

- **`value`** — `string | OpenAI.numeric | boolean | (string | OpenAI.numeric)[]`

The value to compare against the attribute key; supports string, number, or boolean types.

**One of the following:**

- **`string`** — `string`

| Type | Description |
|------|-------------|
| `string` | — |

- **`OpenAI.numeric`** — `OpenAI.numeric`

| Type | Description |
|------|-------------|
| `OpenAI.numeric` | _Format:_ `double` |

- **`boolean`** — `boolean`

| Type | Description |
|------|-------------|
| `boolean` | — |

- **`(string | OpenAI.numeric)[]`** — `(string | OpenAI.numeric)[]`

Type: `(string | OpenAI.numeric)[]`

- **`OpenAI.CompoundFilter`** — `OpenAI.CompoundFilter`

Combine multiple filters using `and` or `or`.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Type of operation: `and` or `or`. _Enum:_ `and`, `or` |
| `filters` | `(OpenAI.ComparisonFilter \| any)[]` | Yes | Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. |

- **`filters`** — `(OpenAI.ComparisonFilter | any)[]`

Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

**One of the following:**

- **`OpenAI.ComparisonFilter`** — `OpenAI.ComparisonFilter`

A filter used to compare a specified attribute key to a given value using a defined comparison operation.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in _Default:_ `"eq"` _Enum:_ `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
| `key` | `string` | Yes | The key to compare against the value. |
| `value` | `string \| OpenAI.numeric \| boolean \| (string \| OpenAI.numeric)[]` | Yes | The value to compare against the attribute key; supports string, number, or boolean types. |

- **`value`** — `string | OpenAI.numeric | boolean | (string | OpenAI.numeric)[]`

The value to compare against the attribute key; supports string, number, or boolean types.

**One of the following:**

- **`string`** — `string`

| Type | Description |
|------|-------------|
| `string` | — |

- **`OpenAI.numeric`** — `OpenAI.numeric`

| Type | Description |
|------|-------------|
| `OpenAI.numeric` | _Format:_ `double` |

- **`boolean`** — `boolean`

| Type | Description |
|------|-------------|
| `boolean` | — |

- **`(string | OpenAI.numeric)[]`** — `(string | OpenAI.numeric)[]`

Type: `(string | OpenAI.numeric)[]`

- **`any`** — `any`

| Type | Description |
|------|-------------|
| `any` | — |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`computer_use_preview`** — `computer_use_preview (OpenAI.ComputerUsePreviewTool)`

A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the computer use tool. Always `computer_use_preview`. _Constant:_ `computer_use_preview` |
| `environment` | `OpenAI.ComputerEnvironment` | Yes | _Enum:_ `windows`, `mac`, `linux`, `ubuntu`, `browser` |
| `display_width` | `OpenAI.integer` | Yes | _Format:_ `int64` |
| `display_height` | `OpenAI.integer` | Yes | _Format:_ `int64` |

- **`web_search`** — `web_search (OpenAI.WebSearchTool)`

Search the Internet for sources related to the prompt. Learn more about the [web search tool](/docs/guides/tools-web-search).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. _Constant:_ `web_search` |
| `external_web_access` | `boolean` | No | Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. _Default:_ `true` |
| `filters` | `OpenAI.WebSearchToolFilters \| null` | No |  |
| `user_location` | `OpenAI.WebSearchApproximateLocation \| null` | No |  |
| `search_context_size` | `enum` | No | High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. _Default:_ `"medium"` _Enum:_ `low`, `medium`, `high` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `custom_search_configuration` | `WebSearchConfiguration` | No | A web search configuration for bing custom search |

- **`filters`** — `OpenAI.WebSearchToolFilters | null`

**One of the following:**

- **`OpenAI.WebSearchToolFilters`** — `OpenAI.WebSearchToolFilters`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `allowed_domains` | `string[] \| null` | No |  |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`user_location`** — `OpenAI.WebSearchApproximateLocation | null`

**One of the following:**

- **`OpenAI.WebSearchApproximateLocation`** — `OpenAI.WebSearchApproximateLocation`

The approximate location of the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of location approximation. Always `approximate`. _Default:_ `"approximate"` _Constant:_ `approximate` |
| `country` | `string \| null` | No |  |
| `region` | `string \| null` | No |  |
| `city` | `string \| null` | No |  |
| `timezone` | `string \| null` | No |  |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`custom_search_configuration`** — `WebSearchConfiguration`

A web search configuration for bing custom search

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `project_connection_id` | `string` | Yes | Project connection id for grounding with bing custom search |
| `instance_name` | `string` | Yes | Name of the custom configuration instance given to config. |

- **`programmatic_tool_calling`** — `programmatic_tool_calling (OpenAI.ProgrammaticToolCallingParam)`

A tool that can be used to generate a response.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `programmatic_tool_calling`. _Constant:_ `programmatic_tool_calling` |

- **`image_generation`** — `image_generation (OpenAI.ImageGenTool)`

A tool that generates images using the GPT image models.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the image generation tool. Always `image_generation`. _Constant:_ `image_generation` |
| `model` | `enum` | No | _Default:_ `"gpt-image-1"` _Enum:_ `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21` |
| `quality` | `enum` | No | The quality of the generated image. One of `low`, `medium`, `high`, or `auto`. Default: `auto`. _Default:_ `"auto"` _Enum:_ `low`, `medium`, `high`, `auto` |
| `size` | `enum` | No | The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. _Default:_ `"auto"` _Enum:_ `1024x1024`, `1024x1536`, `1536x1024`, `auto` |
| `output_format` | `enum` | No | The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. _Default:_ `"png"` _Enum:_ `png`, `webp`, `jpeg` |
| `output_compression` | `OpenAI.integer` | No | _Format:_ `int64` |
| `moderation` | `enum` | No | Moderation level for the generated image. Default: `auto`. _Default:_ `"auto"` _Enum:_ `auto`, `low` |
| `background` | `enum` | No | Set the background of the generated image. One of `transparent`, `opaque`, or `auto`. Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. Default: `auto`. _Default:_ `"auto"` _Enum:_ `transparent`, `opaque`, `auto` |
| `input_fidelity` | `enum` | No | _Enum:_ `high`, `low` |
| `input_image_mask` | `OpenAI.ImageGenToolInputImageMask` | No |  |
| `partial_images` | `OpenAI.integer` | No | _Format:_ `int64` |
| `action` | `OpenAI.ImageGenActionEnum` | No | _Enum:_ `generate`, `edit`, `auto` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |

- **`input_image_mask`** — `OpenAI.ImageGenToolInputImageMask`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `image_url` | `string` | No | _Format:_ `uri` |
| `file_id` | `string` | No |  |

- **`local_shell`** — `local_shell (OpenAI.LocalShellToolParam)`

A tool that allows the model to execute shell commands in a local environment.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the local shell tool. Always `local_shell`. _Constant:_ `local_shell` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |

- **`shell`** — `shell (OpenAI.FunctionShellToolParam)`

A tool that allows the model to execute shell commands.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the shell tool. Always `shell`. _Constant:_ `shell` |
| `environment` | `OpenAI.FunctionShellToolParamEnvironmentLocalEnvironmentParam \| OpenAI.FunctionShellToolParamEnvironmentContainerReferenceParam \| OpenAI.ContainerAutoParam \| null` | No |  |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |
| `name` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `description` | `string` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |

- **`environment`** — `OpenAI.FunctionShellToolParamEnvironmentLocalEnvironmentParam | OpenAI.FunctionShellToolParamEnvironmentContainerReferenceParam | OpenAI.ContainerAutoParam | null`

**One of the following:**

- **`OpenAI.FunctionShellToolParamEnvironment`** — `OpenAI.FunctionShellToolParamEnvironmentLocalEnvironmentParam | OpenAI.FunctionShellToolParamEnvironmentContainerReferenceParam | OpenAI.ContainerAutoParam`

**One of the following:**

- **`local`** — `local (OpenAI.FunctionShellToolParamEnvironmentLocalEnvironmentParam)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Use a local computer environment. _Default:_ `"local"` _Constant:_ `local` |
| `skills` | `OpenAI.LocalSkillParam[]` | No | An optional list of skills. |

- **`skills`** — `OpenAI.LocalSkillParam[]`

An optional list of skills.

**Array of** `OpenAI.LocalSkillParam`**:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | The name of the skill. |
| `description` | `string` | Yes | The description of the skill. |
| `path` | `string` | Yes | The path to the directory containing the skill. |

- **`container_reference`** — `container_reference (OpenAI.FunctionShellToolParamEnvironmentContainerReferenceParam)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | References a container created with the /v1/containers endpoint _Default:_ `"container_reference"` _Constant:_ `container_reference` |
| `container_id` | `string` | Yes | The ID of the referenced container. |

- **`container_auto`** — `container_auto (OpenAI.ContainerAutoParam)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Automatically creates a container for this request _Constant:_ `container_auto` |
| `file_ids` | `string[]` | No | An optional list of uploaded files to make available to your code. |
| `memory_limit` | `enum` | No | _Enum:_ `1g`, `4g`, `16g`, `64g` |
| `skills` | `(OpenAI.SkillReferenceParam \| OpenAI.InlineSkillParam)[]` | No | An optional list of skills referenced by id or inline data. |
| `network_policy` | `OpenAI.ContainerNetworkPolicyDisabledParam \| OpenAI.ContainerNetworkPolicyAllowlistParam` | No | Network access policy for the container. |

- **`skills`** — `(OpenAI.SkillReferenceParam | OpenAI.InlineSkillParam)[]`

An optional list of skills referenced by id or inline data.

**One of the following:**

- **`skill_reference`** — `skill_reference (OpenAI.SkillReferenceParam)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | References a skill created with the /v1/skills endpoint. _Constant:_ `skill_reference` |
| `skill_id` | `string` | Yes | The ID of the referenced skill. |
| `version` | `string` | No | Optional skill version. Use a positive integer or 'latest'. Omit for default. |

- **`inline`** — `inline (OpenAI.InlineSkillParam)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Defines an inline skill for this request. _Constant:_ `inline` |
| `name` | `string` | Yes | The name of the skill. |
| `description` | `string` | Yes | The description of the skill. |
| `source` | `OpenAI.InlineSkillSourceParam` | Yes | Inline skill payload |

- **`source`** — `OpenAI.InlineSkillSourceParam`

Inline skill payload

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the inline skill source. Must be `base64`. _Default:_ `"base64"` _Constant:_ `base64` |
| `media_type` | `enum` | Yes | The media type of the inline skill payload. Must be `application/zip`. _Default:_ `"application/zip"` _Constant:_ `application/zip` |
| `data` | `string` | Yes | Base64-encoded skill zip bundle. |

- **`network_policy`** — `OpenAI.ContainerNetworkPolicyDisabledParam | OpenAI.ContainerNetworkPolicyAllowlistParam`

Network access policy for the container.

**One of the following:**

- **`disabled`** — `disabled (OpenAI.ContainerNetworkPolicyDisabledParam)`

Network access policy for the container.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Disable outbound network access. Always `disabled`. _Constant:_ `disabled` |

- **`allowlist`** — `allowlist (OpenAI.ContainerNetworkPolicyAllowlistParam)`

Network access policy for the container.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Allow outbound network access only to specified domains. Always `allowlist`. _Constant:_ `allowlist` |
| `allowed_domains` | `string[]` | Yes | A list of allowed domains when type is `allowlist`. |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`custom`** — `custom (OpenAI.CustomToolParam)`

A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools)

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the custom tool. Always `custom`. _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `async` | `boolean` | No | Whether the tool response can be returned asynchronously versus immediately returned on next response creation. |
| `description` | `string` | No | Optional description of the custom tool, used to provide more context. |
| `format` | `OpenAI.CustomTextFormatParam \| OpenAI.CustomGrammarFormatParam` | No | The input format for the custom tool. Default is unconstrained text. |
| `defer_loading` | `boolean` | No | Whether this tool should be deferred and discovered via tool search. |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |

- **`format`** — `OpenAI.CustomTextFormatParam | OpenAI.CustomGrammarFormatParam`

The input format for the custom tool. Default is unconstrained text.

**One of the following:**

- **`text`** — `text (OpenAI.CustomTextFormatParam)`

Unconstrained free-form text.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Unconstrained text format. Always `text`. _Constant:_ `text` |

- **`grammar`** — `grammar (OpenAI.CustomGrammarFormatParam)`

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | _Enum:_ `lark`, `regex` |
| `definition` | `string` | Yes | The grammar definition. |

- **`web_search_preview`** — `web_search_preview (OpenAI.WebSearchPreviewTool)`

This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. _Constant:_ `web_search_preview` |
| `user_location` | `OpenAI.ApproximateLocation \| null` | No |  |
| `search_context_size` | `OpenAI.SearchContextSize` | No | _Enum:_ `low`, `medium`, `high` |
| `search_content_types` | `OpenAI.SearchContentType[]` | No | _Enum:_ `text`, `image` |

- **`user_location`** — `OpenAI.ApproximateLocation | null`

**One of the following:**

- **`OpenAI.ApproximateLocation`** — `OpenAI.ApproximateLocation`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of location approximation. Always `approximate`. _Default:_ `"approximate"` _Constant:_ `approximate` |
| `country` | `string \| null` | No |  |
| `region` | `string \| null` | No |  |
| `city` | `string \| null` | No |  |
| `timezone` | `string \| null` | No |  |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`apply_patch`** — `apply_patch (OpenAI.ApplyPatchToolParam)`

Allows the assistant to create, delete, or update files using unified diffs.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `apply_patch`. _Constant:_ `apply_patch` |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |

- **`computer`** — `computer (OpenAI.ComputerTool)`

A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the computer tool. Always `computer`. _Constant:_ `computer` |

- **`namespace`** — `namespace (OpenAI.NamespaceToolParam)`

Groups function/custom tools under a shared namespace.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `namespace`. _Constant:_ `namespace` |
| `name` | `string` | Yes | The namespace name used in tool calls (for example, `crm`). |
| `description` | `string` | Yes | A description of the namespace shown to the model. |
| `tools` | `(OpenAI.FunctionToolParam \| OpenAI.CustomToolParam)[]` | Yes | The function/custom tools available inside this namespace. |

- **`tools`** — `(OpenAI.FunctionToolParam | OpenAI.CustomToolParam)[]`

The function/custom tools available inside this namespace.

**One of the following:**

- **`OpenAI.FunctionToolParam`** — `OpenAI.FunctionToolParam`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes |  |
| `description` | `string \| null` | No |  |
| `parameters` | `OpenAI.EmptyModelParam \| null` | No |  |
| `strict` | `boolean \| null` | No |  |
| `type` | `enum` | Yes | _Default:_ `"function"` _Constant:_ `function` |
| `async` | `boolean` | No | Whether the tool response can be returned asynchronously versus immediately returned on next response creation. |
| `output_schema` | `object \| null` | No |  |
| `defer_loading` | `boolean` | No | Whether this function should be deferred and discovered via tool search. |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |

- **`OpenAI.CustomToolParam`** — `OpenAI.CustomToolParam`

A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools)

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the custom tool. Always `custom`. _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `async` | `boolean` | No | Whether the tool response can be returned asynchronously versus immediately returned on next response creation. |
| `description` | `string` | No | Optional description of the custom tool, used to provide more context. |
| `format` | `OpenAI.CustomTextFormatParam \| OpenAI.CustomGrammarFormatParam` | No | The input format for the custom tool. Default is unconstrained text. |
| `defer_loading` | `boolean` | No | Whether this tool should be deferred and discovered via tool search. |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |

- **`format`** — `OpenAI.CustomTextFormatParam | OpenAI.CustomGrammarFormatParam`

The input format for the custom tool. Default is unconstrained text.

**One of the following:**

- **`text`** — `text (OpenAI.CustomTextFormatParam)`

Unconstrained free-form text.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Unconstrained text format. Always `text`. _Constant:_ `text` |

- **`grammar`** — `grammar (OpenAI.CustomGrammarFormatParam)`

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | _Enum:_ `lark`, `regex` |
| `definition` | `string` | Yes | The grammar definition. |

- **`tool_search`** — `tool_search (OpenAI.ToolSearchToolParam)`

Hosted or BYOT tool search configuration for deferred tools.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `tool_search`. _Constant:_ `tool_search` |
| `execution` | `OpenAI.ToolSearchExecutionType` | No | _Enum:_ `server`, `client` |
| `description` | `string \| null` | No |  |
| `parameters` | `OpenAI.EmptyModelParam \| null` | No |  |

- **`tool_choice`** — `string | OpenAI.ToolChoiceFunction | OpenAI.ToolChoiceMCP | OpenAI.ToolChoiceAllowed | OpenAI.ToolChoiceCustom | OpenAI.SpecificProgrammaticToolCallingParam | OpenAI.SpecificApplyPatchParam | OpenAI.SpecificFunctionShellParam | OpenAI.ToolChoiceFileSearch | OpenAI.ToolChoiceWebSearchPreview | OpenAI.ToolChoiceComputerUsePreview | OpenAI.ToolChoiceWebSearchPreview20250311 | OpenAI.ToolChoiceImageGeneration | OpenAI.ToolChoiceCodeInterpreter | OpenAI.ToolChoiceComputer | OpenAI.ToolChoiceComputerUse`

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.

**One of the following:**

- **`string`** — `string`

| Type | Description |
|------|-------------|
| `string` | — |

- **`OpenAI.ToolChoiceParam`** — `OpenAI.ToolChoiceFunction | OpenAI.ToolChoiceMCP | OpenAI.ToolChoiceAllowed | OpenAI.ToolChoiceCustom | OpenAI.SpecificProgrammaticToolCallingParam | OpenAI.SpecificApplyPatchParam | OpenAI.SpecificFunctionShellParam | OpenAI.ToolChoiceFileSearch | OpenAI.ToolChoiceWebSearchPreview | OpenAI.ToolChoiceComputerUsePreview | OpenAI.ToolChoiceWebSearchPreview20250311 | OpenAI.ToolChoiceImageGeneration | OpenAI.ToolChoiceCodeInterpreter | OpenAI.ToolChoiceComputer | OpenAI.ToolChoiceComputerUse`

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.

**One of the following:**

- **`function`** — `function (OpenAI.ToolChoiceFunction)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For function calling, the type is always `function`. _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |

- **`mcp`** — `mcp (OpenAI.ToolChoiceMCP)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For MCP tools, the type is always `mcp`. _Constant:_ `mcp` |
| `server_label` | `string` | Yes | The label of the MCP server to use. |
| `name` | `string \| null` | No |  |

- **`allowed_tools`** — `allowed_tools (OpenAI.ToolChoiceAllowed)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Allowed tool configuration type. Always `allowed_tools`. _Constant:_ `allowed_tools` |
| `mode` | `enum` | Yes | 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. _Enum:_ `auto`, `required` |
| `tools` | `object[]` | Yes | 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`** — `custom (OpenAI.ToolChoiceCustom)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For custom tool calling, the type is always `custom`. _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool to call. |

- **`programmatic_tool_calling`** — `programmatic_tool_calling (OpenAI.SpecificProgrammaticToolCallingParam)`

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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The tool to call. Always `programmatic_tool_calling`. _Constant:_ `programmatic_tool_calling` |

- **`apply_patch`** — `apply_patch (OpenAI.SpecificApplyPatchParam)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The tool to call. Always `apply_patch`. _Constant:_ `apply_patch` |

- **`shell`** — `shell (OpenAI.SpecificFunctionShellParam)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The tool to call. Always `shell`. _Constant:_ `shell` |

- **`file_search`** — `file_search (OpenAI.ToolChoiceFileSearch)`

Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `file_search` |

- **`web_search_preview`** — `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](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `web_search_preview` |

- **`computer_use_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](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `computer_use_preview` |

- **`web_search_preview_2025_03_11`** — `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](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `web_search_preview_2025_03_11` |

- **`image_generation`** — `image_generation (OpenAI.ToolChoiceImageGeneration)`

Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `image_generation` |

- **`code_interpreter`** — `code_interpreter (OpenAI.ToolChoiceCodeInterpreter)`

Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `code_interpreter` |

- **`computer`** — `computer (OpenAI.ToolChoiceComputer)`

Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `computer` |

- **`computer_use`** — `computer_use (OpenAI.ToolChoiceComputerUse)`

Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `computer_use` |

- **`text`** — `PromptAgentDefinitionTextOptions`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `format` | `OpenAI.TextResponseFormatJsonSchema \| OpenAI.TextResponseFormatConfigurationResponseFormatText \| OpenAI.TextResponseFormatConfigurationResponseFormatJsonObject` | No | 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](/docs/guides/structured-outputs). 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. |

- **`format`** — `OpenAI.TextResponseFormatJsonSchema | OpenAI.TextResponseFormatConfigurationResponseFormatText | OpenAI.TextResponseFormatConfigurationResponseFormatJsonObject`

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](/docs/guides/structured-outputs). 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`** — `json_schema (OpenAI.TextResponseFormatJsonSchema)`

JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](/docs/guides/structured-outputs).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of response format being defined. Always `json_schema`. _Constant:_ `json_schema` |
| `description` | `string` | No | A description of what the response format is for, used by the model to determine how to respond in the format. |
| `name` | `string` | Yes | 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` | Yes | The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). |
| `strict` | `boolean \| null` | No |  |

- **`text`** — `text (OpenAI.TextResponseFormatConfigurationResponseFormatText)`

Default response format. Used to generate text responses.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of response format being defined. Always `text`. _Constant:_ `text` |

- **`json_object`** — `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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of response format being defined. Always `json_object`. _Constant:_ `json_object` |

- **`workflow`** — `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](https://learn.microsoft.com/azure/foundry/agents/concepts/workflow#migration-guide).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | _Constant:_ `workflow` |
| `rai_config` | `RaiConfig` | No | Configuration for Responsible AI (RAI) content filtering and safety features. |
| `workflow` | `string` | No | The CSDL YAML definition of the workflow. |

- **`rai_config`** — `RaiConfig`

Configuration for Responsible AI (RAI) content filtering and safety features.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rai_policy_name` | `string` | Yes | The name of the RAI policy to apply. |
| `invocations_moderation` | `RaiInvocationModeration` | No | Declares where request/response text lives so content-safety guardrails can extract it. |

- **`invocations_moderation`** — `RaiInvocationModeration`

Declares where request/response text lives so content-safety guardrails can extract it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `output_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `response_mode` | `enum` | Yes | Author-declared response shape for the invocations protocol. _Enum:_ `non_streaming`, `streaming`, `both` |
| `input_paths` | `string[]` | No | Path(s) to user text in the REQUEST body. Required when input_content_type is `json`. |
| `output_paths` | `string[]` | No | Path(s) to agent text in a NON-STREAMING response body. Required when response_mode is non_streaming/both and output_content_type is `json`. |
| `stream_selectors` | `RaiSseTextSelector[]` | No | One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`. |

- **`stream_selectors`** — `RaiSseTextSelector[]`

One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`.

**Array of** `RaiSseTextSelector`**:**

An SSE event-type to text-field selector for streaming invocation output.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `event_type` | `string` | Yes | The SSE event `type` value that carries text. |
| `text_field` | `string` | No | The field on a matched event holding the text delta. When omitted, the service defaults to `delta`. _Default:_ `"delta"` |

- **`external`** — `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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | _Constant:_ `external` |
| `rai_config` | `RaiConfig` | No | Configuration for Responsible AI (RAI) content filtering and safety features. |
| `otel_agent_id` | `string` | No | 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. |

- **`rai_config`** — `RaiConfig`

Configuration for Responsible AI (RAI) content filtering and safety features.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rai_policy_name` | `string` | Yes | The name of the RAI policy to apply. |
| `invocations_moderation` | `RaiInvocationModeration` | No | Declares where request/response text lives so content-safety guardrails can extract it. |

- **`invocations_moderation`** — `RaiInvocationModeration`

Declares where request/response text lives so content-safety guardrails can extract it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `output_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `response_mode` | `enum` | Yes | Author-declared response shape for the invocations protocol. _Enum:_ `non_streaming`, `streaming`, `both` |
| `input_paths` | `string[]` | No | Path(s) to user text in the REQUEST body. Required when input_content_type is `json`. |
| `output_paths` | `string[]` | No | Path(s) to agent text in a NON-STREAMING response body. Required when response_mode is non_streaming/both and output_content_type is `json`. |
| `stream_selectors` | `RaiSseTextSelector[]` | No | One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`. |

- **`stream_selectors`** — `RaiSseTextSelector[]`

One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`.

**Array of** `RaiSseTextSelector`**:**

An SSE event-type to text-field selector for streaming invocation output.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `event_type` | `string` | Yes | The SSE event `type` value that carries text. |
| `text_field` | `string` | No | The field on a matched event holding the text delta. When omitted, the service defaults to `delta`. _Default:_ `"delta"` |

- **`voice`** — `voice (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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | The kind discriminator for a voice agent definition. Always `voice`. _Constant:_ `voice` |
| `rai_config` | `RaiConfig` | No | Configuration for Responsible AI (RAI) content filtering and safety features. |
| `model_type` | `enum` | No | 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. _Enum:_ `managed`, `self_deployed` |
| `model` | `string` | No | 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` | `VoiceHostedAgentConversationEngine` | No | An engine that owns conversation handling for a voice agent. |
| `instructions` | `string` | No | 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. |
| `greeting` | `VoiceAgentTemplateGreetingConfig \| VoiceAgentLlmGeneratedGreetingConfig` | No | Session-start greeting configuration for a voice agent. |
| `audio` | `VoiceAgentAudioConfig` | No | The audio configuration for a voice agent. These values are session defaults and may be overridden when connecting. |
| `output_modalities` | `enum[]` | No | The output modalities the agent produces. Defaults to `["audio"]`. `animation` and `avatar` are available when an avatar is configured. _Default:_ `["audio"]` _Enum:_ `text`, `audio`, `animation`, `avatar` |
| `max_output_tokens` | `enum` | No | The maximum output-token count or the literal `inf`. _Constant:_ `inf` |
| `include` | `VoiceAgentSessionIncludeOption[]` | No | Additional fields to include in service outputs. _Enum:_ `item.input_audio_transcription.logprobs`, `item.input_audio_transcription.phrases`, `file_search_call.results` |
| `interim_response` | `VoiceAgentStaticInterimResponseConfig \| VoiceAgentLlmInterimResponseConfig` | No | Fields shared by interim-response configurations. |
| `avatar` | `VoiceAgentAvatarConfig` | No | Avatar configuration for a voice agent. These values are session defaults and may be overridden when connecting. |
| `tools` | `(VoiceAgentFunctionTool \| VoiceAgentMcpTool \| VoiceAgentSystemTool \| VoiceAgentToolboxTool)[]` | No | 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` | No | Tool-selection behavior for a voice agent. _Enum:_ `none`, `auto`, `required` |
| `parallel_tool_calls` | `boolean` | No | Whether the model may call multiple tools in parallel. |
| `structured_inputs` | `object` | No | Set of structured inputs that participate in prompt template substitution, rendered per session before the live session starts. |
| `subagent_config` | `VoiceAgentSubagentConfig` | No | Configuration for sibling Foundry text agents that a voice agent may consult. |
| `store` | `boolean` | No | 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. _Default:_ `false` |

- **`rai_config`** — `RaiConfig`

Configuration for Responsible AI (RAI) content filtering and safety features.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `rai_policy_name` | `string` | Yes | The name of the RAI policy to apply. |
| `invocations_moderation` | `RaiInvocationModeration` | No | Declares where request/response text lives so content-safety guardrails can extract it. |

- **`invocations_moderation`** — `RaiInvocationModeration`

Declares where request/response text lives so content-safety guardrails can extract it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `output_content_type` | `enum` | No | How an invocations request/response body is parsed to locate text for content-safety moderation. _Enum:_ `json`, `text` |
| `response_mode` | `enum` | Yes | Author-declared response shape for the invocations protocol. _Enum:_ `non_streaming`, `streaming`, `both` |
| `input_paths` | `string[]` | No | Path(s) to user text in the REQUEST body. Required when input_content_type is `json`. |
| `output_paths` | `string[]` | No | Path(s) to agent text in a NON-STREAMING response body. Required when response_mode is non_streaming/both and output_content_type is `json`. |
| `stream_selectors` | `RaiSseTextSelector[]` | No | One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`. |

- **`stream_selectors`** — `RaiSseTextSelector[]`

One SSE event->field selector per event type carrying text. Required when response_mode is streaming/both and output_content_type is `json`.

**Array of** `RaiSseTextSelector`**:**

An SSE event-type to text-field selector for streaming invocation output.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `event_type` | `string` | Yes | The SSE event `type` value that carries text. |
| `text_field` | `string` | No | The field on a matched event holding the text delta. When omitted, the service defaults to `delta`. _Default:_ `"delta"` |

- **`conversation_engine`** — `VoiceHostedAgentConversationEngine`

An engine that owns conversation handling for a voice agent.

**One of the following:**

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Selects a hosted Foundry agent as the conversation engine. _Constant:_ `hosted_agent` |
| `name` | `string` | Yes | The non-empty DNS-like name of the target hosted text agent in the same project. |
| `version` | `string` | No | 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`** — `VoiceAgentTemplateGreetingConfig | VoiceAgentLlmGeneratedGreetingConfig`

Session-start greeting configuration for a voice agent.

**One of the following:**

- **`template`** — `template (VoiceAgentTemplateGreetingConfig)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `template` |
| `text` | `string` | Yes | The Handlebars text template spoken at session start. |

- **`llm_generated`** — `llm_generated (VoiceAgentLlmGeneratedGreetingConfig)`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `llm_generated` |
| `prompt` | `string` | Yes | The Handlebars prompt that guides the opening turn. |
| `tool_choice` | `enum \| OpenAI.ToolChoiceFunction \| OpenAI.ToolChoiceMCP` | No | Tool-selection behavior for a voice agent. _Enum:_ `none`, `auto`, `required` |

- **`tool_choice`** — `enum | OpenAI.ToolChoiceFunction | OpenAI.ToolChoiceMCP`

Tool-selection behavior for a voice agent.

**One of the following:**

- **`enum`** — `enum`

| Type | Description |
|------|-------------|
| `enum` | _Enum:_ `none`, `auto`, `required` |

- **`OpenAI.ToolChoiceFunction`** — `OpenAI.ToolChoiceFunction`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For function calling, the type is always `function`. _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |

- **`OpenAI.ToolChoiceMCP`** — `OpenAI.ToolChoiceMCP`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For MCP tools, the type is always `mcp`. _Constant:_ `mcp` |
| `server_label` | `string` | Yes | The label of the MCP server to use. |
| `name` | `string \| null` | No |  |

- **`audio`** — `VoiceAgentAudioConfig`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input` | `VoiceAgentAudioInputConfig` | No | Input audio configuration for a voice agent. |
| `output` | `VoiceAgentAudioOutputConfig` | No | 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. |

- **`input`** — `VoiceAgentAudioInputConfig`

Input audio configuration for a voice agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `format` | `OpenAI.RealtimeAudioFormatsAudioPcm \| OpenAI.RealtimeAudioFormatsAudioPcmu \| OpenAI.RealtimeAudioFormatsAudioPcma` | No |  |
| `noise_reduction` | `VoiceAgentNoiseReduction \| null` | No | Input noise reduction. Set to null to disable. |
| `turn_detection` | `VoiceAgentServerVadTurnDetection \| VoiceAgentAzureSemanticVadTurnDetection \| VoiceAgentAzureSemanticVadEnTurnDetection \| VoiceAgentAzureSemanticVadMultilingualTurnDetection \| VoiceAgentSemanticVadTurnDetection \| null` | No | 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. |
| `echo_cancellation` | `VoiceAgentEchoCancellation \| null` | No | Optional server-side echo cancellation settings. |
| `transcription` | `VoiceAgentInputTranscription \| null` | No | Asynchronous input-audio transcription. Set to null to disable transcription. |

- **`format`** — `OpenAI.RealtimeAudioFormatsAudioPcm | OpenAI.RealtimeAudioFormatsAudioPcmu | OpenAI.RealtimeAudioFormatsAudioPcma`

**One of the following:**

- **`audio/pcm`** — `audio/pcm (OpenAI.RealtimeAudioFormatsAudioPcm)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `audio/pcm` |
| `rate` | `enum` | No | _Constant:_ `24000` |

- **`audio/pcmu`** — `audio/pcmu (OpenAI.RealtimeAudioFormatsAudioPcmu)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `audio/pcmu` |

- **`audio/pcma`** — `audio/pcma (OpenAI.RealtimeAudioFormatsAudioPcma)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `audio/pcma` |

- **`noise_reduction`** — `VoiceAgentNoiseReduction | null`

Input noise reduction. Set to null to disable.

**One of the following:**

- **`VoiceAgentNoiseReduction`** — `VoiceAgentNoiseReduction`

Input audio noise reduction configuration.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The input audio noise reduction mode. _Enum:_ `near_field`, `far_field`, `azure_deep_noise_suppression` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`turn_detection`** — `VoiceAgentServerVadTurnDetection | VoiceAgentAzureSemanticVadTurnDetection | VoiceAgentAzureSemanticVadEnTurnDetection | VoiceAgentAzureSemanticVadMultilingualTurnDetection | VoiceAgentSemanticVadTurnDetection | null`

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:**

- **`VoiceAgentTurnDetectionConfig`** — `VoiceAgentServerVadTurnDetection | VoiceAgentAzureSemanticVadTurnDetection | VoiceAgentAzureSemanticVadEnTurnDetection | VoiceAgentAzureSemanticVadMultilingualTurnDetection | VoiceAgentSemanticVadTurnDetection`

Turn-detection configuration for a voice agent.

**One of the following:**

- **`server_vad`** — `server_vad (VoiceAgentServerVadTurnDetection)`

Server-side voice activity detection.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `server_vad` |
| `auto_truncate` | `boolean` | No | Whether the input audio buffer is truncated automatically when speech stops. _Default:_ `false` |
| `threshold` | `OpenAI.numeric` | No | _Format:_ `double` |
| `prefix_padding_ms` | `OpenAI.integer` | No | _Format:_ `int64` |
| `silence_duration_ms` | `OpenAI.integer` | No | _Format:_ `int64` |
| `create_response` | `boolean` | No | _Default:_ `true` |
| `interrupt_response` | `boolean` | No | _Default:_ `true` |
| `idle_timeout_ms` | `OpenAI.integer \| null` | No |  |
| `speech_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `end_of_utterance_detection` | `VoiceAgentEndOfUtteranceDetection \| null` | No | Semantic end-of-utterance detection configuration. Set to null to disable it. |

- **`end_of_utterance_detection`** — `VoiceAgentEndOfUtteranceDetection | null`

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

**One of the following:**

- **`VoiceAgentEndOfUtteranceDetection`** — `VoiceAgentEndOfUtteranceDetection`

Semantic end-of-utterance detection configuration.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `model` | `enum` | Yes | The semantic end-of-utterance detection model. _Enum:_ `semantic_detection_v1`, `semantic_detection_v1_en`, `semantic_detection_v1_multilingual`, `smart_end_of_turn_detection` |
| `threshold_level` | `enum` | No | The sensitivity threshold for semantic end-of-utterance detection. _Enum:_ `low`, `medium`, `high`, `default` |
| `timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`azure_semantic_vad`** — `azure_semantic_vad (VoiceAgentAzureSemanticVadTurnDetection)`

Azure semantic voice activity detection.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `azure_semantic_vad` |
| `auto_truncate` | `boolean` | No | Whether the input audio buffer is truncated automatically when speech stops. _Default:_ `false` |
| `threshold` | `number` | No | Activation threshold for voice activity detection, from 0 to 1. _Format:_ `float` |
| `prefix_padding_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `silence_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `idle_timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `end_of_utterance_detection` | `VoiceAgentEndOfUtteranceDetection \| null` | No | Semantic end-of-utterance detection configuration. Set to null to disable it. |
| `speech_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `remove_filler_words` | `boolean` | No | Whether filler words are removed from transcription. _Default:_ `false` |
| `create_response` | `boolean` | No | Whether a response is created automatically when speech stops. _Default:_ `true` |
| `interrupt_response` | `boolean` | No | Whether user speech may interrupt the agent's response. _Default:_ `true` |
| `languages` | `string[]` | No | BCP-47 language codes used for speech detection. |

- **`end_of_utterance_detection`** — `VoiceAgentEndOfUtteranceDetection | null`

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

**One of the following:**

- **`VoiceAgentEndOfUtteranceDetection`** — `VoiceAgentEndOfUtteranceDetection`

Semantic end-of-utterance detection configuration.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `model` | `enum` | Yes | The semantic end-of-utterance detection model. _Enum:_ `semantic_detection_v1`, `semantic_detection_v1_en`, `semantic_detection_v1_multilingual`, `smart_end_of_turn_detection` |
| `threshold_level` | `enum` | No | The sensitivity threshold for semantic end-of-utterance detection. _Enum:_ `low`, `medium`, `high`, `default` |
| `timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`azure_semantic_vad_en`** — `azure_semantic_vad_en (VoiceAgentAzureSemanticVadEnTurnDetection)`

English-optimized Azure semantic voice activity detection.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `azure_semantic_vad_en` |
| `auto_truncate` | `boolean` | No | Whether the input audio buffer is truncated automatically when speech stops. _Default:_ `false` |
| `threshold` | `number` | No | Activation threshold for voice activity detection, from 0 to 1. _Format:_ `float` |
| `prefix_padding_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `silence_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `idle_timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `end_of_utterance_detection` | `VoiceAgentEndOfUtteranceDetection \| null` | No | Semantic end-of-utterance detection configuration. Set to null to disable it. |
| `speech_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `remove_filler_words` | `boolean` | No | Whether filler words are removed from transcription. _Default:_ `false` |
| `create_response` | `boolean` | No | Whether a response is created automatically when speech stops. _Default:_ `true` |
| `interrupt_response` | `boolean` | No | Whether user speech may interrupt the agent's response. _Default:_ `true` |

- **`end_of_utterance_detection`** — `VoiceAgentEndOfUtteranceDetection | null`

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

**One of the following:**

- **`VoiceAgentEndOfUtteranceDetection`** — `VoiceAgentEndOfUtteranceDetection`

Semantic end-of-utterance detection configuration.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `model` | `enum` | Yes | The semantic end-of-utterance detection model. _Enum:_ `semantic_detection_v1`, `semantic_detection_v1_en`, `semantic_detection_v1_multilingual`, `smart_end_of_turn_detection` |
| `threshold_level` | `enum` | No | The sensitivity threshold for semantic end-of-utterance detection. _Enum:_ `low`, `medium`, `high`, `default` |
| `timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`azure_semantic_vad_multilingual`** — `azure_semantic_vad_multilingual (VoiceAgentAzureSemanticVadMultilingualTurnDetection)`

Multilingual Azure semantic voice activity detection.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `azure_semantic_vad_multilingual` |
| `auto_truncate` | `boolean` | No | Whether the input audio buffer is truncated automatically when speech stops. _Default:_ `false` |
| `threshold` | `number` | No | Activation threshold for voice activity detection, from 0 to 1. _Format:_ `float` |
| `prefix_padding_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `silence_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `idle_timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `end_of_utterance_detection` | `VoiceAgentEndOfUtteranceDetection \| null` | No | Semantic end-of-utterance detection configuration. Set to null to disable it. |
| `speech_duration_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `remove_filler_words` | `boolean` | No | Whether filler words are removed from transcription. _Default:_ `false` |
| `create_response` | `boolean` | No | Whether a response is created automatically when speech stops. _Default:_ `true` |
| `interrupt_response` | `boolean` | No | Whether user speech may interrupt the agent's response. _Default:_ `true` |
| `languages` | `string[]` | No | BCP-47 language codes used for speech detection. |

- **`end_of_utterance_detection`** — `VoiceAgentEndOfUtteranceDetection | null`

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

**One of the following:**

- **`VoiceAgentEndOfUtteranceDetection`** — `VoiceAgentEndOfUtteranceDetection`

Semantic end-of-utterance detection configuration.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `model` | `enum` | Yes | The semantic end-of-utterance detection model. _Enum:_ `semantic_detection_v1`, `semantic_detection_v1_en`, `semantic_detection_v1_multilingual`, `smart_end_of_turn_detection` |
| `threshold_level` | `enum` | No | The sensitivity threshold for semantic end-of-utterance detection. _Enum:_ `low`, `medium`, `high`, `default` |
| `timeout_ms` | `FoundryDurationMilliseconds` | No | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`semantic_vad`** — `semantic_vad (VoiceAgentSemanticVadTurnDetection)`

OpenAI semantic VAD turn-detection settings.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `semantic_vad` |
| `auto_truncate` | `boolean` | No | Whether the input audio buffer is truncated automatically when speech stops. _Default:_ `false` |
| `eagerness` | `enum` | No | _Default:_ `"auto"` _Enum:_ `low`, `medium`, `high`, `auto` |
| `create_response` | `boolean` | No | _Default:_ `true` |
| `interrupt_response` | `boolean` | No | _Default:_ `true` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`echo_cancellation`** — `VoiceAgentEchoCancellation | null`

Optional server-side echo cancellation settings.

**One of the following:**

- **`VoiceAgentEchoCancellation`** — `VoiceAgentEchoCancellation`

Server-side echo cancellation settings for input audio.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The echo cancellation implementation. Always `server_echo_cancellation`. _Constant:_ `server_echo_cancellation` |
| `reference_source` | `VoiceAgentEchoCancellationReferenceSource` | No | The source of reference audio used for echo cancellation. _Enum:_ `server`, `client` |
| `channels` | `integer` | No | The number of input channels. Use two interleaved channels when `reference_source` is `client`. _Default:_ `1` _Format:_ `int32` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`transcription`** — `VoiceAgentInputTranscription | null`

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

**One of the following:**

- **`VoiceAgentInputTranscription`** — `VoiceAgentInputTranscription`

Asynchronous input-audio transcription configuration. Extends the OpenAI Realtime transcription options with the Azure and MAI transcription models, custom speech models, and phrase hints.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `language` | `string` | No | The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format will improve accuracy and latency. |
| `languages` | `string[]` | No | Possible languages of the input audio, in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) format. Supported by `gpt-transcribe` and `gpt-live-transcribe`. |
| `keywords` | `string[]` | No | Words or phrases to guide transcription of the input audio. Supported by `gpt-transcribe` and `gpt-live-transcribe`. |
| `prompt` | `string` | No | 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](/docs/guides/speech-to-text#prompting). 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` | No | 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. _Enum:_ `minimal`, `low`, `medium`, `high`, `xhigh` |
| `model` | `enum` | Yes | 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. _Enum:_ `whisper-1`, `gpt-realtime-whisper`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-transcribe-diarize`, `gpt-transcribe`, `gpt-live-transcribe`, `mai-transcribe`, `azure-speech` |
| `custom_speech` | `object` | No | Optional customer custom speech deployment configuration, keyed by locale. |
| `phrase_list` | `string[]` | No | Optional phrase hints that bias recognition toward domain terms. |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`output`** — `VoiceAgentAudioOutputConfig`

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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `format` | `OpenAI.RealtimeAudioFormatsAudioPcm \| OpenAI.RealtimeAudioFormatsAudioPcmu \| OpenAI.RealtimeAudioFormatsAudioPcma` | No |  |
| `voice` | `string` | No | 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. |
| `voice_type` | `enum` | No | The voice implementation. Additional values may be added over time. _Enum:_ `openai`, `azure-standard`, `azure-custom`, `azure-personal`, `avatar-voice-sync`, `azure-realtime-native` |
| `voice_locale` | `string` | No | The enforced BCP-47 output locale. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. |
| `speed` | `number` | No | The numeric output speed multiplier. Applies to all known `voice_type` values and defaults to 1. _Default:_ `1` _Format:_ `float` |
| `voice_temperature` | `number` | No | The voice variation temperature. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. _Format:_ `float` |
| `custom_lexicon_url` | `string` | No | The URL of a custom pronunciation lexicon. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. _Format:_ `uri` |
| `custom_text_normalization_url` | `string` | No | The URL of a custom text-normalization configuration. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. _Format:_ `uri` |
| `prefer_locales` | `string[]` | No | Preferred BCP-47 locales for multilingual synthesis. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. |
| `style` | `string` | No | The voice speaking style. Applies only when `voice_type` is `azure-standard`. |
| `pitch` | `string` | No | The voice pitch adjustment. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. |
| `volume` | `string` | No | The voice volume adjustment. Applies to `azure-standard`, `azure-custom`, `azure-personal`, and `avatar-voice-sync`. |
| `custom_voice_endpoint_id` | `string` | No | The Azure custom-voice deployment endpoint identifier. Applies only when `voice_type` is `azure-custom`. |
| `personal_voice_model` | `string` | No | The Azure personal or avatar voice model. Applies only when `voice_type` is `azure-personal` or `avatar-voice-sync`. |
| `output_audio_timestamp_types` | `VoiceAgentAudioTimestampType[]` | No | Timestamp kinds to include with output audio. Applies to every `voice_type`. _Constant:_ `word` |

- **`format`** — `OpenAI.RealtimeAudioFormatsAudioPcm | OpenAI.RealtimeAudioFormatsAudioPcmu | OpenAI.RealtimeAudioFormatsAudioPcma`

**One of the following:**

- **`audio/pcm`** — `audio/pcm (OpenAI.RealtimeAudioFormatsAudioPcm)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `audio/pcm` |
| `rate` | `enum` | No | _Constant:_ `24000` |

- **`audio/pcmu`** — `audio/pcmu (OpenAI.RealtimeAudioFormatsAudioPcmu)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `audio/pcmu` |

- **`audio/pcma`** — `audio/pcma (OpenAI.RealtimeAudioFormatsAudioPcma)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `audio/pcma` |

- **`interim_response`** — `VoiceAgentStaticInterimResponseConfig | VoiceAgentLlmInterimResponseConfig`

Fields shared by interim-response configurations.

**One of the following:**

- **`static_interim_response`** — `static_interim_response (VoiceAgentStaticInterimResponseConfig)`

A static interim response selected from configured text.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `static_interim_response` |
| `triggers` | `enum[]` | No | Conditions that may trigger one interim response. _Default:_ `["latency"]` _Enum:_ `latency`, `tool` |
| `latency_threshold_ms` | `integer` | No | The latency threshold in milliseconds. _Default:_ `2000` _Format:_ `int32` |
| `texts` | `string[]` | No | Candidate text values for the interim response. |

- **`llm_interim_response`** — `llm_interim_response (VoiceAgentLlmInterimResponseConfig)`

An interim response generated by a language model.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `llm_interim_response` |
| `triggers` | `enum[]` | No | Conditions that may trigger one interim response. _Default:_ `["latency"]` _Enum:_ `latency`, `tool` |
| `latency_threshold_ms` | `integer` | No | The latency threshold in milliseconds. _Default:_ `2000` _Format:_ `int32` |
| `model` | `string` | No | The model used to generate interim responses. |
| `instructions` | `string` | No | Optional instructions for generating interim responses. |
| `max_completion_tokens` | `integer` | No | The maximum completion-token count for an interim response. _Default:_ `50` _Format:_ `int32` |

- **`avatar`** — `VoiceAgentAvatarConfig`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The avatar type. _Enum:_ `video_avatar`, `photo_avatar` |
| `character` | `string` | Yes | The avatar character identifier, e.g. 'lisa'. |
| `style` | `string` | No | The avatar style, e.g. 'casual-sitting'. |
| `customized` | `boolean` | No | Whether the avatar is a customer-customized avatar. Defaults to false. _Default:_ `false` |
| `output_protocol` | `enum` | No | The transport used to deliver the avatar video stream. _Enum:_ `webrtc`, `websocket` |
| `model` | `string` | No | The avatar model identifier. |
| `video` | `VoiceAgentAvatarVideoParams` | No | Avatar video encoder and presentation settings. |
| `scene` | `VoiceAgentAvatarScene` | No | Avatar placement and motion settings. |
| `output_audit_audio` | `boolean` | No | Whether audit audio is emitted with avatar output. Defaults to false. _Default:_ `false` |

- **`video`** — `VoiceAgentAvatarVideoParams`

Avatar video encoder and presentation settings.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `bitrate` | `integer` | No | The target video bitrate in bits per second. _Default:_ `2000000` _Format:_ `int32` |
| `crop` | `VoiceAgentAvatarVideoCrop` | No | The rectangular crop applied to avatar video. |
| `resolution` | `VoiceAgentAvatarVideoResolution` | No | The avatar video resolution. |
| `background` | `VoiceAgentAvatarVideoBackground` | No | The avatar video background. |
| `gop_size` | `integer` | No | _Default:_ `10` _Format:_ `int32` |

- **`crop`** — `VoiceAgentAvatarVideoCrop`

The rectangular crop applied to avatar video.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `bottom_right` | `integer[]` | Yes |  |
| `top_left` | `integer[]` | Yes |  |

- **`resolution`** — `VoiceAgentAvatarVideoResolution`

The avatar video resolution.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `width` | `integer` | Yes | _Format:_ `int32` |
| `height` | `integer` | Yes | _Format:_ `int32` |

- **`background`** — `VoiceAgentAvatarVideoBackground`

The avatar video background.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `image_url` | `string` | No | _Format:_ `uri` |
| `color` | `string` | No |  |

- **`scene`** — `VoiceAgentAvatarScene`

Avatar placement and motion settings.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `zoom` | `number` | No | _Default:_ `1` _Format:_ `float` |
| `position_x` | `number` | No | _Default:_ `0` _Format:_ `float` |
| `position_y` | `number` | No | _Default:_ `0` _Format:_ `float` |
| `rotation_x` | `number` | No | _Default:_ `0` _Format:_ `float` |
| `rotation_y` | `number` | No | _Default:_ `0` _Format:_ `float` |
| `rotation_z` | `number` | No | _Default:_ `0` _Format:_ `float` |
| `amplitude` | `number` | No | _Default:_ `1` _Format:_ `float` |

- **`tools`** — `(VoiceAgentFunctionTool | VoiceAgentMcpTool | VoiceAgentSystemTool | VoiceAgentToolboxTool)[]`

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.

**One of the following:**

- **`function`** — `function (VoiceAgentFunctionTool)`

A native function tool executed by the client.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `function` |
| `description` | `string` | No | The description of the function, including guidance on when and how to call it, and guidance about what to tell the user when calling (if anything). |
| `parameters` | `OpenAI.RealtimeFunctionToolParameters` | No |  |
| `name` | `string` | Yes | The function name. |

- **`mcp`** — `mcp (VoiceAgentMcpTool)`

An MCP tool available to a voice agent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `mcp` |
| `server_label` | `string` | Yes | A label for this MCP server, used to identify it in tool calls. |
| `authorization` | `string` | No | An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. |
| `server_description` | `string` | No | Optional description of the MCP server, used to provide more context. |
| `headers` | `object \| null` | No |  |
| `allowed_tools` | `string[] \| OpenAI.MCPToolFilter \| null` | No |  |
| `allowed_callers` | `enum` | No | _Enum:_ `direct`, `programmatic` |
| `require_approval` | `OpenAI.MCPToolRequireApproval \| enum \| null` | No | _Default:_ `"always"` _Enum:_ `always`, `never` |
| `defer_loading` | `boolean` | No | Whether this MCP tool is deferred and discovered via tool search. |
| `project_connection_id` | `string` | No | The connection ID in the project for the MCP server. The connection stores authentication and other connection details needed to connect to the MCP server. |
| `tool_configs` | `object` | No | Deprecated. This property is deprecated and will be removed in a future version. |
| `server_url` | `string` | No | The URL for the MCP server. _Format:_ `uri` |
| `response_scheduling` | `enum` | No | When a tool invocation creates a follow-up response. Additional values may be added over time. _Enum:_ `silent`, `when_idle`, `interrupt`, `skip_if_busy` |

- **`allowed_tools`** — `string[] | OpenAI.MCPToolFilter | null`

**One of the following:**

- **`string[]`** — `string[]`

Type: `string[]`

- **`OpenAI.MCPToolFilter`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`require_approval`** — `OpenAI.MCPToolRequireApproval | enum | null`

**One of the following:**

- **`OpenAI.MCPToolRequireApproval`** — `OpenAI.MCPToolRequireApproval`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `always` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |
| `never` | `OpenAI.MCPToolFilter` | No | A filter object to specify which tools are allowed. |

- **`always`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`never`** — `OpenAI.MCPToolFilter`

A filter object to specify which tools are allowed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `tool_names` | `string[]` | No | List of allowed tool names. |
| `read_only` | `boolean` | No | Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. |

- **`enum`** — `enum`

| Type | Description |
|------|-------------|
| `enum` | _Enum:_ `always`, `never` |

- **`null`** — `null`

| Type | Description |
|------|-------------|
| `null` | — |

- **`system`** — `system (VoiceAgentSystemTool)`

A service-managed control that acts on the active voice session without customer code or external authentication.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `system`. _Constant:_ `system` |
| `name` | `enum` | Yes | A service-managed voice-session control action. Known values are stable; additional values may be added over time. _Constant:_ `end_conversation` |
| `description` | `string` | No | An optional description of the system tool. |

- **`toolbox`** — `toolbox (VoiceAgentToolboxTool)`

A reference to a Foundry toolbox, which is a versioned bundle of tools executed through its MCP endpoint.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `toolbox`. _Constant:_ `toolbox` |
| `toolbox_name` | `string` | Yes | The name of the toolbox to attach. |
| `toolbox_version` | `string` | Yes | The immutable version of the toolbox to attach. |
| `response_scheduling` | `enum` | No | When a tool invocation creates a follow-up response. Additional values may be added over time. _Enum:_ `silent`, `when_idle`, `interrupt`, `skip_if_busy` |

- **`tool_choice`** — `enum | OpenAI.ToolChoiceFunction | OpenAI.ToolChoiceMCP`

Tool-selection behavior for a voice agent.

**One of the following:**

- **`enum`** — `enum`

| Type | Description |
|------|-------------|
| `enum` | _Enum:_ `none`, `auto`, `required` |

- **`OpenAI.ToolChoiceFunction`** — `OpenAI.ToolChoiceFunction`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For function calling, the type is always `function`. _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |

- **`OpenAI.ToolChoiceMCP`** — `OpenAI.ToolChoiceMCP`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | For MCP tools, the type is always `mcp`. _Constant:_ `mcp` |
| `server_label` | `string` | Yes | The label of the MCP server to use. |
| `name` | `string \| null` | No |  |

- **`subagent_config`** — `VoiceAgentSubagentConfig`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `subagents` | `VoiceAgentSubagent[]` | Yes | The sibling Foundry text agents, in the same project, that this voice agent may consult. |

- **`subagents`** — `VoiceAgentSubagent[]`

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

**Array of** `VoiceAgentSubagent`**:**

A sibling Foundry text agent that a voice agent may consult as a background specialist.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `agent_name` | `string` | Yes | The name of the subagent. The subagent must be in the same project as the voice agent. |
| `agent_version` | `string` | No | The version of the subagent. When omitted, the active version is used. |
| `agent_capabilities` | `string` | Yes | A description of the subagent's capabilities, used by the voice agent to decide whether to forward a query. |
| `response_policy` | `VoiceAgentSubagentResponsePolicy` | No | Policy for delivering responses while a voice agent waits for a subagent. |
| `invoke_timeout_seconds` | `integer` | No | The wall-clock timeout, in seconds, for each invocation of this subagent. When omitted, the service timeout is used. _Format:_ `int32` |

- **`response_policy`** — `VoiceAgentSubagentResponsePolicy`

Policy for delivering responses while a voice agent waits for a subagent.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `immediate_ack` | `boolean` | No | Whether the voice agent provides an immediate acknowledgement before forwarding a request to a subagent. |
| `gap_filling_interval` | `integer` | No | The number of seconds without subagent content or user input before the voice agent provides a gap-filling response. _Format:_ `int32` |
| `ack_instructions` | `string` | No | Instructions used to generate the immediate acknowledgement. |
| `gap_filling_instructions` | `string` | No | Instructions used to generate gap-filling speech while waiting for progress. |
| `enable_delta_progress` | `boolean` | No | Whether progress updates are emitted incrementally instead of only when the subagent invocation completes. Defaults to `false`. _Default:_ `false` |
| `progress_instructions` | `string` | No | Instructions used to summarize streamed subagent progress for speech. |
| `progress_update_interval` | `integer` | No | The minimum number of seconds between spoken progress updates. _Format:_ `int32` |

###### `instance_identity` — `AgentIdentity`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `principal_id` | `string` | Yes | The principal ID of the agent instance |
| `client_id` | `string` | Yes | The client ID of the agent instance. Also referred to as the instance ID |
| `status` | `enum` | No | The status of an agent identity, applicable to both the agent instance identity and the agent blueprint. _Enum:_ `active`, `disabled` |

###### `blueprint` — `AgentIdentity`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `principal_id` | `string` | Yes | The principal ID of the agent instance |
| `client_id` | `string` | Yes | The client ID of the agent instance. Also referred to as the instance ID |
| `status` | `enum` | No | The status of an agent identity, applicable to both the agent instance identity and the agent blueprint. _Enum:_ `active`, `disabled` |

###### `blueprint_reference` — `ManagedAgentIdentityBlueprintReference`

**One of the following:**

- **`ManagedAgentIdentityBlueprint`** — `ManagedAgentIdentityBlueprint (ManagedAgentIdentityBlueprintReference)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `ManagedAgentIdentityBlueprint` |
| `blueprint_id` | `string` | Yes | The ID of the managed blueprint |

#### `agent_endpoint` — `AgentEndpointConfig`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `version_selector` | `VersionSelector` | No |  |
| `protocol_configuration` | `ProtocolConfiguration` | No | Per-protocol configuration for the agent endpoint. |
| `authorization_schemes` | `(EntraAuthorizationScheme \| BotServiceAuthorizationScheme \| BotServiceRbacAuthorizationScheme \| BotServiceTenantAuthorizationScheme)[]` | No | The authorization schemes supported by the agent endpoint |
| `publish_approval_status` | `enum` | No | The Microsoft Agent Certification review status of the Microsoft 365 store title published for an agent. _Enum:_ `not_published`, `pending`, `approved`, `rejected`, `no_approval_needed` |

##### `version_selector` — `VersionSelector`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `version_selection_rules` | `FixedRatioVersionSelectionRule[]` | Yes |  |

###### `version_selection_rules` — `FixedRatioVersionSelectionRule[]`

**One of the following:**

- **`FixedRatio`** — `FixedRatio (FixedRatioVersionSelectionRule)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `FixedRatio` |
| `agent_version` | `string` | Yes | The agent version to route traffic to |
| `traffic_percentage` | `integer` | Yes | The percentage of traffic to route to the version. Must be between 0 and 100. _Format:_ `int32` |

##### `protocol_configuration` — `ProtocolConfiguration`

Per-protocol configuration for the agent endpoint.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `activity` | `ActivityProtocolConfiguration` | No | Configuration specific to the activity protocol. |
| `responses` | `ResponsesProtocolConfiguration` | No | Configuration specific to the responses protocol. |
| `a2a` | `A2AProtocolConfiguration` | No | Configuration specific to the A2A protocol. |
| `mcp` | `McpProtocolConfiguration` | No | Configuration specific to the MCP protocol. |
| `invocations` | `InvocationsProtocolConfiguration` | No | Configuration specific to the invocations protocol. |
| `invocations_ws` | `InvocationsWsProtocolConfiguration` | No | Configuration specific to the WebSocket-based invocations protocol. |

###### `activity` — `ActivityProtocolConfiguration`

Configuration specific to the activity protocol.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `enable_m365_public_endpoint` | `boolean` | No | Whether to enable the M365 public endpoint for the activity protocol. |
| `access_boundaries` | `enum[]` | No | The access boundaries for the activity protocol. _Enum:_ `read.1on1.developers`, `read.1on1.manager`, `read.1on1.allowlisted`, `read.1on1.tenant`, `write.1on1.developers`, `write.1on1.manager`, `write.1on1.allowlisted`, `write.1on1.tenant`, `read.group.developers`, `read.group.allowlisted`, `read.group.manager-invited`, `read.group.manager-present`, `read.group.tenant`, `write.group.developers`, `write.group.allowlisted`, `write.group.manager-invited`, `write.group.manager-present`, `write.group.tenant` |

##### `authorization_schemes` — `(EntraAuthorizationScheme | BotServiceAuthorizationScheme | BotServiceRbacAuthorizationScheme | BotServiceTenantAuthorizationScheme)[]`

The authorization schemes supported by the agent endpoint

**One of the following:**

###### `Entra` — `Entra (EntraAuthorizationScheme)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `Entra` |

###### `BotService` — `BotService (BotServiceAuthorizationScheme)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `BotService` |

###### `BotServiceRbac` — `BotServiceRbac (BotServiceRbacAuthorizationScheme)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `BotServiceRbac` |

###### `BotServiceTenant` — `BotServiceTenant (BotServiceTenantAuthorizationScheme)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `BotServiceTenant` |

#### `instance_identity` — `AgentIdentity`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `principal_id` | `string` | Yes | The principal ID of the agent instance |
| `client_id` | `string` | Yes | The client ID of the agent instance. Also referred to as the instance ID |
| `status` | `enum` | No | The status of an agent identity, applicable to both the agent instance identity and the agent blueprint. _Enum:_ `active`, `disabled` |

#### `blueprint` — `AgentIdentity`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `principal_id` | `string` | Yes | The principal ID of the agent instance |
| `client_id` | `string` | Yes | The client ID of the agent instance. Also referred to as the instance ID |
| `status` | `enum` | No | The status of an agent identity, applicable to both the agent instance identity and the agent blueprint. _Enum:_ `active`, `disabled` |

#### `blueprint_reference` — `ManagedAgentIdentityBlueprintReference`

**One of the following:**

##### `ManagedAgentIdentityBlueprint` — `ManagedAgentIdentityBlueprint (ManagedAgentIdentityBlueprintReference)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `ManagedAgentIdentityBlueprint` |
| `blueprint_id` | `string` | Yes | The ID of the managed blueprint |

#### `agent_card` — `AgentCard`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `version` | `string` | Yes | The version of the agent card. |
| `description` | `string` | No | The description of the agent card. |
| `skills` | `AgentCardSkill[]` | Yes | The set of skills that an agent can perform. |

##### `skills` — `AgentCardSkill[]`

The set of skills that an agent can perform.

**Array of** `AgentCardSkill`**:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes | a unique identifier for the skill |
| `name` | `string` | Yes | The name of the skill |
| `description` | `string` | No | A description of the skill |
| `tags` | `AgentCardSkillTag[]` | No | set of tagwords describing classes of capabilities for the skill |
| `examples` | `AgentCardSkillExample[]` | No | A list of example scenarios that the skill can perform. |

### 4XX — Client error

Content-Type: `application/json`

Error response for API failures.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `OpenAI.Error` | Yes |  |

#### `error` — `OpenAI.Error`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string \| null` | Yes |  |
| `message` | `string` | Yes |  |
| `param` | `string \| null` | No |  |
| `type` | `string` | No |  |
| `misalignment` | `OpenAI.MisalignmentErrorDetailsResource` | No |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |

##### `misalignment` — `OpenAI.MisalignmentErrorDetailsResource`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error_type` | `enum` | No | _Enum:_ `potentially_unintended_data_transfer`, `potentially_unintended_data_access`, `potentially_unintended_destructive_activity`, `other` |
| `detailed_explanation` | `string` | No | The public explanation for this block. |
| `steer` | `OpenAI._MisalignmentSteer` | No |  |

###### `steer` — `OpenAI._MisalignmentSteer`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `message` | `string` | Yes | The public continuation instruction. |

### 5XX — Server error

Content-Type: `application/json`

Error response for API failures.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `OpenAI.Error` | Yes |  |

#### `error` — `OpenAI.Error`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string \| null` | Yes |  |
| `message` | `string` | Yes |  |
| `param` | `string \| null` | No |  |
| `type` | `string` | No |  |
| `misalignment` | `OpenAI.MisalignmentErrorDetailsResource` | No |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |

##### `misalignment` — `OpenAI.MisalignmentErrorDetailsResource`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error_type` | `enum` | No | _Enum:_ `potentially_unintended_data_transfer`, `potentially_unintended_data_access`, `potentially_unintended_destructive_activity`, `other` |
| `detailed_explanation` | `string` | No | The public explanation for this block. |
| `steer` | `OpenAI._MisalignmentSteer` | No |  |

###### `steer` — `OpenAI._MisalignmentSteer`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `message` | `string` | Yes | The public continuation instruction. |