AI-LECTURER 速報課|2026-09-12|約 28 分鐘

OpenAI Agents API:你的程式現在能『雇用』一個會寫程式、會操作系統的 AI 員工

取材:OpenAI Agents API(Hacker News(AI 高人氣))
📍 真實場景
阿凱,一人接案的網站維護工程師,同時幫五、六個中小企業客戶顧網站

接到某客戶的緊急客訴「後台登入變得很慢」,得手動 SSH 進主機、跑診斷指令、翻 log、寫修復腳本,整套流程做完常常要一兩個小時

😖 卡住的地方:每次客訴都要重複同一套「連線→診斷→修復→回報」的手動流程,他很想寫一個 AI 幫手自動做完這些事,但只要一想到要自己架設「代理人執行環境」——要有地方安全地跑指令、要處理 AI 中途斷線怎麼辦、對話紀錄太長怎麼辦——就覺得工程量比修 bug 本身還大,只好繼續手動來
💡 這堂課會告訴阿凱,OpenAI 剛推出的 Agents API 把「沙盒環境、狀態管理、失敗復原」全部包好了,他只要告訴 AI「這是任務、這是工具」,就能收到一份自動診斷報告

🧭 這到底是什麼(白話版)

OpenAI 最近推出了一個叫做 Agents API 的新東西,簡單說,它讓你的程式可以透過 API,直接指揮一個「會自己動手做事」的 AgentAI 助理本身的「人設」設定——包含要用哪個模型、給它什麼指令、能操作哪些工具。過去如果你想做一個「AI 自動幫我跑程式、讀寫檔案」的功能,你得自己張羅一堆基礎建設;現在 OpenAI 把這些通通接管過去。

整套系統圍繞四個核心概念運作:Agent(AI 的人設與能力設定)、EnvironmentAI 實際「動手做事」的地方,可以是 OpenAI 代管的沙盒,也可以是你自己指定的電腦(AI 實際做事的地方)、Session一個持續進行中的工作個體,像是幫你開一個「不會斷線」的工作視窗,AI 在裡面持續處理任務直到完成(工作進行的容器),以及 Events/Items(AI 做事過程中送出跟收到的一則則訊息)。

最實用的部分在於,OpenAI 把「長時間執行 AI 任務」最容易出包的幾件事都內建進去了:當對話紀錄太長塞不下時,系統會自動幫你做 Context compaction(上下文壓縮)AI 自動把之前做過的事摘要濃縮,讓它不會忘記前面的進度,也不會佔滿「記憶空間」;如果任務很複雜,主 agent 還能把工作拆成好幾塊,分別交給 Subagent(子代理)由主要 AI 助理另外派出去處理特定小任務的「小幫手」,做完後把結果彙整回來 分頭處理;而你也不用一直傳訊息問「做完了嗎」,可以用 Webhook當事情有進展或完成時,系統主動「打電話」通知你的程式,而不是你自己一直去問 被動接收通知。

如果 AI 需要碰觸你自己的系統(像是內部資料庫、Slack、GitHub),則要透過 MCP(Model Context Protocol)一種讓 AI 助理「插上」外部工具或資料來源的標準接頭,概念上很像 USB,不同工具只要符合這個規格就能被 AI 接上 這個標準接頭串接。整套下來,你要做的事只剩下「定義任務、提供工具、選好執行環境」,其餘的協調、記憶、復原都交給 OpenAI 管理的 Harness(執行骨架)這裡指幫 AI 助理張羅好環境、規則、安全機制的一整套配套系統,讓 AI 不用「裸奔」在你的系統上工作

🎯 為什麼值得你花時間

免蓋一整套代理人基礎設施過去想做「AI 自動執行任務」的功能,光是 session 狀態管理、失敗復原、上下文太長怎麼辦,就得自己寫一大套系統。Agents API 把這些通通內建,對小型團隊或個人接案者來說,等於省下最耗工的基礎建設那一塊。
把「安全煞車」做進 API 核心官方範例裡的 Incident response agent 特別設計成「要做恢復性動作前,得先請求人類核准」。這代表安全機制不是外掛,而是 Agents API 從設計源頭就把「AI 能自己操作系統」的風險納入考量。
從「聊天機器人」進化成「能動手的數位員工」官方直接釋出 Slack bot、資料分析師、GitHub 問題調查員等完整應用範例,代表這套 API 瞄準的不再是「回答問題」,而是「真的幫你把一件工作從頭做到尾」——這是評估這類技術時該關注的分水嶺。

⚙️ 它是怎麼運作的

