Building APIs for Developers and AI Agents

本播客以“构建面向开发者与AI代理的API”为核心议题，深入探讨了现代软件基础设施中API作为“互联网树突”的根本性角色，并揭示了随着人工智能技术演进，尤其是大语言模型（LLM）与AI代理成为新型用户，API设计范式正经历一场深刻变革。报告基于Stainless创始人Alex Rattrade在Stripe期间的实践经验，系统阐述了API平台建设的底层逻辑、SDK生成的技术挑战及其对开发者体验的根本影响。核心观点在于：每一个公司都正在成为API公司，而每一个API公司都需要一个具备SDK、文档、版本管理等完整能力的开发者平台，这一趋势不仅源于技术演进，更由开发者对高效、低摩擦开发体验的刚性需求所驱动。报告进一步指出，当AI代理开始作为第一类用户接入API时，传统以人类开发者为中心的设计模式面临前所未有的挑战，包括上下文窗口限制、工具暴露过多、响应数据过载等问题，这要求我们重新思考接口的本质——即从“人机交互”转向“智能体-系统协同”。在此背景下，Stainless提出了一套创新解决方案，通过动态工具暴露、JQ过滤器和版本化参考文档等机制，使API能够同时服务于人类开发者与AI代理，从而实现真正的“双用户友好”架构。

报告的核心价值在于其将抽象的技术哲学转化为可操作的工程实践。它不仅强调了高质量SDK的必要性——如Python库需符合语言惯用法、支持编辑器内悬停提示、具备类型安全与错误处理能力——更前瞻性地提出了“MCP（Model Context Protocol）”作为连接API与AI代理的新接口标准，将其类比为软件系统的“新感官”，如眼睛或耳朵，使AI能以更自然、更高效的方式感知和操作外部系统。通过对Stripe API文档重构、代码生成系统开发以及后续创业历程的深度复盘，报告揭示了一个关键洞见：优秀的开发者平台并非一蹴而就，而是建立在对细节极致打磨的长期积累之上，这种对“nitty gritty”的执着追求，正是从开源工具无法满足需求到创建商业级解决方案的驱动力。最终，报告展望了未来五至十年的开发者角色演变，预测AI将承担大量基础性编码工作，而人类开发者将聚焦于更高层次的架构设计与业务逻辑定义，形成“人类负责愿景，AI负责实现”的协作新模式，从而推动整个软件开发生态进入一个以效率、可维护性和可解释性为核心的全新纪元。

在当代数字世界中，API被赋予了超越技术协议的哲学意义——它不仅是程序间通信的桥梁，更是构成整个互联网认知网络的“树突”（dendrites）。这一比喻源自神经科学，其深层含义在于：正如大脑中的神经元通过电化学信号在突触（synapse）间传递信息以实现思维活动，互联网中的服务器与应用程序也通过API进行交互，从而实现复杂功能的协同运作。> “So if you think about the brain being a collection of neurons that by firing together, you know, think, you can think of the internet as a collection of servers or programs running and running on servers that by interacting with each other think or do.” 这一论述将抽象的网络行为具象化为一种类脑的集体智能，强调了API作为“连接点”的核心地位。因此，每一次API调用，本质上都是一个微小的“思想火花”，而所有这些火花的汇聚，便构成了我们所依赖的数字化社会。这一视角的转变，使得API不再仅仅是工程师手中的工具，而是整个数字生态系统中不可或缺的“认知基础设施”。

