【2026 最新】OpenAI Agents API 實戰：斷線續跑、取消與復原 7 步教學

你把一個研究任務送進 API，終端機才跑到一半，Wi-Fi 就斷了。重新連線後，最危險的做法不是「什麼都不做」，而是立刻把同一個任務再送一次：第一個 Agent 可能仍在雲端執行，第二個任務又重複寄信、寫檔或呼叫外部服務。OpenAI Agents API 真正要解的，就是這種長任務的生命週期，而不只是再多一個聊天端點。

這篇會用 Python 建立一個 OpenAI-hosted session、故意中斷 client stream，再用 session 與 saved items 接回工作；接著驗收取消、失敗與 artifact。你也會看懂 Agents API、Responses API 與開源 Agents SDK 到底誰代管哪一層，最後能自己決定 hosted 或 self-hosted environment。

先說清楚證據邊界：Agents API 在 2026 年 9 月 10 日進入 public beta；本文依 2026 年 9 月 12 日可見的官方文件與 Python SDK 介面撰寫。AlphaLab 的出版環境沒有獲授權的 Agents API key，因此下方命令已逐項對照官方文件並做靜態檢查，但沒有宣稱完成付費端到端執行。Beta 的模型名稱、事件 schema、價格與限制都可能再變；實作時請以連結中的即時文件為準。

先說結論：可續跑，不等於 event 可以重播

OpenAI Agents API ＝ OpenAI 代管的 Codex harness ＋ 持久 session ＋ 可選執行環境；斷線復原 ＝ 重新訂閱 live events ＋ 回查 saved items，而不是把舊 stream 倒帶。

• 關掉 stream 不會取消 turn：client 不再看直播，不代表雲端工作停止。
• 漏掉的 event 不會補播：完成的訊息與工具呼叫可從 items 回查，但每個中間 delta 未必找得回來。
• turn completed 不等於工具全成功：還要檢查工具結果、最終輸出與預期 artifact。
• self-hosted 不是整套 Agents API 搬回家：你只自管 sandbox／compute，Codex harness 與 session 仍由 OpenAI 服務承載。

OpenAI Agents API 是什麼？先分清四個物件

官方把系統拆成 Agent、Environment、Session、Events／Items。若你讀過 AI Agent Harness 是什麼，可以把 harness 想成「一直幫模型安排工具、上下文與停止條件的領班」；Agents API 則把這位領班連同工作紀錄做成受管雲端服務。

Agent：腦、規則與能力清單

Agent 包含模型、instructions、tools 與 MCP servers。它描述「這位員工會什麼、該怎麼做」，不是正在執行的那一份工作。你仍要設計工具 schema、授權範圍與錯誤回傳；可先用 Code-Implemented Tool Calls 的方法，把輸入驗證與副作用分開。

Session：可延續的工作單

Session 保存 Agent 設定、對話與已保存工作。每次從 idle session 傳入訊息，會開始一個新 turn；工作進行中再傳訊息，則是 steer（中途修正）目前 turn。OpenAI 管理 session、orchestration、context compaction 與 recovery，但你的應用仍要持久保存 session_id，並把它綁定到正確使用者與權限。

Environment：Agent 真正動手的工作室

Environment 可以是 OpenAI-hosted sandbox、你提供的 self-hosted sandbox，或 none。沒有 environment 時仍可用 remote MCP 與 application function tools，但沒有內建 workspace、Bash、apply patch 或 executor。選 self-hosted 時，你負責 provision、連線、檔案與關機；OpenAI 仍執行受管 Codex harness。

Events 與 Items：直播和帳本不能混為一談

Events 是即時狀態變化，每個 event 有自己的 event_id；文字 delta 會以 item_id、output_index、content_index 對回同一段輸出。Items 則是之後可查的 saved messages、tool calls 與 completed responses。白話說，events 像球賽直播，items 像賽後紀錄：後者能告訴你結果，不能保證還原每一秒畫面。

Agents API、Agents SDK、Responses API 怎麼選？

OpenAI 官方 runtime 對照的核心不是功能打勾數，而是「誰擁有 loop 與 state」。

• 選 Agents API：長任務需要受管 Codex harness、持久 session、compaction、subagents 與可回查 items；你願意接受服務端狀態與平台邊界。
• 選 Agents SDK：你想在自己的 application process 裡控制 agent loop、handoffs、guardrails、storage 與 deployment。SDK 預設可用 Responses API 呼叫 OpenAI 模型，但 runner 在你的程式裡運作。
• 選 Responses API：你要直接呼叫模型、使用 hosted tools，或自己打造 loop；conversation state、background mode 與 chaining 可以組合，但不等於 Agents API 的受管 Codex harness。