1
建立 Session你先設定好 Agent(選模型、寫操作指令、決定能用哪些工具),OpenAI 收到後會自動準備好對應的 Environment(例如一個乾淨的沙盒)。
2
派任務把使用者想做的事(例如「幫我列出資料夾樹狀結構」)當作輸入送進去,這就會啟動一輪(turn)工作。
3
即時追蹤進度你可以用串流(streaming)方式持續收到 AI 目前在做什麼,或是設定 webhook,讓它做完/卡住時主動通知你,不用自己一直發問輪詢。
4
必要時插話或加碼任務同一個 Session 可以持續使用——AI 還在工作時你能中途「喊話」調整方向,做完一輪之後也能再丟新任務進同一個 Session,延續先前的記憶與情境。
5
拿到結果與產出物任務完成後,Session 會回傳整理好的訊息,以及它在沙盒裡實際寫出、跑過的檔案(artifact),你可以直接拿來用或檢查。
傳統「自建 Agent 框架」 vs 使用 Agents API
面向傳統自建方式Agents API
環境準備自己找雲端主機、裝好執行環境、設安全隔離OpenAI 代管沙盒,建立 Session 就自動準備好
對話記憶管理自己寫程式偵測 token 超出上限、手動摘要內建 context compaction 自動壓縮
失敗復原自己存檔進度、寫重試邏輯Session 本身具備從中斷處恢復的機制
外部工具串接自己刻串接程式碼用 MCP 標準接頭直接接上

🔍 程式碼漫遊(點有 ● 的行看白話講解)

這段程式碼示範怎麼開一個 Session、丟任務進去,然後即時追蹤 AI 的工作進度。

from openai import OpenAI
💬 先把官方的 openai 套件匯入進來,等一下要用它建立客戶端。
client = OpenAI()
💬 建立客戶端,它會自動讀取環境變數裡的 OPENAI_API_KEY 當作你的身分驗證。
session = client.beta.agents.sessions.create(
💬 開始建立一個新的 Session,也就是這次任務要用的「工作視窗」。
agent={"model": "gpt-6-astra", "instructions": "你是會寫程式的助理"},
💬 設定 Agent 的人設:要用哪個模型、要遵守什麼指令。
environment={"type": "sandbox"},
💬 指定 Environment 為 OpenAI 代管的沙盒,AI 之後執行程式都在這個安全隔離的環境裡進行。
)
💬 設定收尾,這時候 Session 已經準備好、可以開始接任務。
run = session.turns.create(input="幫我列出資料夾樹狀結構")
💬 把具體任務丟進去,啟動這一輪(turn)工作,AI 開始動手做事。
for event in session.turns.stream(run.id):
💬 用串流方式持續接收 AI 的即時進度,不用自己寫輪詢邏輯去問「好了沒」。
if event.type == "tool_call":
💬 遇到 AI 呼叫工具(例如在沙盒裡執行程式)的事件時,就會進到這裡。
print(f"執行工具:{event.tool_name}")
💬 把 AI 正在用的工具名稱印出來,方便你知道它現在在做什麼,而不是悶著頭等結果。

🛠️ 動手做:打造一個會幫你寫「資料夾樹狀圖」小工具的 AI 代理人

這是一個真實小專案:下載(或複製)檔案,照步驟在你電腦上跑起來。

📄 requirements.txt ⬇ 下載
openai>=1.50.0
python-dotenv>=1.0.0
📄 .env.example ⬇ 下載
OPENAI_API_KEY=你的OpenAI_API金鑰貼在這裡
📄 agent_treescript.py ⬇ 下載
import os
import time

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()


def main() -> None:
    api_key = os.environ.get("OPENAI_API_KEY")
    if not api_key:
        raise SystemExit("找不到 OPENAI_API_KEY,請先在 .env 檔案填入你的金鑰")

    client = OpenAI(api_key=api_key)

    session = client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": (
                "你是一個會寫 Python 小工具的助理。收到任務時,"
                "先在沙盒裡寫好程式碼、執行它,再把結果整理成清楚的中文說明給使用者。"
            ),
        },
        environment={"type": "sandbox"},
    )

    task = (
        "請寫一個 Python 腳本,列出目前工作目錄底下的資料夾樹狀結構"
        "(忽略隱藏檔案與 .venv 資料夾),在沙盒裡執行它,再把輸出結果貼給我看。"
    )

    run = session.turns.create(input=task)

    print("=== Agent 開始工作,以下是即時進度 ===")
    try:
        for event in session.turns.stream(run.id):
            if event.type == "message":
                print(f"[訊息] {event.content}")
            elif event.type == "tool_call":
                print(f"[執行工具] {event.tool_name}:{event.arguments}")
            elif event.type == "completed":
                print("=== 任務完成 ===")
                break
    except KeyboardInterrupt:
        print("\n已中斷追蹤,Session 仍會在背景繼續執行這一輪任務。")
        return

    result = session.turns.retrieve(run.id)
    print("\n最終結果:\n", result.output_text)