这一根本性认知的延伸，直接引出了一个颠覆性的结论：每一个公司都在成为API公司。无论其主营业务是金融服务、电子商务、内容创作还是硬件制造，其核心竞争力越来越依赖于能否将其内部能力以标准化、可编程的方式对外暴露。例如，Stripe的崛起并非仅仅因为其支付处理能力，更在于其构建了一个极其完善、易于集成的API平台，使得任何开发者都能在几分钟内完成支付功能的部署。> “Realize that every company is becoming an API company. AND EVERY API COMPANY NEEDS AN API PLATFORM WITH SDKS AND DOCS AND API VERSIONING AND JUST YOU KNOW A MILLION DIFFERENT THINGS THAT AMAZING TEAM THAT I WORKED ON AT STRIPE ALL COLLABORATED ON.” 这句话精准地概括了当前企业战略的转型方向。这意味着，企业必须像对待产品一样，精心设计其API的用户体验，包括提供高质量的SDK（软件开发工具包）、详尽的文档（Docs）、清晰的版本控制策略以及完善的错误处理机制。这些看似“低层”的组件，实则是决定开发者是否愿意采用并持续使用该API的关键因素。缺乏这些要素的API，即便功能再强大，也会因集成成本过高而被市场淘汰。

这一趋势的必然性，根植于现代软件开发的现实需求。开发者普遍希望“专注于其核心能力”，而非陷入繁琐的底层细节之中。> “PEOPLE WANT TO BE ABLE TO FOCUS ON THEIR CORE CAPABILITIES, BE THOUGHTFUL IN EXPOSING THE INTERFACES TO USERS AND NOT HAVE TO WORRY ABOUT THE LOW LEVEL DETAILS.” 这种需求催生了对“开发者平台即服务”（Developer Platform as a Service）的巨大市场需求。然而，构建这样一个平台并非易事。以Stripe为例，其团队规模庞大（约两千人），才足以支撑起如此复杂的内部工具链。对于绝大多数中小企业而言，自行搭建一套媲美Stripe的API平台，面临着难以承受的维护负担和高昂的人力成本。> “The maintenance burden, the headaches involved in trying to set this up is just too much for almost any company other than, you know, something like a Stripe at two thousand people, which was when I worked on that.” 这种“有需求但无能力”的困境，正是Stainless公司创立的直接动因。创始人Alex Rattrade在Stripe期间亲历了这一挑战，他意识到，如果不能为所有公司提供一个“开箱即用”的开发者平台，那么API的普及将永远受限于少数巨头的资源垄断。因此，Stainless的使命应运而生：将Stripe所积累的、经过实战检验的开发者平台经验，封装成一个可复制、可扩展的解决方案，赋能全球每一个API公司，使其无需重复造轮子，即可获得世界级的开发者体验。

在API生态中，SDK的地位远超一般意义上的“工具包”，它实质上是开发者与API之间的第一道也是最核心的“界面”。> “The SDK is the API, and those were kind of falling behind.” 这一断言揭示了一个常被忽视的真相：对于绝大多数开发者而言，他们接触和使用的并非原始的HTTP请求，而是封装好的SDK。因此，SDK的质量直接决定了开发者对整个API的认知和使用体验。一个糟糕的SDK会带来严重的挫败感，而一个卓越的SDK则能极大提升开发效率和代码质量。Stainless创始人在Stripe的经历，正是对这一理念的生动印证。他最初注意到，尽管Stripe的API本身设计精良，但其SDK却未能跟上步伐，导致内部和外部开发者在使用时遭遇诸多不便。这一发现促使他主导了对Stripe API文档的全面重设计，并在此基础上构建了一个强大的代码生成系统。

该代码生成系统的核心目标，是将Stripe的OpenAPI规范（OpenAPI spec）自动转换为高质量的Python和TypeScript等语言的客户端库。> “So I built a code generation system there that can take the Stripe Open API spec and turn it into a great Python library and a great TypeScript library and so on.” 这一过程不仅仅是简单的代码转换，更是一场对编程语言特性和最佳实践的深度探索。例如，在构建Python库时，需要考虑类型系统（types）、异步编程（async）、模式匹配（pattern matching）等现代语言特性，确保生成的代码不仅功能正确，而且在语法上完全符合Python社区的“惯用法”（idiomatic）。> “It's really incredible to see, and what's idiomatic through all of this world, and that's a moving target.” 这意味着，一个优秀的SDK必须是“熟悉”的，能让开发者在不查阅文档的情况下，仅凭代码风格就能理解其意图。这种“熟悉感”来源于对语言文化的深刻理解，而不仅仅是一套机械的规则。创始人本人曾创建过一门小型编程语言，其初衷便是为了打磨这些“细微之处”（nitty gritty），这正是他投身于SDK生成工作的内在驱动力。

