Cannot properly configure OpenAPI tool for Microsoft Foundry Agent

Question

Hello,

I'm trying to create a Microsoft Foundry Agent that can access my API deployed on Azure Web App, but I'm encountering the following error:

Below is my current OpenAPI configuration:

{
  "openapi": "3.0.3",
  "info": {
    "title": "LearningPathsApi",
    "description": "OpenApi for managing learning paths, topics, and topic sources using OpenAPI tool",
    "version": "v1"
  },
  "servers": [
    {
      "url": "{{ my web app url }}",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/LearningPaths": {
      "post": {
        "tags": [
          "LearningPaths"
        ],
        "summary": "Creates a new learning path",
        "operationId": "createLearningPath",
        "requestBody": {
          "description": "The learning path creation request containing name and optional description",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLearningPathDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Learning path created successfully"
          },
          "400": {
            "description": "Invalid request data or validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateLearningPathDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "DTO for creating a new learning path"
      }
    }
  }
}

Authentication method is anonymous.

At the moment, I'm not sure what part of the setup is missing or incorrectly configured. I would appreciate any guidance on what could be causing this issue or what additional configuration steps might be required.

Thanks in advance for your help!

Answer 1

Hello Adrian Bostan,

Welcome to Microsoft Q&A .Thank you for reaching out to us.

Based on the behavior observed, the API endpoint itself appears to be functioning correctly, since direct API testing succeeds outside the Foundry Agent environment.

The key indicator is the following runtime error

SpecificationNotFoundError

No API specification found for spec_id 'LearningPaths'

This error occurs before the API call is executed and typically indicates that the Foundry Agent runtime is unable to locate a successfully registered OpenAPI specification for the attached tool. Based on the current behavior, the issue appears more closely related to OpenAPI tool registration, specification ingestion, or runtime binding rather than the Azure Web App API implementation itself.

Please check if the following steps help isolate and resolve the issue-

1. Recreating the OpenAPI tool and refresh runtime metadata In some cases, OpenAPI tool metadata may become stale or partially registered. Recommended steps:
   1. Remove the existing LearningPaths OpenAPI tool from the agent
   2. Create a new OpenAPI tool
   3. Re-upload the OpenAPI schema
   4. Save the tool configuration
   5. Save the agent configuration
   6. Start a completely new playground session and test again
   This helps ensure the runtime loads the latest tool registration and specification binding correctly.
2. Simplifying the OpenAPI specification temporarily Although the API works correctly, OpenAPI ingestion behavior in Foundry may differ from standard Swagger/OpenAPI validation tools. The following schema areas should be reviewed: "$ref": "#/components/schemas/ProblemDetails" without a matching schema definition
   • Placeholder server URL instead of the deployed HTTPS endpoint
   • Complex or unnecessary schema constructs during initial testing
   As an isolation step, testing with a minimal OpenAPI 3.0.1 schema is recommended:
   • Single POST operation
   • Inline request schema only
   • No $ref
   • Minimal response definition
   This approach helps determine whether the issue is related to schema compatibility during OpenAPI ingestion.
3. Verifying operation extraction after import After importing the OpenAPI tool, successful import should expose callable operations within the tool configuration UI createLearningPath If the operation does not appear after upload, this strongly indicates that the OpenAPI specification ingestion is failing internally. In that situation, the runtime will not be able to resolve the spec_id during execution, which directly aligns with the observed SpecificationNotFoundError.
4. Validating the OpenAPI document directly Please confirm that the OpenAPI document used during tool registration is accessible and returns valid OpenAPI JSON.
   1. Returns HTTP 200
   2. Returns valid OpenAPI JSON
   3. No authentication prompt
   4. No unexpected redirects
   If an OpenAPI or Swagger endpoint is exposed by the application, validating the endpoint response directly can help confirm that the schema is reachable by the Foundry runtime.

The following references might be helpful , please check them out

• Connect OpenAPI tools to Microsoft Foundry agents - Microsoft Foundry | Microsoft Learn
• Agentic app with Microsoft Agent Framework or Foundry Agent Service (.NET) - Azure App Service | Microsoft Learn
• What is Microsoft Foundry Agent Service? - Microsoft Foundry | Microsoft Learn

Please let us know if the response was helpful

Thank you

Answer 2

Hello Adrian!

Thank you for posting on MS Learn Q&A.

The agent tried to call:

spec_id: "LearningPaths"
tool_name: "python_openapi_tool"

but Foundry could not find a saved OpenAPI spec registered under that spec definition.

So the issue is most likely in the tool metadata not in your Azure Web App endpoint.

Microsoft Foundry OpenAPI tools require the OpenAPI schema to be attached as a tool definition with a valid operationId for each operation. Foundry supports OpenAPI 3.0/3.1, anonymous/API key/managed identity authentication and each function must have an operationId using only letters, -, and _.

Delete and recreate the OpenAPI tool and fix the OpenAPI schema reference :

"$ref": "#/components/schemas/ProblemDetails"

but ProblemDetails is not defined in components.schemas. This can make the spec invalid or partially ignored by the tool registration. Either define ProblemDetails or remove that response schema.

Add required: true to the request body :

"requestBody": {
  "required": true,
  "description": "The learning path creation request containing name and optional description",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateLearningPathDto"
      }
    }
  }
}