因此「三者都能接工具」不是好選法。問自己：程序重啟後，誰負責知道做到哪裡？誰重建上下文？誰維護 sandbox？誰處理待回傳的 function result？如果答案希望大多交給 OpenAI，Agents API 才是候選；若法遵、資料位置或客製 loop 要牢牢掌握，就從 SDK 或 Responses API 開始。想先理解三層 stack，也可搭配 Agent stack production 架構閱讀。

動手前準備：權限、SDK 與一條安全規則

這份教學採用 Python 3.10 以上與官方 openai 套件。先在 OpenAI Platform 建立 application API key，授予 api.agents.read、api.agents.write 與 api.responses.write。官方目前要求 Agents API request 帶 OpenAI-Beta: agents=v1；SDK 會自動加，只有直接用 cURL 時要自己寫。

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade openai
export OPENAI_API_KEY="你的 application API key"

不要把 application API key 放進 sandbox。官方 sandbox security 指南說明 Agent 產生的程式可讀取環境裡的檔案、credential 與 network；self-hosted executor 應使用只准連接環境的 CODEX_API_KEY，第三方長效憑證最好留在外部 broker／secret manager。若你的 project 看不到文件範例中的模型，請改成該 project 可用且 Agents API 支援的模型，不要猜一個名稱。

步驟 1：建立會產生 artifact 的最小 session

痛點：只問一句話通常太快結束，無法觀察中斷與復原。解法：建立 OpenAI-hosted environment，要求 Agent 建檔、執行檢查，再把摘要寫進 /workspace/outputs。把下面存成 start_agent.py；模型值採用 2026 年 9 月 12 日官方 quickstart 的 gpt-6-astra 範例。

from openai import OpenAI

TASK = """
Create a small Python project with three files.
Run syntax checks, list the resulting tree, and explain any failure.
Write the final checklist to /workspace/outputs/recovery-report.md.
"""

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": (
                "Work carefully. Run checks and report actual results. "
                "Do not claim success when a command failed."
            ),
        },
        environment={
            "type": "openai_hosted",
            "network": {"access": "disabled"},
        },
        input=TASK,
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

執行 python start_agent.py | tee first-run.ndjson。從 session 事件保存 session_id 到你的應用資料庫；在這個命令列練習裡，可先從輸出的 session JSON 複製它。看到 session ID 後按 Ctrl-C，刻意關掉本地 stream。這一步只製造「觀測端斷線」，不等於要求 Agent 停止。

為什麼先關 network？本例只需本地建檔與 Python 檢查，沒有理由讓 sandbox 對外連線。正式任務若要下載依賴，應用 restricted allowlist 只開精確 host；不要把「方便」當成預設安全策略。

步驟 2：重新訂閱 session，再抓 saved items

痛點：重連後只打開新 stream，會漏掉斷線期間已發生的事；只先抓 snapshot，又可能漏掉 snapshot 查詢期間的新事件。解法：遵守官方 events recovery 順序：先開新 stream 並緩衝、在連線保持時 retrieve session 與 items、以 item_id 重建本地狀態、合併緩衝更新，再接回 live handler。

先設定剛才保存的 ID，將下方存成 recover_agent.py。這是便於觀察的單程序版本：進入 stream context 後才取 snapshot，並把 snapshot 與後續事件都印出。正式 UI 應另開 consumer，把 snapshot 查詢期間收到的 events 放進 queue，再依 item_id 合併。

import os
from openai import OpenAI

session_id = os.environ["SESSION_ID"]
client = OpenAI()

with client.beta.agents.sessions.events.stream(session_id) as events:
    session = client.beta.agents.sessions.retrieve(session_id)
    items = client.beta.agents.sessions.items.list(
        session_id, order="asc", limit=100
    )

    print("SESSION", session.to_json(indent=None))
    for item in items.data:
        print("SAVED_ITEM", item.to_json(indent=None))

    for event in events:
        print("LIVE_EVENT", event.to_json(indent=None), flush=True)
        if event.type in {
            "agent.session.turn.completed",
            "agent.session.turn.failed",
            "agent.session.turn.cancelled",
        } and event.turn.subagent_id is None:
            break

export SESSION_ID="sess_請換成你的值"
python recover_agent.py

驗收時不要只找 agent.session.idle。根 turn 必須出現 agent.session.turn.completed、failed 或 cancelled；即使 completed，也要打開最後的 saved response、檢查每個工具結果，並確認 artifact 存在。這與 Coding Agent 測試驗證的原則相同：流程終止只是訊號，oracle（判定對錯的尺）才是驗收。

步驟 3：下載 artifact，證明成果不只活在對話裡