此外，一个真正可靠的SDK还必须具备强大的鲁棒性（robustness）。它必须能在网络不稳定、API返回异常或出现意料之外的错误时，依然保持稳定，避免崩溃或产生不可预测的行为。> “And when things get weird on the internet, your SDK does not, it's not the thing that's blowing up or causing problems.” 它还需要能够无缝集成监控（telemetry）和日志记录功能，以便在出现问题时快速定位根源。更重要的是，SDK必须与开发环境深度集成。例如，当开发者在IDE中悬停于某个函数或变量上时，应能立即弹出包含详细说明的文档气泡，无论是来自REST API的定义，还是来自SDK本身的实现。> “If they hover over on a thing, there is documentation that pops up in their editor telling them about that thing, whether it's coming from the REST API or from the core of the library.” 这种“即时反馈”极大地提升了开发者的生产力，减少了上下文切换的时间。因此，一个成功的SDK，其价值远不止于提供一组函数调用，而是一个集成了类型检查、错误提示、智能补全、文档查询于一体的完整开发环境。当开发者面对一个高质量的SDK时，他们感受到的不是“在调用API”，而是在“使用一个熟悉的、可靠的语言特性”。

随着大语言模型（LLM）和AI代理的普及，API的用户群体发生了根本性变化。传统的API设计主要面向人类开发者，其接口通常以命令式（imperative）的函数调用形式呈现，如createCharge(amount, currency)。然而，当AI代理成为新的用户时，其交互方式截然不同。它们并非逐行阅读文档，而是通过自然语言指令来理解和执行任务。> “When you come to MCP, which is this kind of new frontier where instead of exposing your API to a Python developer writing Python software, one of the things that you can do with MCP is expose your API to an LLM agent using an MCP client.” 这种转变催生了MCP（Model Context Protocol）这一新兴标准，它被视作连接API与AI代理的“新接口”。创始人将MCP比喻为软件系统的“新感官”，如眼睛或耳朵，因为它让AI能够以全新的方式“感知”和“理解”外部世界。> “I kind of want to compare it to eyes or ears or a new sense when a software system IS COMMUNICATING INTERNALLY.” 这一比喻深刻揭示了MCP的本质：它不再是简单的数据交换，而是一种旨在优化AI代理“认知效率”的接口协议。

然而，将现有API通过MCP暴露给AI代理，面临着一系列严峻的技术挑战。其中最核心的问题是上下文窗口（context window）的限制。一个典型的API可能包含数百个端点和数千个参数，若将所有这些信息一次性全部注入AI的上下文，将瞬间耗尽其有限的计算资源。> “If you want to describe every single endpoint in the Stripe API with every single parameter fully documented, congratulations, you've just used up your entire context window, and that basically just doesn't work.” 这会导致AI模型“过载”，无法有效处理实际任务。此外，AI代理在执行任务时，往往只需要极小一部分功能。例如，它可能只关心“创建一笔付款”这个单一操作，而对其他五百个端点毫无兴趣。因此，如何在不牺牲可用性的情况下，动态地、渐进式地向AI代理揭示其所需的功能，成为了一个关键难题。

