# Create an agent

`POST /agents`

Creates a new agent or a new version of an existing agent.

## 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` | `AgentDefinitionOptInKeys` | No | A feature flag opt-in required when using preview operations or modifying persisted preview resources. _Enum:_ `HostedAgents=V1Preview`, `WorkflowAgents=V1Preview`, `AgentEndpoints=V1Preview`, `CodeAgents=V1Preview`, `ExternalAgents=V1Preview` |
| `x-ms-agent-name` | `string` | No | The unique name that identifies the agent. Max 63 chars, must start and end with alphanumeric, hyphens allowed in the middle. |
| `x-ms-code-zip-sha256` | `string` | No | SHA-256 hex digest of the uploaded code zip. Used for change detection (dedup) and integrity verification. |

## Request Body

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent. - Must start and end with alphanumeric characters, - Can contain hyphens in the middle - Must not exceed 63 characters. |
| `metadata` | `object` | No | 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. |
| `description` | `string` | No | A human-readable description of the agent. |
| `definition` | `HostedAgentDefinition \| PromptAgentDefinition \| WorkflowAgentDefinition \| ExternalAgentDefinition` | Yes | The agent definition. This can be a workflow, hosted agent, or a simple agent definition. |
| `blueprint_reference` | `ManagedAgentIdentityBlueprintReference` | No | The blueprint reference for the agent. |
| `agent_endpoint` | `AgentEndpointConfig` | No | An optional endpoint configuration. If not specified, a default endpoint configuration will be set for the agent |
| `agent_card` | `AgentCard` | No | Optional agent card for the agent |

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

The agent definition. This can be a workflow, hosted agent, or a simple agent definition.

**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. |
| `tools` | `(BingGroundingTool \| MicrosoftFabricPreviewTool \| SharepointPreviewTool \| AzureAISearchTool \| OpenApiTool \| BingCustomSearchPreviewTool \| BrowserAutomationPreviewTool \| AzureFunctionTool \| CaptureStructuredOutputsTool \| A2APreviewTool \| WorkIQPreviewTool \| FabricIQPreviewTool \| MemorySearchPreviewTool \| ToolboxSearchPreviewTool \| OpenAI.CodeInterpreterTool \| OpenAI.FunctionTool \| OpenAI.FileSearchTool \| OpenAI.ComputerUsePreviewTool \| OpenAI.WebSearchTool \| OpenAI.MCPTool \| OpenAI.ImageGenTool \| OpenAI.LocalShellToolParam \| OpenAI.FunctionShellToolParam \| OpenAI.CustomToolParam \| OpenAI.WebSearchPreviewTool \| OpenAI.ApplyPatchToolParam \| OpenAI.ComputerTool \| OpenAI.NamespaceToolParam \| OpenAI.ToolSearchToolParam)[]` | No | An array of tools the hosted agent's model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. |
| `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. Provide this for image-based deployments. Mutually exclusive with code_configuration — the service validates that exactly one is set. |
| `protocol_versions` | `ProtocolVersionRecord[]` | No | The protocols that the agent supports for ingress communication. |
| `code_configuration` | `CodeConfiguration` | No | Code-based deployment configuration. Provide this for code-based deployments. Mutually exclusive with container_configuration — the service validates that exactly one is set. |
| `telemetry_config` | `TelemetryConfig` | No | Optional customer-supplied telemetry configuration for exporting container logs, traces, and metrics. |

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

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

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

**One of the following:**

###### `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `azure_ai_search` | `AzureAISearchToolResource` | Yes | The azure ai search index resource. |

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

The azure ai search index resource.

| 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 | Type of query in an AIIndexResource attached to this agent. _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` |
| `openapi` | `OpenApiFunctionDefinition` | Yes | The openapi function definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The openapi function definition.

| 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 | Open API authentication details |
| `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`

Open API authentication details

**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 | Project connection auth security details |

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

Project connection auth security details

| 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 | Connection auth security details |

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

Connection auth security details

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `browser_automation_preview` | `BrowserAutomationToolParameters` | Yes | The Browser Automation Tool parameters. |

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

The Browser Automation Tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `connection` | `BrowserAutomationToolConnectionParameters` | Yes | The project connection parameters associated with the Browser Automation Tool. |

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

The project connection parameters associated with 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` |
| `azure_function` | `AzureFunctionDefinition` | Yes | The Azure Function Tool definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The Azure Function Tool definition.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `function` | `object` | Yes | The definition of azure function and its parameters. |
| `input_binding` | `AzureFunctionBinding` | Yes | Input storage queue. The queue storage trigger runs a function as messages are added to it. |
| `output_binding` | `AzureFunctionBinding` | Yes | Output storage queue. The function writes output to this queue when the input items are processed. |

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

Input storage queue. The queue storage trigger runs a function as messages are added to it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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`

Output storage queue. The function writes output to this queue when the input items are processed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `outputs` | `StructuredOutputDefinition` | Yes | The structured outputs to capture from the model. |

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

The structured outputs to capture from the model.

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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. |

###### `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. |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

###### `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"` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

###### `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Options for searching the memory store. |
| `update_delay` | `integer` | No | Time to wait before updating memories after inactivity (seconds). Default 300. _Default:_ `300` _Format:_ `int32` |

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

Options for searching the memory store.

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

###### `toolbox_search_preview` — `toolbox_search_preview (ToolboxSearchPreviewTool)`

A tool for searching over the agent's toolbox. When present, deferred tools are hidden from `tools/list` and only discoverable via `search_tools` queries at runtime.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `toolbox_search_preview`. _Constant:_ `toolbox_search_preview` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

###### `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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`. _Default:_ `"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`. _Default:_ `"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`. _Default:_ `"function"` _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |
| `description` | `string \| null` | No |  |
| `parameters` | `object \| null` | Yes |  |
| `strict` | `boolean \| null` | Yes |  |
| `defer_loading` | `boolean` | No | Whether this function is deferred and loaded via tool search. |

