[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"portal-settings:stajic:zh":3,"public-menus:all":38,"post:migrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally:zh":205,"related:post:migrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally:zh:1":2870},{"statusCode":4,"data":5,"message":37},200,{"tenantId":6,"lang":7,"defaultLang":8,"siteUrl":9,"contactEmail":10,"brandName":11,"logoUrl":12,"siteName":11,"siteDescription":13,"ogImage":10,"robotsIndex":14,"socialLinks":10,"reservedSlugs":10,"seoPolicy":15},"stajic","zh","de","https:\u002F\u002Fstajic.de",null,"Stajic Platform","\u002FLogo_Planet.svg","Stajic Portal",true,{"branding":16,"relatedContent":17,"crossDomainLinks":18},{"logoUrl":12},{"enabled":14},[19,22,25,28,31,34],{"url":20,"label":21,"isActive":14,"showInFooter":14,"includeInSameAs":14},"https:\u002F\u002Ffigure.rocks","figure.rocks",{"url":23,"label":24,"isActive":14,"showInFooter":14,"includeInSameAs":14},"https:\u002F\u002Floving.rocks","loving.rocks",{"url":26,"label":27,"isActive":14,"showInFooter":14,"includeInSameAs":14},"https:\u002F\u002Fbazify.com","bazify.com",{"url":29,"label":30,"isActive":14,"showInFooter":14,"includeInSameAs":14},"https:\u002F\u002Fbazify.de","bazify.de",{"url":32,"label":33,"isActive":14,"showInFooter":14,"includeInSameAs":14},"https:\u002F\u002Fbazify.at","bazify.at",{"url":35,"label":36,"isActive":14,"showInFooter":14,"includeInSameAs":14},"https:\u002F\u002Fbazify.ba","bazify.ba","Portal settings resolved",[39,45],{"id":40,"name":41,"location":42,"isActive":14,"isDefault":43,"items":44},1,"main-navigation","header",false,[],{"id":46,"name":47,"location":48,"isActive":14,"isDefault":14,"items":49},4,"main-menu","sidebar",[50,66,79,93,103,118,133],{"id":51,"title":52,"url":60,"target":61,"icon":62,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":64,"portfolioId":10,"children":65},"item-18",{"de":53,"en":54,"es":55,"fr":56,"it":54,"ru":57,"sr":58,"zh":59},"Startseite","Home","Inicio","Accueil","Главная","Почетна","首页","\u002Ffull-stack-web-developer-munich-performance-seo-and-maintainable-builds","_self","i-lucide-home","page",111,[],{"id":67,"title":68,"url":75,"target":61,"icon":76,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":77,"portfolioId":10,"children":78},"item-22",{"de":69,"en":69,"es":70,"fr":69,"it":71,"ru":72,"sr":73,"zh":74},"Vision","Visión","Visione","Видение","Визија","想象","\u002Fueber-uns-webdesign-muenchen-webaplikation","i-lucide-eye",113,[],{"id":80,"title":81,"url":89,"target":61,"icon":90,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":91,"portfolioId":10,"children":92},"item-19",{"de":82,"en":83,"es":84,"fr":83,"it":85,"ru":86,"sr":87,"zh":88},"Leistungen","Services","Servicios","Servizi","Услуги","Услуге","服务","\u002Fservices-dienstleistungen-muenchen","i-lucide-wrench",116,[],{"id":94,"title":95,"url":99,"target":61,"icon":100,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":101,"portfolioId":10,"children":102},"item-23",{"de":96,"en":96,"es":96,"fr":96,"it":96,"ru":97,"sr":97,"zh":98},"Blog","Блог","博客","\u002Fblog","i-lucide-book-open",112,[],{"id":104,"title":105,"url":114,"target":61,"icon":115,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":116,"portfolioId":10,"children":117},"item-32",{"de":106,"en":107,"es":108,"fr":109,"it":110,"ru":111,"sr":112,"zh":113},"Neue Technologien","New Technologies","Nuevas tecnologías","Nouvelles technologies","Nuove tecnologie","Новые технологии","Нове технологије","新技术！","\u002Fneue-webtechnologien","i-lucide-sparkles",122,[],{"id":119,"title":120,"url":129,"target":61,"icon":130,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":131,"portfolioId":10,"children":132},"item-20",{"de":121,"en":122,"es":123,"fr":124,"it":125,"ru":126,"sr":127,"zh":128},"Kontakt","Contact us!","Contacto","Contact","Contatto","Контакт","Контактирајте нас","联系我们！","\u002Fcontact","i-lucide-mail",115,[],{"id":134,"title":135,"url":144,"target":61,"icon":145,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":146,"portfolioId":10,"children":147},"item-21",{"de":136,"en":137,"es":138,"fr":139,"it":140,"ru":141,"sr":142,"zh":143},"Unsere Arbeit","Our Work","Nuestro trabajo","Nos réalisations","I nostri lavori","Наши работы","Наши радови","文件夹","\u002Fportfolio","i-lucide-briefcase",114,[148,161,175,181,193],{"id":149,"title":150,"url":144,"target":61,"icon":159,"isActive":14,"type":63,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":146,"portfolioId":10,"children":160},"item-24",{"de":151,"en":152,"es":153,"fr":154,"it":155,"ru":156,"sr":157,"zh":158},"Alle Projekte","All Projects","Todos los proyectos","Tous les projets","Tutti i progetti","Все проекты","Сви пројекти","所有项目","i-lucide-grid-3x3",[],{"id":162,"title":163,"url":171,"target":61,"icon":172,"isActive":14,"type":173,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":10,"portfolioId":10,"children":174},"item-29",{"de":164,"en":165,"es":166,"fr":167,"it":168,"ru":169,"sr":170,"zh":143},"Local Roots, Global Reach","Local Roots - Global Reach","Empresa local ","Entreprise locale","Azienda locale","Местная компания","Локално предузеће глобално тржиште","\u002Fportfolio\u002Flocal-roots-global-reach-communication-media-systems-for-modern-business","i-lucide-folder","custom",[],{"id":176,"title":177,"url":179,"target":61,"icon":172,"isActive":14,"type":173,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":10,"portfolioId":10,"children":180},"item-28",{"de":178,"en":178,"es":178,"fr":178,"it":178,"ru":178,"sr":178,"zh":178},"Solr Suggester","\u002Fportfolio\u002Fsolr-fuzzy-suggester-und-solr-infix-suggester-abfrage-ueber-ajax-und-filterung",[],{"id":182,"title":183,"url":191,"target":61,"icon":172,"isActive":14,"type":173,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":10,"portfolioId":10,"children":192},"item-27",{"de":184,"en":185,"es":186,"fr":187,"it":188,"ru":189,"sr":190,"zh":185},"Firmenwebseite SEO","Company Website SEO","Sitio web corporativo SEO","Site web d’entreprise SEO","Sito web aziendale SEO","Корпоративный сайт SEO","Пословна веб-страница SEO","\u002Fportfolio\u002Fseo-sem-branding-mobile-webseite-muenchen",[],{"id":194,"title":195,"url":203,"target":61,"icon":172,"isActive":14,"type":173,"productId":10,"categoryId":10,"shopCategoryId":10,"articleId":10,"pageId":10,"portfolioId":10,"children":204},"item-31",{"de":196,"en":197,"es":198,"fr":199,"it":200,"ru":201,"sr":202,"zh":197},"Digitalisierungsportal","Digitalization Portal","Portal de digitalización","Portail de numérisation","Portale di digitalizzazione","Портал цифровизации","Портал за дигитализацију","\u002Fportfolio\u002Fdigitalisierungsportal-archiv-museum-bibliothek-ead-lido-mets-mods",[],{"statusCode":4,"data":206,"message":2869},{"id":207,"title":208,"slug":209,"content":210,"contentJson":211,"excerpt":1310,"featuredImage":1311,"featuredImageAlt":1312,"featuredImageCaption":10,"featuredImageTitle":10,"featuredImageCopyright":10,"featuredImageAuthor":10,"featuredImageSourceUrl":10,"featuredImageLicense":10,"featuredImageIsAiGenerated":43,"status":1313,"publishedAt":1314,"createdAt":1315,"updatedAt":1316,"seoLocalePaths":1317,"categories":1326,"author":1339,"translations":1344},"474","从OpenAI Agents SDK迁移到Agents API：架构上究竟有哪些变化？","migrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u003Cnav class=\"editorjs-toc\" data-editorjs-toc=\"true\" aria-label=\"目录\">\u003Cstrong class=\"editorjs-toc__title\">目录\u003C\u002Fstrong>\u003Col class=\"editorjs-toc__list editorjs-toc__list--depth-0\">\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-6\" class=\"editorjs-toc__link\">迁移是从应用程序拥有的循环转向托管执行框架\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-10\" class=\"editorjs-toc__link\">运行时边界迁移图\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-12\" class=\"editorjs-toc__link\">哪些内容可以在不改变所有权的情况下从概念上迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-16\" class=\"editorjs-toc__link\">哪些内容不应一对一迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-19\" class=\"editorjs-toc__link\">步骤 1 — 将领域状态与代理会话状态分离\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-23\" class=\"editorjs-toc__link\">步骤 2 — 将运行器思维转变为会话与事件思维\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-26\" class=\"editorjs-toc__link\">步骤 3 — 围绕所需操作重新设计函数工具\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-30\" class=\"editorjs-toc__link\">步骤 4 — 决定执行应发生在何处\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-34\" class=\"editorjs-toc__link\">步骤 5 — 用显式生命周期处理替代隐式恢复\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-37\" class=\"editorjs-toc__link\">第6步 — 围绕新的追踪边界重建可观测性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-41\" class=\"editorjs-toc__link\">第7步 — 在更改运行时之前保留评估\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-44\" class=\"editorjs-toc__link\">迁移验证测试\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-46\" class=\"editorjs-toc__link\">迁移期间要衡量什么\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-48\" class=\"editorjs-toc__link\">何时还不要迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-51\" class=\"editorjs-toc__link\">迁移何时变得具有战略重要性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-54\" class=\"editorjs-toc__link\">什么会改变这个答案？\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-57\" class=\"editorjs-toc__link\">局限性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-60\" class=\"editorjs-toc__link\">结论\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-63\" class=\"editorjs-toc__link\">常见问题\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-65\" class=\"editorjs-toc__link\">术语表\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-67\" class=\"editorjs-toc__link\">主要来源与延伸阅读\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-82\" class=\"editorjs-toc__link\">迁移是从应用程序拥有的循环转向托管执行框架\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-86\" class=\"editorjs-toc__link\">运行时边界迁移图\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-88\" class=\"editorjs-toc__link\">哪些内容可以在不改变所有权的情况下进行概念性迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-92\" class=\"editorjs-toc__link\">哪些内容不应一对一迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-95\" class=\"editorjs-toc__link\">第 1 步 — 将领域状态与代理会话状态分离\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-99\" class=\"editorjs-toc__link\">第 2 步 — 将运行器思维转变为会话与事件思维\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-102\" class=\"editorjs-toc__link\">第 3 步 — 围绕所需操作重新设计函数工具\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-106\" class=\"editorjs-toc__link\">第 4 步 — 决定执行应发生在哪里\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-110\" class=\"editorjs-toc__link\">第 5 步 — 用显式生命周期处理替换隐式恢复\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-113\" class=\"editorjs-toc__link\">第 6 步 — 围绕新的追踪边界重建可观测性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-117\" class=\"editorjs-toc__link\">第 7 步 — 在更改运行时之前保留评估\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-120\" class=\"editorjs-toc__link\">迁移验证测试\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-122\" class=\"editorjs-toc__link\">迁移期间应衡量什么\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-124\" class=\"editorjs-toc__link\">何时还不应迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-127\" class=\"editorjs-toc__link\">迁移何时具有战略重要性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-130\" class=\"editorjs-toc__link\">什么会改变这一答案？\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-133\" class=\"editorjs-toc__link\">局限性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-136\" class=\"editorjs-toc__link\">结论\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-139\" class=\"editorjs-toc__link\">常见问题\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-141\" class=\"editorjs-toc__link\">术语表\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-143\" class=\"editorjs-toc__link\">主要来源与延伸阅读\u003C\u002Fa>\u003C\u002Fli>\u003C\u002Fol>\u003C\u002Fnav>\n\u003Cp>从 OpenAI Agents SDK 迁移到 Agents API 并不是重命名导入。核心架构边界发生了变化：SDK 在你的应用程序内部运行智能体循环，而 Agents API 在 OpenAI 一侧运行托管的 Codex 执行框架和持久会话。因此，迁移问题不是“哪些类映射到哪些端点？”，而是“哪些运行时职责跨越边界转移，哪些留在我们的应用程序中，哪些需要重新设计？”\u003C\u002Fp>\n\u003Caside class=\"editorjs-callout editorjs-callout--info my-6 rounded-xl border p-5 border-blue-300 bg-blue-50 dark:border-blue-900 dark:bg-blue-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">直接回答\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\"><strong>真正的 Agents SDK → Agents API 迁移会改变运行时所有权。<\u002Fstrong>你的可复用智能体配置仍然可以包含模型、指令和工具，但循环、持久会话、编排、上下文压缩和恢复会向托管的 Agents API 运行时转移。你的应用程序应将领域状态、授权、业务规则、函数实现和审计逻辑保留在智能体会话之外。将迁移视为边界重新设计，而不是机械的代码转换。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Caside class=\"editorjs-callout editorjs-callout--warning my-6 rounded-xl border p-5 border-amber-300 bg-amber-50 dark:border-amber-900 dark:bg-amber-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">截至 2026 年 9 月 25 日的最新情况\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">OpenAI 目前将 Agents SDK 标记为<strong>功能完备<\u002Fstrong>，并推荐新智能体应用程序使用 Agents API。Agents API 处于公开测试阶段。现有 SDK 应用程序仍受支持，并不自动要求立即迁移。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Caside class=\"editorjs-callout editorjs-callout--note my-6 rounded-xl border p-5 border-gray-300 bg-gray-50 dark:border-gray-700 dark:bg-gray-900\u002F40\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">关于迁移模型\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">本文中的运行时边界迁移图和迁移验证测试是实用的架构工具，并非 OpenAI 官方迁移框架。它们源自 OpenAI 记录的当前运行时差异。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Ch2 id=\"section-6\">迁移是从应用程序拥有的循环转向托管执行框架\u003C\u002Fh2>\n\u003Cp>在 Agents SDK 中，一次运行是应用程序级别的一轮。SDK 运行器调用模型、检查输出、执行工具、遵循交接并持续进行，直到到达停止点。你的进程承载该循环，因此拥有其生命周期。\u003C\u002Fp>\n\u003Cp>在 Agents API 中，OpenAI 运行执行框架。会话是智能体配置的持久实例，它接受任务、产生事件、可以暂停以等待所需操作，并可以随时间继续。OpenAI 管理会话、编排、上下文压缩和恢复；你的应用程序发送工作、处理函数工具、接收事件，并可选地管理自托管执行环境。\u003C\u002Fp>\n\u003Cp>这种所有权转移就是迁移。其他一切——API 语法、工具模式、事件处理、会话 ID——都由此而来。\u003C\u002Fp>\n\u003Ch2 id=\"section-10\">运行时边界迁移图\u003C\u002Fh2>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">关注点\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">Agents SDK\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">Agents API 迁移目标\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">智能体循环\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">通过 SDK 运行器在你的应用程序中运行\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">在托管的 Codex 执行框架中运行\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">可复用智能体定义\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用程序代码中的 Agent 对象\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">包含模型、指令和工具的已保存或内联智能体配置\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">对话 \u002F 工作连续性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 会话策略、历史记录、结果延续或应用程序存储\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">持久 Agents API 会话\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">工具执行\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 在你的运行时中协调工具调用\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">执行框架请求函数调用；你的应用程序返回结果\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">上下文管理\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">你的运行时 \u002F SDK 会话策略\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">托管会话上下文、压缩和恢复，以及你自己的应用程序数据边界\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">交接 \u002F 专家\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 编排原语\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 中的执行框架 \u002F 子智能体行为；不要假设一对一语义\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">执行环境\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">你的应用程序运行时或特定工具环境\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">附加到会话的可选 OpenAI 托管或自托管环境\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">流式传输\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">来自运行的 SDK 流式传输\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 会话事件流\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">异步生命周期\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">通常由应用程序围绕 SDK 运行进行管理\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">原生会话状态、异步轮次和 webhook\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">追踪 \u002F 可观测性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents SDK 追踪和应用程序日志\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents 会话日志、事件、轮次、工具调用、子智能体和可导出追踪\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">恢复\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用程序责任\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">托管执行框架\u002F会话恢复，以及针对外部系统和自托管环境的应用程序自有恢复\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-12\">哪些内容可以在不改变所有权的情况下从概念上迁移\u003C\u002Fh2>\n\u003Cp>若干应用程序概念即使表示形式发生变化，也能顺利通过迁移保留下来。模型、指令、JSON-schema 函数定义、MCP 访问、工具描述和结构化输出要求仍然是智能体配置关注点。\u003C\u002Fp>\n\u003Cp>OpenAI 的 Agents API 配置模型明确通过模型、指令、工具、推理和输出行为来定义智能体。函数工具仍然是应用程序代码：执行框架请求函数调用，你的处理程序返回结果。OpenAI 还指出，与 Responses API 一起使用的函数实现可以在 Agents API 会话流程中复用。\u003C\u002Fp>\n\u003Caside class=\"editorjs-callout editorjs-callout--success my-6 rounded-xl border p-5 border-emerald-300 bg-emerald-50 dark:border-emerald-900 dark:bg-emerald-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">良好的迁移候选\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">像 <code>get_customer(customer_id)<\u002Fcode> 这样的纯业务函数不应需要知道调用方是 Agents SDK 还是 Agents API。将其领域逻辑保留在稳定的应用程序接口之后，只迁移面向智能体的适配器。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Ch2 id=\"section-16\">哪些内容不应一对一迁移\u003C\u002Fh2>\n\u003Cp>危险的迁移模式是在 Agents API 中重建每个 SDK 运行时抽象。这可能导致你为托管执行框架付费，同时仍在应用程序中运行一个影子执行框架。\u003C\u002Fp>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">SDK 时代的假设\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">为什么直接复制有风险\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">迁移问题\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用程序循环拥有每次延续\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 已经拥有执行框架循环\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些延续逻辑是产品逻辑，哪些应转移到托管会话？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">本地会话对象是主要连续性机制\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 会话是具有自身生命周期的持久资源\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些状态属于会话，哪些属于产品数据库？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">每次中断都同步处理\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 轮次是异步的，并可能暴露 action_required 状态\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些操作需要 webhook、工作进程、幂等性和可恢复处理程序？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">所有工具执行都发生在 SDK 进程运行的地方\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">函数处理程序和执行环境可以分离\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">每个工具实际应在哪里执行？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 追踪是运营时间线\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 暴露会话事件、轮次和托管追踪\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些应用程序级审计数据仍需要自己的记录？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">交接对象直接映射到托管子智能体模型\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">运行时语义可能不同\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">必须保留哪些用户可见的所有权和专家行为，而不仅仅是旧的类结构？\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-19\">步骤 1 — 将领域状态与代理会话状态分离\u003C\u002Fh2>\n\u003Cp>在接触 API 调用之前，先对你 SDK 应用当前承载的状态进行分类。有些状态仅用于维持代理对话的推进。其他状态则是业务事实：用户权限、项目状态、订单数据、工作流审批、客户记录、文档版本、策略状态或应用配置。\u003C\u002Fp>\n\u003Cp>第二类状态不应依赖于 Agents API 会话。持久会话对代理而言是有用的连续性，但它不能替代你产品的真实来源。如果会话消失、过期、被重建或更改实现，你的应用仍必须知道什么是真实的。\u003C\u002Fp>\n\u003Csection class=\"editorjs-comparison my-6\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">状态放置测试\u003C\u002Fh3>\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left dark:border-gray-700 dark:bg-gray-900\">\u003C\u002Fth>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left font-semibold dark:border-gray-700 dark:bg-gray-900\">状态类型\u003C\u002Fth>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left font-semibold dark:border-gray-700 dark:bg-gray-900\">首选所有者\u003C\u002Fth>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left font-semibold dark:border-gray-700 dark:bg-gray-900\">原因\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">对话连续性\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">业务事实\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">持久工件\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">工作暂存状态\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\u003C\u002Fsection>\n\u003Ch2 id=\"section-23\">步骤 2 — 将运行器思维转变为会话与事件思维\u003C\u002Fh2>\n\u003Cp>SDK 应用通常以调用 run 并接收结果的方式思考。Agents API 则以持久会话的方式思考，其轮次可以异步运行。向空闲会话发送消息会启动工作；在活动轮次期间发送消息可以引导它。进度通过流式传输或 webhook 到达。\u003C\u002Fp>\n\u003Cp>这会影响应用架构。长时间运行的生产工作不应依赖于单个 HTTP 请求保持存活。你的产品需要稳定的会话标识符、生命周期持久化、webhook 验证、幂等处理器，以及进程重启后协调当前会话状态的方法。\u003C\u002Fp>\n\u003Ch2 id=\"section-26\">步骤 3 — 围绕所需操作重新设计函数工具\u003C\u002Fh2>\n\u003Cp>函数工具仍然是重要的应用边界。你在代理配置中定义函数及其 JSON schema。当 harness 需要该函数时，会话可以进入需要操作的状态。你的应用检索所需操作，执行业务逻辑并返回结果。\u003C\u002Fp>\n\u003Cp>这意味着函数实现应可安全恢复。webhook 可能在另一个工作进程处理时被投递。网络故障可能发生在外部副作用之后但在结果返回之前。因此，迁移是向重要工具添加调用 ID、幂等键、显式授权、超时策略和审计记录的好时机。\u003C\u002Fp>\n\u003Caside class=\"editorjs-callout editorjs-callout--warning my-6 rounded-xl border p-5 border-amber-300 bg-amber-50 dark:border-amber-900 dark:bg-amber-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">工具迁移陷阱\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">不要将来自托管 harness 的函数调用视为执行该操作的授权。harness 决定<em>它想要调用什么<\u002Fem>；你的应用仍然决定当前用户、会话和业务状态是否允许该操作。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Ch2 id=\"section-30\">步骤 4 — 决定执行应发生在何处\u003C\u002Fh2>\n\u003Cp>Agents API 将托管 harness 与执行环境分离。代理可以在没有专用环境的情况下运行，在 OpenAI 托管的沙箱中运行，或通过与会话连接的自托管环境运行。\u003C\u002Fp>\n\u003Cp>这产生了一个 SDK 应用可能从未明确做出的迁移决策：哪些代码应作为应用函数运行，哪些代码属于沙箱，哪些工作负载需要你控制的基础设施？\u003C\u002Fp>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">需求\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">可能的边界\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">通过受控业务逻辑调用现有内部服务\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">由你的应用处理的函数工具\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">在没有私有基础设施的情况下运行隔离代码或处理临时文件\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">OpenAI 托管环境\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">访问私有网络资源、自定义系统软件或受控本地计算\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">自托管环境\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">持久化已接受的产品工件\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用拥有的存储，而不仅仅是沙箱文件系统\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">执行高影响的业务副作用\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">具有授权和审计控制的应用函数\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-34\">步骤 5 — 用显式生命周期处理替代隐式恢复\u003C\u002Fh2>\n\u003Cp>托管 harness 提供会话级恢复，但你的应用仍然拥有其周围的每个外部依赖。自托管环境需要配置、重新连接和关闭。函数处理器可能失败。webhook 可能被重试。产品侧状态可能在代理空闲时发生变化。\u003C\u002Fp>\n\u003Cp>因此，迁移需要两种恢复模型：代理运行时恢复和业务操作恢复。第一种越来越多地由 Agents API 管理。第二种仍然是你的责任。\u003C\u002Fp>\n\u003Ch2 id=\"section-37\">第6步 — 围绕新的追踪边界重建可观测性\u003C\u002Fh2>\n\u003Cp>Agents API 会话会暴露事件、保存的历史记录、轮次、工具调用、子代理和令牌使用情况。OpenAI 还在平台中提供会话日志和追踪导出。\u003C\u002Fp>\n\u003Cp>不要因为平台追踪有所改进就丢弃你的应用可观测性。产品日志仍然需要将代理会话与用户身份、授权决策、领域对象、工具副作用、审批记录和最终接受的结果关联起来。有用的生产追踪是代理运行时证据与业务运行时证据之间的连接。\u003C\u002Fp>\n\u003Caside class=\"editorjs-referral my-6\">\u003Ca href=\"https:\u002F\u002Fstajic.de\u002Fzh\u002Fblog\u002Fai-agent-reliability-why-the-final-answer-is-not-enough\" class=\"flex flex-col sm:flex-row gap-4 rounded-xl border border-gray-200 dark:border-gray-700 p-4 transition hover:border-primary-500\">\u003Cdiv class=\"min-w-0 flex-1\">\u003Cstrong class=\"block text-lg text-gray-900 dark:text-gray-100\">AI 代理可靠性：为什么最终答案还不够\u003C\u002Fstrong>\u003Cp class=\"mt-2 text-sm text-gray-600 dark:text-gray-300\">代理可靠性取决于执行路径、工具和中间决策——而不仅仅是最终输出。\u003C\u002Fp>\u003Cspan class=\"mt-3 inline-flex text-sm font-medium text-primary-600 dark:text-primary-400\">阅读可靠性文章 →\u003C\u002Fspan>\u003C\u002Fdiv>\u003C\u002Fa>\u003C\u002Faside>\n\u003Ch2 id=\"section-41\">第7步 — 在更改运行时之前保留评估\u003C\u002Fh2>\n\u003Cp>迁移可能看起来成功，因为新系统仍然产生看似合理的答案，同时悄然改变了工具选择、会话连续性、交接行为、延迟或故障恢复。在切换运行时之前建立行为基线。\u003C\u002Fp>\n\u003Cp>基线应包括代表性任务、预期工具调用、禁止操作、审批点、状态连续性、恢复场景和最终输出验收标准。尽可能对相同案例运行新旧架构。\u003C\u002Fp>\n\u003Ch2 id=\"section-44\">迁移验证测试\u003C\u002Fh2>\n\u003Csection class=\"editorjs-process my-6\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">在切换之前验证新运行时\u003C\u002Fh3>\u003Cdiv class=\"grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4\">\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">1\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">1. 冻结行为基线\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">捕获代表性 SDK 追踪、预期输出、工具路径、审批点和失败案例。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">2\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">2. 清点状态所有权\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">将每个状态字段标记为代理会话状态、权威领域状态、持久工件或临时工作状态。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">3\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">3. 复用稳定的工具实现\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">将业务功能保留在应用接口之后；尽可能只替换面向代理的集成。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">4\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">4. 构建一个 Agents API 垂直切片\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">迁移一个生产形态的工作流，包括会话创建、工具、事件、环境和持久化。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">5\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">5. 注入中断\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">测试进程重启、webhook 重试、函数超时、自托管环境重连和过期领域状态。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">6\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">6. 比较追踪，而不仅仅是答案\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">对照基线验证工具选择、授权、证据路径、状态转换和副作用。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">7\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">7. 运行影子流量\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">在可行的情况下，在使新运行时成为权威之前重放或镜像代表性任务。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">8\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">8. 在可逆边界之后切换\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">保持集成适配器和回滚能力，直到生产行为稳定。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003C\u002Fdiv>\u003C\u002Fsection>\n\u003Ch2 id=\"section-46\">迁移期间要衡量什么\u003C\u002Fh2>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">维度\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">迁移检查\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">任务成功\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">新运行时是否满足相同或更好的验收标准？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">工具正确性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">它是否使用有效参数和授权调用正确的工具？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">状态连续性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">工作能否在轮次、重启和异步等待之间恢复？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">恢复\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">webhook 丢失、处理器失败、环境断开或超时后会发生什么？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">可追溯性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">每个重要操作能否关联到会话、用户、工具调用和领域对象？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">上下文行为\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">长时间运行的会话是否在不携带过期应用事实的情况下保留约束？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">延迟\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">会话启动、环境配置和多轮工作如何影响用户可见时间？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">成本\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">模型使用、沙箱使用、重复上下文和基础设施操作方面有哪些变化？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">运营负载\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些以前由应用承担的职责真正消失了，哪些只是转移了？\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-48\">何时还不要迁移\u003C\u002Fh2>\n\u003Cp>现有的 Agents SDK 应用不会仅仅因为平台方向改变就变成糟糕的架构。OpenAI 继续维护、安全修复、关键错误修复和兼容性工作。如果应用稳定、评估良好且没有受阻的路线图需求，立即迁移运行时可能并不合理。\u003C\u002Fp>\n\u003Cul>\u003Cli>Agents API 中尚不提供所需的 SDK 能力。\u003C\u002Fli>\u003Cli>迁移会扰乱关键生产期，且无法带来近期价值。\u003C\u002Fli>\u003Cli>应用依赖于尚未在托管 harness 上验证的自定义编排语义。\u003C\u002Fli>\u003Cli>提供商可移植性是硬性要求，且当前 SDK 抽象具有重大价值。\u003C\u002Fli>\u003Cli>你的团队尚未将业务状态与代理运行时状态分离，导致切换不安全。\u003C\u002Fli>\u003Cli>新的 Agents API 行为尚未针对代表性生产工作负载进行测试。\u003C\u002Fli>\u003C\u002Ful>\n\u003Ch2 id=\"section-51\">迁移何时变得具有战略重要性\u003C\u002Fh2>\n\u003Cp>当产品需求与托管 harness 一致时，迁移变得更具吸引力：持久的长时运行工作、平台管理的上下文压缩和恢复、更新的代理运行时能力、沙箱执行、更丰富的托管生命周期管理，或希望减少应用运营的编排代码量。\u003C\u002Fp>\n\u003Cp>最强的信号不是“旧 SDK 功能完备”。而是“我们的路线图现在依赖于那些自然归属于托管 Agents API 运行时的能力。”\u003C\u002Fp>\n\u003Ch2 id=\"section-54\">什么会改变这个答案？\u003C\u002Fh2>\n\u003Cp>如果 OpenAI 发布自动化迁移工具、引入显式兼容层、更改 Agents API 会话语义、扩大或缩小自托管环境支持范围，或更改 Agents SDK 的支持政策，迁移策略将会改变。\u003C\u002Fp>\n\u003Cp>如果你的产品需求发生变化，迁移策略也会改变。简单的请求-响应助手可能根本不需要持久化的托管执行框架。长时间运行的编码、研究或运维智能体则可以从 Agents API 的所有权模型中获益更多。\u003C\u002Fp>\n\u003Ch2 id=\"section-57\">局限性\u003C\u002Fh2>\n\u003Cp>不存在通用的 SDK 到 API 的一对一迁移映射，因为不同应用使用 Agents SDK 的方式各不相同。有些严重依赖会话和交接；有些则将其用作函数工具的轻量运行器。正确的迁移方式取决于你的应用目前实际承担哪些职责。\u003C\u002Fp>\n\u003Cp>Agents API 也处于公开测试阶段，因此实现细节可能会演变。请将本文中的所有权原则视为比任何单个端点形态都更持久。\u003C\u002Fp>\n\u003Ch2 id=\"section-60\">结论\u003C\u002Fh2>\n\u003Cp>从 Agents SDK 迁移到 Agents API 最好理解为移动智能体运行时边界。托管执行框架接管了更多的循环、会话连续性、压缩和恢复。你的应用应该更明确地界定仍属于自身的职责：领域真相、授权、函数副作用、产物、可审计性和产品生命周期。\u003C\u002Fp>\n\u003Cp>如果一次迁移保留了所有旧的编排机制，仅仅将 SDK 调用替换为 Agents API 调用，那么它很可能错失了架构上的机会。目标不是在新运行时之上复制旧运行时。目标是决定哪些运行时职责不再属于你的应用。\u003C\u002Fp>\n\u003Ch2 id=\"section-63\">常见问题\u003C\u002Fh2>\n\u003Csection class=\"editorjs-faq my-6 rounded-xl border border-gray-200 p-5 dark:border-gray-700\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">从 Agents SDK 迁移到 Agents API\u003C\u002Fh3>\u003Cdiv id=\"faq1\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">从 Agents SDK 迁移到 Agents API 只是 API 重写吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">不是。主要变化是运行时所有权：Agents SDK 在你的应用中运行智能体循环，而 Agents API 运行托管的 Codex 执行框架和持久会话。状态、生命周期、事件处理和恢复应作为架构关注点进行审查。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq2\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">我的函数工具需要重写吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">如果业务实现已经位于稳定的应用接口之后，通常可以复用。面向智能体的集成会发生变化，因为 Agents API 函数调用通过会话所需操作和结果来处理。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq3\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">我应该将业务状态迁移到 Agents API 会话中吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">通常不需要。将权威的业务和产品状态保留在你自己的数据库或服务中。将会话用于智能体连续性和工作上下文，而不是作为产品的唯一真相来源。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq4\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">Agents API 需要 webhook 吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">不一定，因为流式传输也可用。Webhook 对于长时间运行或异步会话特别有用，你的应用可以在不保持开放流的情况下对生命周期变化做出反应。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq5\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">每个现有的 Agents SDK 应用现在都应该迁移吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">不是。SDK 仍以维护模式提供支持。当新运行时提供有意义的路线图价值，并且所需行为已针对生产形态的评估进行验证后，再进行迁移。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003C\u002Fsection>\n\u003Ch2 id=\"section-65\">术语表\u003C\u002Fh2>\n\u003Csection class=\"editorjs-glossary my-6 rounded-xl border border-gray-200 dark:border-gray-700 p-5\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">关键迁移术语\u003C\u002Fh3>\u003Cdl>\u003Cdiv id=\"runtime-boundary\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">运行时边界\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">平台管理的智能体运行时与应用拥有的运行时之间的职责划分。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"harness\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">执行框架\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">协调模型调用、工具、上下文、编排和持续执行的智能体运行时。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"session\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">会话\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">一个持久的 Agents API 实例，跨轮次保存智能体的配置、对话和已保存的工作。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"required-action\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">所需操作\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">Agents API 需要外部输入（如函数结果或环境连接）才能继续工作的会话状态。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"self-hosted-environment\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">自托管环境\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">由你的基础设施运行并连接到托管 Agents API 执行框架的执行环境。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"migration-proof-test\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">迁移验证测试\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">一种分阶段验证方法，将新运行时与行为基线、故障注入、追踪和可逆切换标准进行比较。\u003C\u002Fdd>\u003C\u002Fdiv>\u003C\u002Fdl>\u003C\u002Fsection>\n\u003Ch2 id=\"section-67\">主要来源与延伸阅读\u003C\u002Fh2>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Fsdk\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents SDK\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">当前支持政策：Agents SDK 功能完备，仍受维护，新应用应从 Agents API 开始。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Frunning-agents\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 使用 Agents SDK 运行智能体\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">SDK 应用拥有的智能体循环和延续模型的文档。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Foverview\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 概述\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">定义 Agents API 核心概念：智能体、环境、会话、事件和项目。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Farchitecture\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 架构\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">解释托管执行框架、应用服务器、OpenAI 托管和自托管执行环境的边界。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fconfiguration\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 配置智能体\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">定义可复用的智能体配置和会话级自定义。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 运行并继续会话\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">记录持久会话、异步轮次、流式传输和引导。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Ftools\u002Ffunctions\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 函数\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">函数工具定义以及必需函数结果的应用程序处理程序边界。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\u002Fwebhooks\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 会话 Webhook\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">异步会话的生命周期事件、必需操作和自托管环境连接。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fobservability\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 可观测性和使用情况\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">会话日志、事件、轮次、工具调用、子代理、追踪和令牌使用情况检查。\u003C\u002Fp>\u003C\u002Fa>\n\u003Cp>从 OpenAI Agents SDK 迁移到 Agents API 并不是重命名导入。核心架构边界发生了变化：SDK 在您的应用程序内运行代理循环，而 Agents API 在 OpenAI 侧运行托管的 Codex 执行框架和持久会话。因此，迁移问题不是“哪些类映射到哪些端点？”，而是“哪些运行时职责跨越边界转移，哪些留在我们的应用程序中，哪些需要重新设计？”\u003C\u002Fp>\n\u003Caside class=\"editorjs-callout editorjs-callout--info my-6 rounded-xl border p-5 border-blue-300 bg-blue-50 dark:border-blue-900 dark:bg-blue-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">直接回答\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\"><strong>真正的 Agents SDK → Agents API 迁移会改变运行时所有权。<\u002Fstrong> 您可复用的代理配置仍然可以包含模型、指令和工具，但循环、持久会话、编排、上下文压缩和恢复会向托管的 Agents API 运行时转移。您的应用程序应将领域状态、授权、业务规则、函数实现和审计逻辑保留在代理会话之外。将迁移视为边界重新设计，而不是机械的代码转换。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Caside class=\"editorjs-callout editorjs-callout--warning my-6 rounded-xl border p-5 border-amber-300 bg-amber-50 dark:border-amber-900 dark:bg-amber-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">截至 2026 年 9 月 25 日的最新情况\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">OpenAI 目前将 Agents SDK 标记为<strong>功能完备<\u002Fstrong>，并建议新的代理应用程序使用 Agents API。Agents API 处于公开测试阶段。现有 SDK 应用程序仍受支持，并不自动要求立即迁移。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Caside class=\"editorjs-callout editorjs-callout--note my-6 rounded-xl border p-5 border-gray-300 bg-gray-50 dark:border-gray-700 dark:bg-gray-900\u002F40\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">关于迁移模型\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">本文中的运行时边界迁移图和迁移验证测试是实用的架构工具，并非 OpenAI 官方迁移框架。它们源自 OpenAI 当前记录的运行时差异。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Cnav class=\"editorjs-toc\" data-editorjs-toc=\"true\" aria-label=\"目录\">\u003Cstrong class=\"editorjs-toc__title\">目录\u003C\u002Fstrong>\u003Col class=\"editorjs-toc__list editorjs-toc__list--depth-0\">\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-6\" class=\"editorjs-toc__link\">迁移是从应用程序拥有的循环转向托管执行框架\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-10\" class=\"editorjs-toc__link\">运行时边界迁移图\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-12\" class=\"editorjs-toc__link\">哪些内容可以在不改变所有权的情况下从概念上迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-16\" class=\"editorjs-toc__link\">哪些内容不应一对一迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-19\" class=\"editorjs-toc__link\">步骤 1 — 将领域状态与代理会话状态分离\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-23\" class=\"editorjs-toc__link\">步骤 2 — 将运行器思维转变为会话与事件思维\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-26\" class=\"editorjs-toc__link\">步骤 3 — 围绕所需操作重新设计函数工具\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-30\" class=\"editorjs-toc__link\">步骤 4 — 决定执行应发生在何处\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-34\" class=\"editorjs-toc__link\">步骤 5 — 用显式生命周期处理替代隐式恢复\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-37\" class=\"editorjs-toc__link\">第6步 — 围绕新的追踪边界重建可观测性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-41\" class=\"editorjs-toc__link\">第7步 — 在更改运行时之前保留评估\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-44\" class=\"editorjs-toc__link\">迁移验证测试\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-46\" class=\"editorjs-toc__link\">迁移期间要衡量什么\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-48\" class=\"editorjs-toc__link\">何时还不要迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-51\" class=\"editorjs-toc__link\">迁移何时变得具有战略重要性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-54\" class=\"editorjs-toc__link\">什么会改变这个答案？\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-57\" class=\"editorjs-toc__link\">局限性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-60\" class=\"editorjs-toc__link\">结论\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-63\" class=\"editorjs-toc__link\">常见问题\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-65\" class=\"editorjs-toc__link\">术语表\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-67\" class=\"editorjs-toc__link\">主要来源与延伸阅读\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-82\" class=\"editorjs-toc__link\">迁移是从应用程序拥有的循环转向托管执行框架\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-86\" class=\"editorjs-toc__link\">运行时边界迁移图\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-88\" class=\"editorjs-toc__link\">哪些内容可以在不改变所有权的情况下进行概念性迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-92\" class=\"editorjs-toc__link\">哪些内容不应一对一迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-95\" class=\"editorjs-toc__link\">第 1 步 — 将领域状态与代理会话状态分离\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-99\" class=\"editorjs-toc__link\">第 2 步 — 将运行器思维转变为会话与事件思维\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-102\" class=\"editorjs-toc__link\">第 3 步 — 围绕所需操作重新设计函数工具\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-106\" class=\"editorjs-toc__link\">第 4 步 — 决定执行应发生在哪里\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-110\" class=\"editorjs-toc__link\">第 5 步 — 用显式生命周期处理替换隐式恢复\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-113\" class=\"editorjs-toc__link\">第 6 步 — 围绕新的追踪边界重建可观测性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-117\" class=\"editorjs-toc__link\">第 7 步 — 在更改运行时之前保留评估\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-120\" class=\"editorjs-toc__link\">迁移验证测试\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-122\" class=\"editorjs-toc__link\">迁移期间应衡量什么\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-124\" class=\"editorjs-toc__link\">何时还不应迁移\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-127\" class=\"editorjs-toc__link\">迁移何时具有战略重要性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-130\" class=\"editorjs-toc__link\">什么会改变这一答案？\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-133\" class=\"editorjs-toc__link\">局限性\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-136\" class=\"editorjs-toc__link\">结论\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-139\" class=\"editorjs-toc__link\">常见问题\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-141\" class=\"editorjs-toc__link\">术语表\u003C\u002Fa>\u003C\u002Fli>\u003Cli class=\"editorjs-toc__item\">\u003Ca href=\"#section-143\" class=\"editorjs-toc__link\">主要来源与延伸阅读\u003C\u002Fa>\u003C\u002Fli>\u003C\u002Fol>\u003C\u002Fnav>\n\u003Ch2 id=\"section-82\">迁移是从应用程序拥有的循环转向托管执行框架\u003C\u002Fh2>\n\u003Cp>在 Agents SDK 中，一次运行是应用程序级别的轮次。SDK 运行器调用模型、检查输出、执行工具、遵循交接并持续运行，直到到达停止点。您的进程承载该循环，因此拥有其生命周期。\u003C\u002Fp>\n\u003Cp>在 Agents API 中，OpenAI 运行执行框架。会话是代理配置的持久实例，它接受任务、产生事件、可以暂停以执行必需操作，并可以随时间继续。OpenAI 管理会话、编排、上下文压缩和恢复；您的应用程序发送工作、处理函数工具、接收事件，并可选地管理自托管执行环境。\u003C\u002Fp>\n\u003Cp>这种所有权转移就是迁移。其他一切——API 语法、工具模式、事件处理、会话 ID——都由此而来。\u003C\u002Fp>\n\u003Ch2 id=\"section-86\">运行时边界迁移图\u003C\u002Fh2>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">关注点\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">Agents SDK\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">Agents API 迁移目标\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">代理循环\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">通过 SDK 运行器在您的应用程序中运行\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">在托管的 Codex 执行框架中运行\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">可复用代理定义\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用程序代码中的 Agent 对象\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">包含模型、指令和工具的已保存或内联代理配置\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">对话 \u002F 工作连续性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 会话策略、历史记录、结果延续或应用程序存储\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">持久 Agents API 会话\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">工具执行\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 在您的运行时中协调工具调用\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">执行框架请求函数调用；您的应用程序返回结果\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">上下文管理\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">您的运行时 \u002F SDK 会话策略\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">托管会话上下文、压缩和恢复，以及您自己的应用程序数据边界\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">交接 \u002F 专家\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 编排原语\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 中的执行框架 \u002F 子代理行为；不要假设一对一语义\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">执行环境\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">您的应用程序运行时或特定工具环境\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">附加到会话的可选 OpenAI 托管或自托管环境\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">流式传输\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">来自运行的 SDK 流式传输\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 会话事件流\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">异步生命周期\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">通常由应用程序围绕 SDK 运行进行管理\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">原生会话状态、异步轮次和 Webhook\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">追踪 \u002F 可观测性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents SDK 追踪和应用程序日志\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents 会话日志、事件、轮次、工具调用、子代理和可导出的追踪\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">恢复\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用程序责任\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">托管执行框架\u002F会话恢复，以及应用程序拥有的外部系统和自托管环境恢复\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-88\">哪些内容可以在不改变所有权的情况下进行概念性迁移\u003C\u002Fh2>\n\u003Cp>若干应用程序概念在迁移后可以完好保留，尽管其表示形式发生了变化。模型、指令、JSON 模式函数定义、MCP 访问、工具描述和结构化输出要求仍然是代理配置关注点。\u003C\u002Fp>\n\u003Cp>OpenAI 的 Agents API 配置模型通过模型、指令、工具、推理和输出行为明确定义代理。函数工具仍然是应用程序代码：执行框架请求函数调用，您的处理程序返回结果。OpenAI 还指出，与 Responses API 一起使用的函数实现可以在 Agents API 会话流程中复用。\u003C\u002Fp>\n\u003Caside class=\"editorjs-callout editorjs-callout--success my-6 rounded-xl border p-5 border-emerald-300 bg-emerald-50 dark:border-emerald-900 dark:bg-emerald-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">良好的迁移候选对象\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">像 <code>get_customer(customer_id)<\u002Fcode> 这样的纯业务函数不应需要知道调用方是 Agents SDK 还是 Agents API。将其领域逻辑保持在稳定的应用接口之后，只迁移面向代理的适配器。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Ch2 id=\"section-92\">哪些内容不应一对一迁移\u003C\u002Fh2>\n\u003Cp>危险的迁移模式是在 Agents API 中重建每一个 SDK 运行时抽象。这可能导致你为托管执行框架付费，同时仍在应用中运行一个影子执行框架。\u003C\u002Fp>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">SDK 时代的假设\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">为什么直接复制有风险\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">迁移问题\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用循环拥有每一次继续执行\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 已经拥有执行框架循环\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些继续执行逻辑是产品逻辑，哪些应移至托管会话？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">本地会话对象是主要的连续性机制\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 会话是具有自身生命周期的持久资源\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些状态属于会话，哪些属于产品数据库？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">每次中断都同步处理\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 轮次是异步的，可能呈现 action_required 状态\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些操作需要 webhook、工作进程、幂等性和可恢复处理器？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">所有工具执行都发生在 SDK 进程运行的地方\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">函数处理器和执行环境可以分离\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">每个工具实际应在哪里执行？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">SDK 追踪是操作时间线\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Agents API 暴露会话事件、轮次和托管追踪\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些应用级审计数据仍需要自己的记录？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">交接对象直接映射到托管子代理模型\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">运行时语义可能不同\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">必须保留哪些用户可见的所有权和专家行为，而不仅仅是旧的类结构？\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-95\">第 1 步 — 将领域状态与代理会话状态分离\u003C\u002Fh2>\n\u003Cp>在接触 API 调用之前，先对你 SDK 应用当前承载的状态进行分类。有些状态仅用于保持代理对话继续进行。其他状态是业务事实：用户权限、项目状态、订单数据、工作流审批、客户记录、文档版本、策略状态或应用配置。\u003C\u002Fp>\n\u003Cp>第二类不应变得依赖于 Agents API 会话。持久会话对代理来说是有用的连续性；它不是产品事实来源的替代品。如果会话消失、过期、重建或更改实现，你的应用仍必须知道什么是真实的。\u003C\u002Fp>\n\u003Csection class=\"editorjs-comparison my-6\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">状态放置测试\u003C\u002Fh3>\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left dark:border-gray-700 dark:bg-gray-900\">\u003C\u002Fth>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left font-semibold dark:border-gray-700 dark:bg-gray-900\">状态类型\u003C\u002Fth>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left font-semibold dark:border-gray-700 dark:bg-gray-900\">首选所有者\u003C\u002Fth>\u003Cth class=\"border border-gray-300 bg-gray-50 px-4 py-3 text-left font-semibold dark:border-gray-700 dark:bg-gray-900\">原因\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">对话连续性\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">业务事实\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">持久工件\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-3 text-left font-semibold dark:border-gray-700\">工作暂存状态\u003C\u002Fth>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-3 dark:border-gray-700\">\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\u003C\u002Fsection>\n\u003Ch2 id=\"section-99\">第 2 步 — 将运行器思维转变为会话与事件思维\u003C\u002Fh2>\n\u003Cp>SDK 应用通常以调用 run 并接收结果的思维方式思考。Agents API 则以持久会话的思维方式思考，其轮次可以异步运行。向空闲会话发送消息会启动工作；在活动轮次期间发送消息可以引导它。进度通过流式传输或 webhook 到达。\u003C\u002Fp>\n\u003Cp>这会影响应用架构。长时间运行的生产工作不应依赖于一个保持存活的 HTTP 请求。你的产品需要稳定的会话标识符、生命周期持久化、webhook 验证、幂等处理器，以及进程重启后协调当前会话状态的方法。\u003C\u002Fp>\n\u003Ch2 id=\"section-102\">第 3 步 — 围绕所需操作重新设计函数工具\u003C\u002Fh2>\n\u003Cp>函数工具仍然是重要的应用边界。你在代理配置中定义函数及其 JSON schema。当执行框架需要该函数时，会话可以进入 action-required 状态。你的应用检索所需操作，执行业务逻辑并返回结果。\u003C\u002Fp>\n\u003Cp>这意味着函数实现应可安全恢复。webhook 可能在另一个工作进程处理时被送达。网络故障可能发生在外部副作用之后但结果返回之前。因此，迁移是向重要工具添加调用 ID、幂等键、显式授权、超时策略和审计记录的好时机。\u003C\u002Fp>\n\u003Caside class=\"editorjs-callout editorjs-callout--warning my-6 rounded-xl border p-5 border-amber-300 bg-amber-50 dark:border-amber-900 dark:bg-amber-950\u002F20\" role=\"note\">\u003Cstrong class=\"block mb-2 text-gray-900 dark:text-gray-100\">工具迁移陷阱\u003C\u002Fstrong>\u003Cdiv class=\"text-gray-700 dark:text-gray-200\">不要将来自托管执行框架的函数调用视为执行该操作的授权。执行框架决定<em>它想要调用什么<\u002Fem>；你的应用仍然决定当前用户、会话和业务状态是否允许该操作。\u003C\u002Fdiv>\u003C\u002Faside>\n\u003Ch2 id=\"section-106\">第 4 步 — 决定执行应发生在哪里\u003C\u002Fh2>\n\u003Cp>Agents API 将托管执行框架与执行环境分离。代理可以在没有专用环境的情况下运行，在 OpenAI 托管的沙箱中运行，或通过与会话连接的自托管环境运行。\u003C\u002Fp>\n\u003Cp>这产生了一个 SDK 应用可能从未明确做出的迁移决策：哪些代码应作为应用函数运行，哪些代码属于沙箱，以及哪些工作负载需要你控制的基础设施？\u003C\u002Fp>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">需求\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">可能的边界\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">通过受控的业务逻辑调用现有的内部服务\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">由你的应用程序处理的函数工具\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">在没有私有基础设施的情况下运行隔离代码或处理临时文件\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">OpenAI 托管环境\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">访问私有网络资源、自定义系统软件或受控的本地计算\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">自托管环境\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">持久化已接受的产品产物\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">应用程序拥有的存储，而不仅仅是沙箱文件系统\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">执行高影响力的业务副作用\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">具有授权和审计控制的应用程序函数\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-110\">第 5 步 — 用显式生命周期处理替换隐式恢复\u003C\u002Fh2>\n\u003Cp>托管执行框架提供会话级恢复，但你的应用程序仍然拥有其周围的每一个外部依赖。自托管环境需要配置、重新连接和关闭。函数处理器可能失败。Webhook 可能被重试。产品侧状态可能在代理空闲时发生变化。\u003C\u002Fp>\n\u003Cp>因此，迁移需要两种恢复模型：代理运行时恢复和业务操作恢复。第一种正越来越多地由 Agents API 管理。第二种仍然是你的责任。\u003C\u002Fp>\n\u003Ch2 id=\"section-113\">第 6 步 — 围绕新的追踪边界重建可观测性\u003C\u002Fh2>\n\u003Cp>Agents API 会话暴露事件、保存的历史记录、轮次、工具调用、子代理和令牌使用情况。OpenAI 还在平台中提供会话日志和追踪导出。\u003C\u002Fp>\n\u003Cp>不要因为平台追踪有所改进就丢弃你的应用程序可观测性。产品日志仍然需要将代理会话连接到用户身份、授权决策、领域对象、工具副作用、审批记录和最终接受的结果。有用的生产追踪是代理运行时证据与业务运行时证据之间的连接。\u003C\u002Fp>\n\u003Caside class=\"editorjs-referral my-6\">\u003Ca href=\"https:\u002F\u002Fstajic.de\u002Fzh\u002Fblog\u002Fai-agent-reliability-why-the-final-answer-is-not-enough\" class=\"flex flex-col sm:flex-row gap-4 rounded-xl border border-gray-200 dark:border-gray-700 p-4 transition hover:border-primary-500\">\u003Cdiv class=\"min-w-0 flex-1\">\u003Cstrong class=\"block text-lg text-gray-900 dark:text-gray-100\">AI 代理可靠性：为什么最终答案还不够\u003C\u002Fstrong>\u003Cp class=\"mt-2 text-sm text-gray-600 dark:text-gray-300\">代理可靠性取决于执行路径、工具和中间决策——而不仅仅是最终输出。\u003C\u002Fp>\u003Cspan class=\"mt-3 inline-flex text-sm font-medium text-primary-600 dark:text-primary-400\">阅读可靠性文章 →\u003C\u002Fspan>\u003C\u002Fdiv>\u003C\u002Fa>\u003C\u002Faside>\n\u003Ch2 id=\"section-117\">第 7 步 — 在更改运行时之前保留评估\u003C\u002Fh2>\n\u003Cp>迁移可能看起来成功，因为新系统仍然产生看似合理的答案，同时悄悄改变了工具选择、会话连续性、交接行为、延迟或故障恢复。在切换运行时之前建立行为基线。\u003C\u002Fp>\n\u003Cp>基线应包括代表性任务、预期工具调用、禁止操作、审批点、状态连续性、恢复场景和最终输出验收标准。尽可能针对相同用例运行旧架构和新架构。\u003C\u002Fp>\n\u003Ch2 id=\"section-120\">迁移验证测试\u003C\u002Fh2>\n\u003Csection class=\"editorjs-process my-6\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">在切换之前验证新运行时\u003C\u002Fh3>\u003Cdiv class=\"grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4\">\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">1\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">1. 冻结行为基线\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">捕获代表性的 SDK 追踪、预期输出、工具路径、审批点和失败用例。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">2\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">2. 盘点状态所有权\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">将每个状态字段标记为代理会话状态、权威领域状态、持久产物或临时工作状态。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">3\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">3. 复用稳定的工具实现\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">将业务函数保留在应用程序接口之后；尽可能只替换面向代理的集成。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">4\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">4. 构建一个 Agents API 垂直切片\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">迁移一个生产形态的工作流，包括会话创建、工具、事件、环境和持久化。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">5\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">5. 注入中断\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">测试进程重启、Webhook 重试、函数超时、自托管环境重新连接和过期领域状态。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">6\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">6. 比较追踪，而不仅仅是答案\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">对照基线验证工具选择、授权、证据路径、状态转换和副作用。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">7\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">7. 运行影子流量\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">在可行的情况下，在使新运行时成为权威之前重放或镜像代表性任务。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv class=\"editorjs-process__step min-w-0  rounded-xl border border-gray-200 dark:border-gray-700 p-4\">\u003Cdiv class=\"text-xs font-semibold text-gray-500 dark:text-gray-400\">8\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 font-semibold text-gray-900 dark:text-gray-100\">8. 在可逆边界之后切换\u003C\u002Fdiv>\u003Cdiv class=\"mt-1 text-sm text-gray-600 dark:text-gray-300\">在生产行为稳定之前保留集成适配器和回滚能力。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003C\u002Fdiv>\u003C\u002Fsection>\n\u003Ch2 id=\"section-122\">迁移期间应衡量什么\u003C\u002Fh2>\n\u003Cdiv class=\"overflow-x-auto\">\u003Ctable class=\"w-full border-collapse\">\u003Cthead>\u003Ctr>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">维度\u003C\u002Fth>\u003Cth class=\"border border-gray-300 px-4 py-2 text-left font-semibold\">迁移检查\u003C\u002Fth>\u003C\u002Ftr>\u003C\u002Fthead>\u003Ctbody>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">任务成功\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">新运行时是否满足相同或更好的验收标准？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">工具正确性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">它是否使用有效参数和授权调用正确的工具？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">状态连续性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">工作能否跨轮次、重启和异步等待恢复？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">恢复\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">Webhook 丢失、处理器失败、环境断开或超时后会发生什么？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">可追溯性\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">每个有后果的操作能否连接到会话、用户、工具调用和领域对象？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">上下文行为\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">长时间运行的会话能否在不携带过期应用程序事实的情况下保留约束？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">延迟\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">会话启动、环境配置和多轮工作如何影响用户可见时间？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">成本\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">模型使用、沙箱使用、重复上下文和基础设施操作会发生什么变化？\u003C\u002Ftd>\u003C\u002Ftr>\u003Ctr>\u003Ctd class=\"border border-gray-300 px-4 py-2\">运营负载\u003C\u002Ftd>\u003Ctd class=\"border border-gray-300 px-4 py-2\">哪些以前由应用程序拥有的责任实际上消失了，哪些只是转移了？\u003C\u002Ftd>\u003C\u002Ftr>\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Ch2 id=\"section-124\">何时还不应迁移\u003C\u002Fh2>\n\u003Cp>现有的 Agents SDK 应用程序不会仅仅因为平台方向改变就变成糟糕的架构。OpenAI 继续维护、安全修复、关键错误修复和兼容性工作。如果应用程序稳定、经过良好评估并且没有受阻的路线图需求，那么立即进行运行时迁移可能并不合理。\u003C\u002Fp>\n\u003Cul>\u003Cli>Agents API 中尚不提供所需的 SDK 能力。\u003C\u002Fli>\u003Cli>迁移会扰乱关键生产期，且无法带来近期价值。\u003C\u002Fli>\u003Cli>应用程序依赖于尚未在托管执行框架上验证的自定义编排语义。\u003C\u002Fli>\u003Cli>提供商可移植性是硬性要求，而当前 SDK 抽象具有实质性价值。\u003C\u002Fli>\u003Cli>你的团队尚未将业务状态与代理运行时状态分离，导致切换不安全。\u003C\u002Fli>\u003Cli>新的 Agents API 行为尚未针对代表性生产工作负载进行测试。\u003C\u002Fli>\u003C\u002Ful>\n\u003Ch2 id=\"section-127\">迁移何时具有战略重要性\u003C\u002Fh2>\n\u003Cp>当产品需求与托管执行框架相匹配时，迁移会变得更具吸引力：持久的长时运行工作、平台管理的上下文压缩与恢复、更新的智能体运行时能力、沙箱化执行、更丰富的托管生命周期管理，或希望减少应用程序所运行的编排代码量。\u003C\u002Fp>\n\u003Cp>最强的信号不是“旧 SDK 功能已完备”，而是“我们的路线图现在依赖于那些天然归属于托管 Agents API 运行时的能力”。\u003C\u002Fp>\n\u003Ch2 id=\"section-130\">什么会改变这一答案？\u003C\u002Fh2>\n\u003Cp>如果 OpenAI 发布自动化迁移工具、引入明确的兼容层、更改 Agents API 会话语义、扩大或缩小自托管环境支持，或更改 Agents SDK 的支持政策，迁移策略将会改变。\u003C\u002Fp>\n\u003Cp>如果你的产品需求发生变化，它也会改变。简单的请求-响应助手可能根本不需要持久的托管执行框架。长时运行的编码、研究或运维智能体则可以从 Agents API 的所有权模型中获益更多。\u003C\u002Fp>\n\u003Ch2 id=\"section-133\">局限性\u003C\u002Fh2>\n\u003Cp>不存在通用的 SDK 到 API 的一对一迁移映射，因为应用程序对 Agents SDK 的使用方式各不相同。有些严重依赖会话和交接；另一些则将其用作围绕函数工具的轻量运行器。正确的迁移取决于你的应用程序当前实际承担哪些职责。\u003C\u002Fp>\n\u003Cp>Agents API 也处于公开测试阶段，因此实现细节可能会演变。请将本文中的所有权原则视为比任何单个端点形态都更持久。\u003C\u002Fp>\n\u003Ch2 id=\"section-136\">结论\u003C\u002Fh2>\n\u003Cp>从 Agents SDK 迁移到 Agents API 最好理解为移动智能体运行时边界。托管执行框架接管了更多的循环、会话连续性、压缩和恢复。你的应用程序应更明确地界定仍属于自身的职责：领域真相、授权、函数副作用、工件、可审计性和产品生命周期。\u003C\u002Fp>\n\u003Cp>如果一次迁移保留了所有旧的编排机制，仅仅将 SDK 调用替换为 Agents API 调用，那么它很可能错失了架构上的机会。目标不是在新运行时之上复现旧运行时，而是决定哪些运行时职责不再属于你的应用程序。\u003C\u002Fp>\n\u003Ch2 id=\"section-139\">常见问题\u003C\u002Fh2>\n\u003Csection class=\"editorjs-faq my-6 rounded-xl border border-gray-200 p-5 dark:border-gray-700\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">从 Agents SDK 迁移到 Agents API\u003C\u002Fh3>\u003Cdiv id=\"faq1\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">从 Agents SDK 迁移到 Agents API 只是重写 API 吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">不是。主要变化是运行时所有权：Agents SDK 在你的应用程序中运行智能体循环，而 Agents API 运行托管的 Codex 执行框架和持久会话。状态、生命周期、事件处理和恢复应作为架构问题来审查。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq2\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">我的函数工具需要重写吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">如果业务实现已经位于稳定的应用程序接口之后，通常可以复用。面向智能体的集成会发生变化，因为 Agents API 函数调用通过会话所需操作和结果来处理。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq3\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">我应该将业务状态移入 Agents API 会话吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">通常不需要。将权威的业务和产品状态保留在你自己的数据库或服务中。将会话用于智能体连续性和工作上下文，而不是作为产品的唯一真相来源。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq4\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">Agents API 需要 webhook 吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">不一定，因为流式传输也可用。Webhook 对于长时运行或异步会话特别有用，在这些场景中，你的应用程序应对生命周期变化做出反应，而无需保持打开的流。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003Cdiv id=\"faq5\" class=\"border-t border-gray-200 py-4 first:border-t-0 dark:border-gray-700\">\u003Ch4 class=\"font-semibold text-gray-900 dark:text-gray-100\">每个现有的 Agents SDK 应用程序现在都应该迁移吗？\u003C\u002Fh4>\u003Cdiv class=\"mt-2 text-gray-600 dark:text-gray-300\">不。SDK 仍以维护模式提供支持。当新运行时提供有意义的路线图价值，并且在所需行为已针对生产形态的评估验证之后，再进行迁移。\u003C\u002Fdiv>\u003C\u002Fdiv>\u003C\u002Fsection>\n\u003Ch2 id=\"section-141\">术语表\u003C\u002Fh2>\n\u003Csection class=\"editorjs-glossary my-6 rounded-xl border border-gray-200 dark:border-gray-700 p-5\">\u003Ch3 class=\"mb-3 text-lg font-semibold\">关键迁移术语\u003C\u002Fh3>\u003Cdl>\u003Cdiv id=\"runtime-boundary\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">运行时边界\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">平台管理的智能体运行时与应用程序拥有的运行时之间的职责划分。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"harness\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">执行框架\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">协调模型调用、工具、上下文、编排和持续执行的智能体运行时。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"session\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">会话\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">一个持久的 Agents API 实例，保存智能体的配置、对话和跨轮次保存的工作。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"required-action\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">所需操作\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">Agents API 需要外部输入（如函数结果或环境连接）才能继续工作的会话状态。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"self-hosted-environment\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">自托管环境\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">由你的基础设施运行并连接到托管 Agents API 执行框架的执行环境。\u003C\u002Fdd>\u003C\u002Fdiv>\u003Cdiv id=\"migration-proof-test\" class=\"border-t border-gray-200 dark:border-gray-700 py-3 first:border-t-0\">\u003Cdt class=\"font-semibold text-gray-900 dark:text-gray-100\">迁移验证测试\u003C\u002Fdt>\u003Cdd class=\"mt-1 text-gray-600 dark:text-gray-300\">一种分阶段验证方法，将新运行时与行为基线、故障注入、追踪和可逆切换标准进行比较。\u003C\u002Fdd>\u003C\u002Fdiv>\u003C\u002Fdl>\u003C\u002Fsection>\n\u003Ch2 id=\"section-143\">主要来源与延伸阅读\u003C\u002Fh2>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Fsdk\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents SDK\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">当前支持政策：Agents SDK 功能已完备，仍受维护，新应用程序应从 Agents API 开始。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Frunning-agents\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 使用 Agents SDK 运行智能体\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">SDK 应用拥有的智能体循环与延续模型的文档。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Foverview\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 概述\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">定义 Agents API 核心概念：智能体、环境、会话、事件和条目。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Farchitecture\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 架构\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">解释托管执行框架、应用服务器、OpenAI 托管和自托管执行环境的边界。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fconfiguration\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 配置智能体\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">定义可复用的智能体配置和会话级自定义。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 运行和延续会话\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">记录持久会话、异步轮次、流式传输和引导。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Ftools\u002Ffunctions\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 函数\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">函数工具定义以及必需函数结果的应用处理程序边界。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\u002Fwebhooks\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — 会话 Webhook\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">异步会话的生命周期事件、必需操作和自托管环境连接。\u003C\u002Fp>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fobservability\" target=\"_blank\" rel=\"noopener noreferrer\" class=\"editorjs-link-tool block border border-gray-200 dark:border-gray-700 rounded-lg p-4 transition text-gray-900 dark:text-gray-100 hover:border-primary-500 hover:bg-primary-50 dark:hover:bg-gray-900 hover:text-gray-900 dark:hover:text-gray-100\">\u003Cstrong class=\"block font-semibold\">OpenAI — Agents API 可观测性和使用情况\u003C\u002Fstrong>\u003Cp class=\"text-sm text-gray-600 dark:text-gray-400\">会话日志、事件、轮次、工具调用、子智能体、追踪和令牌使用情况检查。\u003C\u002Fp>\u003C\u002Fa>",{"time":212,"blocks":213,"version":1309},1790352674499,[214,222,228,236,243,250,255,260,265,270,275,329,334,339,344,351,356,361,394,399,404,409,443,448,453,458,463,468,473,479,484,489,494,517,522,527,532,537,542,547,556,561,566,571,576,608,613,647,652,657,671,676,681,686,691,696,701,706,711,716,721,726,731,736,762,767,795,800,810,819,828,837,846,855,864,873,882,886,890,894,898,902,905,909,913,916,919,948,952,956,960,965,968,972,992,996,1000,1004,1020,1024,1028,1032,1036,1040,1044,1048,1052,1056,1060,1077,1081,1085,1089,1093,1097,1101,1104,1108,1112,1116,1119,1137,1141,1161,1165,1169,1176,1180,1184,1188,1192,1196,1200,1203,1207,1210,1213,1217,1221,1224,1240,1243,1255,1258,1264,1270,1276,1281,1286,1292,1298,1303],{"id":215,"data":216,"type":220,"tunes":221},"24Foq4L2Wb",{"title":217,"maxLevel":218,"minLevel":219},"目录",3,2,"tableOfContents",{},{"id":223,"data":224,"type":226,"tunes":227},"intro",{"text":225},"从 OpenAI Agents SDK 迁移到 Agents API 并不是重命名导入。核心架构边界发生了变化：SDK 在你的应用程序内部运行智能体循环，而 Agents API 在 OpenAI 一侧运行托管的 Codex 执行框架和持久会话。因此，迁移问题不是“哪些类映射到哪些端点？”，而是“哪些运行时职责跨越边界转移，哪些留在我们的应用程序中，哪些需要重新设计？”","paragraph",{},{"id":229,"data":230,"type":234,"tunes":235},"direct",{"body":231,"title":232,"variant":233},"\u003Cstrong>真正的 Agents SDK → Agents API 迁移会改变运行时所有权。\u003C\u002Fstrong>你的可复用智能体配置仍然可以包含模型、指令和工具，但循环、持久会话、编排、上下文压缩和恢复会向托管的 Agents API 运行时转移。你的应用程序应将领域状态、授权、业务规则、函数实现和审计逻辑保留在智能体会话之外。将迁移视为边界重新设计，而不是机械的代码转换。","直接回答","info","callout",{},{"id":237,"data":238,"type":234,"tunes":242},"current",{"body":239,"title":240,"variant":241},"OpenAI 目前将 Agents SDK 标记为\u003Cstrong>功能完备\u003C\u002Fstrong>，并推荐新智能体应用程序使用 Agents API。Agents API 处于公开测试阶段。现有 SDK 应用程序仍受支持，并不自动要求立即迁移。","截至 2026 年 9 月 25 日的最新情况","warning",{},{"id":244,"data":245,"type":234,"tunes":249},"model-note",{"body":246,"title":247,"variant":248},"本文中的运行时边界迁移图和迁移验证测试是实用的架构工具，并非 OpenAI 官方迁移框架。它们源自 OpenAI 记录的当前运行时差异。","关于迁移模型","note",{},{"id":251,"data":252,"type":42,"tunes":254},"h-boundary",{"text":253,"level":219},"迁移是从应用程序拥有的循环转向托管执行框架",{},{"id":256,"data":257,"type":226,"tunes":259},"p-boundary-1",{"text":258},"在 Agents SDK 中，一次运行是应用程序级别的一轮。SDK 运行器调用模型、检查输出、执行工具、遵循交接并持续进行，直到到达停止点。你的进程承载该循环，因此拥有其生命周期。",{},{"id":261,"data":262,"type":226,"tunes":264},"p-boundary-2",{"text":263},"在 Agents API 中，OpenAI 运行执行框架。会话是智能体配置的持久实例，它接受任务、产生事件、可以暂停以等待所需操作，并可以随时间继续。OpenAI 管理会话、编排、上下文压缩和恢复；你的应用程序发送工作、处理函数工具、接收事件，并可选地管理自托管执行环境。",{},{"id":266,"data":267,"type":226,"tunes":269},"p-boundary-3",{"text":268},"这种所有权转移就是迁移。其他一切——API 语法、工具模式、事件处理、会话 ID——都由此而来。",{},{"id":271,"data":272,"type":42,"tunes":274},"h-map",{"text":273,"level":219},"运行时边界迁移图",{},{"id":276,"data":277,"type":327,"tunes":328},"migration-map",{"content":278,"stretched":43,"withHeadings":14},[279,283,287,291,295,299,303,307,311,315,319,323],[280,281,282],"关注点","Agents SDK","Agents API 迁移目标",[284,285,286],"智能体循环","通过 SDK 运行器在你的应用程序中运行","在托管的 Codex 执行框架中运行",[288,289,290],"可复用智能体定义","应用程序代码中的 Agent 对象","包含模型、指令和工具的已保存或内联智能体配置",[292,293,294],"对话 \u002F 工作连续性","SDK 会话策略、历史记录、结果延续或应用程序存储","持久 Agents API 会话",[296,297,298],"工具执行","SDK 在你的运行时中协调工具调用","执行框架请求函数调用；你的应用程序返回结果",[300,301,302],"上下文管理","你的运行时 \u002F SDK 会话策略","托管会话上下文、压缩和恢复，以及你自己的应用程序数据边界",[304,305,306],"交接 \u002F 专家","SDK 编排原语","Agents API 中的执行框架 \u002F 子智能体行为；不要假设一对一语义",[308,309,310],"执行环境","你的应用程序运行时或特定工具环境","附加到会话的可选 OpenAI 托管或自托管环境",[312,313,314],"流式传输","来自运行的 SDK 流式传输","Agents API 会话事件流",[316,317,318],"异步生命周期","通常由应用程序围绕 SDK 运行进行管理","原生会话状态、异步轮次和 webhook",[320,321,322],"追踪 \u002F 可观测性","Agents SDK 追踪和应用程序日志","Agents 会话日志、事件、轮次、工具调用、子智能体和可导出追踪",[324,325,326],"恢复","应用程序责任","托管执行框架\u002F会话恢复，以及针对外部系统和自托管环境的应用程序自有恢复","table",{},{"id":330,"data":331,"type":42,"tunes":333},"h-conceptual",{"text":332,"level":219},"哪些内容可以在不改变所有权的情况下从概念上迁移",{},{"id":335,"data":336,"type":226,"tunes":338},"p-conceptual-1",{"text":337},"若干应用程序概念即使表示形式发生变化，也能顺利通过迁移保留下来。模型、指令、JSON-schema 函数定义、MCP 访问、工具描述和结构化输出要求仍然是智能体配置关注点。",{},{"id":340,"data":341,"type":226,"tunes":343},"p-conceptual-2",{"text":342},"OpenAI 的 Agents API 配置模型明确通过模型、指令、工具、推理和输出行为来定义智能体。函数工具仍然是应用程序代码：执行框架请求函数调用，你的处理程序返回结果。OpenAI 还指出，与 Responses API 一起使用的函数实现可以在 Agents API 会话流程中复用。",{},{"id":345,"data":346,"type":234,"tunes":350},"good-candidate",{"body":347,"title":348,"variant":349},"像 \u003Ccode>get_customer(customer_id)\u003C\u002Fcode> 这样的纯业务函数不应需要知道调用方是 Agents SDK 还是 Agents API。将其领域逻辑保留在稳定的应用程序接口之后，只迁移面向智能体的适配器。","良好的迁移候选","success",{},{"id":352,"data":353,"type":42,"tunes":355},"h-no-one",{"text":354,"level":219},"哪些内容不应一对一迁移",{},{"id":357,"data":358,"type":226,"tunes":360},"p-no-one-1",{"text":359},"危险的迁移模式是在 Agents API 中重建每个 SDK 运行时抽象。这可能导致你为托管执行框架付费，同时仍在应用程序中运行一个影子执行框架。",{},{"id":362,"data":363,"type":327,"tunes":393},"no-one-table",{"content":364,"stretched":43,"withHeadings":14},[365,369,373,377,381,385,389],[366,367,368],"SDK 时代的假设","为什么直接复制有风险","迁移问题",[370,371,372],"应用程序循环拥有每次延续","Agents API 已经拥有执行框架循环","哪些延续逻辑是产品逻辑，哪些应转移到托管会话？",[374,375,376],"本地会话对象是主要连续性机制","Agents API 会话是具有自身生命周期的持久资源","哪些状态属于会话，哪些属于产品数据库？",[378,379,380],"每次中断都同步处理","Agents API 轮次是异步的，并可能暴露 action_required 状态","哪些操作需要 webhook、工作进程、幂等性和可恢复处理程序？",[382,383,384],"所有工具执行都发生在 SDK 进程运行的地方","函数处理程序和执行环境可以分离","每个工具实际应在哪里执行？",[386,387,388],"SDK 追踪是运营时间线","Agents API 暴露会话事件、轮次和托管追踪","哪些应用程序级审计数据仍需要自己的记录？",[390,391,392],"交接对象直接映射到托管子智能体模型","运行时语义可能不同","必须保留哪些用户可见的所有权和专家行为，而不仅仅是旧的类结构？",{},{"id":395,"data":396,"type":42,"tunes":398},"h-domain",{"text":397,"level":219},"步骤 1 — 将领域状态与代理会话状态分离",{},{"id":400,"data":401,"type":226,"tunes":403},"p-domain-1",{"text":402},"在接触 API 调用之前，先对你 SDK 应用当前承载的状态进行分类。有些状态仅用于维持代理对话的推进。其他状态则是业务事实：用户权限、项目状态、订单数据、工作流审批、客户记录、文档版本、策略状态或应用配置。",{},{"id":405,"data":406,"type":226,"tunes":408},"p-domain-2",{"text":407},"第二类状态不应依赖于 Agents API 会话。持久会话对代理而言是有用的连续性，但它不能替代你产品的真实来源。如果会话消失、过期、被重建或更改实现，你的应用仍必须知道什么是真实的。",{},{"id":410,"data":411,"type":441,"tunes":442},"state-test",{"rows":412,"title":430,"layout":327,"columns":431},[413,418,422,426],{"id":414,"label":415,"values":416},"conversation","对话连续性",[417,417,417],"",{"id":419,"label":420,"values":421},"domain","业务事实",[417,417,417],{"id":423,"label":424,"values":425},"artifact","持久工件",[417,417,417],{"id":427,"label":428,"values":429},"ephemeral","工作暂存状态",[417,417,417],"状态放置测试",[432,435,438],{"id":433,"label":434},"type","状态类型",{"id":436,"label":437},"place","首选所有者",{"id":439,"label":440},"reason","原因","comparison",{},{"id":444,"data":445,"type":42,"tunes":447},"h-events",{"text":446,"level":219},"步骤 2 — 将运行器思维转变为会话与事件思维",{},{"id":449,"data":450,"type":226,"tunes":452},"p-events-1",{"text":451},"SDK 应用通常以调用 run 并接收结果的方式思考。Agents API 则以持久会话的方式思考，其轮次可以异步运行。向空闲会话发送消息会启动工作；在活动轮次期间发送消息可以引导它。进度通过流式传输或 webhook 到达。",{},{"id":454,"data":455,"type":226,"tunes":457},"p-events-2",{"text":456},"这会影响应用架构。长时间运行的生产工作不应依赖于单个 HTTP 请求保持存活。你的产品需要稳定的会话标识符、生命周期持久化、webhook 验证、幂等处理器，以及进程重启后协调当前会话状态的方法。",{},{"id":459,"data":460,"type":42,"tunes":462},"h-functions",{"text":461,"level":219},"步骤 3 — 围绕所需操作重新设计函数工具",{},{"id":464,"data":465,"type":226,"tunes":467},"p-functions-1",{"text":466},"函数工具仍然是重要的应用边界。你在代理配置中定义函数及其 JSON schema。当 harness 需要该函数时，会话可以进入需要操作的状态。你的应用检索所需操作，执行业务逻辑并返回结果。",{},{"id":469,"data":470,"type":226,"tunes":472},"p-functions-2",{"text":471},"这意味着函数实现应可安全恢复。webhook 可能在另一个工作进程处理时被投递。网络故障可能发生在外部副作用之后但在结果返回之前。因此，迁移是向重要工具添加调用 ID、幂等键、显式授权、超时策略和审计记录的好时机。",{},{"id":474,"data":475,"type":234,"tunes":478},"tool-trap",{"body":476,"title":477,"variant":241},"不要将来自托管 harness 的函数调用视为执行该操作的授权。harness 决定\u003Cem>它想要调用什么\u003C\u002Fem>；你的应用仍然决定当前用户、会话和业务状态是否允许该操作。","工具迁移陷阱",{},{"id":480,"data":481,"type":42,"tunes":483},"h-environment",{"text":482,"level":219},"步骤 4 — 决定执行应发生在何处",{},{"id":485,"data":486,"type":226,"tunes":488},"p-env-1",{"text":487},"Agents API 将托管 harness 与执行环境分离。代理可以在没有专用环境的情况下运行，在 OpenAI 托管的沙箱中运行，或通过与会话连接的自托管环境运行。",{},{"id":490,"data":491,"type":226,"tunes":493},"p-env-2",{"text":492},"这产生了一个 SDK 应用可能从未明确做出的迁移决策：哪些代码应作为应用函数运行，哪些代码属于沙箱，哪些工作负载需要你控制的基础设施？",{},{"id":495,"data":496,"type":327,"tunes":516},"environment-table",{"content":497,"stretched":43,"withHeadings":14},[498,501,504,507,510,513],[499,500],"需求","可能的边界",[502,503],"通过受控业务逻辑调用现有内部服务","由你的应用处理的函数工具",[505,506],"在没有私有基础设施的情况下运行隔离代码或处理临时文件","OpenAI 托管环境",[508,509],"访问私有网络资源、自定义系统软件或受控本地计算","自托管环境",[511,512],"持久化已接受的产品工件","应用拥有的存储，而不仅仅是沙箱文件系统",[514,515],"执行高影响的业务副作用","具有授权和审计控制的应用函数",{},{"id":518,"data":519,"type":42,"tunes":521},"h-recovery",{"text":520,"level":219},"步骤 5 — 用显式生命周期处理替代隐式恢复",{},{"id":523,"data":524,"type":226,"tunes":526},"p-recovery-1",{"text":525},"托管 harness 提供会话级恢复，但你的应用仍然拥有其周围的每个外部依赖。自托管环境需要配置、重新连接和关闭。函数处理器可能失败。webhook 可能被重试。产品侧状态可能在代理空闲时发生变化。",{},{"id":528,"data":529,"type":226,"tunes":531},"p-recovery-2",{"text":530},"因此，迁移需要两种恢复模型：代理运行时恢复和业务操作恢复。第一种越来越多地由 Agents API 管理。第二种仍然是你的责任。",{},{"id":533,"data":534,"type":42,"tunes":536},"h-observability",{"text":535,"level":219},"第6步 — 围绕新的追踪边界重建可观测性",{},{"id":538,"data":539,"type":226,"tunes":541},"p-obs-1",{"text":540},"Agents API 会话会暴露事件、保存的历史记录、轮次、工具调用、子代理和令牌使用情况。OpenAI 还在平台中提供会话日志和追踪导出。",{},{"id":543,"data":544,"type":226,"tunes":546},"p-obs-2",{"text":545},"不要因为平台追踪有所改进就丢弃你的应用可观测性。产品日志仍然需要将代理会话与用户身份、授权决策、领域对象、工具副作用、审批记录和最终接受的结果关联起来。有用的生产追踪是代理运行时证据与业务运行时证据之间的连接。",{},{"id":548,"data":549,"type":554,"tunes":555},"ref-reliability",{"url":550,"title":551,"excerpt":552,"ctaLabel":553},"https:\u002F\u002Fstajic.de\u002Fzh\u002Fblog\u002Fai-agent-reliability-why-the-final-answer-is-not-enough","AI 代理可靠性：为什么最终答案还不够","代理可靠性取决于执行路径、工具和中间决策——而不仅仅是最终输出。","阅读可靠性文章","referralArticle",{},{"id":557,"data":558,"type":42,"tunes":560},"h-evals",{"text":559,"level":219},"第7步 — 在更改运行时之前保留评估",{},{"id":562,"data":563,"type":226,"tunes":565},"p-evals-1",{"text":564},"迁移可能看起来成功，因为新系统仍然产生看似合理的答案，同时悄然改变了工具选择、会话连续性、交接行为、延迟或故障恢复。在切换运行时之前建立行为基线。",{},{"id":567,"data":568,"type":226,"tunes":570},"p-evals-2",{"text":569},"基线应包括代表性任务、预期工具调用、禁止操作、审批点、状态连续性、恢复场景和最终输出验收标准。尽可能对相同案例运行新旧架构。",{},{"id":572,"data":573,"type":42,"tunes":575},"h-proof",{"text":574,"level":219},"迁移验证测试",{},{"id":577,"data":578,"type":606,"tunes":607},"proof-flow",{"steps":579,"title":604,"orientation":605},[580,583,586,589,592,595,598,601],{"label":581,"description":582},"1. 冻结行为基线","捕获代表性 SDK 追踪、预期输出、工具路径、审批点和失败案例。",{"label":584,"description":585},"2. 清点状态所有权","将每个状态字段标记为代理会话状态、权威领域状态、持久工件或临时工作状态。",{"label":587,"description":588},"3. 复用稳定的工具实现","将业务功能保留在应用接口之后；尽可能只替换面向代理的集成。",{"label":590,"description":591},"4. 构建一个 Agents API 垂直切片","迁移一个生产形态的工作流，包括会话创建、工具、事件、环境和持久化。",{"label":593,"description":594},"5. 注入中断","测试进程重启、webhook 重试、函数超时、自托管环境重连和过期领域状态。",{"label":596,"description":597},"6. 比较追踪，而不仅仅是答案","对照基线验证工具选择、授权、证据路径、状态转换和副作用。",{"label":599,"description":600},"7. 运行影子流量","在可行的情况下，在使新运行时成为权威之前重放或镜像代表性任务。",{"label":602,"description":603},"8. 在可逆边界之后切换","保持集成适配器和回滚能力，直到生产行为稳定。","在切换之前验证新运行时","auto","processFlow",{},{"id":609,"data":610,"type":42,"tunes":612},"h-metrics",{"text":611,"level":219},"迁移期间要衡量什么",{},{"id":614,"data":615,"type":327,"tunes":646},"metrics-table",{"content":616,"stretched":43,"withHeadings":14},[617,620,623,626,629,631,634,637,640,643],[618,619],"维度","迁移检查",[621,622],"任务成功","新运行时是否满足相同或更好的验收标准？",[624,625],"工具正确性","它是否使用有效参数和授权调用正确的工具？",[627,628],"状态连续性","工作能否在轮次、重启和异步等待之间恢复？",[324,630],"webhook 丢失、处理器失败、环境断开或超时后会发生什么？",[632,633],"可追溯性","每个重要操作能否关联到会话、用户、工具调用和领域对象？",[635,636],"上下文行为","长时间运行的会话是否在不携带过期应用事实的情况下保留约束？",[638,639],"延迟","会话启动、环境配置和多轮工作如何影响用户可见时间？",[641,642],"成本","模型使用、沙箱使用、重复上下文和基础设施操作方面有哪些变化？",[644,645],"运营负载","哪些以前由应用承担的职责真正消失了，哪些只是转移了？",{},{"id":648,"data":649,"type":42,"tunes":651},"h-not-yet",{"text":650,"level":219},"何时还不要迁移",{},{"id":653,"data":654,"type":226,"tunes":656},"p-not-yet-1",{"text":655},"现有的 Agents SDK 应用不会仅仅因为平台方向改变就变成糟糕的架构。OpenAI 继续维护、安全修复、关键错误修复和兼容性工作。如果应用稳定、评估良好且没有受阻的路线图需求，立即迁移运行时可能并不合理。",{},{"id":658,"data":659,"type":669,"tunes":670},"not-yet-list",{"meta":660,"items":661,"style":668},{},[662,663,664,665,666,667],"Agents API 中尚不提供所需的 SDK 能力。","迁移会扰乱关键生产期，且无法带来近期价值。","应用依赖于尚未在托管 harness 上验证的自定义编排语义。","提供商可移植性是硬性要求，且当前 SDK 抽象具有重大价值。","你的团队尚未将业务状态与代理运行时状态分离，导致切换不安全。","新的 Agents API 行为尚未针对代表性生产工作负载进行测试。","unordered","list",{},{"id":672,"data":673,"type":42,"tunes":675},"h-when",{"text":674,"level":219},"迁移何时变得具有战略重要性",{},{"id":677,"data":678,"type":226,"tunes":680},"p-when-1",{"text":679},"当产品需求与托管 harness 一致时，迁移变得更具吸引力：持久的长时运行工作、平台管理的上下文压缩和恢复、更新的代理运行时能力、沙箱执行、更丰富的托管生命周期管理，或希望减少应用运营的编排代码量。",{},{"id":682,"data":683,"type":226,"tunes":685},"p-when-2",{"text":684},"最强的信号不是“旧 SDK 功能完备”。而是“我们的路线图现在依赖于那些自然归属于托管 Agents API 运行时的能力。”",{},{"id":687,"data":688,"type":42,"tunes":690},"h-change",{"text":689,"level":219},"什么会改变这个答案？",{},{"id":692,"data":693,"type":226,"tunes":695},"p-change-1",{"text":694},"如果 OpenAI 发布自动化迁移工具、引入显式兼容层、更改 Agents API 会话语义、扩大或缩小自托管环境支持范围，或更改 Agents SDK 的支持政策，迁移策略将会改变。",{},{"id":697,"data":698,"type":226,"tunes":700},"p-change-2",{"text":699},"如果你的产品需求发生变化，迁移策略也会改变。简单的请求-响应助手可能根本不需要持久化的托管执行框架。长时间运行的编码、研究或运维智能体则可以从 Agents API 的所有权模型中获益更多。",{},{"id":702,"data":703,"type":42,"tunes":705},"h-limitations",{"text":704,"level":219},"局限性",{},{"id":707,"data":708,"type":226,"tunes":710},"p-limit-1",{"text":709},"不存在通用的 SDK 到 API 的一对一迁移映射，因为不同应用使用 Agents SDK 的方式各不相同。有些严重依赖会话和交接；有些则将其用作函数工具的轻量运行器。正确的迁移方式取决于你的应用目前实际承担哪些职责。",{},{"id":712,"data":713,"type":226,"tunes":715},"p-limit-2",{"text":714},"Agents API 也处于公开测试阶段，因此实现细节可能会演变。请将本文中的所有权原则视为比任何单个端点形态都更持久。",{},{"id":717,"data":718,"type":42,"tunes":720},"h-conclusion",{"text":719,"level":219},"结论",{},{"id":722,"data":723,"type":226,"tunes":725},"p-conclusion-1",{"text":724},"从 Agents SDK 迁移到 Agents API 最好理解为移动智能体运行时边界。托管执行框架接管了更多的循环、会话连续性、压缩和恢复。你的应用应该更明确地界定仍属于自身的职责：领域真相、授权、函数副作用、产物、可审计性和产品生命周期。",{},{"id":727,"data":728,"type":226,"tunes":730},"p-conclusion-2",{"text":729},"如果一次迁移保留了所有旧的编排机制，仅仅将 SDK 调用替换为 Agents API 调用，那么它很可能错失了架构上的机会。目标不是在新运行时之上复制旧运行时。目标是决定哪些运行时职责不再属于你的应用。",{},{"id":732,"data":733,"type":42,"tunes":735},"h-faq",{"text":734,"level":219},"常见问题",{},{"id":737,"data":738,"type":737,"tunes":761},"faq",{"items":739,"title":760},[740,744,748,752,756],{"id":741,"answer":742,"question":743},"faq1","不是。主要变化是运行时所有权：Agents SDK 在你的应用中运行智能体循环，而 Agents API 运行托管的 Codex 执行框架和持久会话。状态、生命周期、事件处理和恢复应作为架构关注点进行审查。","从 Agents SDK 迁移到 Agents API 只是 API 重写吗？",{"id":745,"answer":746,"question":747},"faq2","如果业务实现已经位于稳定的应用接口之后，通常可以复用。面向智能体的集成会发生变化，因为 Agents API 函数调用通过会话所需操作和结果来处理。","我的函数工具需要重写吗？",{"id":749,"answer":750,"question":751},"faq3","通常不需要。将权威的业务和产品状态保留在你自己的数据库或服务中。将会话用于智能体连续性和工作上下文，而不是作为产品的唯一真相来源。","我应该将业务状态迁移到 Agents API 会话中吗？",{"id":753,"answer":754,"question":755},"faq4","不一定，因为流式传输也可用。Webhook 对于长时间运行或异步会话特别有用，你的应用可以在不保持开放流的情况下对生命周期变化做出反应。","Agents API 需要 webhook 吗？",{"id":757,"answer":758,"question":759},"faq5","不是。SDK 仍以维护模式提供支持。当新运行时提供有意义的路线图价值，并且所需行为已针对生产形态的评估进行验证后，再进行迁移。","每个现有的 Agents SDK 应用现在都应该迁移吗？","从 Agents SDK 迁移到 Agents API",{},{"id":763,"data":764,"type":42,"tunes":766},"h-glossary",{"text":765,"level":219},"术语表",{},{"id":768,"data":769,"type":768,"tunes":794},"glossary",{"title":770,"entries":771},"关键迁移术语",[772,776,780,784,788,791],{"term":773,"anchor":774,"definition":775},"运行时边界","runtime-boundary","平台管理的智能体运行时与应用拥有的运行时之间的职责划分。",{"term":777,"anchor":778,"definition":779},"执行框架","harness","协调模型调用、工具、上下文、编排和持续执行的智能体运行时。",{"term":781,"anchor":782,"definition":783},"会话","session","一个持久的 Agents API 实例，跨轮次保存智能体的配置、对话和已保存的工作。",{"term":785,"anchor":786,"definition":787},"所需操作","required-action","Agents API 需要外部输入（如函数结果或环境连接）才能继续工作的会话状态。",{"term":509,"anchor":789,"definition":790},"self-hosted-environment","由你的基础设施运行并连接到托管 Agents API 执行框架的执行环境。",{"term":574,"anchor":792,"definition":793},"migration-proof-test","一种分阶段验证方法，将新运行时与行为基线、故障注入、追踪和可逆切换标准进行比较。",{},{"id":796,"data":797,"type":42,"tunes":799},"h-sources",{"text":798,"level":219},"主要来源与延伸阅读",{},{"id":801,"data":802,"type":808,"tunes":809},"src-sdk",{"link":803,"meta":804},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Fsdk",{"image":805,"title":806,"description":807},{"url":417},"OpenAI — Agents SDK","当前支持政策：Agents SDK 功能完备，仍受维护，新应用应从 Agents API 开始。","linkTool",{},{"id":811,"data":812,"type":808,"tunes":818},"src-running-sdk",{"link":813,"meta":814},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Frunning-agents",{"image":815,"title":816,"description":817},{"url":417},"OpenAI — 使用 Agents SDK 运行智能体","SDK 应用拥有的智能体循环和延续模型的文档。",{},{"id":820,"data":821,"type":808,"tunes":827},"src-api-overview",{"link":822,"meta":823},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Foverview",{"image":824,"title":825,"description":826},{"url":417},"OpenAI — Agents API 概述","定义 Agents API 核心概念：智能体、环境、会话、事件和项目。",{},{"id":829,"data":830,"type":808,"tunes":836},"src-api-architecture",{"link":831,"meta":832},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Farchitecture",{"image":833,"title":834,"description":835},{"url":417},"OpenAI — Agents API 架构","解释托管执行框架、应用服务器、OpenAI 托管和自托管执行环境的边界。",{},{"id":838,"data":839,"type":808,"tunes":845},"src-api-config",{"link":840,"meta":841},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fconfiguration",{"image":842,"title":843,"description":844},{"url":417},"OpenAI — 配置智能体","定义可复用的智能体配置和会话级自定义。",{},{"id":847,"data":848,"type":808,"tunes":854},"src-api-sessions",{"link":849,"meta":850},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions",{"image":851,"title":852,"description":853},{"url":417},"OpenAI — 运行并继续会话","记录持久会话、异步轮次、流式传输和引导。",{},{"id":856,"data":857,"type":808,"tunes":863},"src-api-functions",{"link":858,"meta":859},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Ftools\u002Ffunctions",{"image":860,"title":861,"description":862},{"url":417},"OpenAI — Agents API 函数","函数工具定义以及必需函数结果的应用程序处理程序边界。",{},{"id":865,"data":866,"type":808,"tunes":872},"src-api-webhooks",{"link":867,"meta":868},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\u002Fwebhooks",{"image":869,"title":870,"description":871},{"url":417},"OpenAI — 会话 Webhook","异步会话的生命周期事件、必需操作和自托管环境连接。",{},{"id":874,"data":875,"type":808,"tunes":881},"src-api-observability",{"link":876,"meta":877},"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fobservability",{"image":878,"title":879,"description":880},{"url":417},"OpenAI — Agents API 可观测性和使用情况","会话日志、事件、轮次、工具调用、子代理、追踪和令牌使用情况检查。",{},{"id":223,"data":883,"type":226,"tunes":885},{"text":884},"从 OpenAI Agents SDK 迁移到 Agents API 并不是重命名导入。核心架构边界发生了变化：SDK 在您的应用程序内运行代理循环，而 Agents API 在 OpenAI 侧运行托管的 Codex 执行框架和持久会话。因此，迁移问题不是“哪些类映射到哪些端点？”，而是“哪些运行时职责跨越边界转移，哪些留在我们的应用程序中，哪些需要重新设计？”",{},{"id":229,"data":887,"type":234,"tunes":889},{"body":888,"title":232,"variant":233},"\u003Cstrong>真正的 Agents SDK → Agents API 迁移会改变运行时所有权。\u003C\u002Fstrong> 您可复用的代理配置仍然可以包含模型、指令和工具，但循环、持久会话、编排、上下文压缩和恢复会向托管的 Agents API 运行时转移。您的应用程序应将领域状态、授权、业务规则、函数实现和审计逻辑保留在代理会话之外。将迁移视为边界重新设计，而不是机械的代码转换。",{},{"id":237,"data":891,"type":234,"tunes":893},{"body":892,"title":240,"variant":241},"OpenAI 目前将 Agents SDK 标记为\u003Cstrong>功能完备\u003C\u002Fstrong>，并建议新的代理应用程序使用 Agents API。Agents API 处于公开测试阶段。现有 SDK 应用程序仍受支持，并不自动要求立即迁移。",{},{"id":244,"data":895,"type":234,"tunes":897},{"body":896,"title":247,"variant":248},"本文中的运行时边界迁移图和迁移验证测试是实用的架构工具，并非 OpenAI 官方迁移框架。它们源自 OpenAI 当前记录的运行时差异。",{},{"id":899,"data":900,"type":220,"tunes":901},"toc",{"title":217,"maxLevel":218,"minLevel":219},{},{"id":251,"data":903,"type":42,"tunes":904},{"text":253,"level":219},{},{"id":256,"data":906,"type":226,"tunes":908},{"text":907},"在 Agents SDK 中，一次运行是应用程序级别的轮次。SDK 运行器调用模型、检查输出、执行工具、遵循交接并持续运行，直到到达停止点。您的进程承载该循环，因此拥有其生命周期。",{},{"id":261,"data":910,"type":226,"tunes":912},{"text":911},"在 Agents API 中，OpenAI 运行执行框架。会话是代理配置的持久实例，它接受任务、产生事件、可以暂停以执行必需操作，并可以随时间继续。OpenAI 管理会话、编排、上下文压缩和恢复；您的应用程序发送工作、处理函数工具、接收事件，并可选地管理自托管执行环境。",{},{"id":266,"data":914,"type":226,"tunes":915},{"text":268},{},{"id":271,"data":917,"type":42,"tunes":918},{"text":273,"level":219},{},{"id":276,"data":920,"type":327,"tunes":947},{"content":921,"stretched":43,"withHeadings":14},[922,923,926,929,930,933,936,938,940,941,943,945],[280,281,282],[924,925,286],"代理循环","通过 SDK 运行器在您的应用程序中运行",[927,289,928],"可复用代理定义","包含模型、指令和工具的已保存或内联代理配置",[292,293,294],[296,931,932],"SDK 在您的运行时中协调工具调用","执行框架请求函数调用；您的应用程序返回结果",[300,934,935],"您的运行时 \u002F SDK 会话策略","托管会话上下文、压缩和恢复，以及您自己的应用程序数据边界",[304,305,937],"Agents API 中的执行框架 \u002F 子代理行为；不要假设一对一语义",[308,939,310],"您的应用程序运行时或特定工具环境",[312,313,314],[316,317,942],"原生会话状态、异步轮次和 Webhook",[320,321,944],"Agents 会话日志、事件、轮次、工具调用、子代理和可导出的追踪",[324,325,946],"托管执行框架\u002F会话恢复，以及应用程序拥有的外部系统和自托管环境恢复",{},{"id":330,"data":949,"type":42,"tunes":951},{"text":950,"level":219},"哪些内容可以在不改变所有权的情况下进行概念性迁移",{},{"id":335,"data":953,"type":226,"tunes":955},{"text":954},"若干应用程序概念在迁移后可以完好保留，尽管其表示形式发生了变化。模型、指令、JSON 模式函数定义、MCP 访问、工具描述和结构化输出要求仍然是代理配置关注点。",{},{"id":340,"data":957,"type":226,"tunes":959},{"text":958},"OpenAI 的 Agents API 配置模型通过模型、指令、工具、推理和输出行为明确定义代理。函数工具仍然是应用程序代码：执行框架请求函数调用，您的处理程序返回结果。OpenAI 还指出，与 Responses API 一起使用的函数实现可以在 Agents API 会话流程中复用。",{},{"id":345,"data":961,"type":234,"tunes":964},{"body":962,"title":963,"variant":349},"像 \u003Ccode>get_customer(customer_id)\u003C\u002Fcode> 这样的纯业务函数不应需要知道调用方是 Agents SDK 还是 Agents API。将其领域逻辑保持在稳定的应用接口之后，只迁移面向代理的适配器。","良好的迁移候选对象",{},{"id":352,"data":966,"type":42,"tunes":967},{"text":354,"level":219},{},{"id":357,"data":969,"type":226,"tunes":971},{"text":970},"危险的迁移模式是在 Agents API 中重建每一个 SDK 运行时抽象。这可能导致你为托管执行框架付费，同时仍在应用中运行一个影子执行框架。",{},{"id":362,"data":973,"type":327,"tunes":991},{"content":974,"stretched":43,"withHeadings":14},[975,976,979,981,984,986,989],[366,367,368],[977,371,978],"应用循环拥有每一次继续执行","哪些继续执行逻辑是产品逻辑，哪些应移至托管会话？",[980,375,376],"本地会话对象是主要的连续性机制",[378,982,983],"Agents API 轮次是异步的，可能呈现 action_required 状态","哪些操作需要 webhook、工作进程、幂等性和可恢复处理器？",[382,985,384],"函数处理器和执行环境可以分离",[987,387,988],"SDK 追踪是操作时间线","哪些应用级审计数据仍需要自己的记录？",[990,391,392],"交接对象直接映射到托管子代理模型",{},{"id":395,"data":993,"type":42,"tunes":995},{"text":994,"level":219},"第 1 步 — 将领域状态与代理会话状态分离",{},{"id":400,"data":997,"type":226,"tunes":999},{"text":998},"在接触 API 调用之前，先对你 SDK 应用当前承载的状态进行分类。有些状态仅用于保持代理对话继续进行。其他状态是业务事实：用户权限、项目状态、订单数据、工作流审批、客户记录、文档版本、策略状态或应用配置。",{},{"id":405,"data":1001,"type":226,"tunes":1003},{"text":1002},"第二类不应变得依赖于 Agents API 会话。持久会话对代理来说是有用的连续性；它不是产品事实来源的替代品。如果会话消失、过期、重建或更改实现，你的应用仍必须知道什么是真实的。",{},{"id":410,"data":1005,"type":441,"tunes":1019},{"rows":1006,"title":430,"layout":327,"columns":1015},[1007,1009,1011,1013],{"id":414,"label":415,"values":1008},[417,417,417],{"id":419,"label":420,"values":1010},[417,417,417],{"id":423,"label":424,"values":1012},[417,417,417],{"id":427,"label":428,"values":1014},[417,417,417],[1016,1017,1018],{"id":433,"label":434},{"id":436,"label":437},{"id":439,"label":440},{},{"id":444,"data":1021,"type":42,"tunes":1023},{"text":1022,"level":219},"第 2 步 — 将运行器思维转变为会话与事件思维",{},{"id":449,"data":1025,"type":226,"tunes":1027},{"text":1026},"SDK 应用通常以调用 run 并接收结果的思维方式思考。Agents API 则以持久会话的思维方式思考，其轮次可以异步运行。向空闲会话发送消息会启动工作；在活动轮次期间发送消息可以引导它。进度通过流式传输或 webhook 到达。",{},{"id":454,"data":1029,"type":226,"tunes":1031},{"text":1030},"这会影响应用架构。长时间运行的生产工作不应依赖于一个保持存活的 HTTP 请求。你的产品需要稳定的会话标识符、生命周期持久化、webhook 验证、幂等处理器，以及进程重启后协调当前会话状态的方法。",{},{"id":459,"data":1033,"type":42,"tunes":1035},{"text":1034,"level":219},"第 3 步 — 围绕所需操作重新设计函数工具",{},{"id":464,"data":1037,"type":226,"tunes":1039},{"text":1038},"函数工具仍然是重要的应用边界。你在代理配置中定义函数及其 JSON schema。当执行框架需要该函数时，会话可以进入 action-required 状态。你的应用检索所需操作，执行业务逻辑并返回结果。",{},{"id":469,"data":1041,"type":226,"tunes":1043},{"text":1042},"这意味着函数实现应可安全恢复。webhook 可能在另一个工作进程处理时被送达。网络故障可能发生在外部副作用之后但结果返回之前。因此，迁移是向重要工具添加调用 ID、幂等键、显式授权、超时策略和审计记录的好时机。",{},{"id":474,"data":1045,"type":234,"tunes":1047},{"body":1046,"title":477,"variant":241},"不要将来自托管执行框架的函数调用视为执行该操作的授权。执行框架决定\u003Cem>它想要调用什么\u003C\u002Fem>；你的应用仍然决定当前用户、会话和业务状态是否允许该操作。",{},{"id":480,"data":1049,"type":42,"tunes":1051},{"text":1050,"level":219},"第 4 步 — 决定执行应发生在哪里",{},{"id":485,"data":1053,"type":226,"tunes":1055},{"text":1054},"Agents API 将托管执行框架与执行环境分离。代理可以在没有专用环境的情况下运行，在 OpenAI 托管的沙箱中运行，或通过与会话连接的自托管环境运行。",{},{"id":490,"data":1057,"type":226,"tunes":1059},{"text":1058},"这产生了一个 SDK 应用可能从未明确做出的迁移决策：哪些代码应作为应用函数运行，哪些代码属于沙箱，以及哪些工作负载需要你控制的基础设施？",{},{"id":495,"data":1061,"type":327,"tunes":1076},{"content":1062,"stretched":43,"withHeadings":14},[1063,1064,1067,1068,1070,1073],[499,500],[1065,1066],"通过受控的业务逻辑调用现有的内部服务","由你的应用程序处理的函数工具",[505,506],[1069,509],"访问私有网络资源、自定义系统软件或受控的本地计算",[1071,1072],"持久化已接受的产品产物","应用程序拥有的存储，而不仅仅是沙箱文件系统",[1074,1075],"执行高影响力的业务副作用","具有授权和审计控制的应用程序函数",{},{"id":518,"data":1078,"type":42,"tunes":1080},{"text":1079,"level":219},"第 5 步 — 用显式生命周期处理替换隐式恢复",{},{"id":523,"data":1082,"type":226,"tunes":1084},{"text":1083},"托管执行框架提供会话级恢复，但你的应用程序仍然拥有其周围的每一个外部依赖。自托管环境需要配置、重新连接和关闭。函数处理器可能失败。Webhook 可能被重试。产品侧状态可能在代理空闲时发生变化。",{},{"id":528,"data":1086,"type":226,"tunes":1088},{"text":1087},"因此，迁移需要两种恢复模型：代理运行时恢复和业务操作恢复。第一种正越来越多地由 Agents API 管理。第二种仍然是你的责任。",{},{"id":533,"data":1090,"type":42,"tunes":1092},{"text":1091,"level":219},"第 6 步 — 围绕新的追踪边界重建可观测性",{},{"id":538,"data":1094,"type":226,"tunes":1096},{"text":1095},"Agents API 会话暴露事件、保存的历史记录、轮次、工具调用、子代理和令牌使用情况。OpenAI 还在平台中提供会话日志和追踪导出。",{},{"id":543,"data":1098,"type":226,"tunes":1100},{"text":1099},"不要因为平台追踪有所改进就丢弃你的应用程序可观测性。产品日志仍然需要将代理会话连接到用户身份、授权决策、领域对象、工具副作用、审批记录和最终接受的结果。有用的生产追踪是代理运行时证据与业务运行时证据之间的连接。",{},{"id":548,"data":1102,"type":554,"tunes":1103},{"url":550,"title":551,"excerpt":552,"ctaLabel":553},{},{"id":557,"data":1105,"type":42,"tunes":1107},{"text":1106,"level":219},"第 7 步 — 在更改运行时之前保留评估",{},{"id":562,"data":1109,"type":226,"tunes":1111},{"text":1110},"迁移可能看起来成功，因为新系统仍然产生看似合理的答案，同时悄悄改变了工具选择、会话连续性、交接行为、延迟或故障恢复。在切换运行时之前建立行为基线。",{},{"id":567,"data":1113,"type":226,"tunes":1115},{"text":1114},"基线应包括代表性任务、预期工具调用、禁止操作、审批点、状态连续性、恢复场景和最终输出验收标准。尽可能针对相同用例运行旧架构和新架构。",{},{"id":572,"data":1117,"type":42,"tunes":1118},{"text":574,"level":219},{},{"id":577,"data":1120,"type":606,"tunes":1136},{"steps":1121,"title":604,"orientation":605},[1122,1124,1127,1129,1130,1132,1133,1134],{"label":581,"description":1123},"捕获代表性的 SDK 追踪、预期输出、工具路径、审批点和失败用例。",{"label":1125,"description":1126},"2. 盘点状态所有权","将每个状态字段标记为代理会话状态、权威领域状态、持久产物或临时工作状态。",{"label":587,"description":1128},"将业务函数保留在应用程序接口之后；尽可能只替换面向代理的集成。",{"label":590,"description":591},{"label":593,"description":1131},"测试进程重启、Webhook 重试、函数超时、自托管环境重新连接和过期领域状态。",{"label":596,"description":597},{"label":599,"description":600},{"label":602,"description":1135},"在生产行为稳定之前保留集成适配器和回滚能力。",{},{"id":609,"data":1138,"type":42,"tunes":1140},{"text":1139,"level":219},"迁移期间应衡量什么",{},{"id":614,"data":1142,"type":327,"tunes":1160},{"content":1143,"stretched":43,"withHeadings":14},[1144,1145,1146,1147,1149,1151,1153,1155,1156,1158],[618,619],[621,622],[624,625],[627,1148],"工作能否跨轮次、重启和异步等待恢复？",[324,1150],"Webhook 丢失、处理器失败、环境断开或超时后会发生什么？",[632,1152],"每个有后果的操作能否连接到会话、用户、工具调用和领域对象？",[635,1154],"长时间运行的会话能否在不携带过期应用程序事实的情况下保留约束？",[638,639],[641,1157],"模型使用、沙箱使用、重复上下文和基础设施操作会发生什么变化？",[644,1159],"哪些以前由应用程序拥有的责任实际上消失了，哪些只是转移了？",{},{"id":648,"data":1162,"type":42,"tunes":1164},{"text":1163,"level":219},"何时还不应迁移",{},{"id":653,"data":1166,"type":226,"tunes":1168},{"text":1167},"现有的 Agents SDK 应用程序不会仅仅因为平台方向改变就变成糟糕的架构。OpenAI 继续维护、安全修复、关键错误修复和兼容性工作。如果应用程序稳定、经过良好评估并且没有受阻的路线图需求，那么立即进行运行时迁移可能并不合理。",{},{"id":658,"data":1170,"type":669,"tunes":1175},{"meta":1171,"items":1172,"style":668},{},[662,663,1173,1174,666,667],"应用程序依赖于尚未在托管执行框架上验证的自定义编排语义。","提供商可移植性是硬性要求，而当前 SDK 抽象具有实质性价值。",{},{"id":672,"data":1177,"type":42,"tunes":1179},{"text":1178,"level":219},"迁移何时具有战略重要性",{},{"id":677,"data":1181,"type":226,"tunes":1183},{"text":1182},"当产品需求与托管执行框架相匹配时，迁移会变得更具吸引力：持久的长时运行工作、平台管理的上下文压缩与恢复、更新的智能体运行时能力、沙箱化执行、更丰富的托管生命周期管理，或希望减少应用程序所运行的编排代码量。",{},{"id":682,"data":1185,"type":226,"tunes":1187},{"text":1186},"最强的信号不是“旧 SDK 功能已完备”，而是“我们的路线图现在依赖于那些天然归属于托管 Agents API 运行时的能力”。",{},{"id":687,"data":1189,"type":42,"tunes":1191},{"text":1190,"level":219},"什么会改变这一答案？",{},{"id":692,"data":1193,"type":226,"tunes":1195},{"text":1194},"如果 OpenAI 发布自动化迁移工具、引入明确的兼容层、更改 Agents API 会话语义、扩大或缩小自托管环境支持，或更改 Agents SDK 的支持政策，迁移策略将会改变。",{},{"id":697,"data":1197,"type":226,"tunes":1199},{"text":1198},"如果你的产品需求发生变化，它也会改变。简单的请求-响应助手可能根本不需要持久的托管执行框架。长时运行的编码、研究或运维智能体则可以从 Agents API 的所有权模型中获益更多。",{},{"id":702,"data":1201,"type":42,"tunes":1202},{"text":704,"level":219},{},{"id":707,"data":1204,"type":226,"tunes":1206},{"text":1205},"不存在通用的 SDK 到 API 的一对一迁移映射，因为应用程序对 Agents SDK 的使用方式各不相同。有些严重依赖会话和交接；另一些则将其用作围绕函数工具的轻量运行器。正确的迁移取决于你的应用程序当前实际承担哪些职责。",{},{"id":712,"data":1208,"type":226,"tunes":1209},{"text":714},{},{"id":717,"data":1211,"type":42,"tunes":1212},{"text":719,"level":219},{},{"id":722,"data":1214,"type":226,"tunes":1216},{"text":1215},"从 Agents SDK 迁移到 Agents API 最好理解为移动智能体运行时边界。托管执行框架接管了更多的循环、会话连续性、压缩和恢复。你的应用程序应更明确地界定仍属于自身的职责：领域真相、授权、函数副作用、工件、可审计性和产品生命周期。",{},{"id":727,"data":1218,"type":226,"tunes":1220},{"text":1219},"如果一次迁移保留了所有旧的编排机制，仅仅将 SDK 调用替换为 Agents API 调用，那么它很可能错失了架构上的机会。目标不是在新运行时之上复现旧运行时，而是决定哪些运行时职责不再属于你的应用程序。",{},{"id":732,"data":1222,"type":42,"tunes":1223},{"text":734,"level":219},{},{"id":737,"data":1225,"type":737,"tunes":1239},{"items":1226,"title":760},[1227,1230,1232,1234,1236],{"id":741,"answer":1228,"question":1229},"不是。主要变化是运行时所有权：Agents SDK 在你的应用程序中运行智能体循环，而 Agents API 运行托管的 Codex 执行框架和持久会话。状态、生命周期、事件处理和恢复应作为架构问题来审查。","从 Agents SDK 迁移到 Agents API 只是重写 API 吗？",{"id":745,"answer":1231,"question":747},"如果业务实现已经位于稳定的应用程序接口之后，通常可以复用。面向智能体的集成会发生变化，因为 Agents API 函数调用通过会话所需操作和结果来处理。",{"id":749,"answer":750,"question":1233},"我应该将业务状态移入 Agents API 会话吗？",{"id":753,"answer":1235,"question":755},"不一定，因为流式传输也可用。Webhook 对于长时运行或异步会话特别有用，在这些场景中，你的应用程序应对生命周期变化做出反应，而无需保持打开的流。",{"id":757,"answer":1237,"question":1238},"不。SDK 仍以维护模式提供支持。当新运行时提供有意义的路线图价值，并且在所需行为已针对生产形态的评估验证之后，再进行迁移。","每个现有的 Agents SDK 应用程序现在都应该迁移吗？",{},{"id":763,"data":1241,"type":42,"tunes":1242},{"text":765,"level":219},{},{"id":768,"data":1244,"type":768,"tunes":1254},{"title":770,"entries":1245},[1246,1248,1249,1251,1252,1253],{"term":773,"anchor":774,"definition":1247},"平台管理的智能体运行时与应用程序拥有的运行时之间的职责划分。",{"term":777,"anchor":778,"definition":779},{"term":781,"anchor":782,"definition":1250},"一个持久的 Agents API 实例，保存智能体的配置、对话和跨轮次保存的工作。",{"term":785,"anchor":786,"definition":787},{"term":509,"anchor":789,"definition":790},{"term":574,"anchor":792,"definition":793},{},{"id":796,"data":1256,"type":42,"tunes":1257},{"text":798,"level":219},{},{"id":801,"data":1259,"type":808,"tunes":1263},{"link":803,"meta":1260},{"image":1261,"title":806,"description":1262},{"url":417},"当前支持政策：Agents SDK 功能已完备，仍受维护，新应用程序应从 Agents API 开始。",{},{"id":811,"data":1265,"type":808,"tunes":1269},{"link":813,"meta":1266},{"image":1267,"title":816,"description":1268},{"url":417},"SDK 应用拥有的智能体循环与延续模型的文档。",{},{"id":820,"data":1271,"type":808,"tunes":1275},{"link":822,"meta":1272},{"image":1273,"title":825,"description":1274},{"url":417},"定义 Agents API 核心概念：智能体、环境、会话、事件和条目。",{},{"id":829,"data":1277,"type":808,"tunes":1280},{"link":831,"meta":1278},{"image":1279,"title":834,"description":835},{"url":417},{},{"id":838,"data":1282,"type":808,"tunes":1285},{"link":840,"meta":1283},{"image":1284,"title":843,"description":844},{"url":417},{},{"id":847,"data":1287,"type":808,"tunes":1291},{"link":849,"meta":1288},{"image":1289,"title":1290,"description":853},{"url":417},"OpenAI — 运行和延续会话",{},{"id":856,"data":1293,"type":808,"tunes":1297},{"link":858,"meta":1294},{"image":1295,"title":861,"description":1296},{"url":417},"函数工具定义以及必需函数结果的应用处理程序边界。",{},{"id":865,"data":1299,"type":808,"tunes":1302},{"link":867,"meta":1300},{"image":1301,"title":870,"description":871},{"url":417},{},{"id":874,"data":1304,"type":808,"tunes":1308},{"link":876,"meta":1305},{"image":1306,"title":879,"description":1307},{"url":417},"会话日志、事件、轮次、工具调用、子智能体、追踪和令牌使用情况检查。",{},"2.31","从 OpenAI Agents SDK 迁移到新的 Agents API 并不是简单的导入重命名。运行时边界发生了变化：代理循环、持久会话、编排、上下文压缩与恢复都向托管执行框架迁移。本指南说明哪些应当迁移、哪些应当保留在您的应用程序中，以及如何在切换前验证迁移。","\u002Fuploads\u002F2026\u002F09\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally-1790352171968-ienxr9.webp","migrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally-1790352171968-ienxr9","PUBLISHED","2026-09-25T12:01:00.000Z","2026-09-25T16:01:18.925Z","2026-09-25T16:11:21.632Z",{"en":1318,"de":1319,"sr":1320,"es":1321,"fr":1322,"it":1323,"ru":1324,"zh":1325},"\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Fde\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Fsr\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Fes\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Ffr\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Fit\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Fru\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally","\u002Fzh\u002Fblog\u002Fmigrating-from-openai-agents-sdk-to-the-agents-api-what-actually-changes-architecturally",[1327,1331,1335],{"id":1328,"name":1329,"slug":1330},70,"阶段（计划→执行→验证）","phases",{"id":1332,"name":1333,"slug":1334},73,"验证与对比","verification-and-diffing",{"id":1336,"name":1337,"slug":1338},71,"风险登记册","risk-register",{"id":1340,"login":1341,"email":1342,"displayName":1343},"20","rooth8233","aleksandar@stajic.de","Aleksandar Stajić",[1345,2222],{"lang":1346,"title":1347,"content":1348,"contentJson":1349,"excerpt":2221},"en","Migrating from OpenAI Agents SDK to the Agents API: What Actually Changes Architecturally?","{\"time\":1790352173087,\"blocks\":[{\"id\":\"24Foq4L2Wb\",\"type\":\"tableOfContents\",\"data\":{\"title\":\"Contents\",\"minLevel\":2,\"maxLevel\":3},\"tunes\":{}},{\"id\":\"intro\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migrating from the OpenAI Agents SDK to the Agents API is not an import rename. The core architectural boundary changes: the SDK runs the agent loop inside your application, while the Agents API runs a managed Codex harness and durable session on OpenAI's side. The migration question is therefore not “Which classes map to which endpoints?” but “Which runtime responsibilities move across the boundary, which stay in our application, and which need to be redesigned?”\"},\"tunes\":{}},{\"id\":\"direct\",\"type\":\"callout\",\"data\":{\"variant\":\"info\",\"title\":\"Direct answer\",\"body\":\"\u003Cstrong>A real Agents SDK → Agents API migration changes runtime ownership.\u003C\u002Fstrong> Your reusable agent configuration can still contain model, instructions and tools, but the loop, durable session, orchestration, context compaction and recovery move toward the managed Agents API runtime. Your application should keep domain state, authorization, business rules, function implementations and audit logic outside the agent session. Treat the migration as a boundary redesign, not a mechanical code conversion.\"},\"tunes\":{}},{\"id\":\"current\",\"type\":\"callout\",\"data\":{\"variant\":\"warning\",\"title\":\"Current as of 25 September 2026\",\"body\":\"OpenAI currently marks the Agents SDK as \u003Cstrong>feature complete\u003C\u002Fstrong> and recommends the Agents API for new agent applications. The Agents API is in public beta. Existing SDK applications remain supported, and immediate migration is not automatically required.\"},\"tunes\":{}},{\"id\":\"model-note\",\"type\":\"callout\",\"data\":{\"variant\":\"note\",\"title\":\"About the migration model\",\"body\":\"The Runtime Boundary Migration Map and Migration Proof Test in this article are practical architecture tools, not official OpenAI migration frameworks. They are derived from the current runtime differences documented by OpenAI.\"},\"tunes\":{}},{\"id\":\"h-boundary\",\"type\":\"header\",\"data\":{\"text\":\"The migration is from an application-owned loop to a managed harness\",\"level\":2},\"tunes\":{}},{\"id\":\"p-boundary-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"In the Agents SDK, one run is an application-level turn. The SDK runner calls the model, inspects the output, executes tools, follows handoffs and continues until it reaches a stopping point. Your process hosts that loop and therefore owns its lifecycle.\"},\"tunes\":{}},{\"id\":\"p-boundary-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"In the Agents API, OpenAI runs the harness. A session is a durable instance of an agent configuration that accepts tasks, produces events, can pause for required actions, and can continue over time. OpenAI manages sessions, orchestration, context compaction and recovery; your application sends work, handles function tools, receives events and optionally manages a self-hosted execution environment.\"},\"tunes\":{}},{\"id\":\"p-boundary-3\",\"type\":\"paragraph\",\"data\":{\"text\":\"That ownership shift is the migration. Everything else — API syntax, tool schemas, event handling, session IDs — follows from it.\"},\"tunes\":{}},{\"id\":\"h-map\",\"type\":\"header\",\"data\":{\"text\":\"The Runtime Boundary Migration Map\",\"level\":2},\"tunes\":{}},{\"id\":\"migration-map\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"Concern\",\"Agents SDK\",\"Agents API migration target\"],[\"Agent loop\",\"Runs in your application through the SDK runner\",\"Runs in the managed Codex harness\"],[\"Reusable agent definition\",\"Agent object in application code\",\"Saved or inline agent configuration with model, instructions and tools\"],[\"Conversation \u002F work continuity\",\"SDK session strategy, history, result continuation or application storage\",\"Durable Agents API session\"],[\"Tool execution\",\"SDK coordinates tool calls in your runtime\",\"Harness requests function calls; your application returns results\"],[\"Context management\",\"Your runtime \u002F SDK session strategy\",\"Managed session context, compaction and recovery, plus your own application data boundaries\"],[\"Handoffs \u002F specialists\",\"SDK orchestration primitives\",\"Harness \u002F subagent behaviour in Agents API; do not assume one-to-one semantics\"],[\"Execution environment\",\"Your application runtime or tool-specific environment\",\"Optional OpenAI-hosted or self-hosted environment attached to the session\"],[\"Streaming\",\"SDK streaming from the run\",\"Agents API session event stream\"],[\"Async lifecycle\",\"Usually application-managed around the SDK run\",\"Native session states, asynchronous turns and webhooks\"],[\"Tracing \u002F observability\",\"Agents SDK tracing and application logs\",\"Agents session logs, events, turns, tool calls, subagents and exportable traces\"],[\"Recovery\",\"Application responsibility\",\"Managed harness\u002Fsession recovery plus application-owned recovery for external systems and self-hosted environments\"]]},\"tunes\":{}},{\"id\":\"h-conceptual\",\"type\":\"header\",\"data\":{\"text\":\"What can migrate conceptually without changing ownership\",\"level\":2},\"tunes\":{}},{\"id\":\"p-conceptual-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Several application concepts survive the migration cleanly even though their representation changes. Models, instructions, JSON-schema function definitions, MCP access, tool descriptions and structured output requirements are still agent configuration concerns.\"},\"tunes\":{}},{\"id\":\"p-conceptual-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"OpenAI's Agents API configuration model explicitly defines an agent through model, instructions, tools, reasoning and output behaviour. Function tools remain application code: the harness requests a function call, and your handler returns the result. OpenAI also notes that function implementations used with the Responses API can be reused with the Agents API session flow.\"},\"tunes\":{}},{\"id\":\"good-candidate\",\"type\":\"callout\",\"data\":{\"variant\":\"success\",\"title\":\"Good migration candidate\",\"body\":\"A pure business function such as \u003Ccode>get_customer(customer_id)\u003C\u002Fcode> should not need to know whether the caller is the Agents SDK or the Agents API. Keep its domain logic behind a stable application interface and migrate only the agent-facing adapter.\"},\"tunes\":{}},{\"id\":\"h-no-one\",\"type\":\"header\",\"data\":{\"text\":\"What should not be migrated one-to-one\",\"level\":2},\"tunes\":{}},{\"id\":\"p-no-one-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The dangerous migration pattern is to recreate every SDK runtime abstraction inside the Agents API. That can leave you paying for a managed harness while still operating a shadow harness in your application.\"},\"tunes\":{}},{\"id\":\"no-one-table\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"SDK-era assumption\",\"Why a direct copy is risky\",\"Migration question\"],[\"Application loop owns every continuation\",\"The Agents API already owns the harness loop\",\"Which continuation logic is product logic, and which should move to the managed session?\"],[\"Local session object is the primary continuity mechanism\",\"Agents API sessions are durable resources with their own lifecycle\",\"Which state belongs in the session versus the product database?\"],[\"Every interruption is handled synchronously\",\"Agents API turns are asynchronous and can surface action_required states\",\"Which actions need webhooks, workers, idempotency and resumable handlers?\"],[\"All tool execution happens where the SDK process runs\",\"Function handlers and execution environments can be separate\",\"Where should each tool actually execute?\"],[\"SDK trace is the operational timeline\",\"Agents API exposes session events, turns and managed traces\",\"What application-level audit data still needs its own record?\"],[\"Handoff object maps directly to a hosted subagent model\",\"Runtime semantics can differ\",\"What user-visible ownership and specialist behaviour must be preserved, not merely the old class structure?\"]]},\"tunes\":{}},{\"id\":\"h-domain\",\"type\":\"header\",\"data\":{\"text\":\"Step 1 — Separate domain state from agent session state\",\"level\":2},\"tunes\":{}},{\"id\":\"p-domain-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Before touching API calls, classify the state your SDK application currently carries. Some state exists only to keep the agent conversation moving. Other state is business truth: user permissions, project status, order data, workflow approval, customer records, document versions, policy state or application configuration.\"},\"tunes\":{}},{\"id\":\"p-domain-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The second category should not become dependent on an Agents API session. A durable session is useful continuity for the agent; it is not a replacement for your product's source of truth. If the session disappears, expires, is rebuilt, or changes implementation, your application must still know what is true.\"},\"tunes\":{}},{\"id\":\"state-test\",\"type\":\"comparison\",\"data\":{\"title\":\"State placement test\",\"layout\":\"table\",\"columns\":[{\"id\":\"type\",\"label\":\"State type\"},{\"id\":\"place\",\"label\":\"Preferred owner\"},{\"id\":\"reason\",\"label\":\"Reason\"}],\"rows\":[{\"id\":\"conversation\",\"label\":\"Conversation continuity\",\"values\":[\"\",\"\",\"\"]},{\"id\":\"domain\",\"label\":\"Business truth\",\"values\":[\"\",\"\",\"\"]},{\"id\":\"artifact\",\"label\":\"Durable artifact\",\"values\":[\"\",\"\",\"\"]},{\"id\":\"ephemeral\",\"label\":\"Working scratch state\",\"values\":[\"\",\"\",\"\"]}]},\"tunes\":{}},{\"id\":\"h-events\",\"type\":\"header\",\"data\":{\"text\":\"Step 2 — Convert the runner mindset into a session-and-events mindset\",\"level\":2},\"tunes\":{}},{\"id\":\"p-events-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"SDK applications often think in terms of calling run and receiving a result. The Agents API thinks in terms of a durable session whose turns can run asynchronously. A message to an idle session starts work; a message during an active turn can steer it. Progress arrives through streaming or webhooks.\"},\"tunes\":{}},{\"id\":\"p-events-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"This affects application architecture. Long-running production work should not depend on one HTTP request remaining alive. Your product needs stable session identifiers, lifecycle persistence, webhook verification, idempotent handlers and a way to reconcile current session state after process restarts.\"},\"tunes\":{}},{\"id\":\"h-functions\",\"type\":\"header\",\"data\":{\"text\":\"Step 3 — Redesign function tools around required actions\",\"level\":2},\"tunes\":{}},{\"id\":\"p-functions-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Function tools remain an important application boundary. You define the function and its JSON schema in the agent configuration. When the harness needs the function, the session can enter an action-required state. Your application retrieves the required action, executes the business logic and returns the result.\"},\"tunes\":{}},{\"id\":\"p-functions-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"That means the function implementation should be safe to resume. A webhook may be delivered while another worker is processing. A network failure can occur after the external side effect but before the result is returned. Migration is therefore a good moment to add call IDs, idempotency keys, explicit authorization, timeout policies and audit records to consequential tools.\"},\"tunes\":{}},{\"id\":\"tool-trap\",\"type\":\"callout\",\"data\":{\"variant\":\"warning\",\"title\":\"Tool migration trap\",\"body\":\"Do not treat a function call from the managed harness as authorization to perform the action. The harness decides \u003Cem>what it wants to call\u003C\u002Fem>; your application still decides whether the current user, session and business state allow that action.\"},\"tunes\":{}},{\"id\":\"h-environment\",\"type\":\"header\",\"data\":{\"text\":\"Step 4 — Decide where execution should happen\",\"level\":2},\"tunes\":{}},{\"id\":\"p-env-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The Agents API separates the managed harness from the execution environment. An agent can operate without a dedicated environment, in an OpenAI-hosted sandbox, or through a self-hosted environment connected to the session.\"},\"tunes\":{}},{\"id\":\"p-env-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"This creates a migration decision that SDK applications may never have made explicitly: which code should run as an application function, which code belongs in a sandbox, and which workloads require infrastructure you control?\"},\"tunes\":{}},{\"id\":\"environment-table\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"Need\",\"Likely boundary\"],[\"Call an existing internal service through controlled business logic\",\"Function tool handled by your application\"],[\"Run isolated code or work with temporary files without private infrastructure\",\"OpenAI-hosted environment\"],[\"Access private network resources, custom system software or controlled local compute\",\"Self-hosted environment\"],[\"Persist accepted product artifacts\",\"Application-owned storage, not only sandbox filesystem\"],[\"Execute a high-impact business side effect\",\"Application function with authorization and audit controls\"]]},\"tunes\":{}},{\"id\":\"h-recovery\",\"type\":\"header\",\"data\":{\"text\":\"Step 5 — Replace implicit recovery with explicit lifecycle handling\",\"level\":2},\"tunes\":{}},{\"id\":\"p-recovery-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The managed harness provides session-level recovery, but your application still owns every external dependency around it. Self-hosted environments need provisioning, reconnection and shutdown. Function handlers can fail. Webhooks can be retried. Product-side state can change while an agent is idle.\"},\"tunes\":{}},{\"id\":\"p-recovery-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migration therefore needs two recovery models: agent-runtime recovery and business-operation recovery. The first is increasingly managed by the Agents API. The second remains your responsibility.\"},\"tunes\":{}},{\"id\":\"h-observability\",\"type\":\"header\",\"data\":{\"text\":\"Step 6 — Rebuild observability around the new trace boundary\",\"level\":2},\"tunes\":{}},{\"id\":\"p-obs-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Agents API sessions expose events, saved history, turns, tool calls, subagents and token usage. OpenAI also provides session logs in the platform and trace export.\"},\"tunes\":{}},{\"id\":\"p-obs-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"Do not discard your application observability because platform traces improved. Product logs still need to connect the agent session to user identity, authorization decision, domain object, tool side effect, approval record and final accepted result. The useful production trace is the join between agent-runtime evidence and business-runtime evidence.\"},\"tunes\":{}},{\"id\":\"ref-reliability\",\"type\":\"referralArticle\",\"data\":{\"url\":\"https:\u002F\u002Fstajic.de\u002Fblog\u002Fai-agent-reliability-why-the-final-answer-is-not-enough\",\"title\":\"AI Agent Reliability: Why the Final Answer Is Not Enough\",\"excerpt\":\"Agent reliability depends on the execution path, tools and intermediate decisions — not only the final output.\",\"ctaLabel\":\"Read the reliability article\"},\"tunes\":{}},{\"id\":\"h-evals\",\"type\":\"header\",\"data\":{\"text\":\"Step 7 — Preserve evals before changing the runtime\",\"level\":2},\"tunes\":{}},{\"id\":\"p-evals-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"A migration can appear successful because the new system still produces plausible answers while silently changing tool choice, session continuity, handoff behaviour, latency or failure recovery. Build the behavioural baseline before switching runtimes.\"},\"tunes\":{}},{\"id\":\"p-evals-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The baseline should include representative tasks, expected tool calls, forbidden actions, approval points, state continuity, recovery scenarios and final-output acceptance criteria. Run the old and new architectures against the same cases wherever possible.\"},\"tunes\":{}},{\"id\":\"h-proof\",\"type\":\"header\",\"data\":{\"text\":\"The Migration Proof Test\",\"level\":2},\"tunes\":{}},{\"id\":\"proof-flow\",\"type\":\"processFlow\",\"data\":{\"title\":\"Prove the new runtime before cutting over\",\"orientation\":\"auto\",\"steps\":[{\"label\":\"1. Freeze the behavioural baseline\",\"description\":\"Capture representative SDK traces, expected outputs, tool paths, approval points and failure cases.\"},{\"label\":\"2. Inventory state ownership\",\"description\":\"Mark each state field as agent-session state, authoritative domain state, durable artifact or ephemeral working state.\"},{\"label\":\"3. Reuse stable tool implementations\",\"description\":\"Keep business functions behind application interfaces; replace only the agent-facing integration where possible.\"},{\"label\":\"4. Build one Agents API vertical slice\",\"description\":\"Migrate one production-shaped workflow including session creation, tools, events, environment and persistence.\"},{\"label\":\"5. Inject interruptions\",\"description\":\"Test process restart, webhook retry, function timeout, self-hosted environment reconnect and stale domain state.\"},{\"label\":\"6. Compare traces, not only answers\",\"description\":\"Verify tool choice, authorization, evidence path, state transitions and side effects against the baseline.\"},{\"label\":\"7. Run shadow traffic\",\"description\":\"Where feasible, replay or mirror representative tasks before making the new runtime authoritative.\"},{\"label\":\"8. Cut over behind a reversible boundary\",\"description\":\"Keep integration adapters and rollback capability until production behaviour is stable.\"}]},\"tunes\":{}},{\"id\":\"h-metrics\",\"type\":\"header\",\"data\":{\"text\":\"What to measure during migration\",\"level\":2},\"tunes\":{}},{\"id\":\"metrics-table\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"Dimension\",\"Migration check\"],[\"Task success\",\"Does the new runtime meet the same or better acceptance criteria?\"],[\"Tool correctness\",\"Does it call the right tool with valid arguments and authorization?\"],[\"State continuity\",\"Can work resume across turns, restarts and asynchronous waits?\"],[\"Recovery\",\"What happens after webhook loss, handler failure, environment disconnect or timeout?\"],[\"Traceability\",\"Can every consequential action be joined to session, user, tool call and domain object?\"],[\"Context behaviour\",\"Do long-running sessions preserve constraints without carrying stale application truth?\"],[\"Latency\",\"How do session startup, environment provisioning and multi-turn work affect user-visible time?\"],[\"Cost\",\"What changes in model usage, sandbox usage, repeated context and infrastructure operations?\"],[\"Operational load\",\"Which previously application-owned responsibilities actually disappeared, and which merely moved?\"]]},\"tunes\":{}},{\"id\":\"h-not-yet\",\"type\":\"header\",\"data\":{\"text\":\"When not to migrate yet\",\"level\":2},\"tunes\":{}},{\"id\":\"p-not-yet-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"An existing Agents SDK application does not become bad architecture simply because the platform direction changed. OpenAI continues maintenance, security fixes, critical bug fixes and compatibility work. If the application is stable, well evaluated and has no blocked roadmap requirement, an immediate runtime migration may not be justified.\"},\"tunes\":{}},{\"id\":\"not-yet-list\",\"type\":\"list\",\"data\":{\"style\":\"unordered\",\"meta\":{},\"items\":[\"A required SDK capability is not yet available in the Agents API.\",\"The migration would disrupt a critical production period without delivering near-term value.\",\"The application depends on custom orchestration semantics that have not been validated on the managed harness.\",\"Provider portability is a hard requirement and the current SDK abstraction is materially valuable.\",\"Your team has not yet separated business state from agent runtime state, making cutover unsafe.\",\"The new Agents API behaviour has not been tested against representative production workloads.\"]},\"tunes\":{}},{\"id\":\"h-when\",\"type\":\"header\",\"data\":{\"text\":\"When the migration becomes strategically important\",\"level\":2},\"tunes\":{}},{\"id\":\"p-when-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migration becomes more compelling when product requirements align with the managed harness: durable long-running work, platform-managed context compaction and recovery, newer agent-runtime capabilities, sandboxed execution, richer hosted lifecycle management, or a desire to reduce the amount of orchestration code your application operates.\"},\"tunes\":{}},{\"id\":\"p-when-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The strongest signal is not “the old SDK is feature complete.” It is “our roadmap now depends on capabilities whose natural home is the managed Agents API runtime.”\"},\"tunes\":{}},{\"id\":\"h-change\",\"type\":\"header\",\"data\":{\"text\":\"What would change this answer?\",\"level\":2},\"tunes\":{}},{\"id\":\"p-change-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The migration strategy would change if OpenAI publishes automated migration tooling, introduces explicit compatibility layers, changes Agents API session semantics, expands or narrows self-hosted environment support, or changes the support policy for the Agents SDK.\"},\"tunes\":{}},{\"id\":\"p-change-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"It would also change if your product requirements change. A simple request-response assistant may not need a durable managed harness at all. A long-running coding, research or operations agent can benefit much more from the Agents API ownership model.\"},\"tunes\":{}},{\"id\":\"h-limitations\",\"type\":\"header\",\"data\":{\"text\":\"Limitations\",\"level\":2},\"tunes\":{}},{\"id\":\"p-limit-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"There is no universal one-to-one SDK-to-API migration map because applications use the Agents SDK differently. Some rely heavily on sessions and handoffs; others use it as a thin runner around function tools. The correct migration depends on which responsibilities your application actually owns today.\"},\"tunes\":{}},{\"id\":\"p-limit-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The Agents API is also in public beta, so implementation details can evolve. Treat the ownership principles in this article as more durable than any individual endpoint shape.\"},\"tunes\":{}},{\"id\":\"h-conclusion\",\"type\":\"header\",\"data\":{\"text\":\"Conclusion\",\"level\":2},\"tunes\":{}},{\"id\":\"p-conclusion-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migrating from the Agents SDK to the Agents API is best understood as moving the agent-runtime boundary. The managed harness takes over more of the loop, session continuity, compaction and recovery. Your application should become more explicit about the responsibilities that remain yours: domain truth, authorization, function side effects, artifacts, auditability and product lifecycle.\"},\"tunes\":{}},{\"id\":\"p-conclusion-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"If a migration leaves all of the old orchestration machinery in place and merely replaces SDK calls with Agents API calls, it has probably missed the architectural opportunity. The goal is not to reproduce the old runtime on top of the new one. The goal is to decide which runtime responsibilities no longer belong in your application.\"},\"tunes\":{}},{\"id\":\"h-faq\",\"type\":\"header\",\"data\":{\"text\":\"FAQ\",\"level\":2},\"tunes\":{}},{\"id\":\"faq\",\"type\":\"faq\",\"data\":{\"title\":\"Migrating from Agents SDK to Agents API\",\"items\":[{\"id\":\"faq1\",\"question\":\"Is migrating from the Agents SDK to the Agents API just an API rewrite?\",\"answer\":\"No. The main change is runtime ownership: the Agents SDK runs the agent loop in your application, while the Agents API runs a managed Codex harness and durable session. State, lifecycle, event handling and recovery should be reviewed as architecture concerns.\"},{\"id\":\"faq2\",\"question\":\"Do my function tools need to be rewritten?\",\"answer\":\"The business implementation often can be reused if it is already behind a stable application interface. The agent-facing integration changes because Agents API function calls are handled through session required actions and results.\"},{\"id\":\"faq3\",\"question\":\"Should I move business state into the Agents API session?\",\"answer\":\"Generally no. Keep authoritative business and product state in your own databases or services. Use the agent session for agent continuity and working context, not as the sole source of truth for your product.\"},{\"id\":\"faq4\",\"question\":\"Do I need webhooks for the Agents API?\",\"answer\":\"Not always, because streaming is also available. Webhooks are especially useful for long-running or asynchronous sessions where your application should react to lifecycle changes without holding an open stream.\"},{\"id\":\"faq5\",\"question\":\"Should every existing Agents SDK application migrate now?\",\"answer\":\"No. The SDK remains supported in maintenance mode. Migrate when the new runtime provides meaningful roadmap value and after required behaviour has been validated against production-shaped evals.\"}]},\"tunes\":{}},{\"id\":\"h-glossary\",\"type\":\"header\",\"data\":{\"text\":\"Glossary\",\"level\":2},\"tunes\":{}},{\"id\":\"glossary\",\"type\":\"glossary\",\"data\":{\"title\":\"Key migration terms\",\"entries\":[{\"term\":\"Runtime boundary\",\"definition\":\"The division of responsibility between the platform-managed agent runtime and the application-owned runtime.\",\"anchor\":\"runtime-boundary\"},{\"term\":\"Harness\",\"definition\":\"The agent runtime that coordinates model calls, tools, context, orchestration and continued execution.\",\"anchor\":\"harness\"},{\"term\":\"Session\",\"definition\":\"A durable Agents API instance that holds an agent's configuration, conversation and saved work across turns.\",\"anchor\":\"session\"},{\"term\":\"Required action\",\"definition\":\"A session state in which the Agents API needs external input such as a function result or environment connection before work can continue.\",\"anchor\":\"required-action\"},{\"term\":\"Self-hosted environment\",\"definition\":\"An execution environment operated by your infrastructure and connected to the managed Agents API harness.\",\"anchor\":\"self-hosted-environment\"},{\"term\":\"Migration proof test\",\"definition\":\"A staged validation method that compares the new runtime against behavioural baselines, failure injections, traces and reversible cutover criteria.\",\"anchor\":\"migration-proof-test\"}]},\"tunes\":{}},{\"id\":\"h-sources\",\"type\":\"header\",\"data\":{\"text\":\"Primary sources and further reading\",\"level\":2},\"tunes\":{}},{\"id\":\"src-sdk\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Fsdk\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents SDK\",\"description\":\"Current support policy: the Agents SDK is feature complete, remains maintained, and new applications should start with the Agents API.\"}},\"tunes\":{}},{\"id\":\"src-running-sdk\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Frunning-agents\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Running agents with the Agents SDK\",\"description\":\"Documentation of the SDK application-owned agent loop and continuation model.\"}},\"tunes\":{}},{\"id\":\"src-api-overview\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Foverview\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API overview\",\"description\":\"Defines the Agents API core concepts: agent, environment, session, events and items.\"}},\"tunes\":{}},{\"id\":\"src-api-architecture\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Farchitecture\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API architecture\",\"description\":\"Explains the hosted harness, application server, OpenAI-hosted and self-hosted execution environment boundaries.\"}},\"tunes\":{}},{\"id\":\"src-api-config\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fconfiguration\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Configuring Agents\",\"description\":\"Defines reusable agent configuration and session-level customization.\"}},\"tunes\":{}},{\"id\":\"src-api-sessions\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Run and continue sessions\",\"description\":\"Documents durable sessions, asynchronous turns, streaming and steering.\"}},\"tunes\":{}},{\"id\":\"src-api-functions\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Ftools\u002Ffunctions\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API Functions\",\"description\":\"Function-tool definition and the application handler boundary for required function results.\"}},\"tunes\":{}},{\"id\":\"src-api-webhooks\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\u002Fwebhooks\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Session webhooks\",\"description\":\"Lifecycle events for asynchronous sessions, required actions and self-hosted environment connections.\"}},\"tunes\":{}},{\"id\":\"src-api-observability\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fobservability\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API observability and usage\",\"description\":\"Session logs, events, turns, tool calls, subagents, traces and token-usage inspection.\"}},\"tunes\":{}},{\"id\":\"intro\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migrating from the OpenAI Agents SDK to the Agents API is not an import rename. The core architectural boundary changes: the SDK runs the agent loop inside your application, while the Agents API runs a managed Codex harness and durable session on OpenAI's side. The migration question is therefore not “Which classes map to which endpoints?” but “Which runtime responsibilities move across the boundary, which stay in our application, and which need to be redesigned?”\"},\"tunes\":{}},{\"id\":\"direct\",\"type\":\"callout\",\"data\":{\"variant\":\"info\",\"title\":\"Direct answer\",\"body\":\"\u003Cstrong>A real Agents SDK → Agents API migration changes runtime ownership.\u003C\u002Fstrong> Your reusable agent configuration can still contain model, instructions and tools, but the loop, durable session, orchestration, context compaction and recovery move toward the managed Agents API runtime. Your application should keep domain state, authorization, business rules, function implementations and audit logic outside the agent session. Treat the migration as a boundary redesign, not a mechanical code conversion.\"},\"tunes\":{}},{\"id\":\"current\",\"type\":\"callout\",\"data\":{\"variant\":\"warning\",\"title\":\"Current as of 25 September 2026\",\"body\":\"OpenAI currently marks the Agents SDK as \u003Cstrong>feature complete\u003C\u002Fstrong> and recommends the Agents API for new agent applications. The Agents API is in public beta. Existing SDK applications remain supported, and immediate migration is not automatically required.\"},\"tunes\":{}},{\"id\":\"model-note\",\"type\":\"callout\",\"data\":{\"variant\":\"note\",\"title\":\"About the migration model\",\"body\":\"The Runtime Boundary Migration Map and Migration Proof Test in this article are practical architecture tools, not official OpenAI migration frameworks. They are derived from the current runtime differences documented by OpenAI.\"},\"tunes\":{}},{\"id\":\"toc\",\"type\":\"tableOfContents\",\"data\":{\"title\":\"Contents\",\"minLevel\":2,\"maxLevel\":3},\"tunes\":{}},{\"id\":\"h-boundary\",\"type\":\"header\",\"data\":{\"text\":\"The migration is from an application-owned loop to a managed harness\",\"level\":2},\"tunes\":{}},{\"id\":\"p-boundary-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"In the Agents SDK, one run is an application-level turn. The SDK runner calls the model, inspects the output, executes tools, follows handoffs and continues until it reaches a stopping point. Your process hosts that loop and therefore owns its lifecycle.\"},\"tunes\":{}},{\"id\":\"p-boundary-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"In the Agents API, OpenAI runs the harness. A session is a durable instance of an agent configuration that accepts tasks, produces events, can pause for required actions, and can continue over time. OpenAI manages sessions, orchestration, context compaction and recovery; your application sends work, handles function tools, receives events and optionally manages a self-hosted execution environment.\"},\"tunes\":{}},{\"id\":\"p-boundary-3\",\"type\":\"paragraph\",\"data\":{\"text\":\"That ownership shift is the migration. Everything else — API syntax, tool schemas, event handling, session IDs — follows from it.\"},\"tunes\":{}},{\"id\":\"h-map\",\"type\":\"header\",\"data\":{\"text\":\"The Runtime Boundary Migration Map\",\"level\":2},\"tunes\":{}},{\"id\":\"migration-map\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"Concern\",\"Agents SDK\",\"Agents API migration target\"],[\"Agent loop\",\"Runs in your application through the SDK runner\",\"Runs in the managed Codex harness\"],[\"Reusable agent definition\",\"Agent object in application code\",\"Saved or inline agent configuration with model, instructions and tools\"],[\"Conversation \u002F work continuity\",\"SDK session strategy, history, result continuation or application storage\",\"Durable Agents API session\"],[\"Tool execution\",\"SDK coordinates tool calls in your runtime\",\"Harness requests function calls; your application returns results\"],[\"Context management\",\"Your runtime \u002F SDK session strategy\",\"Managed session context, compaction and recovery, plus your own application data boundaries\"],[\"Handoffs \u002F specialists\",\"SDK orchestration primitives\",\"Harness \u002F subagent behaviour in Agents API; do not assume one-to-one semantics\"],[\"Execution environment\",\"Your application runtime or tool-specific environment\",\"Optional OpenAI-hosted or self-hosted environment attached to the session\"],[\"Streaming\",\"SDK streaming from the run\",\"Agents API session event stream\"],[\"Async lifecycle\",\"Usually application-managed around the SDK run\",\"Native session states, asynchronous turns and webhooks\"],[\"Tracing \u002F observability\",\"Agents SDK tracing and application logs\",\"Agents session logs, events, turns, tool calls, subagents and exportable traces\"],[\"Recovery\",\"Application responsibility\",\"Managed harness\u002Fsession recovery plus application-owned recovery for external systems and self-hosted environments\"]]},\"tunes\":{}},{\"id\":\"h-conceptual\",\"type\":\"header\",\"data\":{\"text\":\"What can migrate conceptually without changing ownership\",\"level\":2},\"tunes\":{}},{\"id\":\"p-conceptual-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Several application concepts survive the migration cleanly even though their representation changes. Models, instructions, JSON-schema function definitions, MCP access, tool descriptions and structured output requirements are still agent configuration concerns.\"},\"tunes\":{}},{\"id\":\"p-conceptual-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"OpenAI's Agents API configuration model explicitly defines an agent through model, instructions, tools, reasoning and output behaviour. Function tools remain application code: the harness requests a function call, and your handler returns the result. OpenAI also notes that function implementations used with the Responses API can be reused with the Agents API session flow.\"},\"tunes\":{}},{\"id\":\"good-candidate\",\"type\":\"callout\",\"data\":{\"variant\":\"success\",\"title\":\"Good migration candidate\",\"body\":\"A pure business function such as \u003Ccode>get_customer(customer_id)\u003C\u002Fcode> should not need to know whether the caller is the Agents SDK or the Agents API. Keep its domain logic behind a stable application interface and migrate only the agent-facing adapter.\"},\"tunes\":{}},{\"id\":\"h-no-one\",\"type\":\"header\",\"data\":{\"text\":\"What should not be migrated one-to-one\",\"level\":2},\"tunes\":{}},{\"id\":\"p-no-one-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The dangerous migration pattern is to recreate every SDK runtime abstraction inside the Agents API. That can leave you paying for a managed harness while still operating a shadow harness in your application.\"},\"tunes\":{}},{\"id\":\"no-one-table\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"SDK-era assumption\",\"Why a direct copy is risky\",\"Migration question\"],[\"Application loop owns every continuation\",\"The Agents API already owns the harness loop\",\"Which continuation logic is product logic, and which should move to the managed session?\"],[\"Local session object is the primary continuity mechanism\",\"Agents API sessions are durable resources with their own lifecycle\",\"Which state belongs in the session versus the product database?\"],[\"Every interruption is handled synchronously\",\"Agents API turns are asynchronous and can surface action_required states\",\"Which actions need webhooks, workers, idempotency and resumable handlers?\"],[\"All tool execution happens where the SDK process runs\",\"Function handlers and execution environments can be separate\",\"Where should each tool actually execute?\"],[\"SDK trace is the operational timeline\",\"Agents API exposes session events, turns and managed traces\",\"What application-level audit data still needs its own record?\"],[\"Handoff object maps directly to a hosted subagent model\",\"Runtime semantics can differ\",\"What user-visible ownership and specialist behaviour must be preserved, not merely the old class structure?\"]]},\"tunes\":{}},{\"id\":\"h-domain\",\"type\":\"header\",\"data\":{\"text\":\"Step 1 — Separate domain state from agent session state\",\"level\":2},\"tunes\":{}},{\"id\":\"p-domain-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Before touching API calls, classify the state your SDK application currently carries. Some state exists only to keep the agent conversation moving. Other state is business truth: user permissions, project status, order data, workflow approval, customer records, document versions, policy state or application configuration.\"},\"tunes\":{}},{\"id\":\"p-domain-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The second category should not become dependent on an Agents API session. A durable session is useful continuity for the agent; it is not a replacement for your product's source of truth. If the session disappears, expires, is rebuilt, or changes implementation, your application must still know what is true.\"},\"tunes\":{}},{\"id\":\"state-test\",\"type\":\"comparison\",\"data\":{\"title\":\"State placement test\",\"layout\":\"table\",\"columns\":[{\"id\":\"type\",\"label\":\"State type\"},{\"id\":\"place\",\"label\":\"Preferred owner\"},{\"id\":\"reason\",\"label\":\"Reason\"}],\"rows\":[{\"id\":\"conversation\",\"label\":\"Conversation continuity\",\"values\":[\"\",\"\",\"\"]},{\"id\":\"domain\",\"label\":\"Business truth\",\"values\":[\"\",\"\",\"\"]},{\"id\":\"artifact\",\"label\":\"Durable artifact\",\"values\":[\"\",\"\",\"\"]},{\"id\":\"ephemeral\",\"label\":\"Working scratch state\",\"values\":[\"\",\"\",\"\"]}]},\"tunes\":{}},{\"id\":\"h-events\",\"type\":\"header\",\"data\":{\"text\":\"Step 2 — Convert the runner mindset into a session-and-events mindset\",\"level\":2},\"tunes\":{}},{\"id\":\"p-events-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"SDK applications often think in terms of calling run and receiving a result. The Agents API thinks in terms of a durable session whose turns can run asynchronously. A message to an idle session starts work; a message during an active turn can steer it. Progress arrives through streaming or webhooks.\"},\"tunes\":{}},{\"id\":\"p-events-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"This affects application architecture. Long-running production work should not depend on one HTTP request remaining alive. Your product needs stable session identifiers, lifecycle persistence, webhook verification, idempotent handlers and a way to reconcile current session state after process restarts.\"},\"tunes\":{}},{\"id\":\"h-functions\",\"type\":\"header\",\"data\":{\"text\":\"Step 3 — Redesign function tools around required actions\",\"level\":2},\"tunes\":{}},{\"id\":\"p-functions-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Function tools remain an important application boundary. You define the function and its JSON schema in the agent configuration. When the harness needs the function, the session can enter an action-required state. Your application retrieves the required action, executes the business logic and returns the result.\"},\"tunes\":{}},{\"id\":\"p-functions-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"That means the function implementation should be safe to resume. A webhook may be delivered while another worker is processing. A network failure can occur after the external side effect but before the result is returned. Migration is therefore a good moment to add call IDs, idempotency keys, explicit authorization, timeout policies and audit records to consequential tools.\"},\"tunes\":{}},{\"id\":\"tool-trap\",\"type\":\"callout\",\"data\":{\"variant\":\"warning\",\"title\":\"Tool migration trap\",\"body\":\"Do not treat a function call from the managed harness as authorization to perform the action. The harness decides \u003Cem>what it wants to call\u003C\u002Fem>; your application still decides whether the current user, session and business state allow that action.\"},\"tunes\":{}},{\"id\":\"h-environment\",\"type\":\"header\",\"data\":{\"text\":\"Step 4 — Decide where execution should happen\",\"level\":2},\"tunes\":{}},{\"id\":\"p-env-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The Agents API separates the managed harness from the execution environment. An agent can operate without a dedicated environment, in an OpenAI-hosted sandbox, or through a self-hosted environment connected to the session.\"},\"tunes\":{}},{\"id\":\"p-env-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"This creates a migration decision that SDK applications may never have made explicitly: which code should run as an application function, which code belongs in a sandbox, and which workloads require infrastructure you control?\"},\"tunes\":{}},{\"id\":\"environment-table\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"Need\",\"Likely boundary\"],[\"Call an existing internal service through controlled business logic\",\"Function tool handled by your application\"],[\"Run isolated code or work with temporary files without private infrastructure\",\"OpenAI-hosted environment\"],[\"Access private network resources, custom system software or controlled local compute\",\"Self-hosted environment\"],[\"Persist accepted product artifacts\",\"Application-owned storage, not only sandbox filesystem\"],[\"Execute a high-impact business side effect\",\"Application function with authorization and audit controls\"]]},\"tunes\":{}},{\"id\":\"h-recovery\",\"type\":\"header\",\"data\":{\"text\":\"Step 5 — Replace implicit recovery with explicit lifecycle handling\",\"level\":2},\"tunes\":{}},{\"id\":\"p-recovery-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The managed harness provides session-level recovery, but your application still owns every external dependency around it. Self-hosted environments need provisioning, reconnection and shutdown. Function handlers can fail. Webhooks can be retried. Product-side state can change while an agent is idle.\"},\"tunes\":{}},{\"id\":\"p-recovery-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migration therefore needs two recovery models: agent-runtime recovery and business-operation recovery. The first is increasingly managed by the Agents API. The second remains your responsibility.\"},\"tunes\":{}},{\"id\":\"h-observability\",\"type\":\"header\",\"data\":{\"text\":\"Step 6 — Rebuild observability around the new trace boundary\",\"level\":2},\"tunes\":{}},{\"id\":\"p-obs-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Agents API sessions expose events, saved history, turns, tool calls, subagents and token usage. OpenAI also provides session logs in the platform and trace export.\"},\"tunes\":{}},{\"id\":\"p-obs-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"Do not discard your application observability because platform traces improved. Product logs still need to connect the agent session to user identity, authorization decision, domain object, tool side effect, approval record and final accepted result. The useful production trace is the join between agent-runtime evidence and business-runtime evidence.\"},\"tunes\":{}},{\"id\":\"ref-reliability\",\"type\":\"referralArticle\",\"data\":{\"url\":\"https:\u002F\u002Fstajic.de\u002Fblog\u002Fai-agent-reliability-why-the-final-answer-is-not-enough\",\"title\":\"AI Agent Reliability: Why the Final Answer Is Not Enough\",\"excerpt\":\"Agent reliability depends on the execution path, tools and intermediate decisions — not only the final output.\",\"ctaLabel\":\"Read the reliability article\"},\"tunes\":{}},{\"id\":\"h-evals\",\"type\":\"header\",\"data\":{\"text\":\"Step 7 — Preserve evals before changing the runtime\",\"level\":2},\"tunes\":{}},{\"id\":\"p-evals-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"A migration can appear successful because the new system still produces plausible answers while silently changing tool choice, session continuity, handoff behaviour, latency or failure recovery. Build the behavioural baseline before switching runtimes.\"},\"tunes\":{}},{\"id\":\"p-evals-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The baseline should include representative tasks, expected tool calls, forbidden actions, approval points, state continuity, recovery scenarios and final-output acceptance criteria. Run the old and new architectures against the same cases wherever possible.\"},\"tunes\":{}},{\"id\":\"h-proof\",\"type\":\"header\",\"data\":{\"text\":\"The Migration Proof Test\",\"level\":2},\"tunes\":{}},{\"id\":\"proof-flow\",\"type\":\"processFlow\",\"data\":{\"title\":\"Prove the new runtime before cutting over\",\"orientation\":\"auto\",\"steps\":[{\"label\":\"1. Freeze the behavioural baseline\",\"description\":\"Capture representative SDK traces, expected outputs, tool paths, approval points and failure cases.\"},{\"label\":\"2. Inventory state ownership\",\"description\":\"Mark each state field as agent-session state, authoritative domain state, durable artifact or ephemeral working state.\"},{\"label\":\"3. Reuse stable tool implementations\",\"description\":\"Keep business functions behind application interfaces; replace only the agent-facing integration where possible.\"},{\"label\":\"4. Build one Agents API vertical slice\",\"description\":\"Migrate one production-shaped workflow including session creation, tools, events, environment and persistence.\"},{\"label\":\"5. Inject interruptions\",\"description\":\"Test process restart, webhook retry, function timeout, self-hosted environment reconnect and stale domain state.\"},{\"label\":\"6. Compare traces, not only answers\",\"description\":\"Verify tool choice, authorization, evidence path, state transitions and side effects against the baseline.\"},{\"label\":\"7. Run shadow traffic\",\"description\":\"Where feasible, replay or mirror representative tasks before making the new runtime authoritative.\"},{\"label\":\"8. Cut over behind a reversible boundary\",\"description\":\"Keep integration adapters and rollback capability until production behaviour is stable.\"}]},\"tunes\":{}},{\"id\":\"h-metrics\",\"type\":\"header\",\"data\":{\"text\":\"What to measure during migration\",\"level\":2},\"tunes\":{}},{\"id\":\"metrics-table\",\"type\":\"table\",\"data\":{\"withHeadings\":true,\"stretched\":false,\"content\":[[\"Dimension\",\"Migration check\"],[\"Task success\",\"Does the new runtime meet the same or better acceptance criteria?\"],[\"Tool correctness\",\"Does it call the right tool with valid arguments and authorization?\"],[\"State continuity\",\"Can work resume across turns, restarts and asynchronous waits?\"],[\"Recovery\",\"What happens after webhook loss, handler failure, environment disconnect or timeout?\"],[\"Traceability\",\"Can every consequential action be joined to session, user, tool call and domain object?\"],[\"Context behaviour\",\"Do long-running sessions preserve constraints without carrying stale application truth?\"],[\"Latency\",\"How do session startup, environment provisioning and multi-turn work affect user-visible time?\"],[\"Cost\",\"What changes in model usage, sandbox usage, repeated context and infrastructure operations?\"],[\"Operational load\",\"Which previously application-owned responsibilities actually disappeared, and which merely moved?\"]]},\"tunes\":{}},{\"id\":\"h-not-yet\",\"type\":\"header\",\"data\":{\"text\":\"When not to migrate yet\",\"level\":2},\"tunes\":{}},{\"id\":\"p-not-yet-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"An existing Agents SDK application does not become bad architecture simply because the platform direction changed. OpenAI continues maintenance, security fixes, critical bug fixes and compatibility work. If the application is stable, well evaluated and has no blocked roadmap requirement, an immediate runtime migration may not be justified.\"},\"tunes\":{}},{\"id\":\"not-yet-list\",\"type\":\"list\",\"data\":{\"style\":\"unordered\",\"meta\":{},\"items\":[\"A required SDK capability is not yet available in the Agents API.\",\"The migration would disrupt a critical production period without delivering near-term value.\",\"The application depends on custom orchestration semantics that have not been validated on the managed harness.\",\"Provider portability is a hard requirement and the current SDK abstraction is materially valuable.\",\"Your team has not yet separated business state from agent runtime state, making cutover unsafe.\",\"The new Agents API behaviour has not been tested against representative production workloads.\"]},\"tunes\":{}},{\"id\":\"h-when\",\"type\":\"header\",\"data\":{\"text\":\"When the migration becomes strategically important\",\"level\":2},\"tunes\":{}},{\"id\":\"p-when-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migration becomes more compelling when product requirements align with the managed harness: durable long-running work, platform-managed context compaction and recovery, newer agent-runtime capabilities, sandboxed execution, richer hosted lifecycle management, or a desire to reduce the amount of orchestration code your application operates.\"},\"tunes\":{}},{\"id\":\"p-when-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The strongest signal is not “the old SDK is feature complete.” It is “our roadmap now depends on capabilities whose natural home is the managed Agents API runtime.”\"},\"tunes\":{}},{\"id\":\"h-change\",\"type\":\"header\",\"data\":{\"text\":\"What would change this answer?\",\"level\":2},\"tunes\":{}},{\"id\":\"p-change-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"The migration strategy would change if OpenAI publishes automated migration tooling, introduces explicit compatibility layers, changes Agents API session semantics, expands or narrows self-hosted environment support, or changes the support policy for the Agents SDK.\"},\"tunes\":{}},{\"id\":\"p-change-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"It would also change if your product requirements change. A simple request-response assistant may not need a durable managed harness at all. A long-running coding, research or operations agent can benefit much more from the Agents API ownership model.\"},\"tunes\":{}},{\"id\":\"h-limitations\",\"type\":\"header\",\"data\":{\"text\":\"Limitations\",\"level\":2},\"tunes\":{}},{\"id\":\"p-limit-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"There is no universal one-to-one SDK-to-API migration map because applications use the Agents SDK differently. Some rely heavily on sessions and handoffs; others use it as a thin runner around function tools. The correct migration depends on which responsibilities your application actually owns today.\"},\"tunes\":{}},{\"id\":\"p-limit-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"The Agents API is also in public beta, so implementation details can evolve. Treat the ownership principles in this article as more durable than any individual endpoint shape.\"},\"tunes\":{}},{\"id\":\"h-conclusion\",\"type\":\"header\",\"data\":{\"text\":\"Conclusion\",\"level\":2},\"tunes\":{}},{\"id\":\"p-conclusion-1\",\"type\":\"paragraph\",\"data\":{\"text\":\"Migrating from the Agents SDK to the Agents API is best understood as moving the agent-runtime boundary. The managed harness takes over more of the loop, session continuity, compaction and recovery. Your application should become more explicit about the responsibilities that remain yours: domain truth, authorization, function side effects, artifacts, auditability and product lifecycle.\"},\"tunes\":{}},{\"id\":\"p-conclusion-2\",\"type\":\"paragraph\",\"data\":{\"text\":\"If a migration leaves all of the old orchestration machinery in place and merely replaces SDK calls with Agents API calls, it has probably missed the architectural opportunity. The goal is not to reproduce the old runtime on top of the new one. The goal is to decide which runtime responsibilities no longer belong in your application.\"},\"tunes\":{}},{\"id\":\"h-faq\",\"type\":\"header\",\"data\":{\"text\":\"FAQ\",\"level\":2},\"tunes\":{}},{\"id\":\"faq\",\"type\":\"faq\",\"data\":{\"title\":\"Migrating from Agents SDK to Agents API\",\"items\":[{\"id\":\"faq1\",\"question\":\"Is migrating from the Agents SDK to the Agents API just an API rewrite?\",\"answer\":\"No. The main change is runtime ownership: the Agents SDK runs the agent loop in your application, while the Agents API runs a managed Codex harness and durable session. State, lifecycle, event handling and recovery should be reviewed as architecture concerns.\"},{\"id\":\"faq2\",\"question\":\"Do my function tools need to be rewritten?\",\"answer\":\"The business implementation often can be reused if it is already behind a stable application interface. The agent-facing integration changes because Agents API function calls are handled through session required actions and results.\"},{\"id\":\"faq3\",\"question\":\"Should I move business state into the Agents API session?\",\"answer\":\"Generally no. Keep authoritative business and product state in your own databases or services. Use the agent session for agent continuity and working context, not as the sole source of truth for your product.\"},{\"id\":\"faq4\",\"question\":\"Do I need webhooks for the Agents API?\",\"answer\":\"Not always, because streaming is also available. Webhooks are especially useful for long-running or asynchronous sessions where your application should react to lifecycle changes without holding an open stream.\"},{\"id\":\"faq5\",\"question\":\"Should every existing Agents SDK application migrate now?\",\"answer\":\"No. The SDK remains supported in maintenance mode. Migrate when the new runtime provides meaningful roadmap value and after required behaviour has been validated against production-shaped evals.\"}]},\"tunes\":{}},{\"id\":\"h-glossary\",\"type\":\"header\",\"data\":{\"text\":\"Glossary\",\"level\":2},\"tunes\":{}},{\"id\":\"glossary\",\"type\":\"glossary\",\"data\":{\"title\":\"Key migration terms\",\"entries\":[{\"term\":\"Runtime boundary\",\"definition\":\"The division of responsibility between the platform-managed agent runtime and the application-owned runtime.\",\"anchor\":\"runtime-boundary\"},{\"term\":\"Harness\",\"definition\":\"The agent runtime that coordinates model calls, tools, context, orchestration and continued execution.\",\"anchor\":\"harness\"},{\"term\":\"Session\",\"definition\":\"A durable Agents API instance that holds an agent's configuration, conversation and saved work across turns.\",\"anchor\":\"session\"},{\"term\":\"Required action\",\"definition\":\"A session state in which the Agents API needs external input such as a function result or environment connection before work can continue.\",\"anchor\":\"required-action\"},{\"term\":\"Self-hosted environment\",\"definition\":\"An execution environment operated by your infrastructure and connected to the managed Agents API harness.\",\"anchor\":\"self-hosted-environment\"},{\"term\":\"Migration proof test\",\"definition\":\"A staged validation method that compares the new runtime against behavioural baselines, failure injections, traces and reversible cutover criteria.\",\"anchor\":\"migration-proof-test\"}]},\"tunes\":{}},{\"id\":\"h-sources\",\"type\":\"header\",\"data\":{\"text\":\"Primary sources and further reading\",\"level\":2},\"tunes\":{}},{\"id\":\"src-sdk\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Fsdk\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents SDK\",\"description\":\"Current support policy: the Agents SDK is feature complete, remains maintained, and new applications should start with the Agents API.\"}},\"tunes\":{}},{\"id\":\"src-running-sdk\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents\u002Frunning-agents\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Running agents with the Agents SDK\",\"description\":\"Documentation of the SDK application-owned agent loop and continuation model.\"}},\"tunes\":{}},{\"id\":\"src-api-overview\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Foverview\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API overview\",\"description\":\"Defines the Agents API core concepts: agent, environment, session, events and items.\"}},\"tunes\":{}},{\"id\":\"src-api-architecture\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Farchitecture\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API architecture\",\"description\":\"Explains the hosted harness, application server, OpenAI-hosted and self-hosted execution environment boundaries.\"}},\"tunes\":{}},{\"id\":\"src-api-config\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fconfiguration\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Configuring Agents\",\"description\":\"Defines reusable agent configuration and session-level customization.\"}},\"tunes\":{}},{\"id\":\"src-api-sessions\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Run and continue sessions\",\"description\":\"Documents durable sessions, asynchronous turns, streaming and steering.\"}},\"tunes\":{}},{\"id\":\"src-api-functions\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Ftools\u002Ffunctions\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API Functions\",\"description\":\"Function-tool definition and the application handler boundary for required function results.\"}},\"tunes\":{}},{\"id\":\"src-api-webhooks\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fsessions\u002Fwebhooks\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Session webhooks\",\"description\":\"Lifecycle events for asynchronous sessions, required actions and self-hosted environment connections.\"}},\"tunes\":{}},{\"id\":\"src-api-observability\",\"type\":\"linkTool\",\"data\":{\"link\":\"https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Fagents-api\u002Fobservability\",\"meta\":{\"image\":{\"url\":\"\"},\"title\":\"OpenAI — Agents API observability and usage\",\"description\":\"Session logs, events, turns, tool calls, subagents, traces and token-usage inspection.\"}},\"tunes\":{}}],\"version\":\"2.31.6\"}",{"time":1350,"blocks":1351,"version":2220},1790352173087,[1352,1356,1360,1365,1370,1375,1379,1383,1387,1391,1395,1446,1450,1454,1458,1463,1467,1471,1503,1507,1511,1515,1539,1543,1547,1551,1555,1559,1563,1568,1572,1576,1580,1602,1606,1610,1614,1618,1622,1626,1633,1637,1641,1645,1649,1678,1682,1715,1719,1723,1734,1738,1742,1746,1750,1754,1758,1762,1766,1770,1774,1778,1782,1786,1806,1810,1832,1836,1842,1849,1856,1863,1870,1877,1884,1891,1898,1901,1904,1907,1910,1913,1916,1919,1922,1925,1928,1944,1947,1950,1953,1956,1959,1962,1973,1976,1979,1982,1998,2001,2004,2007,2010,2013,2016,2019,2022,2025,2028,2038,2041,2044,2047,2050,2053,2056,2059,2062,2065,2068,2071,2083,2086,2100,2103,2106,2111,2114,2117,2120,2123,2126,2129,2132,2135,2138,2141,2144,2147,2150,2159,2162,2172,2175,2180,2185,2190,2195,2200,2205,2210,2215],{"id":215,"data":1353,"type":220,"tunes":1355},{"title":1354,"maxLevel":218,"minLevel":219},"Contents",{},{"id":223,"data":1357,"type":226,"tunes":1359},{"text":1358},"Migrating from the OpenAI Agents SDK to the Agents API is not an import rename. The core architectural boundary changes: the SDK runs the agent loop inside your application, while the Agents API runs a managed Codex harness and durable session on OpenAI's side. The migration question is therefore not “Which classes map to which endpoints?” but “Which runtime responsibilities move across the boundary, which stay in our application, and which need to be redesigned?”",{},{"id":229,"data":1361,"type":234,"tunes":1364},{"body":1362,"title":1363,"variant":233},"\u003Cstrong>A real Agents SDK → Agents API migration changes runtime ownership.\u003C\u002Fstrong> Your reusable agent configuration can still contain model, instructions and tools, but the loop, durable session, orchestration, context compaction and recovery move toward the managed Agents API runtime. Your application should keep domain state, authorization, business rules, function implementations and audit logic outside the agent session. Treat the migration as a boundary redesign, not a mechanical code conversion.","Direct answer",{},{"id":237,"data":1366,"type":234,"tunes":1369},{"body":1367,"title":1368,"variant":241},"OpenAI currently marks the Agents SDK as \u003Cstrong>feature complete\u003C\u002Fstrong> and recommends the Agents API for new agent applications. The Agents API is in public beta. Existing SDK applications remain supported, and immediate migration is not automatically required.","Current as of 25 September 2026",{},{"id":244,"data":1371,"type":234,"tunes":1374},{"body":1372,"title":1373,"variant":248},"The Runtime Boundary Migration Map and Migration Proof Test in this article are practical architecture tools, not official OpenAI migration frameworks. They are derived from the current runtime differences documented by OpenAI.","About the migration model",{},{"id":251,"data":1376,"type":42,"tunes":1378},{"text":1377,"level":219},"The migration is from an application-owned loop to a managed harness",{},{"id":256,"data":1380,"type":226,"tunes":1382},{"text":1381},"In the Agents SDK, one run is an application-level turn. The SDK runner calls the model, inspects the output, executes tools, follows handoffs and continues until it reaches a stopping point. Your process hosts that loop and therefore owns its lifecycle.",{},{"id":261,"data":1384,"type":226,"tunes":1386},{"text":1385},"In the Agents API, OpenAI runs the harness. A session is a durable instance of an agent configuration that accepts tasks, produces events, can pause for required actions, and can continue over time. OpenAI manages sessions, orchestration, context compaction and recovery; your application sends work, handles function tools, receives events and optionally manages a self-hosted execution environment.",{},{"id":266,"data":1388,"type":226,"tunes":1390},{"text":1389},"That ownership shift is the migration. Everything else — API syntax, tool schemas, event handling, session IDs — follows from it.",{},{"id":271,"data":1392,"type":42,"tunes":1394},{"text":1393,"level":219},"The Runtime Boundary Migration Map",{},{"id":276,"data":1396,"type":327,"tunes":1445},{"content":1397,"stretched":43,"withHeadings":14},[1398,1401,1405,1409,1413,1417,1421,1425,1429,1433,1437,1441],[1399,281,1400],"Concern","Agents API migration target",[1402,1403,1404],"Agent loop","Runs in your application through the SDK runner","Runs in the managed Codex harness",[1406,1407,1408],"Reusable agent definition","Agent object in application code","Saved or inline agent configuration with model, instructions and tools",[1410,1411,1412],"Conversation \u002F work continuity","SDK session strategy, history, result continuation or application storage","Durable Agents API session",[1414,1415,1416],"Tool execution","SDK coordinates tool calls in your runtime","Harness requests function calls; your application returns results",[1418,1419,1420],"Context management","Your runtime \u002F SDK session strategy","Managed session context, compaction and recovery, plus your own application data boundaries",[1422,1423,1424],"Handoffs \u002F specialists","SDK orchestration primitives","Harness \u002F subagent behaviour in Agents API; do not assume one-to-one semantics",[1426,1427,1428],"Execution environment","Your application runtime or tool-specific environment","Optional OpenAI-hosted or self-hosted environment attached to the session",[1430,1431,1432],"Streaming","SDK streaming from the run","Agents API session event stream",[1434,1435,1436],"Async lifecycle","Usually application-managed around the SDK run","Native session states, asynchronous turns and webhooks",[1438,1439,1440],"Tracing \u002F observability","Agents SDK tracing and application logs","Agents session logs, events, turns, tool calls, subagents and exportable traces",[1442,1443,1444],"Recovery","Application responsibility","Managed harness\u002Fsession recovery plus application-owned recovery for external systems and self-hosted environments",{},{"id":330,"data":1447,"type":42,"tunes":1449},{"text":1448,"level":219},"What can migrate conceptually without changing ownership",{},{"id":335,"data":1451,"type":226,"tunes":1453},{"text":1452},"Several application concepts survive the migration cleanly even though their representation changes. Models, instructions, JSON-schema function definitions, MCP access, tool descriptions and structured output requirements are still agent configuration concerns.",{},{"id":340,"data":1455,"type":226,"tunes":1457},{"text":1456},"OpenAI's Agents API configuration model explicitly defines an agent through model, instructions, tools, reasoning and output behaviour. Function tools remain application code: the harness requests a function call, and your handler returns the result. OpenAI also notes that function implementations used with the Responses API can be reused with the Agents API session flow.",{},{"id":345,"data":1459,"type":234,"tunes":1462},{"body":1460,"title":1461,"variant":349},"A pure business function such as \u003Ccode>get_customer(customer_id)\u003C\u002Fcode> should not need to know whether the caller is the Agents SDK or the Agents API. Keep its domain logic behind a stable application interface and migrate only the agent-facing adapter.","Good migration candidate",{},{"id":352,"data":1464,"type":42,"tunes":1466},{"text":1465,"level":219},"What should not be migrated one-to-one",{},{"id":357,"data":1468,"type":226,"tunes":1470},{"text":1469},"The dangerous migration pattern is to recreate every SDK runtime abstraction inside the Agents API. That can leave you paying for a managed harness while still operating a shadow harness in your application.",{},{"id":362,"data":1472,"type":327,"tunes":1502},{"content":1473,"stretched":43,"withHeadings":14},[1474,1478,1482,1486,1490,1494,1498],[1475,1476,1477],"SDK-era assumption","Why a direct copy is risky","Migration question",[1479,1480,1481],"Application loop owns every continuation","The Agents API already owns the harness loop","Which continuation logic is product logic, and which should move to the managed session?",[1483,1484,1485],"Local session object is the primary continuity mechanism","Agents API sessions are durable resources with their own lifecycle","Which state belongs in the session versus the product database?",[1487,1488,1489],"Every interruption is handled synchronously","Agents API turns are asynchronous and can surface action_required states","Which actions need webhooks, workers, idempotency and resumable handlers?",[1491,1492,1493],"All tool execution happens where the SDK process runs","Function handlers and execution environments can be separate","Where should each tool actually execute?",[1495,1496,1497],"SDK trace is the operational timeline","Agents API exposes session events, turns and managed traces","What application-level audit data still needs its own record?",[1499,1500,1501],"Handoff object maps directly to a hosted subagent model","Runtime semantics can differ","What user-visible ownership and specialist behaviour must be preserved, not merely the old class structure?",{},{"id":395,"data":1504,"type":42,"tunes":1506},{"text":1505,"level":219},"Step 1 — Separate domain state from agent session state",{},{"id":400,"data":1508,"type":226,"tunes":1510},{"text":1509},"Before touching API calls, classify the state your SDK application currently carries. Some state exists only to keep the agent conversation moving. Other state is business truth: user permissions, project status, order data, workflow approval, customer records, document versions, policy state or application configuration.",{},{"id":405,"data":1512,"type":226,"tunes":1514},{"text":1513},"The second category should not become dependent on an Agents API session. A durable session is useful continuity for the agent; it is not a replacement for your product's source of truth. If the session disappears, expires, is rebuilt, or changes implementation, your application must still know what is true.",{},{"id":410,"data":1516,"type":441,"tunes":1538},{"rows":1517,"title":1530,"layout":327,"columns":1531},[1518,1521,1524,1527],{"id":414,"label":1519,"values":1520},"Conversation continuity",[417,417,417],{"id":419,"label":1522,"values":1523},"Business truth",[417,417,417],{"id":423,"label":1525,"values":1526},"Durable artifact",[417,417,417],{"id":427,"label":1528,"values":1529},"Working scratch state",[417,417,417],"State placement test",[1532,1534,1536],{"id":433,"label":1533},"State type",{"id":436,"label":1535},"Preferred owner",{"id":439,"label":1537},"Reason",{},{"id":444,"data":1540,"type":42,"tunes":1542},{"text":1541,"level":219},"Step 2 — Convert the runner mindset into a session-and-events mindset",{},{"id":449,"data":1544,"type":226,"tunes":1546},{"text":1545},"SDK applications often think in terms of calling run and receiving a result. The Agents API thinks in terms of a durable session whose turns can run asynchronously. A message to an idle session starts work; a message during an active turn can steer it. Progress arrives through streaming or webhooks.",{},{"id":454,"data":1548,"type":226,"tunes":1550},{"text":1549},"This affects application architecture. Long-running production work should not depend on one HTTP request remaining alive. Your product needs stable session identifiers, lifecycle persistence, webhook verification, idempotent handlers and a way to reconcile current session state after process restarts.",{},{"id":459,"data":1552,"type":42,"tunes":1554},{"text":1553,"level":219},"Step 3 — Redesign function tools around required actions",{},{"id":464,"data":1556,"type":226,"tunes":1558},{"text":1557},"Function tools remain an important application boundary. You define the function and its JSON schema in the agent configuration. When the harness needs the function, the session can enter an action-required state. Your application retrieves the required action, executes the business logic and returns the result.",{},{"id":469,"data":1560,"type":226,"tunes":1562},{"text":1561},"That means the function implementation should be safe to resume. A webhook may be delivered while another worker is processing. A network failure can occur after the external side effect but before the result is returned. Migration is therefore a good moment to add call IDs, idempotency keys, explicit authorization, timeout policies and audit records to consequential tools.",{},{"id":474,"data":1564,"type":234,"tunes":1567},{"body":1565,"title":1566,"variant":241},"Do not treat a function call from the managed harness as authorization to perform the action. The harness decides \u003Cem>what it wants to call\u003C\u002Fem>; your application still decides whether the current user, session and business state allow that action.","Tool migration trap",{},{"id":480,"data":1569,"type":42,"tunes":1571},{"text":1570,"level":219},"Step 4 — Decide where execution should happen",{},{"id":485,"data":1573,"type":226,"tunes":1575},{"text":1574},"The Agents API separates the managed harness from the execution environment. An agent can operate without a dedicated environment, in an OpenAI-hosted sandbox, or through a self-hosted environment connected to the session.",{},{"id":490,"data":1577,"type":226,"tunes":1579},{"text":1578},"This creates a migration decision that SDK applications may never have made explicitly: which code should run as an application function, which code belongs in a sandbox, and which workloads require infrastructure you control?",{},{"id":495,"data":1581,"type":327,"tunes":1601},{"content":1582,"stretched":43,"withHeadings":14},[1583,1586,1589,1592,1595,1598],[1584,1585],"Need","Likely boundary",[1587,1588],"Call an existing internal service through controlled business logic","Function tool handled by your application",[1590,1591],"Run isolated code or work with temporary files without private infrastructure","OpenAI-hosted environment",[1593,1594],"Access private network resources, custom system software or controlled local compute","Self-hosted environment",[1596,1597],"Persist accepted product artifacts","Application-owned storage, not only sandbox filesystem",[1599,1600],"Execute a high-impact business side effect","Application function with authorization and audit controls",{},{"id":518,"data":1603,"type":42,"tunes":1605},{"text":1604,"level":219},"Step 5 — Replace implicit recovery with explicit lifecycle handling",{},{"id":523,"data":1607,"type":226,"tunes":1609},{"text":1608},"The managed harness provides session-level recovery, but your application still owns every external dependency around it. Self-hosted environments need provisioning, reconnection and shutdown. Function handlers can fail. Webhooks can be retried. Product-side state can change while an agent is idle.",{},{"id":528,"data":1611,"type":226,"tunes":1613},{"text":1612},"Migration therefore needs two recovery models: agent-runtime recovery and business-operation recovery. The first is increasingly managed by the Agents API. The second remains your responsibility.",{},{"id":533,"data":1615,"type":42,"tunes":1617},{"text":1616,"level":219},"Step 6 — Rebuild observability around the new trace boundary",{},{"id":538,"data":1619,"type":226,"tunes":1621},{"text":1620},"Agents API sessions expose events, saved history, turns, tool calls, subagents and token usage. OpenAI also provides session logs in the platform and trace export.",{},{"id":543,"data":1623,"type":226,"tunes":1625},{"text":1624},"Do not discard your application observability because platform traces improved. Product logs still need to connect the agent session to user identity, authorization decision, domain object, tool side effect, approval record and final accepted result. The useful production trace is the join between agent-runtime evidence and business-runtime evidence.",{},{"id":548,"data":1627,"type":554,"tunes":1632},{"url":1628,"title":1629,"excerpt":1630,"ctaLabel":1631},"https:\u002F\u002Fstajic.de\u002Fblog\u002Fai-agent-reliability-why-the-final-answer-is-not-enough","AI Agent Reliability: Why the Final Answer Is Not Enough","Agent reliability depends on the execution path, tools and intermediate decisions — not only the final output.","Read the reliability article",{},{"id":557,"data":1634,"type":42,"tunes":1636},{"text":1635,"level":219},"Step 7 — Preserve evals before changing the runtime",{},{"id":562,"data":1638,"type":226,"tunes":1640},{"text":1639},"A migration can appear successful because the new system still produces plausible answers while silently changing tool choice, session continuity, handoff behaviour, latency or failure recovery. Build the behavioural baseline before switching runtimes.",{},{"id":567,"data":1642,"type":226,"tunes":1644},{"text":1643},"The baseline should include representative tasks, expected tool calls, forbidden actions, approval points, state continuity, recovery scenarios and final-output acceptance criteria. Run the old and new architectures against the same cases wherever possible.",{},{"id":572,"data":1646,"type":42,"tunes":1648},{"text":1647,"level":219},"The Migration Proof Test",{},{"id":577,"data":1650,"type":606,"tunes":1677},{"steps":1651,"title":1676,"orientation":605},[1652,1655,1658,1661,1664,1667,1670,1673],{"label":1653,"description":1654},"1. Freeze the behavioural baseline","Capture representative SDK traces, expected outputs, tool paths, approval points and failure cases.",{"label":1656,"description":1657},"2. Inventory state ownership","Mark each state field as agent-session state, authoritative domain state, durable artifact or ephemeral working state.",{"label":1659,"description":1660},"3. Reuse stable tool implementations","Keep business functions behind application interfaces; replace only the agent-facing integration where possible.",{"label":1662,"description":1663},"4. Build one Agents API vertical slice","Migrate one production-shaped workflow including session creation, tools, events, environment and persistence.",{"label":1665,"description":1666},"5. Inject interruptions","Test process restart, webhook retry, function timeout, self-hosted environment reconnect and stale domain state.",{"label":1668,"description":1669},"6. Compare traces, not only answers","Verify tool choice, authorization, evidence path, state transitions and side effects against the baseline.",{"label":1671,"description":1672},"7. Run shadow traffic","Where feasible, replay or mirror representative tasks before making the new runtime authoritative.",{"label":1674,"description":1675},"8. Cut over behind a reversible boundary","Keep integration adapters and rollback capability until production behaviour is stable.","Prove the new runtime before cutting over",{},{"id":609,"data":1679,"type":42,"tunes":1681},{"text":1680,"level":219},"What to measure during migration",{},{"id":614,"data":1683,"type":327,"tunes":1714},{"content":1684,"stretched":43,"withHeadings":14},[1685,1688,1691,1694,1697,1699,1702,1705,1708,1711],[1686,1687],"Dimension","Migration check",[1689,1690],"Task success","Does the new runtime meet the same or better acceptance criteria?",[1692,1693],"Tool correctness","Does it call the right tool with valid arguments and authorization?",[1695,1696],"State continuity","Can work resume across turns, restarts and asynchronous waits?",[1442,1698],"What happens after webhook loss, handler failure, environment disconnect or timeout?",[1700,1701],"Traceability","Can every consequential action be joined to session, user, tool call and domain object?",[1703,1704],"Context behaviour","Do long-running sessions preserve constraints without carrying stale application truth?",[1706,1707],"Latency","How do session startup, environment provisioning and multi-turn work affect user-visible time?",[1709,1710],"Cost","What changes in model usage, sandbox usage, repeated context and infrastructure operations?",[1712,1713],"Operational load","Which previously application-owned responsibilities actually disappeared, and which merely moved?",{},{"id":648,"data":1716,"type":42,"tunes":1718},{"text":1717,"level":219},"When not to migrate yet",{},{"id":653,"data":1720,"type":226,"tunes":1722},{"text":1721},"An existing Agents SDK application does not become bad architecture simply because the platform direction changed. OpenAI continues maintenance, security fixes, critical bug fixes and compatibility work. If the application is stable, well evaluated and has no blocked roadmap requirement, an immediate runtime migration may not be justified.",{},{"id":658,"data":1724,"type":669,"tunes":1733},{"meta":1725,"items":1726,"style":668},{},[1727,1728,1729,1730,1731,1732],"A required SDK capability is not yet available in the Agents API.","The migration would disrupt a critical production period without delivering near-term value.","The application depends on custom orchestration semantics that have not been validated on the managed harness.","Provider portability is a hard requirement and the current SDK abstraction is materially valuable.","Your team has not yet separated business state from agent runtime state, making cutover unsafe.","The new Agents API behaviour has not been tested against representative production workloads.",{},{"id":672,"data":1735,"type":42,"tunes":1737},{"text":1736,"level":219},"When the migration becomes strategically important",{},{"id":677,"data":1739,"type":226,"tunes":1741},{"text":1740},"Migration becomes more compelling when product requirements align with the managed harness: durable long-running work, platform-managed context compaction and recovery, newer agent-runtime capabilities, sandboxed execution, richer hosted lifecycle management, or a desire to reduce the amount of orchestration code your application operates.",{},{"id":682,"data":1743,"type":226,"tunes":1745},{"text":1744},"The strongest signal is not “the old SDK is feature complete.” It is “our roadmap now depends on capabilities whose natural home is the managed Agents API runtime.”",{},{"id":687,"data":1747,"type":42,"tunes":1749},{"text":1748,"level":219},"What would change this answer?",{},{"id":692,"data":1751,"type":226,"tunes":1753},{"text":1752},"The migration strategy would change if OpenAI publishes automated migration tooling, introduces explicit compatibility layers, changes Agents API session semantics, expands or narrows self-hosted environment support, or changes the support policy for the Agents SDK.",{},{"id":697,"data":1755,"type":226,"tunes":1757},{"text":1756},"It would also change if your product requirements change. A simple request-response assistant may not need a durable managed harness at all. A long-running coding, research or operations agent can benefit much more from the Agents API ownership model.",{},{"id":702,"data":1759,"type":42,"tunes":1761},{"text":1760,"level":219},"Limitations",{},{"id":707,"data":1763,"type":226,"tunes":1765},{"text":1764},"There is no universal one-to-one SDK-to-API migration map because applications use the Agents SDK differently. Some rely heavily on sessions and handoffs; others use it as a thin runner around function tools. The correct migration depends on which responsibilities your application actually owns today.",{},{"id":712,"data":1767,"type":226,"tunes":1769},{"text":1768},"The Agents API is also in public beta, so implementation details can evolve. Treat the ownership principles in this article as more durable than any individual endpoint shape.",{},{"id":717,"data":1771,"type":42,"tunes":1773},{"text":1772,"level":219},"Conclusion",{},{"id":722,"data":1775,"type":226,"tunes":1777},{"text":1776},"Migrating from the Agents SDK to the Agents API is best understood as moving the agent-runtime boundary. The managed harness takes over more of the loop, session continuity, compaction and recovery. Your application should become more explicit about the responsibilities that remain yours: domain truth, authorization, function side effects, artifacts, auditability and product lifecycle.",{},{"id":727,"data":1779,"type":226,"tunes":1781},{"text":1780},"If a migration leaves all of the old orchestration machinery in place and merely replaces SDK calls with Agents API calls, it has probably missed the architectural opportunity. The goal is not to reproduce the old runtime on top of the new one. The goal is to decide which runtime responsibilities no longer belong in your application.",{},{"id":732,"data":1783,"type":42,"tunes":1785},{"text":1784,"level":219},"FAQ",{},{"id":737,"data":1787,"type":737,"tunes":1805},{"items":1788,"title":1804},[1789,1792,1795,1798,1801],{"id":741,"answer":1790,"question":1791},"No. The main change is runtime ownership: the Agents SDK runs the agent loop in your application, while the Agents API runs a managed Codex harness and durable session. State, lifecycle, event handling and recovery should be reviewed as architecture concerns.","Is migrating from the Agents SDK to the Agents API just an API rewrite?",{"id":745,"answer":1793,"question":1794},"The business implementation often can be reused if it is already behind a stable application interface. The agent-facing integration changes because Agents API function calls are handled through session required actions and results.","Do my function tools need to be rewritten?",{"id":749,"answer":1796,"question":1797},"Generally no. Keep authoritative business and product state in your own databases or services. Use the agent session for agent continuity and working context, not as the sole source of truth for your product.","Should I move business state into the Agents API session?",{"id":753,"answer":1799,"question":1800},"Not always, because streaming is also available. Webhooks are especially useful for long-running or asynchronous sessions where your application should react to lifecycle changes without holding an open stream.","Do I need webhooks for the Agents API?",{"id":757,"answer":1802,"question":1803},"No. The SDK remains supported in maintenance mode. Migrate when the new runtime provides meaningful roadmap value and after required behaviour has been validated against production-shaped evals.","Should every existing Agents SDK application migrate now?","Migrating from Agents SDK to Agents API",{},{"id":763,"data":1807,"type":42,"tunes":1809},{"text":1808,"level":219},"Glossary",{},{"id":768,"data":1811,"type":768,"tunes":1831},{"title":1812,"entries":1813},"Key migration terms",[1814,1817,1820,1823,1826,1828],{"term":1815,"anchor":774,"definition":1816},"Runtime boundary","The division of responsibility between the platform-managed agent runtime and the application-owned runtime.",{"term":1818,"anchor":778,"definition":1819},"Harness","The agent runtime that coordinates model calls, tools, context, orchestration and continued execution.",{"term":1821,"anchor":782,"definition":1822},"Session","A durable Agents API instance that holds an agent's configuration, conversation and saved work across turns.",{"term":1824,"anchor":786,"definition":1825},"Required action","A session state in which the Agents API needs external input such as a function result or environment connection before work can continue.",{"term":1594,"anchor":789,"definition":1827},"An execution environment operated by your infrastructure and connected to the managed Agents API harness.",{"term":1829,"anchor":792,"definition":1830},"Migration proof test","A staged validation method that compares the new runtime against behavioural baselines, failure injections, traces and reversible cutover criteria.",{},{"id":796,"data":1833,"type":42,"tunes":1835},{"text":1834,"level":219},"Primary sources and further reading",{},{"id":801,"data":1837,"type":808,"tunes":1841},{"link":803,"meta":1838},{"image":1839,"title":806,"description":1840},{"url":417},"Current support policy: the Agents SDK is feature complete, remains maintained, and new applications should start with the Agents API.",{},{"id":811,"data":1843,"type":808,"tunes":1848},{"link":813,"meta":1844},{"image":1845,"title":1846,"description":1847},{"url":417},"OpenAI — Running agents with the Agents SDK","Documentation of the SDK application-owned agent loop and continuation model.",{},{"id":820,"data":1850,"type":808,"tunes":1855},{"link":822,"meta":1851},{"image":1852,"title":1853,"description":1854},{"url":417},"OpenAI — Agents API overview","Defines the Agents API core concepts: agent, environment, session, events and items.",{},{"id":829,"data":1857,"type":808,"tunes":1862},{"link":831,"meta":1858},{"image":1859,"title":1860,"description":1861},{"url":417},"OpenAI — Agents API architecture","Explains the hosted harness, application server, OpenAI-hosted and self-hosted execution environment boundaries.",{},{"id":838,"data":1864,"type":808,"tunes":1869},{"link":840,"meta":1865},{"image":1866,"title":1867,"description":1868},{"url":417},"OpenAI — Configuring Agents","Defines reusable agent configuration and session-level customization.",{},{"id":847,"data":1871,"type":808,"tunes":1876},{"link":849,"meta":1872},{"image":1873,"title":1874,"description":1875},{"url":417},"OpenAI — Run and continue sessions","Documents durable sessions, asynchronous turns, streaming and steering.",{},{"id":856,"data":1878,"type":808,"tunes":1883},{"link":858,"meta":1879},{"image":1880,"title":1881,"description":1882},{"url":417},"OpenAI — Agents API Functions","Function-tool definition and the application handler boundary for required function results.",{},{"id":865,"data":1885,"type":808,"tunes":1890},{"link":867,"meta":1886},{"image":1887,"title":1888,"description":1889},{"url":417},"OpenAI — Session webhooks","Lifecycle events for asynchronous sessions, required actions and self-hosted environment connections.",{},{"id":874,"data":1892,"type":808,"tunes":1897},{"link":876,"meta":1893},{"image":1894,"title":1895,"description":1896},{"url":417},"OpenAI — Agents API observability and usage","Session logs, events, turns, tool calls, subagents, traces and token-usage inspection.",{},{"id":223,"data":1899,"type":226,"tunes":1900},{"text":1358},{},{"id":229,"data":1902,"type":234,"tunes":1903},{"body":1362,"title":1363,"variant":233},{},{"id":237,"data":1905,"type":234,"tunes":1906},{"body":1367,"title":1368,"variant":241},{},{"id":244,"data":1908,"type":234,"tunes":1909},{"body":1372,"title":1373,"variant":248},{},{"id":899,"data":1911,"type":220,"tunes":1912},{"title":1354,"maxLevel":218,"minLevel":219},{},{"id":251,"data":1914,"type":42,"tunes":1915},{"text":1377,"level":219},{},{"id":256,"data":1917,"type":226,"tunes":1918},{"text":1381},{},{"id":261,"data":1920,"type":226,"tunes":1921},{"text":1385},{},{"id":266,"data":1923,"type":226,"tunes":1924},{"text":1389},{},{"id":271,"data":1926,"type":42,"tunes":1927},{"text":1393,"level":219},{},{"id":276,"data":1929,"type":327,"tunes":1943},{"content":1930,"stretched":43,"withHeadings":14},[1931,1932,1933,1934,1935,1936,1937,1938,1939,1940,1941,1942],[1399,281,1400],[1402,1403,1404],[1406,1407,1408],[1410,1411,1412],[1414,1415,1416],[1418,1419,1420],[1422,1423,1424],[1426,1427,1428],[1430,1431,1432],[1434,1435,1436],[1438,1439,1440],[1442,1443,1444],{},{"id":330,"data":1945,"type":42,"tunes":1946},{"text":1448,"level":219},{},{"id":335,"data":1948,"type":226,"tunes":1949},{"text":1452},{},{"id":340,"data":1951,"type":226,"tunes":1952},{"text":1456},{},{"id":345,"data":1954,"type":234,"tunes":1955},{"body":1460,"title":1461,"variant":349},{},{"id":352,"data":1957,"type":42,"tunes":1958},{"text":1465,"level":219},{},{"id":357,"data":1960,"type":226,"tunes":1961},{"text":1469},{},{"id":362,"data":1963,"type":327,"tunes":1972},{"content":1964,"stretched":43,"withHeadings":14},[1965,1966,1967,1968,1969,1970,1971],[1475,1476,1477],[1479,1480,1481],[1483,1484,1485],[1487,1488,1489],[1491,1492,1493],[1495,1496,1497],[1499,1500,1501],{},{"id":395,"data":1974,"type":42,"tunes":1975},{"text":1505,"level":219},{},{"id":400,"data":1977,"type":226,"tunes":1978},{"text":1509},{},{"id":405,"data":1980,"type":226,"tunes":1981},{"text":1513},{},{"id":410,"data":1983,"type":441,"tunes":1997},{"rows":1984,"title":1530,"layout":327,"columns":1993},[1985,1987,1989,1991],{"id":414,"label":1519,"values":1986},[417,417,417],{"id":419,"label":1522,"values":1988},[417,417,417],{"id":423,"label":1525,"values":1990},[417,417,417],{"id":427,"label":1528,"values":1992},[417,417,417],[1994,1995,1996],{"id":433,"label":1533},{"id":436,"label":1535},{"id":439,"label":1537},{},{"id":444,"data":1999,"type":42,"tunes":2000},{"text":1541,"level":219},{},{"id":449,"data":2002,"type":226,"tunes":2003},{"text":1545},{},{"id":454,"data":2005,"type":226,"tunes":2006},{"text":1549},{},{"id":459,"data":2008,"type":42,"tunes":2009},{"text":1553,"level":219},{},{"id":464,"data":2011,"type":226,"tunes":2012},{"text":1557},{},{"id":469,"data":2014,"type":226,"tunes":2015},{"text":1561},{},{"id":474,"data":2017,"type":234,"tunes":2018},{"body":1565,"title":1566,"variant":241},{},{"id":480,"data":2020,"type":42,"tunes":2021},{"text":1570,"level":219},{},{"id":485,"data":2023,"type":226,"tunes":2024},{"text":1574},{},{"id":490,"data":2026,"type":226,"tunes":2027},{"text":1578},{},{"id":495,"data":2029,"type":327,"tunes":2037},{"content":2030,"stretched":43,"withHeadings":14},[2031,2032,2033,2034,2035,2036],[1584,1585],[1587,1588],[1590,1591],[1593,1594],[1596,1597],[1599,1600],{},{"id":518,"data":2039,"type":42,"tunes":2040},{"text":1604,"level":219},{},{"id":523,"data":2042,"type":226,"tunes":2043},{"text":1608},{},{"id":528,"data":2045,"type":226,"tunes":2046},{"text":1612},{},{"id":533,"data":2048,"type":42,"tunes":2049},{"text":1616,"level":219},{},{"id":538,"data":2051,"type":226,"tunes":2052},{"text":1620},{},{"id":543,"data":2054,"type":226,"tunes":2055},{"text":1624},{},{"id":548,"data":2057,"type":554,"tunes":2058},{"url":1628,"title":1629,"excerpt":1630,"ctaLabel":1631},{},{"id":557,"data":2060,"type":42,"tunes":2061},{"text":1635,"level":219},{},{"id":562,"data":2063,"type":226,"tunes":2064},{"text":1639},{},{"id":567,"data":2066,"type":226,"tunes":2067},{"text":1643},{},{"id":572,"data":2069,"type":42,"tunes":2070},{"text":1647,"level":219},{},{"id":577,"data":2072,"type":606,"tunes":2082},{"steps":2073,"title":1676,"orientation":605},[2074,2075,2076,2077,2078,2079,2080,2081],{"label":1653,"description":1654},{"label":1656,"description":1657},{"label":1659,"description":1660},{"label":1662,"description":1663},{"label":1665,"description":1666},{"label":1668,"description":1669},{"label":1671,"description":1672},{"label":1674,"description":1675},{},{"id":609,"data":2084,"type":42,"tunes":2085},{"text":1680,"level":219},{},{"id":614,"data":2087,"type":327,"tunes":2099},{"content":2088,"stretched":43,"withHeadings":14},[2089,2090,2091,2092,2093,2094,2095,2096,2097,2098],[1686,1687],[1689,1690],[1692,1693],[1695,1696],[1442,1698],[1700,1701],[1703,1704],[1706,1707],[1709,1710],[1712,1713],{},{"id":648,"data":2101,"type":42,"tunes":2102},{"text":1717,"level":219},{},{"id":653,"data":2104,"type":226,"tunes":2105},{"text":1721},{},{"id":658,"data":2107,"type":669,"tunes":2110},{"meta":2108,"items":2109,"style":668},{},[1727,1728,1729,1730,1731,1732],{},{"id":672,"data":2112,"type":42,"tunes":2113},{"text":1736,"level":219},{},{"id":677,"data":2115,"type":226,"tunes":2116},{"text":1740},{},{"id":682,"data":2118,"type":226,"tunes":2119},{"text":1744},{},{"id":687,"data":2121,"type":42,"tunes":2122},{"text":1748,"level":219},{},{"id":692,"data":2124,"type":226,"tunes":2125},{"text":1752},{},{"id":697,"data":2127,"type":226,"tunes":2128},{"text":1756},{},{"id":702,"data":2130,"type":42,"tunes":2131},{"text":1760,"level":219},{},{"id":707,"data":2133,"type":226,"tunes":2134},{"text":1764},{},{"id":712,"data":2136,"type":226,"tunes":2137},{"text":1768},{},{"id":717,"data":2139,"type":42,"tunes":2140},{"text":1772,"level":219},{},{"id":722,"data":2142,"type":226,"tunes":2143},{"text":1776},{},{"id":727,"data":2145,"type":226,"tunes":2146},{"text":1780},{},{"id":732,"data":2148,"type":42,"tunes":2149},{"text":1784,"level":219},{},{"id":737,"data":2151,"type":737,"tunes":2158},{"items":2152,"title":1804},[2153,2154,2155,2156,2157],{"id":741,"answer":1790,"question":1791},{"id":745,"answer":1793,"question":1794},{"id":749,"answer":1796,"question":1797},{"id":753,"answer":1799,"question":1800},{"id":757,"answer":1802,"question":1803},{},{"id":763,"data":2160,"type":42,"tunes":2161},{"text":1808,"level":219},{},{"id":768,"data":2163,"type":768,"tunes":2171},{"title":1812,"entries":2164},[2165,2166,2167,2168,2169,2170],{"term":1815,"anchor":774,"definition":1816},{"term":1818,"anchor":778,"definition":1819},{"term":1821,"anchor":782,"definition":1822},{"term":1824,"anchor":786,"definition":1825},{"term":1594,"anchor":789,"definition":1827},{"term":1829,"anchor":792,"definition":1830},{},{"id":796,"data":2173,"type":42,"tunes":2174},{"text":1834,"level":219},{},{"id":801,"data":2176,"type":808,"tunes":2179},{"link":803,"meta":2177},{"image":2178,"title":806,"description":1840},{"url":417},{},{"id":811,"data":2181,"type":808,"tunes":2184},{"link":813,"meta":2182},{"image":2183,"title":1846,"description":1847},{"url":417},{},{"id":820,"data":2186,"type":808,"tunes":2189},{"link":822,"meta":2187},{"image":2188,"title":1853,"description":1854},{"url":417},{},{"id":829,"data":2191,"type":808,"tunes":2194},{"link":831,"meta":2192},{"image":2193,"title":1860,"description":1861},{"url":417},{},{"id":838,"data":2196,"type":808,"tunes":2199},{"link":840,"meta":2197},{"image":2198,"title":1867,"description":1868},{"url":417},{},{"id":847,"data":2201,"type":808,"tunes":2204},{"link":849,"meta":2202},{"image":2203,"title":1874,"description":1875},{"url":417},{},{"id":856,"data":2206,"type":808,"tunes":2209},{"link":858,"meta":2207},{"image":2208,"title":1881,"description":1882},{"url":417},{},{"id":865,"data":2211,"type":808,"tunes":2214},{"link":867,"meta":2212},{"image":2213,"title":1888,"description":1889},{"url":417},{},{"id":874,"data":2216,"type":808,"tunes":2219},{"link":876,"meta":2217},{"image":2218,"title":1895,"description":1896},{"url":417},{},"2.31.6","Migrating from the OpenAI Agents SDK to the new Agents API is not an import rename. The runtime boundary changes: the agent loop, durable session, orchestration, context compaction and recovery move toward a managed harness. This guide shows what should move, what should stay in your application, and how to prove the migration before cutover.",{"lang":7,"title":208,"content":210,"contentJson":2223,"excerpt":1310},{"time":212,"blocks":2224,"version":1309},[2225,2228,2231,2234,2237,2240,2243,2246,2249,2252,2255,2271,2274,2277,2280,2283,2286,2289,2300,2303,2306,2309,2325,2328,2331,2334,2337,2340,2343,2346,2349,2352,2355,2365,2368,2371,2374,2377,2380,2383,2386,2389,2392,2395,2398,2410,2413,2427,2430,2433,2438,2441,2444,2447,2450,2453,2456,2459,2462,2465,2468,2471,2474,2477,2486,2489,2499,2502,2507,2512,2517,2522,2527,2532,2537,2542,2547,2550,2553,2556,2559,2562,2565,2568,2571,2574,2577,2593,2596,2599,2602,2605,2608,2611,2622,2625,2628,2631,2647,2650,2653,2656,2659,2662,2665,2668,2671,2674,2677,2687,2690,2693,2696,2699,2702,2705,2708,2711,2714,2717,2720,2732,2735,2749,2752,2755,2760,2763,2766,2769,2772,2775,2778,2781,2784,2787,2790,2793,2796,2799,2808,2811,2821,2824,2829,2834,2839,2844,2849,2854,2859,2864],{"id":215,"data":2226,"type":220,"tunes":2227},{"title":217,"maxLevel":218,"minLevel":219},{},{"id":223,"data":2229,"type":226,"tunes":2230},{"text":225},{},{"id":229,"data":2232,"type":234,"tunes":2233},{"body":231,"title":232,"variant":233},{},{"id":237,"data":2235,"type":234,"tunes":2236},{"body":239,"title":240,"variant":241},{},{"id":244,"data":2238,"type":234,"tunes":2239},{"body":246,"title":247,"variant":248},{},{"id":251,"data":2241,"type":42,"tunes":2242},{"text":253,"level":219},{},{"id":256,"data":2244,"type":226,"tunes":2245},{"text":258},{},{"id":261,"data":2247,"type":226,"tunes":2248},{"text":263},{},{"id":266,"data":2250,"type":226,"tunes":2251},{"text":268},{},{"id":271,"data":2253,"type":42,"tunes":2254},{"text":273,"level":219},{},{"id":276,"data":2256,"type":327,"tunes":2270},{"content":2257,"stretched":43,"withHeadings":14},[2258,2259,2260,2261,2262,2263,2264,2265,2266,2267,2268,2269],[280,281,282],[284,285,286],[288,289,290],[292,293,294],[296,297,298],[300,301,302],[304,305,306],[308,309,310],[312,313,314],[316,317,318],[320,321,322],[324,325,326],{},{"id":330,"data":2272,"type":42,"tunes":2273},{"text":332,"level":219},{},{"id":335,"data":2275,"type":226,"tunes":2276},{"text":337},{},{"id":340,"data":2278,"type":226,"tunes":2279},{"text":342},{},{"id":345,"data":2281,"type":234,"tunes":2282},{"body":347,"title":348,"variant":349},{},{"id":352,"data":2284,"type":42,"tunes":2285},{"text":354,"level":219},{},{"id":357,"data":2287,"type":226,"tunes":2288},{"text":359},{},{"id":362,"data":2290,"type":327,"tunes":2299},{"content":2291,"stretched":43,"withHeadings":14},[2292,2293,2294,2295,2296,2297,2298],[366,367,368],[370,371,372],[374,375,376],[378,379,380],[382,383,384],[386,387,388],[390,391,392],{},{"id":395,"data":2301,"type":42,"tunes":2302},{"text":397,"level":219},{},{"id":400,"data":2304,"type":226,"tunes":2305},{"text":402},{},{"id":405,"data":2307,"type":226,"tunes":2308},{"text":407},{},{"id":410,"data":2310,"type":441,"tunes":2324},{"rows":2311,"title":430,"layout":327,"columns":2320},[2312,2314,2316,2318],{"id":414,"label":415,"values":2313},[417,417,417],{"id":419,"label":420,"values":2315},[417,417,417],{"id":423,"label":424,"values":2317},[417,417,417],{"id":427,"label":428,"values":2319},[417,417,417],[2321,2322,2323],{"id":433,"label":434},{"id":436,"label":437},{"id":439,"label":440},{},{"id":444,"data":2326,"type":42,"tunes":2327},{"text":446,"level":219},{},{"id":449,"data":2329,"type":226,"tunes":2330},{"text":451},{},{"id":454,"data":2332,"type":226,"tunes":2333},{"text":456},{},{"id":459,"data":2335,"type":42,"tunes":2336},{"text":461,"level":219},{},{"id":464,"data":2338,"type":226,"tunes":2339},{"text":466},{},{"id":469,"data":2341,"type":226,"tunes":2342},{"text":471},{},{"id":474,"data":2344,"type":234,"tunes":2345},{"body":476,"title":477,"variant":241},{},{"id":480,"data":2347,"type":42,"tunes":2348},{"text":482,"level":219},{},{"id":485,"data":2350,"type":226,"tunes":2351},{"text":487},{},{"id":490,"data":2353,"type":226,"tunes":2354},{"text":492},{},{"id":495,"data":2356,"type":327,"tunes":2364},{"content":2357,"stretched":43,"withHeadings":14},[2358,2359,2360,2361,2362,2363],[499,500],[502,503],[505,506],[508,509],[511,512],[514,515],{},{"id":518,"data":2366,"type":42,"tunes":2367},{"text":520,"level":219},{},{"id":523,"data":2369,"type":226,"tunes":2370},{"text":525},{},{"id":528,"data":2372,"type":226,"tunes":2373},{"text":530},{},{"id":533,"data":2375,"type":42,"tunes":2376},{"text":535,"level":219},{},{"id":538,"data":2378,"type":226,"tunes":2379},{"text":540},{},{"id":543,"data":2381,"type":226,"tunes":2382},{"text":545},{},{"id":548,"data":2384,"type":554,"tunes":2385},{"url":550,"title":551,"excerpt":552,"ctaLabel":553},{},{"id":557,"data":2387,"type":42,"tunes":2388},{"text":559,"level":219},{},{"id":562,"data":2390,"type":226,"tunes":2391},{"text":564},{},{"id":567,"data":2393,"type":226,"tunes":2394},{"text":569},{},{"id":572,"data":2396,"type":42,"tunes":2397},{"text":574,"level":219},{},{"id":577,"data":2399,"type":606,"tunes":2409},{"steps":2400,"title":604,"orientation":605},[2401,2402,2403,2404,2405,2406,2407,2408],{"label":581,"description":582},{"label":584,"description":585},{"label":587,"description":588},{"label":590,"description":591},{"label":593,"description":594},{"label":596,"description":597},{"label":599,"description":600},{"label":602,"description":603},{},{"id":609,"data":2411,"type":42,"tunes":2412},{"text":611,"level":219},{},{"id":614,"data":2414,"type":327,"tunes":2426},{"content":2415,"stretched":43,"withHeadings":14},[2416,2417,2418,2419,2420,2421,2422,2423,2424,2425],[618,619],[621,622],[624,625],[627,628],[324,630],[632,633],[635,636],[638,639],[641,642],[644,645],{},{"id":648,"data":2428,"type":42,"tunes":2429},{"text":650,"level":219},{},{"id":653,"data":2431,"type":226,"tunes":2432},{"text":655},{},{"id":658,"data":2434,"type":669,"tunes":2437},{"meta":2435,"items":2436,"style":668},{},[662,663,664,665,666,667],{},{"id":672,"data":2439,"type":42,"tunes":2440},{"text":674,"level":219},{},{"id":677,"data":2442,"type":226,"tunes":2443},{"text":679},{},{"id":682,"data":2445,"type":226,"tunes":2446},{"text":684},{},{"id":687,"data":2448,"type":42,"tunes":2449},{"text":689,"level":219},{},{"id":692,"data":2451,"type":226,"tunes":2452},{"text":694},{},{"id":697,"data":2454,"type":226,"tunes":2455},{"text":699},{},{"id":702,"data":2457,"type":42,"tunes":2458},{"text":704,"level":219},{},{"id":707,"data":2460,"type":226,"tunes":2461},{"text":709},{},{"id":712,"data":2463,"type":226,"tunes":2464},{"text":714},{},{"id":717,"data":2466,"type":42,"tunes":2467},{"text":719,"level":219},{},{"id":722,"data":2469,"type":226,"tunes":2470},{"text":724},{},{"id":727,"data":2472,"type":226,"tunes":2473},{"text":729},{},{"id":732,"data":2475,"type":42,"tunes":2476},{"text":734,"level":219},{},{"id":737,"data":2478,"type":737,"tunes":2485},{"items":2479,"title":760},[2480,2481,2482,2483,2484],{"id":741,"answer":742,"question":743},{"id":745,"answer":746,"question":747},{"id":749,"answer":750,"question":751},{"id":753,"answer":754,"question":755},{"id":757,"answer":758,"question":759},{},{"id":763,"data":2487,"type":42,"tunes":2488},{"text":765,"level":219},{},{"id":768,"data":2490,"type":768,"tunes":2498},{"title":770,"entries":2491},[2492,2493,2494,2495,2496,2497],{"term":773,"anchor":774,"definition":775},{"term":777,"anchor":778,"definition":779},{"term":781,"anchor":782,"definition":783},{"term":785,"anchor":786,"definition":787},{"term":509,"anchor":789,"definition":790},{"term":574,"anchor":792,"definition":793},{},{"id":796,"data":2500,"type":42,"tunes":2501},{"text":798,"level":219},{},{"id":801,"data":2503,"type":808,"tunes":2506},{"link":803,"meta":2504},{"image":2505,"title":806,"description":807},{"url":417},{},{"id":811,"data":2508,"type":808,"tunes":2511},{"link":813,"meta":2509},{"image":2510,"title":816,"description":817},{"url":417},{},{"id":820,"data":2513,"type":808,"tunes":2516},{"link":822,"meta":2514},{"image":2515,"title":825,"description":826},{"url":417},{},{"id":829,"data":2518,"type":808,"tunes":2521},{"link":831,"meta":2519},{"image":2520,"title":834,"description":835},{"url":417},{},{"id":838,"data":2523,"type":808,"tunes":2526},{"link":840,"meta":2524},{"image":2525,"title":843,"description":844},{"url":417},{},{"id":847,"data":2528,"type":808,"tunes":2531},{"link":849,"meta":2529},{"image":2530,"title":852,"description":853},{"url":417},{},{"id":856,"data":2533,"type":808,"tunes":2536},{"link":858,"meta":2534},{"image":2535,"title":861,"description":862},{"url":417},{},{"id":865,"data":2538,"type":808,"tunes":2541},{"link":867,"meta":2539},{"image":2540,"title":870,"description":871},{"url":417},{},{"id":874,"data":2543,"type":808,"tunes":2546},{"link":876,"meta":2544},{"image":2545,"title":879,"description":880},{"url":417},{},{"id":223,"data":2548,"type":226,"tunes":2549},{"text":884},{},{"id":229,"data":2551,"type":234,"tunes":2552},{"body":888,"title":232,"variant":233},{},{"id":237,"data":2554,"type":234,"tunes":2555},{"body":892,"title":240,"variant":241},{},{"id":244,"data":2557,"type":234,"tunes":2558},{"body":896,"title":247,"variant":248},{},{"id":899,"data":2560,"type":220,"tunes":2561},{"title":217,"maxLevel":218,"minLevel":219},{},{"id":251,"data":2563,"type":42,"tunes":2564},{"text":253,"level":219},{},{"id":256,"data":2566,"type":226,"tunes":2567},{"text":907},{},{"id":261,"data":2569,"type":226,"tunes":2570},{"text":911},{},{"id":266,"data":2572,"type":226,"tunes":2573},{"text":268},{},{"id":271,"data":2575,"type":42,"tunes":2576},{"text":273,"level":219},{},{"id":276,"data":2578,"type":327,"tunes":2592},{"content":2579,"stretched":43,"withHeadings":14},[2580,2581,2582,2583,2584,2585,2586,2587,2588,2589,2590,2591],[280,281,282],[924,925,286],[927,289,928],[292,293,294],[296,931,932],[300,934,935],[304,305,937],[308,939,310],[312,313,314],[316,317,942],[320,321,944],[324,325,946],{},{"id":330,"data":2594,"type":42,"tunes":2595},{"text":950,"level":219},{},{"id":335,"data":2597,"type":226,"tunes":2598},{"text":954},{},{"id":340,"data":2600,"type":226,"tunes":2601},{"text":958},{},{"id":345,"data":2603,"type":234,"tunes":2604},{"body":962,"title":963,"variant":349},{},{"id":352,"data":2606,"type":42,"tunes":2607},{"text":354,"level":219},{},{"id":357,"data":2609,"type":226,"tunes":2610},{"text":970},{},{"id":362,"data":2612,"type":327,"tunes":2621},{"content":2613,"stretched":43,"withHeadings":14},[2614,2615,2616,2617,2618,2619,2620],[366,367,368],[977,371,978],[980,375,376],[378,982,983],[382,985,384],[987,387,988],[990,391,392],{},{"id":395,"data":2623,"type":42,"tunes":2624},{"text":994,"level":219},{},{"id":400,"data":2626,"type":226,"tunes":2627},{"text":998},{},{"id":405,"data":2629,"type":226,"tunes":2630},{"text":1002},{},{"id":410,"data":2632,"type":441,"tunes":2646},{"rows":2633,"title":430,"layout":327,"columns":2642},[2634,2636,2638,2640],{"id":414,"label":415,"values":2635},[417,417,417],{"id":419,"label":420,"values":2637},[417,417,417],{"id":423,"label":424,"values":2639},[417,417,417],{"id":427,"label":428,"values":2641},[417,417,417],[2643,2644,2645],{"id":433,"label":434},{"id":436,"label":437},{"id":439,"label":440},{},{"id":444,"data":2648,"type":42,"tunes":2649},{"text":1022,"level":219},{},{"id":449,"data":2651,"type":226,"tunes":2652},{"text":1026},{},{"id":454,"data":2654,"type":226,"tunes":2655},{"text":1030},{},{"id":459,"data":2657,"type":42,"tunes":2658},{"text":1034,"level":219},{},{"id":464,"data":2660,"type":226,"tunes":2661},{"text":1038},{},{"id":469,"data":2663,"type":226,"tunes":2664},{"text":1042},{},{"id":474,"data":2666,"type":234,"tunes":2667},{"body":1046,"title":477,"variant":241},{},{"id":480,"data":2669,"type":42,"tunes":2670},{"text":1050,"level":219},{},{"id":485,"data":2672,"type":226,"tunes":2673},{"text":1054},{},{"id":490,"data":2675,"type":226,"tunes":2676},{"text":1058},{},{"id":495,"data":2678,"type":327,"tunes":2686},{"content":2679,"stretched":43,"withHeadings":14},[2680,2681,2682,2683,2684,2685],[499,500],[1065,1066],[505,506],[1069,509],[1071,1072],[1074,1075],{},{"id":518,"data":2688,"type":42,"tunes":2689},{"text":1079,"level":219},{},{"id":523,"data":2691,"type":226,"tunes":2692},{"text":1083},{},{"id":528,"data":2694,"type":226,"tunes":2695},{"text":1087},{},{"id":533,"data":2697,"type":42,"tunes":2698},{"text":1091,"level":219},{},{"id":538,"data":2700,"type":226,"tunes":2701},{"text":1095},{},{"id":543,"data":2703,"type":226,"tunes":2704},{"text":1099},{},{"id":548,"data":2706,"type":554,"tunes":2707},{"url":550,"title":551,"excerpt":552,"ctaLabel":553},{},{"id":557,"data":2709,"type":42,"tunes":2710},{"text":1106,"level":219},{},{"id":562,"data":2712,"type":226,"tunes":2713},{"text":1110},{},{"id":567,"data":2715,"type":226,"tunes":2716},{"text":1114},{},{"id":572,"data":2718,"type":42,"tunes":2719},{"text":574,"level":219},{},{"id":577,"data":2721,"type":606,"tunes":2731},{"steps":2722,"title":604,"orientation":605},[2723,2724,2725,2726,2727,2728,2729,2730],{"label":581,"description":1123},{"label":1125,"description":1126},{"label":587,"description":1128},{"label":590,"description":591},{"label":593,"description":1131},{"label":596,"description":597},{"label":599,"description":600},{"label":602,"description":1135},{},{"id":609,"data":2733,"type":42,"tunes":2734},{"text":1139,"level":219},{},{"id":614,"data":2736,"type":327,"tunes":2748},{"content":2737,"stretched":43,"withHeadings":14},[2738,2739,2740,2741,2742,2743,2744,2745,2746,2747],[618,619],[621,622],[624,625],[627,1148],[324,1150],[632,1152],[635,1154],[638,639],[641,1157],[644,1159],{},{"id":648,"data":2750,"type":42,"tunes":2751},{"text":1163,"level":219},{},{"id":653,"data":2753,"type":226,"tunes":2754},{"text":1167},{},{"id":658,"data":2756,"type":669,"tunes":2759},{"meta":2757,"items":2758,"style":668},{},[662,663,1173,1174,666,667],{},{"id":672,"data":2761,"type":42,"tunes":2762},{"text":1178,"level":219},{},{"id":677,"data":2764,"type":226,"tunes":2765},{"text":1182},{},{"id":682,"data":2767,"type":226,"tunes":2768},{"text":1186},{},{"id":687,"data":2770,"type":42,"tunes":2771},{"text":1190,"level":219},{},{"id":692,"data":2773,"type":226,"tunes":2774},{"text":1194},{},{"id":697,"data":2776,"type":226,"tunes":2777},{"text":1198},{},{"id":702,"data":2779,"type":42,"tunes":2780},{"text":704,"level":219},{},{"id":707,"data":2782,"type":226,"tunes":2783},{"text":1205},{},{"id":712,"data":2785,"type":226,"tunes":2786},{"text":714},{},{"id":717,"data":2788,"type":42,"tunes":2789},{"text":719,"level":219},{},{"id":722,"data":2791,"type":226,"tunes":2792},{"text":1215},{},{"id":727,"data":2794,"type":226,"tunes":2795},{"text":1219},{},{"id":732,"data":2797,"type":42,"tunes":2798},{"text":734,"level":219},{},{"id":737,"data":2800,"type":737,"tunes":2807},{"items":2801,"title":760},[2802,2803,2804,2805,2806],{"id":741,"answer":1228,"question":1229},{"id":745,"answer":1231,"question":747},{"id":749,"answer":750,"question":1233},{"id":753,"answer":1235,"question":755},{"id":757,"answer":1237,"question":1238},{},{"id":763,"data":2809,"type":42,"tunes":2810},{"text":765,"level":219},{},{"id":768,"data":2812,"type":768,"tunes":2820},{"title":770,"entries":2813},[2814,2815,2816,2817,2818,2819],{"term":773,"anchor":774,"definition":1247},{"term":777,"anchor":778,"definition":779},{"term":781,"anchor":782,"definition":1250},{"term":785,"anchor":786,"definition":787},{"term":509,"anchor":789,"definition":790},{"term":574,"anchor":792,"definition":793},{},{"id":796,"data":2822,"type":42,"tunes":2823},{"text":798,"level":219},{},{"id":801,"data":2825,"type":808,"tunes":2828},{"link":803,"meta":2826},{"image":2827,"title":806,"description":1262},{"url":417},{},{"id":811,"data":2830,"type":808,"tunes":2833},{"link":813,"meta":2831},{"image":2832,"title":816,"description":1268},{"url":417},{},{"id":820,"data":2835,"type":808,"tunes":2838},{"link":822,"meta":2836},{"image":2837,"title":825,"description":1274},{"url":417},{},{"id":829,"data":2840,"type":808,"tunes":2843},{"link":831,"meta":2841},{"image":2842,"title":834,"description":835},{"url":417},{},{"id":838,"data":2845,"type":808,"tunes":2848},{"link":840,"meta":2846},{"image":2847,"title":843,"description":844},{"url":417},{},{"id":847,"data":2850,"type":808,"tunes":2853},{"link":849,"meta":2851},{"image":2852,"title":1290,"description":853},{"url":417},{},{"id":856,"data":2855,"type":808,"tunes":2858},{"link":858,"meta":2856},{"image":2857,"title":861,"description":1296},{"url":417},{},{"id":865,"data":2860,"type":808,"tunes":2863},{"link":867,"meta":2861},{"image":2862,"title":870,"description":871},{"url":417},{},{"id":874,"data":2865,"type":808,"tunes":2868},{"link":876,"meta":2866},{"image":2867,"title":879,"description":1307},{"url":417},{},"Post erfolgreich abgerufen",{"items":2871,"source":2893,"manualIds":2894,"manualMatchedIds":2895},[2872,2879,2886],{"id":2873,"slug":2874,"title":2875,"excerpt":2876,"featuredImage":2877,"publishedAt":2878},"451","test-dev-enterprise","Test DEv Enterprise Stajic.de 全面指南：架构与最佳实践","探索使用 Test DEv Enterprise Stajic.de 管理企业级开发和测试环境的架构原则、优势及技术细节。","\u002Fuploads\u002F2026\u002F05\u002Ftest-dev-enterprise-1779534260081-r4dvxn.webp","2026-05-22T23:01:00.000Z",{"id":2880,"slug":2881,"title":2882,"excerpt":2883,"featuredImage":2884,"publishedAt":2885},"457","should-you-buy-5g-openwrt-router-old-firmware","你应该购买带有旧固件的5G OpenWrt路由器吗？以ZBT Z8102AX为例","购买搭载旧版固件的5G OpenWrt路由器在特定条件下是合理的。ZBT Z8102AX型号清晰展现了利弊两面：硬件实用、调制解调器工作正常，测试中路由器保持稳定，但OpenWrt 21.02版本、简陋的包装以及不明确的升级路径，要求消费者在购买时需审慎决策。","\u002Fuploads\u002F2026\u002F06\u002Fopenwrt-router-review-dual-sim-05-1781620596218-5ldld4.webp","2026-06-16T10:41:00.000Z",{"id":2887,"slug":2888,"title":2889,"excerpt":2890,"featuredImage":2891,"publishedAt":2892},"477","computer-use-agents-why-a-successful-demo-can-still-be-an-unreliable-system","计算机使用代理：为什么成功的演示仍可能是一个不可靠的系统","计算机使用代理如今能够完成令人印象深刻的浏览器和桌面工作流程，但一次成功的运行证明的是能力——而非可靠性。本文展示了如何测试可重复性、环境鲁棒性、长时程控制、状态感知、结果验证以及安全的目标处理。","\u002Fuploads\u002F2026\u002F09\u002Fcomputer-use-agents-why-a-successful-demo-can-still-be-an-unreliable-system-1790352854690-75qnrg.webp","2026-09-25T12:13:00.000Z","fallback",[],[]]