为应对这一挑战，Stainless提出了一系列创新解决方案。首先，它允许用户通过命令行标志（CLI flags）或远程URL的查询参数（query parameters），在启动MCP服务器时，精确限定其可见的API资源范围。> “HEY, I ONLY WANT TO INTERACT WITH THESE RESOURCES, SO I ONLY GIVE ME THE YOU KNOW PAYMENT INTENSE PART OF THE STRIPE API, OR ONLY GIVE ME THE CUSTOMERS PART OF THE STRIPE API, OR I ONLY WANT READS, OR I ONLY WANT WRITES.” 这种“按需加载”的模式，能将工具数量从数百个锐减至几个，极大地缓解了上下文压力。其次，Stainless提供了“动态模式”（dynamic mode），将所有工具的定义简化为三个核心工具：获取可用端点列表、描述单个端点的参数、执行端点调用。> “YOU HAVE A TOOL TO DESCRIBE A SINGLE ENDPOINT AND GET ALL THOSE REQUEST PARAMETERS, AND YOU HAVE A TOOL TO EXECUTE AN ENDPOINT, AND SO YOU'VE GONE AND MADE THESE TOOL DEFINITIONS TOTALLY DYNAMIC.” 虽然这需要多轮交互（三轮才能完成一次操作），但其优势在于上下文占用极低，尤其适合那些不确定具体需求的探索性任务。最后，针对API响应数据过大的问题，Stainless引入了JQ（JSON Query）过滤器。> “We've added sort of this JQ filter to all of these requests.” 该功能允许AI代理在发起请求时，明确指定其需要的数据字段，例如“我只需要Jennifer的姓名和邮箱，不需要其他任何信息”。这相当于在SQL中使用SELECT name, email FROM customers WHERE name = 'Jennifer'，将庞大的响应数据压缩为精简的、相关性强的信息，从而显著降低对上下文窗口的冲击。

一个普遍存在的误解是，随着MCP等协议的出现，API和SDK的质量变得不再重要，因为AI代理可以直接“理解”API。然而，事实恰恰相反。> “It's exactly because there's more usage, you need strongly typed. Very polished SDKs as well.” 当AI代理的使用量激增时，对API接口的准确性和可靠性要求反而更高。一个错误的SDK版本或一份模糊的文档，可能导致AI代理生成完全错误的代码，造成严重后果。创始人分享了一个真实案例：某大型金融科技公司的开发者关系负责人反映，当她要求一个编码代理（coding agent）集成该公司API时，代理首先会安装该公司的SDK。> “THE FIRST THING THAT CODING AGENT IS GOING TO DO IS INSTALL THIS COMPANY'S SDK.” 然而，由于缺乏版本管理，代理往往会安装一个十个月前的旧版本，然后基于这个过时的、甚至已废弃的接口进行“幻觉”（hallucination），生成的代码必然存在缺陷。> “IT'S GOING TO INSTALL A VERSION FROM TEN MONTHS AGO, AN OLD VERSION, AND THEN IT'S GOING TO HALLUCINATE THE WHOLE INTERFACE, RIGHT?” 这种情况在实践中屡见不鲜，严重损害了自动化开发的可信度。

这一现象凸显了SDK在AI代理工作流中的核心地位。> “But it's important to note that the agent preferred to use the SDK. It didn't want to just make a fetch request given the option.” AI代理之所以偏好使用SDK，正是因为其内置的类型检查（type checking）功能。当代理尝试调用一个函数时，如果传入的参数类型错误，或者假设某个字段永远不会为空，而实际上它可能是空值，类型检查器会立刻发出警告（如红色波浪线）。> “You really want those red squiggly lines saying hey this property. It has a typo or hey, you're assuming that this string is always going to be string and it's never going to be null in the response.” 这种即时的、机器可读的反馈，是人类开发者无法轻易察觉的细微错误，但对于保证代码的健壮性至关重要。它使得人类审查者可以快速判断AI生成的代码是否“方向正确”，从而将精力集中在更高层次的业务逻辑验证上，而非纠缠于底层的语法错误。