###### `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`. _Default:_ `"file_search"` _Constant:_ `file_search` |
| `vector_store_ids` | `string[]` | Yes | The IDs of the vector stores to search. |
| `max_num_results` | `OpenAI.integer` | No | The maximum number of results to return. This number should be between 1 and 50 inclusive. _Format:_ `int64` |
| `ranking_options` | `OpenAI.RankingOptions` | No | Ranking options for search. |
| `filters` | `OpenAI.ComparisonFilter \| OpenAI.CompoundFilter \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Ranking options for search.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ranker` | `OpenAI.RankerVersionType` | No | The ranker to use for the file search. _Enum:_ `auto`, `default-2024-11-15` |
| `score_threshold` | `OpenAI.numeric` | No | The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. _Format:_ `double` |
| `hybrid_search` | `OpenAI.HybridSearchOptions` | No | Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. |

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

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `embedding_weight` | `OpenAI.numeric` | Yes | The weight of the embedding in the reciprocal ranking fusion. _Format:_ `double` |
| `text_weight` | `OpenAI.numeric` | Yes | The weight of the text in the reciprocal ranking fusion. _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`. _Default:_ `"computer_use_preview"` _Constant:_ `computer_use_preview` |
| `environment` | `OpenAI.ComputerEnvironment` | Yes | The type of computer environment to control. _Enum:_ `windows`, `mac`, `linux`, `ubuntu`, `browser` |
| `display_width` | `OpenAI.integer` | Yes | The width of the computer display. _Format:_ `int64` |
| `display_height` | `OpenAI.integer` | Yes | The height of the computer display. _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`. _Default:_ `"web_search"` _Constant:_ `web_search` |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `custom_search_configuration` | `WebSearchConfiguration` | No | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

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

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

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

###### `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` or `connector_id` must be provided. _Format:_ `uri` |
| `connector_id` | `enum` | No | Identifier for service connectors, like those available in ChatGPT. One of `server_url` or `connector_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` |
| `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 |  |
| `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 | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

###### `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`. _Default:_ `"image_generation"` _Constant:_ `image_generation` |
| `model` | `enum` | No | _Default:_ `"gpt-image-1"` _Enum:_ `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5` |
| `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 | Compression level for the output image. Default: 100. _Default:_ `100` _Format:_ `int64` |
| `moderation` | `enum` | No | Moderation level for the generated image. Default: `auto`. _Default:_ `"auto"` _Enum:_ `auto`, `low` |
| `background` | `enum` | No | Background type for the generated image. One of `transparent`, `opaque`, or `auto`. Default: `auto`. _Default:_ `"auto"` _Enum:_ `transparent`, `opaque`, `auto` |
| `input_fidelity` | `enum` | No | _Enum:_ `high`, `low` |
| `input_image_mask` | `OpenAI.ImageGenToolInputImageMask` | No | Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). |
| `partial_images` | `OpenAI.integer` | No | Number of partial images to generate in streaming mode, from 0 (default value) to 3. _Format:_ `int64` |
| `action` | `OpenAI.ImageGenActionEnum` | No | Whether to generate a new image or edit an existing image. Default: `auto`. _Enum:_ `generate`, `edit`, `auto` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).

| 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`. _Default:_ `"local_shell"` _Constant:_ `local_shell` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

###### `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`. _Default:_ `"shell"` _Constant:_ `shell` |
| `environment` | `OpenAI.FunctionShellToolParamEnvironment \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`environment`** — `OpenAI.FunctionShellToolParamEnvironment | null`

**One of the following:**

- **`OpenAI.FunctionShellToolParamEnvironment`** — `OpenAI.FunctionShellToolParamEnvironment`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Enum:_ `container_auto`, `local`, `container_reference` |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"web_search_preview"` _Constant:_ `web_search_preview` |
| `user_location` | `OpenAI.ApproximateLocation \| null` | No |  |
| `search_context_size` | `OpenAI.SearchContextSize` | 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. _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`. _Default:_ `"apply_patch"` _Constant:_ `apply_patch` |

###### `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`. _Default:_ `"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`. _Default:_ `"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` |
| `defer_loading` | `boolean` | No | Whether this function should be deferred and discovered via tool search. |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"tool_search"` _Constant:_ `tool_search` |
| `execution` | `OpenAI.ToolSearchExecutionType` | No | Whether tool search is executed by the server or by the client. _Enum:_ `server`, `client` |
| `description` | `string \| null` | No |  |
| `parameters` | `OpenAI.EmptyModelParam \| null` | No |  |

##### `container_configuration` — `ContainerConfiguration`

Container-based deployment configuration. Provide this for image-based deployments. Mutually exclusive with code_configuration — the service validates that exactly one is set.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `image` | `string` | Yes | The container image for the hosted agent. |

##### `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 | The protocol type. _Enum:_ `activity_protocol`, `responses`, `mcp`, `invocations`, `invocations_ws` |
| `version` | `string` | Yes | The version string for the protocol, e.g. 'v0.1.1'. |

##### `code_configuration` — `CodeConfiguration`

Code-based deployment configuration. Provide this for code-based deployments. Mutually exclusive with container_configuration — the service validates that exactly one is set.