Also test the API directly before using it from the agent:

curl -X POST "https://ai-agent-test-abbsc8dmcff9axd4.germanywestcentral-01.azurewebsites.net/api/LearningPaths" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\".NET learning path\",\"description\":\"First learning path\"}"

Answer 3

The error message indicates that the agent doesn’t have an API specification bound to the OpenAPI tool with spec_id LearningPaths. The issue isn’t with the JSON itself, but with how the tool is configured and saved in Microsoft Foundry.

To fix the problem, ensure the following steps are completed in the new Foundry portal:

1. Verify the OpenAPI tool is created and saved on the agent
   1. Open the Foundry portal (https://ai.azure.com) and select the project.
   2. Open the agent that should call the LearningPaths API.
   3. In the agent playground, expand Tools.
   4. Confirm there is a custom OpenAPI tool (for example named LearningPaths) listed.
   5. Select the tool and check that the OpenAPI 3.0+ schema box contains your JSON (including openapi, info, servers, paths, and components).
   6. Select Save on the tool, then Save on the agent. If the agent isn’t saved after adding the tool, the spec won’t be available at runtime and you’ll see spec_not_found / No API specification available.
2. Confirm the tool is attached to the agent action
   1. In the agent playground, open the Setup pane.
   2. Ensure an action is configured that uses the OpenAPI tool (the same one shown under Tools).
   3. Save the agent again.
3. Validate the OpenAPI prerequisites The OpenAPI tool requires certain elements in the spec:
   • Each function must have an operationId (your createLearningPath already satisfies this).
   • The operationId should contain only letters, -, and _ and be descriptive. createLearningPath is acceptable.
   • The servers.url should point to the deployed app endpoint (as in your JSON).
   These requirements are described in the OpenAPI tool guidance and are already met by your sample.
4. Test from the playground
   1. In the agent playground, select Try in playground.
   2. Send a prompt like: Create a learning path named "Test path" with description "First learning path".
   3. If the tool is correctly configured and saved, the agent should now call the OpenAPI tool instead of returning SpecificationNotFoundError.

If the error persists, re-create the OpenAPI tool:

1. Remove the existing LearningPaths tool from the agent.
2. Add a new Custom → OpenAPI tool.
3. Paste the same OpenAPI JSON.
4. Save the tool and the agent, then test again.

---

References:

• Add an App Service app as a tool in Foundry Agent Service (.NET)
• Tutorial: Build an agentic web app in Azure App Service with Microsoft Agent Framework or Foundry Agent Service (.NET)
• Tutorial: Build an agentic web app in Azure App Service with LangGraph or Foundry Agent Service (Node.js)
• How to use Foundry Agent Service with OpenAPI Specified Tools (classic)
• Connect agents to OpenAPI tools (rest)
• Connect agents to OpenAPI tools (typescript)
• Secure OpenAPI endpoints for Foundry Agent Service