因此，Stainless的下一个重大突破，正是解决这一“信任链”问题。> “something that we need to see with MCP... is the ability to get comprehensive REFERENCE DOCUMENTATION FOR THE API OF YOUR LIBRARY.” 公司即将推出一项功能，能够将特定版本SDK的完整API参考文档，直接交付给AI代理。这样一来，当代理被要求“帮我写一个集成”时，它不仅能知道如何调用API，还能确切地知道“哪个版本的SDK”应该被使用，以及“该版本的所有方法和参数”是什么。> “It'll know the right version, and it'll have access to the full API of that version's SDK, and it won't make mistakes.” 这从根本上解决了因版本不一致导致的“幻觉”问题，使AI代理的输出更加可靠和可预测。这表明，未来的开发者平台，其价值不仅体现在提供API，更体现在提供一个“可信的、可追溯的、可验证的”知识库，让AI代理能够像人类专家一样，基于权威信息进行决策和行动。

播客中还深入探讨了从人类开发者到AI代理，API设计思维的深层演变。创始人以一个极具启发性的类比展开：过去，软件通过“眼睛”（用户界面）与现实世界互动，如用户登录Stripe仪表板进行退款操作；后来，自动化流程通过“手指”（API）实现，如脚本自动执行支付。如今，AI代理的出现，标志着我们正在“生长出一个新的肢体”——一个能够自主探索、学习和执行任务的“新感官”。> “I definitely imagine a hand raising up in the air of like here you can use me and like I can do these things.” 这个比喻形象地描绘了AI代理作为“主动参与者”而非“被动接收者”的角色转变。它不再等待人类下达明确指令，而是能够主动探索API的可用能力，寻找解决问题的路径。

这一转变对API设计提出了全新的要求。首先，API的设计必须更加“声明式”（declarative）和“简洁”（dry）。> “WRITING YOUR CODE MEANS YOU WANT YOUR CODE TO BE MORE DECLARATIVE AND MORE DRY.” 因为AI代理在生成代码时，需要在一个高度受限的探索空间内进行，过于复杂或冗余的代码会增加其出错的概率。其次，企业需要建立清晰、可遵循的API设计标准。> “you're going to want more clear and prescriptive standards around what API design should look like, so that the LLM can follow a set of rules.” 这些标准应涵盖命名规范、错误码定义、分页策略等，使AI代理能够像遵循编程规范一样，自动地、一致地生成符合企业风格的代码。最后，开发者自身的角色也将发生根本性变化。> “the humans should be thinking about, as you say, the high levels of what the business needs, and letting the robots do all the less exciting stuff.” 未来的开发者将不再是编写每一行代码的“工匠”，而是负责定义“高阶目标”（high-level goals）的“架构师”和“设计师”。他们将利用AI工具，快速生成原型，然后集中精力进行代码审查、业务逻辑验证和系统整体优化。这预示着一个“人机共生”的新时代，其中，人类的创造力与AI的执行力相结合，共同推动软件开发的边界不断向前拓展。

综上所述，本播客深刻揭示了API作为数字时代“神经连接”的核心地位，并前瞻性地指明了其未来发展的两大方向：一是继续深化对人类开发者的服务，通过打造极致的SDK、文档和平台体验，降低开发门槛；二是主动拥抱AI代理这一新用户，通过MCP等协议，构建能够高效、安全、可信赖地与智能体协同的接口体系。这两个方向并非对立，而是相辅相成，共同构成了一个完整的“双用户友好”开发者平台蓝图。

其核心启示在于，API的未来，不在于技术本身，而在于其承载的“体验”与“信任”。Stainless的实践证明，一个成功的平台，必须将对细节的极致追求（如Python库的惯用法、JQ过滤器的智能性）与对宏观架构的深刻洞察（如动态工具暴露、版本化文档）相结合。它不仅解决了技术难题，更重塑了开发者与AI之间的协作关系。在未来，我们预期看到的将不再是“开发者写代码”，而是“人类定义目标，AI生成实现，平台保障质量”的全新范式。在这个范式中，API平台的角色将从“工具提供者”进化为“智能协作中枢”，其价值将体现在对效率、可维护性和可解释性的全面提升上。因此，对于所有致力于构建下一代软件基础设施的企业而言，投资于一个强大、灵活且面向未来的开发者平台，已不再是可选项，而是通向智能经济时代的必经之路。