| 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. Defaults to `bundled`, where the caller bundles all dependencies into the uploaded zip and the service performs no remote build. `remote_build` instructs the service to build dependencies remotely from the manifest included in the uploaded zip. _Default:_ `"bundled"` _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`

Optional 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 | Optional authentication configuration. |
| `endpoint` | `string` | Yes | The OTLP collector endpoint URL. |
| `protocol` | `enum` | Yes | The transport protocol for the OTLP endpoint. _Enum:_ `Http`, `Grpc` |

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

Optional authentication configuration.

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

#### `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. |
| `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. |
| `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` | `(BingGroundingTool \| MicrosoftFabricPreviewTool \| SharepointPreviewTool \| AzureAISearchTool \| OpenApiTool \| BingCustomSearchPreviewTool \| BrowserAutomationPreviewTool \| AzureFunctionTool \| CaptureStructuredOutputsTool \| A2APreviewTool \| WorkIQPreviewTool \| FabricIQPreviewTool \| MemorySearchPreviewTool \| ToolboxSearchPreviewTool \| OpenAI.CodeInterpreterTool \| OpenAI.FunctionTool \| OpenAI.FileSearchTool \| OpenAI.ComputerUsePreviewTool \| OpenAI.WebSearchTool \| OpenAI.MCPTool \| 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.ToolChoiceParam` | 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. |

##### `reasoning` — `OpenAI.Reasoning | null`

**One of the following:**

###### `OpenAI.Reasoning` — `OpenAI.Reasoning`

**gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `effort` | `enum` | No | Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is supported for all models after `gpt-5.1-codex-max`. _Enum:_ `none`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| `summary` | `enum` | No | _Enum:_ `auto`, `concise`, `detailed` |
| `generate_summary` | `enum` | No | _Enum:_ `auto`, `concise`, `detailed` |

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

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

##### `tools` — `(BingGroundingTool | MicrosoftFabricPreviewTool | SharepointPreviewTool | AzureAISearchTool | OpenApiTool | BingCustomSearchPreviewTool | BrowserAutomationPreviewTool | AzureFunctionTool | CaptureStructuredOutputsTool | A2APreviewTool | WorkIQPreviewTool | FabricIQPreviewTool | MemorySearchPreviewTool | ToolboxSearchPreviewTool | OpenAI.CodeInterpreterTool | OpenAI.FunctionTool | OpenAI.FileSearchTool | OpenAI.ComputerUsePreviewTool | OpenAI.WebSearchTool | OpenAI.MCPTool | 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:**

###### `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `azure_ai_search` | `AzureAISearchToolResource` | Yes | The azure ai search index resource. |

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

The azure ai search index resource.

| 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 | Type of query in an AIIndexResource attached to this agent. _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` |
| `openapi` | `OpenApiFunctionDefinition` | Yes | The openapi function definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The openapi function definition.

| 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 | Open API authentication details |
| `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`

Open API authentication details

**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 | Project connection auth security details |

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

Project connection auth security details

| 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 | Connection auth security details |

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

Connection auth security details

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `browser_automation_preview` | `BrowserAutomationToolParameters` | Yes | The Browser Automation Tool parameters. |

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

The Browser Automation Tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `connection` | `BrowserAutomationToolConnectionParameters` | Yes | The project connection parameters associated with the Browser Automation Tool. |

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

The project connection parameters associated with 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` |
| `azure_function` | `AzureFunctionDefinition` | Yes | The Azure Function Tool definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The Azure Function Tool definition.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `function` | `object` | Yes | The definition of azure function and its parameters. |
| `input_binding` | `AzureFunctionBinding` | Yes | Input storage queue. The queue storage trigger runs a function as messages are added to it. |
| `output_binding` | `AzureFunctionBinding` | Yes | Output storage queue. The function writes output to this queue when the input items are processed. |

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

Input storage queue. The queue storage trigger runs a function as messages are added to it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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`

Output storage queue. The function writes output to this queue when the input items are processed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `outputs` | `StructuredOutputDefinition` | Yes | The structured outputs to capture from the model. |

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

The structured outputs to capture from the model.

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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. |

###### `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. |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

###### `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"` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

###### `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Options for searching the memory store. |
| `update_delay` | `integer` | No | Time to wait before updating memories after inactivity (seconds). Default 300. _Default:_ `300` _Format:_ `int32` |

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

Options for searching the memory store.

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

###### `toolbox_search_preview` — `toolbox_search_preview (ToolboxSearchPreviewTool)`

A tool for searching over the agent's toolbox. When present, deferred tools are hidden from `tools/list` and only discoverable via `search_tools` queries at runtime.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `toolbox_search_preview`. _Constant:_ `toolbox_search_preview` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

###### `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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`. _Default:_ `"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`. _Default:_ `"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`. _Default:_ `"function"` _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |
| `description` | `string \| null` | No |  |
| `parameters` | `object \| null` | Yes |  |
| `strict` | `boolean \| null` | Yes |  |
| `defer_loading` | `boolean` | No | Whether this function is deferred and loaded via tool search. |

###### `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`. _Default:_ `"file_search"` _Constant:_ `file_search` |
| `vector_store_ids` | `string[]` | Yes | The IDs of the vector stores to search. |
| `max_num_results` | `OpenAI.integer` | No | The maximum number of results to return. This number should be between 1 and 50 inclusive. _Format:_ `int64` |
| `ranking_options` | `OpenAI.RankingOptions` | No | Ranking options for search. |
| `filters` | `OpenAI.ComparisonFilter \| OpenAI.CompoundFilter \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Ranking options for search.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ranker` | `OpenAI.RankerVersionType` | No | The ranker to use for the file search. _Enum:_ `auto`, `default-2024-11-15` |
| `score_threshold` | `OpenAI.numeric` | No | The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. _Format:_ `double` |
| `hybrid_search` | `OpenAI.HybridSearchOptions` | No | Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. |

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

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `embedding_weight` | `OpenAI.numeric` | Yes | The weight of the embedding in the reciprocal ranking fusion. _Format:_ `double` |
| `text_weight` | `OpenAI.numeric` | Yes | The weight of the text in the reciprocal ranking fusion. _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`. _Default:_ `"computer_use_preview"` _Constant:_ `computer_use_preview` |
| `environment` | `OpenAI.ComputerEnvironment` | Yes | The type of computer environment to control. _Enum:_ `windows`, `mac`, `linux`, `ubuntu`, `browser` |
| `display_width` | `OpenAI.integer` | Yes | The width of the computer display. _Format:_ `int64` |
| `display_height` | `OpenAI.integer` | Yes | The height of the computer display. _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`. _Default:_ `"web_search"` _Constant:_ `web_search` |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `custom_search_configuration` | `WebSearchConfiguration` | No | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

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

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

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

###### `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` or `connector_id` must be provided. _Format:_ `uri` |
| `connector_id` | `enum` | No | Identifier for service connectors, like those available in ChatGPT. One of `server_url` or `connector_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` |
| `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 |  |
| `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 | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

###### `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`. _Default:_ `"image_generation"` _Constant:_ `image_generation` |
| `model` | `enum` | No | _Default:_ `"gpt-image-1"` _Enum:_ `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5` |
| `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 | Compression level for the output image. Default: 100. _Default:_ `100` _Format:_ `int64` |
| `moderation` | `enum` | No | Moderation level for the generated image. Default: `auto`. _Default:_ `"auto"` _Enum:_ `auto`, `low` |
| `background` | `enum` | No | Background type for the generated image. One of `transparent`, `opaque`, or `auto`. Default: `auto`. _Default:_ `"auto"` _Enum:_ `transparent`, `opaque`, `auto` |
| `input_fidelity` | `enum` | No | _Enum:_ `high`, `low` |
| `input_image_mask` | `OpenAI.ImageGenToolInputImageMask` | No | Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). |
| `partial_images` | `OpenAI.integer` | No | Number of partial images to generate in streaming mode, from 0 (default value) to 3. _Format:_ `int64` |
| `action` | `OpenAI.ImageGenActionEnum` | No | Whether to generate a new image or edit an existing image. Default: `auto`. _Enum:_ `generate`, `edit`, `auto` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).

| 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`. _Default:_ `"local_shell"` _Constant:_ `local_shell` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

###### `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`. _Default:_ `"shell"` _Constant:_ `shell` |
| `environment` | `OpenAI.FunctionShellToolParamEnvironment \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`environment`** — `OpenAI.FunctionShellToolParamEnvironment | null`

**One of the following:**

- **`OpenAI.FunctionShellToolParamEnvironment`** — `OpenAI.FunctionShellToolParamEnvironment`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Enum:_ `container_auto`, `local`, `container_reference` |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"web_search_preview"` _Constant:_ `web_search_preview` |
| `user_location` | `OpenAI.ApproximateLocation \| null` | No |  |
| `search_context_size` | `OpenAI.SearchContextSize` | 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. _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`. _Default:_ `"apply_patch"` _Constant:_ `apply_patch` |

###### `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`. _Default:_ `"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`. _Default:_ `"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` |
| `defer_loading` | `boolean` | No | Whether this function should be deferred and discovered via tool search. |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"tool_search"` _Constant:_ `tool_search` |
| `execution` | `OpenAI.ToolSearchExecutionType` | No | Whether tool search is executed by the server or by the client. _Enum:_ `server`, `client` |
| `description` | `string \| null` | No |  |
| `parameters` | `OpenAI.EmptyModelParam \| null` | No |  |

##### `tool_choice` — `string | OpenAI.ToolChoiceParam`

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

**One of the following:**

###### `string` — `string`

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

###### `OpenAI.ToolChoiceParam` — `OpenAI.ToolChoiceParam`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Enum:_ `allowed_tools`, `function`, `mcp`, `custom`, `apply_patch`, `shell`, `file_search`, `web_search_preview`, `computer_use_preview`, `web_search_preview_2025_03_11`, `image_generation`, `code_interpreter`, `computer`, `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.

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

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

### `blueprint_reference` — `ManagedAgentIdentityBlueprintReference`

The blueprint reference for the agent.

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

An optional endpoint configuration. If not specified, a default endpoint configuration will be set for the agent

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `version_selector` | `VersionSelector` | No | The version selector of the agent endpoint determines how traffic is routed to different versions of the agent. |
| `protocols` | `enum[]` | No | The protocols that the agent supports _Enum:_ `activity`, `responses`, `a2a`, `mcp`, `invocations`, `invocations_ws` |
| `authorization_schemes` | `(EntraAuthorizationScheme \| BotServiceAuthorizationScheme \| BotServiceRbacAuthorizationScheme)[]` | No | The authorization schemes supported by the agent endpoint |

#### `version_selector` — `VersionSelector`

The version selector of the agent endpoint determines how traffic is routed to different versions of the agent.

| 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` |

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

The authorization schemes supported by the agent endpoint

**One of the following:**

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `Entra` |
| `isolation_key_source` | `EntraIsolationKeySource \| HeaderIsolationKeySource` | No | The source from which the per-user isolation key is derived for requests authorized via this scheme. Defaults to Entra-based isolation when omitted. |

###### `isolation_key_source` — `EntraIsolationKeySource | HeaderIsolationKeySource`

The source from which the per-user isolation key is derived for requests authorized via this scheme. Defaults to Entra-based isolation when omitted.

**One of the following:**

- **`Entra`** — `Entra (EntraIsolationKeySource)`

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

- **`Header`** — `Header (HeaderIsolationKeySource)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | _Constant:_ `Header` |

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

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

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

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

### `agent_card` — `AgentCard`

Optional agent card for the agent

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

## 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. |
| `versions` | `object` | Yes | The latest version of the agent. |
| `agent_endpoint` | `AgentEndpointConfig` | No | The endpoint configuration for the agent |
| `instance_identity` | `AgentIdentity` | No | The instance identity of the agent |
| `blueprint` | `AgentIdentity` | No | The blueprint for the agent |
| `blueprint_reference` | `ManagedAgentIdentityBlueprintReference` | No | The blueprint for the agent |
| `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 | The Unix timestamp (seconds) when the agent was created. _Format:_ `unixtime` |
| `definition` | `HostedAgentDefinition \| PromptAgentDefinition \| WorkflowAgentDefinition \| ExternalAgentDefinition` | Yes |  |
| `status` | `AgentVersionStatus` | No | The provisioning status of the agent version. Defaults to 'active' for non-hosted agents. For hosted agents, reflects infrastructure readiness. _Enum:_ `creating`, `active`, `failed`, `deleting`, `deleted` |
| `instance_identity` | `AgentIdentity` | No | The instance identity of the agent |
| `blueprint` | `AgentIdentity` | No | The blueprint for the agent |
| `blueprint_reference` | `ManagedAgentIdentityBlueprintReference` | No | The blueprint for the agent |
| `agent_guid` | `string` | No | The unique GUID identifier of the agent. |

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

**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. |
| `tools` | `(BingGroundingTool \| MicrosoftFabricPreviewTool \| SharepointPreviewTool \| AzureAISearchTool \| OpenApiTool \| BingCustomSearchPreviewTool \| BrowserAutomationPreviewTool \| AzureFunctionTool \| CaptureStructuredOutputsTool \| A2APreviewTool \| WorkIQPreviewTool \| FabricIQPreviewTool \| MemorySearchPreviewTool \| ToolboxSearchPreviewTool \| OpenAI.CodeInterpreterTool \| OpenAI.FunctionTool \| OpenAI.FileSearchTool \| OpenAI.ComputerUsePreviewTool \| OpenAI.WebSearchTool \| OpenAI.MCPTool \| OpenAI.ImageGenTool \| OpenAI.LocalShellToolParam \| OpenAI.FunctionShellToolParam \| OpenAI.CustomToolParam \| OpenAI.WebSearchPreviewTool \| OpenAI.ApplyPatchToolParam \| OpenAI.ComputerTool \| OpenAI.NamespaceToolParam \| OpenAI.ToolSearchToolParam)[]` | No | An array of tools the hosted agent's model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. |
| `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. Provide this for image-based deployments. Mutually exclusive with code_configuration — the service validates that exactly one is set. |
| `protocol_versions` | `ProtocolVersionRecord[]` | No | The protocols that the agent supports for ingress communication. |
| `code_configuration` | `CodeConfiguration` | No | Code-based deployment configuration. Provide this for code-based deployments. Mutually exclusive with container_configuration — the service validates that exactly one is set. |
| `telemetry_config` | `TelemetryConfig` | No | Optional customer-supplied telemetry configuration for exporting container logs, traces, and metrics. |

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

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

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

**One of the following:**

- **`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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `azure_ai_search` | `AzureAISearchToolResource` | Yes | The azure ai search index resource. |

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

The azure ai search index resource.

| 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 | Type of query in an AIIndexResource attached to this agent. _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` |
| `openapi` | `OpenApiFunctionDefinition` | Yes | The openapi function definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The openapi function definition.

| 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 | Open API authentication details |
| `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`

Open API authentication details

**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 | Project connection auth security details |

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

Project connection auth security details

| 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 | Connection auth security details |

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

Connection auth security details

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `browser_automation_preview` | `BrowserAutomationToolParameters` | Yes | The Browser Automation Tool parameters. |

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

The Browser Automation Tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `connection` | `BrowserAutomationToolConnectionParameters` | Yes | The project connection parameters associated with the Browser Automation Tool. |

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

The project connection parameters associated with 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` |
| `azure_function` | `AzureFunctionDefinition` | Yes | The Azure Function Tool definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The Azure Function Tool definition.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `function` | `object` | Yes | The definition of azure function and its parameters. |
| `input_binding` | `AzureFunctionBinding` | Yes | Input storage queue. The queue storage trigger runs a function as messages are added to it. |
| `output_binding` | `AzureFunctionBinding` | Yes | Output storage queue. The function writes output to this queue when the input items are processed. |

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

Input storage queue. The queue storage trigger runs a function as messages are added to it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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`

Output storage queue. The function writes output to this queue when the input items are processed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `outputs` | `StructuredOutputDefinition` | Yes | The structured outputs to capture from the model. |

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

The structured outputs to capture from the model.

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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. |

- **`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. |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`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"` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

- **`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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Options for searching the memory store. |
| `update_delay` | `integer` | No | Time to wait before updating memories after inactivity (seconds). Default 300. _Default:_ `300` _Format:_ `int32` |

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

Options for searching the memory store.

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

- **`toolbox_search_preview`** — `toolbox_search_preview (ToolboxSearchPreviewTool)`

A tool for searching over the agent's toolbox. When present, deferred tools are hidden from `tools/list` and only discoverable via `search_tools` queries at runtime.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `toolbox_search_preview`. _Constant:_ `toolbox_search_preview` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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`. _Default:_ `"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`. _Default:_ `"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`. _Default:_ `"function"` _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |
| `description` | `string \| null` | No |  |
| `parameters` | `object \| null` | Yes |  |
| `strict` | `boolean \| null` | Yes |  |
| `defer_loading` | `boolean` | No | Whether this function is deferred and loaded via tool search. |

- **`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`. _Default:_ `"file_search"` _Constant:_ `file_search` |
| `vector_store_ids` | `string[]` | Yes | The IDs of the vector stores to search. |
| `max_num_results` | `OpenAI.integer` | No | The maximum number of results to return. This number should be between 1 and 50 inclusive. _Format:_ `int64` |
| `ranking_options` | `OpenAI.RankingOptions` | No | Ranking options for search. |
| `filters` | `OpenAI.ComparisonFilter \| OpenAI.CompoundFilter \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Ranking options for search.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ranker` | `OpenAI.RankerVersionType` | No | The ranker to use for the file search. _Enum:_ `auto`, `default-2024-11-15` |
| `score_threshold` | `OpenAI.numeric` | No | The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. _Format:_ `double` |
| `hybrid_search` | `OpenAI.HybridSearchOptions` | No | Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. |

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

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `embedding_weight` | `OpenAI.numeric` | Yes | The weight of the embedding in the reciprocal ranking fusion. _Format:_ `double` |
| `text_weight` | `OpenAI.numeric` | Yes | The weight of the text in the reciprocal ranking fusion. _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`. _Default:_ `"computer_use_preview"` _Constant:_ `computer_use_preview` |
| `environment` | `OpenAI.ComputerEnvironment` | Yes | The type of computer environment to control. _Enum:_ `windows`, `mac`, `linux`, `ubuntu`, `browser` |
| `display_width` | `OpenAI.integer` | Yes | The width of the computer display. _Format:_ `int64` |
| `display_height` | `OpenAI.integer` | Yes | The height of the computer display. _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`. _Default:_ `"web_search"` _Constant:_ `web_search` |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `custom_search_configuration` | `WebSearchConfiguration` | No | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

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

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

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

- **`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` or `connector_id` must be provided. _Format:_ `uri` |
| `connector_id` | `enum` | No | Identifier for service connectors, like those available in ChatGPT. One of `server_url` or `connector_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` |
| `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 |  |
| `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 | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

- **`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`. _Default:_ `"image_generation"` _Constant:_ `image_generation` |
| `model` | `enum` | No | _Default:_ `"gpt-image-1"` _Enum:_ `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5` |
| `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 | Compression level for the output image. Default: 100. _Default:_ `100` _Format:_ `int64` |
| `moderation` | `enum` | No | Moderation level for the generated image. Default: `auto`. _Default:_ `"auto"` _Enum:_ `auto`, `low` |
| `background` | `enum` | No | Background type for the generated image. One of `transparent`, `opaque`, or `auto`. Default: `auto`. _Default:_ `"auto"` _Enum:_ `transparent`, `opaque`, `auto` |
| `input_fidelity` | `enum` | No | _Enum:_ `high`, `low` |
| `input_image_mask` | `OpenAI.ImageGenToolInputImageMask` | No | Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). |
| `partial_images` | `OpenAI.integer` | No | Number of partial images to generate in streaming mode, from 0 (default value) to 3. _Format:_ `int64` |
| `action` | `OpenAI.ImageGenActionEnum` | No | Whether to generate a new image or edit an existing image. Default: `auto`. _Enum:_ `generate`, `edit`, `auto` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).

| 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`. _Default:_ `"local_shell"` _Constant:_ `local_shell` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`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`. _Default:_ `"shell"` _Constant:_ `shell` |
| `environment` | `OpenAI.FunctionShellToolParamEnvironment \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`environment`** — `OpenAI.FunctionShellToolParamEnvironment | null`

**One of the following:**

- **`OpenAI.FunctionShellToolParamEnvironment`** — `OpenAI.FunctionShellToolParamEnvironment`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Enum:_ `container_auto`, `local`, `container_reference` |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"web_search_preview"` _Constant:_ `web_search_preview` |
| `user_location` | `OpenAI.ApproximateLocation \| null` | No |  |
| `search_context_size` | `OpenAI.SearchContextSize` | 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. _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`. _Default:_ `"apply_patch"` _Constant:_ `apply_patch` |

- **`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`. _Default:_ `"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`. _Default:_ `"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` |
| `defer_loading` | `boolean` | No | Whether this function should be deferred and discovered via tool search. |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"tool_search"` _Constant:_ `tool_search` |
| `execution` | `OpenAI.ToolSearchExecutionType` | No | Whether tool search is executed by the server or by the client. _Enum:_ `server`, `client` |
| `description` | `string \| null` | No |  |
| `parameters` | `OpenAI.EmptyModelParam \| null` | No |  |

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

Container-based deployment configuration. Provide this for image-based deployments. Mutually exclusive with code_configuration — the service validates that exactly one is set.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `image` | `string` | Yes | The container image for the hosted agent. |

- **`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 | The protocol type. _Enum:_ `activity_protocol`, `responses`, `mcp`, `invocations`, `invocations_ws` |
| `version` | `string` | Yes | The version string for the protocol, e.g. 'v0.1.1'. |

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

Code-based deployment configuration. Provide this for code-based deployments. Mutually exclusive with container_configuration — the service validates that exactly one is set.

| 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. Defaults to `bundled`, where the caller bundles all dependencies into the uploaded zip and the service performs no remote build. `remote_build` instructs the service to build dependencies remotely from the manifest included in the uploaded zip. _Default:_ `"bundled"` _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`

Optional 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 | Optional authentication configuration. |
| `endpoint` | `string` | Yes | The OTLP collector endpoint URL. |
| `protocol` | `enum` | Yes | The transport protocol for the OTLP endpoint. _Enum:_ `Http`, `Grpc` |

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

Optional authentication configuration.

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

- **`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. |
| `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. |
| `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` | `(BingGroundingTool \| MicrosoftFabricPreviewTool \| SharepointPreviewTool \| AzureAISearchTool \| OpenApiTool \| BingCustomSearchPreviewTool \| BrowserAutomationPreviewTool \| AzureFunctionTool \| CaptureStructuredOutputsTool \| A2APreviewTool \| WorkIQPreviewTool \| FabricIQPreviewTool \| MemorySearchPreviewTool \| ToolboxSearchPreviewTool \| OpenAI.CodeInterpreterTool \| OpenAI.FunctionTool \| OpenAI.FileSearchTool \| OpenAI.ComputerUsePreviewTool \| OpenAI.WebSearchTool \| OpenAI.MCPTool \| 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.ToolChoiceParam` | 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. |

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

**One of the following:**

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

**gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `effort` | `enum` | No | Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1. - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`. - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort. - `xhigh` is supported for all models after `gpt-5.1-codex-max`. _Enum:_ `none`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| `summary` | `enum` | No | _Enum:_ `auto`, `concise`, `detailed` |
| `generate_summary` | `enum` | No | _Enum:_ `auto`, `concise`, `detailed` |

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

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

- **`tools`** — `(BingGroundingTool | MicrosoftFabricPreviewTool | SharepointPreviewTool | AzureAISearchTool | OpenApiTool | BingCustomSearchPreviewTool | BrowserAutomationPreviewTool | AzureFunctionTool | CaptureStructuredOutputsTool | A2APreviewTool | WorkIQPreviewTool | FabricIQPreviewTool | MemorySearchPreviewTool | ToolboxSearchPreviewTool | OpenAI.CodeInterpreterTool | OpenAI.FunctionTool | OpenAI.FileSearchTool | OpenAI.ComputerUsePreviewTool | OpenAI.WebSearchTool | OpenAI.MCPTool | 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:**

- **`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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `azure_ai_search` | `AzureAISearchToolResource` | Yes | The azure ai search index resource. |

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

The azure ai search index resource.

| 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 | Type of query in an AIIndexResource attached to this agent. _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` |
| `openapi` | `OpenApiFunctionDefinition` | Yes | The openapi function definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The openapi function definition.

| 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 | Open API authentication details |
| `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`

Open API authentication details

**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 | Project connection auth security details |

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

Project connection auth security details

| 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 | Connection auth security details |

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

Connection auth security details

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `browser_automation_preview` | `BrowserAutomationToolParameters` | Yes | The Browser Automation Tool parameters. |

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

The Browser Automation Tool parameters.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `connection` | `BrowserAutomationToolConnectionParameters` | Yes | The project connection parameters associated with the Browser Automation Tool. |

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

The project connection parameters associated with 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` |
| `azure_function` | `AzureFunctionDefinition` | Yes | The Azure Function Tool definition. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

The Azure Function Tool definition.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `function` | `object` | Yes | The definition of azure function and its parameters. |
| `input_binding` | `AzureFunctionBinding` | Yes | Input storage queue. The queue storage trigger runs a function as messages are added to it. |
| `output_binding` | `AzureFunctionBinding` | Yes | Output storage queue. The function writes output to this queue when the input items are processed. |

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

Input storage queue. The queue storage trigger runs a function as messages are added to it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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`

Output storage queue. The function writes output to this queue when the input items are processed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of binding, which is always 'storage_queue'. _Constant:_ `storage_queue` |
| `storage_queue` | `AzureFunctionStorageQueue` | Yes | Storage queue. |

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

Storage queue.

| 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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `outputs` | `StructuredOutputDefinition` | Yes | The structured outputs to capture from the model. |

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

The structured outputs to capture from the model.

| 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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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. |

- **`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. |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`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"` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

- **`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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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 | Options for searching the memory store. |
| `update_delay` | `integer` | No | Time to wait before updating memories after inactivity (seconds). Default 300. _Default:_ `300` _Format:_ `int32` |

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

Options for searching the memory store.

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

- **`toolbox_search_preview`** — `toolbox_search_preview (ToolboxSearchPreviewTool)`

A tool for searching over the agent's toolbox. When present, deferred tools are hidden from `tools/list` and only discoverable via `search_tools` queries at runtime.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | The type of the tool. Always `toolbox_search_preview`. _Constant:_ `toolbox_search_preview` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`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` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `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`. _Default:_ `"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`. _Default:_ `"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`. _Default:_ `"function"` _Constant:_ `function` |
| `name` | `string` | Yes | The name of the function to call. |
| `description` | `string \| null` | No |  |
| `parameters` | `object \| null` | Yes |  |
| `strict` | `boolean \| null` | Yes |  |
| `defer_loading` | `boolean` | No | Whether this function is deferred and loaded via tool search. |

- **`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`. _Default:_ `"file_search"` _Constant:_ `file_search` |
| `vector_store_ids` | `string[]` | Yes | The IDs of the vector stores to search. |
| `max_num_results` | `OpenAI.integer` | No | The maximum number of results to return. This number should be between 1 and 50 inclusive. _Format:_ `int64` |
| `ranking_options` | `OpenAI.RankingOptions` | No | Ranking options for search. |
| `filters` | `OpenAI.ComparisonFilter \| OpenAI.CompoundFilter \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Ranking options for search.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ranker` | `OpenAI.RankerVersionType` | No | The ranker to use for the file search. _Enum:_ `auto`, `default-2024-11-15` |
| `score_threshold` | `OpenAI.numeric` | No | The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. _Format:_ `double` |
| `hybrid_search` | `OpenAI.HybridSearchOptions` | No | Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. |

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

Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `embedding_weight` | `OpenAI.numeric` | Yes | The weight of the embedding in the reciprocal ranking fusion. _Format:_ `double` |
| `text_weight` | `OpenAI.numeric` | Yes | The weight of the text in the reciprocal ranking fusion. _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`. _Default:_ `"computer_use_preview"` _Constant:_ `computer_use_preview` |
| `environment` | `OpenAI.ComputerEnvironment` | Yes | The type of computer environment to control. _Enum:_ `windows`, `mac`, `linux`, `ubuntu`, `browser` |
| `display_width` | `OpenAI.integer` | Yes | The width of the computer display. _Format:_ `int64` |
| `display_height` | `OpenAI.integer` | Yes | The height of the computer display. _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`. _Default:_ `"web_search"` _Constant:_ `web_search` |
| `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 | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |
| `custom_search_configuration` | `WebSearchConfiguration` | No | The project connections attached to this tool. There can be a maximum of 1 connection resource attached to the tool. |

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

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

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

- **`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` or `connector_id` must be provided. _Format:_ `uri` |
| `connector_id` | `enum` | No | Identifier for service connectors, like those available in ChatGPT. One of `server_url` or `connector_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` |
| `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 |  |
| `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 | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

- **`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`. _Default:_ `"image_generation"` _Constant:_ `image_generation` |
| `model` | `enum` | No | _Default:_ `"gpt-image-1"` _Enum:_ `gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5` |
| `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 | Compression level for the output image. Default: 100. _Default:_ `100` _Format:_ `int64` |
| `moderation` | `enum` | No | Moderation level for the generated image. Default: `auto`. _Default:_ `"auto"` _Enum:_ `auto`, `low` |
| `background` | `enum` | No | Background type for the generated image. One of `transparent`, `opaque`, or `auto`. Default: `auto`. _Default:_ `"auto"` _Enum:_ `transparent`, `opaque`, `auto` |
| `input_fidelity` | `enum` | No | _Enum:_ `high`, `low` |
| `input_image_mask` | `OpenAI.ImageGenToolInputImageMask` | No | Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). |
| `partial_images` | `OpenAI.integer` | No | Number of partial images to generate in streaming mode, from 0 (default value) to 3. _Format:_ `int64` |
| `action` | `OpenAI.ImageGenActionEnum` | No | Whether to generate a new image or edit an existing image. Default: `auto`. _Enum:_ `generate`, `edit`, `auto` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

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

Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).

| 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`. _Default:_ `"local_shell"` _Constant:_ `local_shell` |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`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`. _Default:_ `"shell"` _Constant:_ `shell` |
| `environment` | `OpenAI.FunctionShellToolParamEnvironment \| null` | No |  |
| `name` | `string` | No | Optional user-defined name for this tool or configuration. |
| `description` | `string` | No | Optional user-defined description for this tool or configuration. |
| `tool_configs` | `object` | No | Per-tool configuration map. Keys are tool names or `*` (catch-all default). Resolution order: exact tool name match takes priority over `*`. Unknown tool names are silently ignored at runtime. |

- **`environment`** — `OpenAI.FunctionShellToolParamEnvironment | null`

**One of the following:**

- **`OpenAI.FunctionShellToolParamEnvironment`** — `OpenAI.FunctionShellToolParamEnvironment`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Enum:_ `container_auto`, `local`, `container_reference` |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"web_search_preview"` _Constant:_ `web_search_preview` |
| `user_location` | `OpenAI.ApproximateLocation \| null` | No |  |
| `search_context_size` | `OpenAI.SearchContextSize` | 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. _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`. _Default:_ `"apply_patch"` _Constant:_ `apply_patch` |

- **`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`. _Default:_ `"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`. _Default:_ `"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` |
| `defer_loading` | `boolean` | No | Whether this function should be deferred and discovered via tool search. |

- **`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`. _Default:_ `"custom"` _Constant:_ `custom` |
| `name` | `string` | Yes | The name of the custom tool, used to identify it in tool calls. |
| `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. |

- **`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`. _Default:_ `"text"` _Constant:_ `text` |

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

A grammar defined by the user.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Grammar format. Always `grammar`. _Default:_ `"grammar"` _Constant:_ `grammar` |
| `syntax` | `OpenAI.GrammarSyntax1` | Yes | The syntax of the grammar definition. One of `lark` or `regex`. _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`. _Default:_ `"tool_search"` _Constant:_ `tool_search` |
| `execution` | `OpenAI.ToolSearchExecutionType` | No | Whether tool search is executed by the server or by the client. _Enum:_ `server`, `client` |
| `description` | `string \| null` | No |  |
| `parameters` | `OpenAI.EmptyModelParam \| null` | No |  |

- **`tool_choice`** — `string | OpenAI.ToolChoiceParam`

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

**One of the following:**

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

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

- **`OpenAI.ToolChoiceParam`** — `OpenAI.ToolChoiceParam`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Enum:_ `allowed_tools`, `function`, `mcp`, `custom`, `apply_patch`, `shell`, `file_search`, `web_search_preview`, `computer_use_preview`, `web_search_preview_2025_03_11`, `image_generation`, `code_interpreter`, `computer`, `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.

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

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

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

The instance identity of the agent

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

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

The blueprint for the agent

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

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

The blueprint for the agent

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

The endpoint configuration for the agent

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `version_selector` | `VersionSelector` | No | The version selector of the agent endpoint determines how traffic is routed to different versions of the agent. |
| `protocols` | `enum[]` | No | The protocols that the agent supports _Enum:_ `activity`, `responses`, `a2a`, `mcp`, `invocations`, `invocations_ws` |
| `authorization_schemes` | `(EntraAuthorizationScheme \| BotServiceAuthorizationScheme \| BotServiceRbacAuthorizationScheme)[]` | No | The authorization schemes supported by the agent endpoint |

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

The version selector of the agent endpoint determines how traffic is routed to different versions of the agent.

| 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` |

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

The authorization schemes supported by the agent endpoint

**One of the following:**

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | _Constant:_ `Entra` |
| `isolation_key_source` | `EntraIsolationKeySource \| HeaderIsolationKeySource` | No | The source from which the per-user isolation key is derived for requests authorized via this scheme. Defaults to Entra-based isolation when omitted. |

- **`isolation_key_source`** — `EntraIsolationKeySource | HeaderIsolationKeySource`

The source from which the per-user isolation key is derived for requests authorized via this scheme. Defaults to Entra-based isolation when omitted.

**One of the following:**

- **`Entra`** — `Entra (EntraIsolationKeySource)`

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

- **`Header`** — `Header (HeaderIsolationKeySource)`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | _Constant:_ `Header` |

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

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

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

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

#### `instance_identity` — `AgentIdentity`

The instance identity of the agent

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

#### `blueprint` — `AgentIdentity`

The blueprint for the agent

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

#### `blueprint_reference` — `ManagedAgentIdentityBlueprintReference`

The blueprint for the agent

**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 |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |

### 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 |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |