let allTools = { 
    ...convertOpenApiSpecToAgentTool
  };

  // iterate through all openapi specs
  for (let j = 0; j < agentContext.openApiSpecs?.length; j++) {
    const postSpec = await fetch(agentContext.openApiSpecs[j].url);
    const postSpecResponse = await postSpec.json();

    const converter = new OpenAPIToTools(
      postSpecResponse,
      agentContext.openApiSpecs[j].authHeader || "" // instantiate the spec converter
    );
    const openApiTools = converter.generateTools(); // extract the tools from spec
    console.log(
      `✅ Processed OpenAPI spec ${j + 1}, generated ${
        Object.keys(openApiTools).length
      } tools`
    );
    allTools = { ...allTools, ...openApiTools }; // add them to toolkit
    }

Now, upon rebooting, your agent can use these OpenAPI specs as if they were native tools it had access to all along. Here is the complete OpenAPIToTools class implementation for formalizing an OpenAPI endpoint into a Vercel AI SDK tool if you’d like to take a closer look.

An Alternative Approach: Two-Tool Pattern

If you don’t want to start/stop your agent or create and load new tools for each OpenAPI spec, you can still take advantage of OpenAPI specs with a two-tool pattern:

1. Tool A: This tool fetches the OpenAPI spec with a simple GET request. The OpenAPI spec is returned from the tool, which loads the spec into the agent’s context window.
2. Tool B: This tool builds and executes an API call. Given headers, a path, a method, and parameters (supplied by the agent in the tool call arguments), this generic tool builds the HTTP request and executes it.

In this approach, the developer is giving the agent full responsibility for reading the OpenAI spec and writing the correct API call to make. It’s less structured than actually generating a tool, but still opens up the entire API to the agent.

Despite being less structured, the two tool approach can scale better because not every API has an OpenAPI spec. Documentation can take all forms from webpages to Markdown to Postman collections and more. An agent that can fetch and read documentation and then execute the API call correctly is all we are really trying to accomplish here. “Correctly” is a key word here. The approach of letting the agent formulate its own request has a large drawback wherein the agent can malform its request, leading to inconsistency between agent runs. This approach also requires loading the entire OpenAPI spec (or at least its general structure) into the agent’s context window, so that the agent can later correctly write a call to the API. Depending on the size of the OpenAPI spec, this could be a very costly operation, and it could make more sense to run code that will process the spec and turn it into specific tools for the agent to call instead.

Since the agents we showed above demanded reliability and consistent behavior across runs, we chose to restart them with the transformed tools—avoiding the uncertainty of having the agent issue raw API calls itself.

The two general approaches to utilizing external OpenAPI specs both have their benefits and drawbacks. The two tool approach is highly scalable across different types of APIs and different frameworks, while the code to convert OpenAPI specs to agent tools needs to be tailored to each agent framework. However, the two tool approach also introduces more uncertainty in making reliable API calls and adds overhead into the LLM model context, whereas the tools generated by converting the OpenAPI spec are bound to work predictably once tested.

Ultimately, as with almost everything, the correct approach depends on the tradeoffs you need to make for your specific agentic use case. Godspeed developers.

Lessons Learned

Through experimenting with this approach across frameworks, we’ve learnt a few important things:

• OpenAPI specs are messy. Some are missing servers, some misuse the required keyword, some declare impossible schemas. Build resilience into the way you process OpenAPI specs.
• Authentication needs handling. Many APIs require tokens, headers, or OAuth flows. Your OpenAPI spec converter should give agents a way to pass custom headers or API keys.
• Tool naming matters. Clear, short names improve agent reliability. Some LLM models and agent frameworks cannot handle tool names that are too long.

The Takeaway

Converting OpenAPI specs into agent tools is not just a neat hack—it’s a major unlock.

It means your agent is no longer limited to the sliver of services that have MCP servers. It can work with the APIs that power nearly every service on the internet. Plus, integrating Skyfire means the system can also incorporate payment and identity credentials for authenticated service calls or to programmatically pay for API usage.

Yes, MCP is definitely preferable when available, but until every company adopts it, OpenAPI conversion is a pragmatic stopgap. Google, recognizing this fact, has already included an OpenAPI integration into their Agent Development Kit. This simplifies the process of using OpenAPI specs to a couple lines of code and it is likely other agent frameworks will follow suit, allowing agents to interface with both OpenAPIs and MCPs seamlessly.

The real win: you don’t need to wait for the ecosystem to catch up and for more companies to release MCPs to build useful agents! Your agent can start calling APIs today using the approaches outlined in this post!

At Skyfire, we’re actively testing these integrations across Strands, Vercel AI SDK, and more. If you’ve built your own OpenAPI-to-tool converters—or run into weird spec quirks—we’d love to hear about it.