依官方 files and artifacts 指南，在 OpenAI-hosted environment 裡，/workspace/outputs 下的檔案會在 turn 完成時發布成 immutable artifact。它在 environment 過期後仍可下載；刪除 session 前，仍應把要長期保存的檔案搬到自己的 storage。Self-hosted environment 的檔案不會經由這套 Artifacts API 發布，要用自己的 provider file API 或 mounted filesystem 取回。

def download_report(client, session_id, turn_id, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if (
            artifact.turn_id == turn_id
            and artifact.path == "/workspace/outputs/recovery-report.md"
        ):
            response_api = (
                client.beta.agents.sessions.artifacts
                .with_streaming_response.content
            )
            with response_api(artifact.id, session_id=session_id) as response:
                response.stream_to_file(destination)
            return
    raise FileNotFoundError("recovery-report.md was not published")

可觀察結果：下載成功、檔案可讀、內容包含實際檢查結果，三者才一起算通過。Artifact 是 completed turn 的發布副本，不是持續同步磁碟；同一路徑的新版本要以 turn ID 區分。

步驟 4：取消 active turn，不要用斷線冒充取消

痛點：關閉瀏覽器、HTTP stream 或 terminal，只會讓觀測者離場。解法：對同一 session 傳入明確的 agent.session.input.cancel，再等 root turn 的 cancelled 終態。把下面存成 cancel_agent.py：

import os
from openai import OpenAI

session_id = os.environ["SESSION_ID"]
client = OpenAI()
client.beta.agents.sessions.events.create(
    session_id,
    events=[{"type": "agent.session.input.cancel"}],
)
print("cancel requested", session_id)

Session 與先前工作仍可查；cancelled 也不表示外部副作用自動回滾。若工具可能寄信、扣款、建 ticket 或修改資料，工具端必須支援狀態查詢、自己的 idempotency key 與補償動作。截至 2026 年 9 月 12 日，官方 input event reference只明載 idempotency_key 接受 1–256 字元，未定義保存窗口、跨 request 範圍或外部工具 exactly-once 語意；不要把它延伸成業務副作用保證。

步驟 5：失敗復原，先查結果再決定要不要重送

痛點：網路 timeout 只代表 client 沒拿到答案，不代表 server 沒收到工作。解法：以 session_id retrieve session、items 與 turns，先判斷原 turn 是 waiting、failed、cancelled 或 completed，再決定下一步。

1. 看到 requires_action：讀取 required_actions；它可能在等 application function result，或等 self-hosted environment connection。處理後繼續追蹤原 turn，不要另開一份重複工作。
2. 看到 turn failed：保存 turn.error、工具輸出與 items；修正可恢復原因後，以新訊息開始新的 turn，並在自己的 job ledger 記錄它取代哪一個失敗 turn。
3. client timeout、結果未知：先查原 session outcome。官方對 self-hosted lifecycle 特別提醒，不要在原 request 仍等待時重送；晚到的 environment connection 也不會重播已 timeout 的 input。
4. turn completed：先驗收輸出和副作用。缺 artifact 或工具回報 error，就不能因 completed 標籤自動宣告成功。

你可以為應用另建一張最小 ledger：app_job_id、session_id、turn_id、預期 artifact、外部副作用 key、最後已知狀態與人工處置。Agents API 幫你保存 agent-side state，卻不會知道「同一張訂單只能寄一次」這種業務不變量。想把 log、trace 與回歸測試接起來，可延伸閱讀 Agent Observability。

步驟 6：Hosted vs self-hosted，真正的決策邊界

選 OpenAI-hosted：先用最少維運驗證產品

• OpenAI provision 與管理 Linux sandbox，工作目錄是 /workspace。
• 可設定 packages、setup commands、files、env、skills、plugins、templates 與 network policy。
• /workspace/outputs 可發布成 artifact；適合 coding、research 與可攜的批次成果。
• 成本除了模型 token 與工具費，也包含 hosted container；請用官方即時 pricing估算，不把 beta 期間的單價寫死進商業模型。

選 self-hosted：你需要自己的 compute 與檔案控制面

• 適合既有 VPC、GPU、內部套件、客製 snapshot 或特定 sandbox provider。
• 你負責 environment lifecycle、executor、重新連線、持久檔案與 shutdown。
• 中途斷線可能讓某個 tool 失敗，即使 turn 最後 completed；斷線不會自動透過 webhook 要求重連，也不會重啟被殺掉的 command。
• 換一台 compute 後重用 environment ID，不會自動還原檔案；要靠自己的 storage 或 snapshot。

最容易誤判的是資料邊界。截至 2026 年 9 月 12 日，官方 Agents API overview明載 session state 會保留，Agents API 目前只支援美國 data residency，且不支援 Zero Data Retention；選 self-hosted sandbox 也不會讓 Agents API 變成 ZDR eligible。若這與你的政策衝突，應在 POC 前就停下來，不要以「compute 在我方」自行推論整條資料路徑都在我方。

步驟 7：把「能跑」改成四組故障驗收

最後不要做一次 happy path 就上線。把同一份 task 固定成 regression fixture，至少跑四組：

1. 正常完成：root turn completed、工具輸出無錯、artifact 可下載且內容符合 checklist。
2. stream 中斷：保存 session ID 後關閉 client；重連先訂閱再 snapshot，最終 UI 不重複 item，也不把 idle 當成功。
3. 明確取消：送 cancel event；root turn 進 cancelled，先前 items 仍可查，外部副作用另行核對。
4. 環境／工具失敗：刻意讓 setup command、function result 或 self-hosted connection 失敗；應用顯示具體 error、保留 ledger，且在 outcome 未知時不盲目重送。

再加兩條不變量會更接近 production：同一 item_id 的 done event 要取代暫存 delta，而不是再 append 一次；subagent 的 completed event 不能讓 root session 提前收工。這些狀態測試比比較一張模型榜更直接，因為它們回答「系統出錯時會不會做兩次」。若要擴充成通用 harness，可接著做 30 行 Agent Harness，再用 MCP 設定曝險盤點檢查工具面。

上線前最常踩的 6 個坑

1. 把 stream 當工作本體：直播斷了不代表球賽停了。取消必須送明確 event。
2. 只保存最後一段文字：至少保存 session、turn、item 與 application job 的對照，才能處理重連與人工調查。
3. 把 completed 當全綠：工具可能失敗或輸出缺檔；成功條件要由你的 oracle 定義。
4. 把 API key 塞進 workspace：Agent-generated code 能讀 environment；application key 留在外面，第三方 secret 走 broker。
5. self-hosted 卻沒有 snapshot：environment ID 不是磁碟備份，replacement compute 不會憑空長回檔案。
6. 沒有退出策略：定期把必要 artifact、業務 ledger 與評測資料存回自家系統；否則 session schema、受管 harness 與平台工具會形成實際 switching cost。

OpenAI Agents API 常見問題 FAQ

1. Agents API 和 OpenAI Agents SDK 是同一個東西嗎？

不是。Agents API 是 OpenAI 代管 Codex harness 與 session 的 beta 服務；Agents SDK 是在你的 application runtime 中執行 agent loop 的開源 SDK。兩者可以共享一些工具與概念，但 state ownership 不同。

2. 關掉 Python 程式，雲端 turn 會停止嗎？

不會因為關掉 event stream 就自動取消。若要停止 active turn，送出 agent.session.input.cancel，再確認 root turn 的取消結果。

3. 重連後能拿回每一個漏掉的 token delta 嗎？

不能這樣假設。官方明確說 streams 不 replay missed events；saved items 可恢復完成工作，但不是每個漏掉的中間 event。UI 要以 item 的 final state 為準。

4. Session idle 是否代表任務成功？

不是。要找 root turn 的 completed、failed 或 cancelled，並檢查工具輸出與 artifact；completed 也不是每個 tool 都成功的保證。

5. Self-hosted environment 能符合 ZDR 嗎？

截至 2026 年 9 月 12 日不行。官方說 self-hosted sandbox 不會讓 Agents API 取得 Zero Data Retention eligibility；資料 residency 目前也只支援美國。

6. Environment 裡可以放第三方 API key 嗎？

技術上能注入的 secret，也可能被 Agent-generated code 讀到。官方建議把第三方 credential 留在環境外，盡量用 credential broker 只替核准的 outbound request 加上 scoped secret。

7. Agents API 費用只算 token 嗎？

不是。官方列為三塊：所選模型的 API usage、OpenAI tools 的標準費率，以及 OpenAI-hosted sandbox 的 container 費率。實際預算還要加上你的 self-hosted infrastructure 或 function service。

8. Production 最先該保存哪個 ID？

先保存 session_id，再把 application job、turn、item 與 artifact 對回去。只存畫面文字，無法安全判斷斷線後原工作到底完成、等待、取消或失敗。

給新手的 7 個重點

1. Agents API 代管的是 Codex harness 與 session，不是你的業務責任。
2. Events 是直播，Items 是可回查帳本；斷線後兩者要一起用。
3. 先開新 stream，再 retrieve session 與 saved items。
4. 關 stream 不會 cancel；取消要送明確 input event。
5. Root turn completed 後仍要檢查 tools、output 與 artifact。
6. Self-hosted 只代表 sandbox 自管，不代表整條資料路徑自動 ZDR。
7. 上線前注入斷線、取消、tool failure 與 environment failure。

想繼續建立完整開發能力，可瀏覽 AlphaLab AI 專區，或依序完成 AlphaLab 線上課程中的 AI 工具與自動化練習。