Azure AI services
A group of Azure services, SDKs, and APIs designed to make apps more intelligent, engaging, and discoverable.
3,422 questions
Azure AI Foundry agent: I can't Configure OpenAPI 3.0 Specified Tools
![](data:image/svg+xml, %3Csvg xmlns='http://www.w3.org/2000/svg' height='64' class='font-weight-bold' style='font: 600 30.11764705882353px "SegoeUI", Arial' width='64'%3E%3Ccircle fill='hsl(233.6, 15%, 32%)' cx='32' cy='32' r='32' /%3E%3Ctext x='50%25' y='55%25' dominant-baseline='middle' text-anchor='middle' fill='%23FFF' %3EAG%3C/text%3E%3C/svg%3E)
Andres Garcia
5
Reputation points
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.
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.
Azure AI services
{count} vote
-
Prashanth Veeragoni 4,360 Reputation points Microsoft External Staff Moderator2025-04-28T15:04:49.8733333+00:00 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 4,360 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 4,360 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!
Sign in to comment
Sign in to answer