if __name__ == "__main__":
    main()
  1. 開啟 PowerShell,切換到你想放這個小專案的資料夾,例如輸入 cd D:\my_projects,接著輸入 mkdir agents_api_demo 再輸入 cd agents_api_demo。
  2. 建立虛擬環境:輸入 python -m venv .venv
  3. 啟動虛擬環境:輸入 .venv\Scripts\Activate.ps1(如果出現「無法載入,因為執行原則」的錯誤,先執行 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass 再重試)
  4. 把上面三個檔案(requirements.txt、.env.example、agent_treescript.py)存進這個資料夾裡
  5. 安裝套件:輸入 pip install -r requirements.txt
  6. 把 .env.example 複製一份改名為 .env,打開它,把你申請到的 OpenAI API 金鑰貼進去(需要你的帳號已開通 Agents API 的搶先體驗權限)
  7. 執行 python agent_treescript.py,觀察終端機印出的 Agent 即時進度,以及最後產生的資料夾樹狀圖結果

🧠 工程思維透鏡(資深工程師看到的是什麼)

🔭 為什麼 OpenAI 要把 session 狀態、上下文壓縮這些「麻煩事」都攬在自己身上,而不是像過去一樣讓開發者自己組?
這是一個「控制權換取開發速度」的取捨。開發者失去了自己微調 orchestration 細節的自由(例如你不能自訂上下文要怎麼摘要),換到的是不用再重造輪子——尤其上下文管理、失敗復原這些「長時間執行 agent」最容易出包的地方,正是最多團隊在正式環境踩雷的坑。對於想快速上線的團隊,這筆交易划算;但對需要精細控制 agent 行為的團隊,等於把一部分「黑盒子」焦慮換了個位置。
🔭 Environment 被設計成「可選的沙盒或電腦」,這個彈性背後的工程考量是什麼?
把「AI 大腦」(Agent 設定)和「AI 手腳」(Environment 執行環境)拆開來設計,是很典型的關注點分離。這樣 OpenAI 可以同時服務兩種需求:不想管基礎設施的人直接用代管沙盒;需要碰觸自己內部系統(像資料庫、內部 API)的企業則能指定自己的執行環境。這種可替換的執行後端設計,讓同一套 Agent 邏輯能在「雲端沙盒」和「企業內網」之間搬動,而不用重寫。
🔭 官方範例特別強調「Incident response agent 要先請求核准才能做恢復動作」,這反映了什麼設計哲學?
這是把「人在迴圈中」當作預設安全機制,而不是事後補救。當 agent 能自己執行程式、碰觸真實系統時,最大的風險不是它做錯事,而是它在你沒注意的時候就把事情做完了。把「危險動作前先暫停等核准」設計進 API 的核心流程,代表 OpenAI 把「可控性」看得跟「自動化程度」一樣重要,這也是任何要把 agent 導入正式環境的工程團隊都該學的取捨。

📝 隨堂考(點選答案,立即回饋)

Q1. 在 Agents API 的設計裡,下列哪一個負責「提供沙盒、讓 agent 讀寫檔案跟跑指令」?
✅ Environment 是 AI 實際動手做事的地方,可以是 OpenAI 代管的沙盒,也可以是你自己指定的電腦;Agent 只是「人設設定」,本身不執行任何動作。
Q2. 上下文壓縮(context compaction)主要是為了解決什麼問題?
✅ 當 AI 長時間工作、累積的訊息越來越多時,系統會自動幫忙摘要壓縮,讓 AI 不會因為記憶體塞滿而忘記前面做過的事。
Q3. 文中提到的 Incident response agent 範例,在執行「恢復動作」前會怎麼做?
✅ 這個範例特別設計了「請求核准」的流程,代表危險或不可逆的操作,需要人類把關才會真的執行。
Q4. MCP 在這篇文章的脈絡下,最貼切的比喻是?
✅ MCP(Model Context Protocol)的作用就是讓不同的外部工具或資料來源,用同一套標準規格被 AI 助理接上,概念上很像 USB 接頭。
Q5. 為什麼「Subagent(子代理)」機制對處理複雜任務有幫助?
✅ Subagent 讓主要的 Agent 可以把複雜工作拆解成幾個小任務,分頭指派給子代理處理,最後再把各自的結果彙整成一個完整答案。

🃏 翻牌記憶卡(先想答案,再點開對答)

Session點我翻面
一個持續進行中的 AI 工作個體,可以中途插話、事後也能延續同一個情境繼續派新任務
Sandbox(沙盒)點我翻面
AI 執行程式碼、讀寫檔案的隔離安全環境,不會碰到你電腦裡真正的系統
MCP點我翻面
讓 AI 助理接上外部工具或資料來源的標準協定,概念上像 USB 接頭
Context Compaction(上下文壓縮)點我翻面
自動把過長的對話紀錄摘要濃縮,避免 AI 忘記前面做過的事
Subagent(子代理)點我翻面
主要 Agent 把任務拆解、分派給小助手處理,再把結果彙整回來
Webhook點我翻面
事件發生時系統主動通知你的程式,不必自己一直輪詢問「好了沒」

✅ 離開前自測(全勾=這課真的學會了)

0%