Azure AI Foundry agent: I can't Configure OpenAPI 3.0 Specified Tools

Question

Azure AI Foundry agent: I can't Configure OpenAPI 3.0 Specified Tools

Andres Garcia 5

I deployed a new agent in the Azure AI portal, but when I try to configure OpenAPI 3.0 Specified Tool from a JSON file, the process shows an error message with code 400.
User's image

Context: I want to give my agent the ability to connect to my service so it can perform some Jira tasks (like an MCP server). So, I prepared my service with some endpoints and made the corresponding JSON schema for it. After I set it and pressed the "create tool" button, I received that error message.
I am attaching my schema in a txt file.

schema.txt

Prashanth Veeragoni 5,245 Microsoft External Staff Moderator

Hi Andres Garcia,

Thanks for sharing the error details and your OpenAPI schema.

Problem:

· You get Failed to update agent - 400 Bad Request when trying to add a tool using OpenAPI 3.0 schema in Azure AI Studio.

· You are trying to allow your Azure AI Foundry Agent to connect to your Jira Service using your custom OpenAPI spec.

Diagnosis:

· HTTP 400 typically means the request payload was invalid.

· In Azure AI Agents, OpenAPI schema needs to meet stricter requirements compared to general OpenAPI validation:

o Only GET, POST methods are supported (you are OK here).

o Authentication must be specified correctly if required.

o Servers URL must be valid (not placeholder).

o Descriptions, operationId might be required.

o Some missing mandatory fields like operationId can cause 400.

Here main problems in your schema are:

1.url is "my_public_url"

Azure expects a real public URL, not a placeholder.

Missing operationId for each endpoint

Azure OpenAI expects each operation to have a unique operationId.

No authentication section

(Maybe optional, depending on your server setup)

No servers object with description field

Not critical, but sometimes Azure expects complete metadata.

How to Fix It: You need to fix at least these 2 things first:

Replace "my_public_url" with your actual endpoint URL (e.g., https://yourdomain.com).

Add operationId for every method (GET /tickets, GET /tickets/{ticketKey}, POST /tickets/search).

Here’s the corrected OpenAPI you should upload:

{
  "openapi": "3.0.3",
  "info": {
    "title": "Jira Ticket Reader API",
    "version": "1.0.0",
    "description": "Read-only API for retrieving Jira tickets and searching with JQL."
  },
  "servers": [
    {
      "url": "https://yourdomain.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/tickets": {
      "get": {
        "summary": "Get all Jira tickets",
        "operationId": "getAllTickets",
        "responses": {
          "200": {
            "description": "A list of Jira tickets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Ticket"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/tickets/{ticketKey}": {
      "get": {
        "summary": "Get a Jira ticket by key",
        "operationId": "getTicketByKey",
        "parameters": [
          {
            "in": "path",
            "name": "ticketKey",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The Jira issue key (e.g., DEMO-123)"
          }
        ],
        "responses": {
          "200": {
            "description": "Jira ticket found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ticket"
                }
              }
            }
          }
        }
      }
    },
    "/tickets/search": {
      "post": {
        "summary": "Search tickets using JQL",
        "operationId": "searchTickets",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jql": {
                    "type": "string",
                    "example": "project = DEMO AND assignee = currentUser()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of matched Jira tickets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Ticket"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Ticket": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "DEMO-123"
          },
          "summary": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "assignee": {
            "type": "string"
          },
          "reporter": {
            "type": "string"
          },
          "created": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

Checklist before uploading again:

· Use a real HTTPS server URL.

· Add operationId for every method.

· (Optional) Add authentication section if your API needs auth.

Hope this helps, do let me know if you have any queries.

Thank you!

Prashanth Veeragoni 5,245 Reputation points Microsoft External Staff Moderator

2025-04-29T16:24:07.5366667+00:00

Hi Andres Garcia,

Following up to see if the above suggestion was helpful. And, if you have any further query do let me know.

Thank you!
Prashanth Veeragoni 5,245 Reputation points Microsoft External Staff Moderator

2025-04-30T17:51:29.35+00:00

Hi Andres Garcia,

We haven’t heard from you on the last response and was just checking back to see if you have a resolution yet. In case if you have any resolution, please do share that same with the community as it can be helpful to others. Otherwise, will respond with more details and we will try to help.

Thank you!
Adarsh Devineni 0 Reputation points

2025-06-03T19:25:30.5933333+00:00

Hi @Prashanth Veeragoni , Thank you for your helpful response. Adding the operationId resolved my issue.I wanted to check whether OAuth 2.0 authentication is supported in the OpenAPI 3.0 Specified Tool. If so, where should I securely provide the Client id and secret required to fetch the bearer token?

Appreciate your help!

Thank you!

1 answer

Your answer

Prashanth Veeragoni 5,245 Reputation points Microsoft External Staff Moderator

2025-04-29T16:24:07.5366667+00:00

Hi Andres Garcia,

Following up to see if the above suggestion was helpful. And, if you have any further query do let me know.

Thank you!
Prashanth Veeragoni 5,245 Reputation points Microsoft External Staff Moderator

2025-04-30T17:51:29.35+00:00

Hi Andres Garcia,

We haven’t heard from you on the last response and was just checking back to see if you have a resolution yet. In case if you have any resolution, please do share that same with the community as it can be helpful to others. Otherwise, will respond with more details and we will try to help.

Thank you!
Adarsh Devineni 0 Reputation points

2025-06-03T19:25:30.5933333+00:00

Hi @Prashanth Veeragoni , Thank you for your helpful response. Adding the operationId resolved my issue.I wanted to check whether OAuth 2.0 authentication is supported in the OpenAPI 3.0 Specified Tool. If so, where should I securely provide the Client id and secret required to fetch the bearer token?

Appreciate your help!

Thank you!

Answer 1

Hi Adarsh Devineni,

Glad to hear adding operationId resolved your earlier issue!

Yes, OAuth 2.0 is supported in Azure AI Foundry Agents when using OpenAPI 3.0 specifications. However, there are a few things to keep in mind:

How to Securely Provide Client ID and Secret

Azure AI Studio does not allow you to directly embed sensitive credentials like client_id and client_secret in the OpenAPI spec for security reasons. Instead, you should:

1.Define OAuth2 Security Scheme in the Spec

Add this to your components.securitySchemes section:

"components": {
  "securitySchemes": {
    "OAuth2": {
      "type": "oauth2",
      "flows": {
        "clientCredentials": {
          "tokenUrl": "https://your-auth-server.com/oauth/token",
          "scopes": {
            "read:jira": "Read access to Jira tickets"
          }
        }
      }
    }
  }
}

2.Reference the Security Scheme in Your Endpoints

For each secured endpoint, add:

"security": [
  {
    "OAuth2": ["read:jira"]
  }
]

3.Use Azure Portal to Provide Secrets

After uploading the OpenAPI file, Azure AI Studio will detect that OAuth2 is required and prompt you to enter the Client ID and Secret via a secure UI form. These values are stored securely and not embedded into the spec.

Hope this helps.

Adarsh Devineni 0 Reputation points

2025-06-04T15:21:46.19+00:00

Thank you for the response. But what should I select as the Authentication Method? OpenAPI spec doc.png
Adarsh Devineni 0 Reputation points

2025-06-04T15:25:13.33+00:00

I tried with 'Anonymous' and added the security section OpenAPI spec connection selection.png and I could create the connection but it is not working. I am getting a 403 error

Share via

Azure AI Foundry agent: I can't Configure OpenAPI 3.0 Specified Tools

1 answer

Your answer