**Arazzo is solving the right problem for AI tools. The spec just isn't there yet**

> From API contract to documentation portal: streamline your workflow and deliver the best API experience. Built for engineers and tech writers. One of the biggest struggles with AI tools is making them as deterministic and reliable as possible. We saw a surge in API calls made directly by AIs that inevitably faced the same issue. A huge part of the guess work is about what actions need to be chained in order to accomplish a real business use case, showing the need to document workflows on top of standard API (per endpoint) documentation. That’s exactly what Arazzo is made for: pushed by the OpenAPI Initiative (the folks behind OpenAPI), this specification is made to document workflows, aka action chainings. While it struggled to get traction upon release in 2024, there’s now a clear use case around API reliability for AI tools. In this article, I’ll talk about Arazzo’s current strengths and limits, and how our internal data model filled the gap while waiting for future versions of the specification. MCP and the emergence of AI-orchestrated API workflows 2025 was a huge shakeup in the API world: it was now easier than ever to run API workflows by asking LLMs in natural language, or even through autonomous agents, by different means: MCP servers with one tool per endpoint, skills, CLIs, direct cURL commands, etc., while leaving the AI tool with the burden of understanding how to use the API to achieve a specific user-requested action. Limits were quickly reached: guessing API chains led to hallucinations, unreliable successes, slowness, and heavy token costs. The need for upper-level orchestration became clear: we couldn’t leave uncertainty to AI tools. Arazzo solved some of these problems: Sebastien wrote a great article on that specific topic . My relationship with Arazzo I’ve been following Arazzo development since 2023, when our focus was still on human-only documentation. We thought about supporting Arazzo to document workflows as a layer on top of our clients’ existing API documentation. We didn’t get much traction, as it’s quite natural for a developer to roam around an API doc for a while to get a good view of the API’s capabilities and chainings. For complex API ecosystems, a diagram or a global getting-started guide was often more than enough to onboard their users. We also thought about supporting it in the API Explorer, to run real workflows instead of single API calls. But as the API Explorer is mostly used during the early discovery process (either pre-sale or in early onboarding), fiddling with API calls and knowing that these options exist in the API was enough. It was no game changer for us, hence not something we wanted to invest heavily in. The specification found itself truly useful when we started thinking about providing our own agentic runner, the MCP Platform. We tried to describe our API workflows using Arazzo. Here’s what fell short. For the MCP Platform, we needed to support a standard allowing our users to describe their workflows. That’s why we started digging into Arazzo, to understand its philosophy, see if it could fit our clients’ needs, and what would be needed to support it. We also discussed what data model to pick to store users’ workflows. We have a dedicated internal data model for API documentation: OpenAPI and AsyncAPI documents are converted into our own data model, ensuring a cohesive experience no matter what specification was used. We ended up doing the same for workflows, as we didn’t want to depend on the direction a workflow specification like Arazzo would take and wanted to have the latitude to support another specification if needed. For that reason, we designed our own internal data...

**来源信息**
- **来源**：Hacker News：AI 热帖
- **分类**：ai-products
- **发布时间**：2026-09-15 20:44（北京时间）
- **原文**：[打开原文](https://bump.sh/blog/arazzo-is-solving-the-right-problem-for-ai-tools-the-spec-just-isnt-there-yet)