如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

Agents API 快速入門

建立智慧體,讓它在 OpenAI 託管的沙盒中撰寫並執行指令碼。

建立一個程式設計助理,讓它撰寫並執行 tree.py,以樹狀結構顯示目錄內容。OpenAI 會管理智慧體、它的對話,以及它執行任務的沙盒。

事前準備

在你的 OpenAI Platform 專案中建立應用程式 API 金鑰。授予金鑰 api.agents.read 和 api.agents.write 權限,以便操作工作階段,並授予 api.responses.write 權限,以便執行模型推論。接著將金鑰匯出為環境變數:

export OPENAI_API_KEY="your-api-key"

請將金鑰保存在智慧體的沙盒外。如需瞭解沙盒的設定與限制,請參閱 OpenAI 託管的沙盒。

每個請求都必須包含 OpenAI-Beta: agents=v1 標頭。OpenAI SDK 會自動加入此標頭,使用 cURL 時則須自行加入。

1. 執行任務

選擇程式語言,安裝 OpenAI SDK,然後執行範例。SDK 範例使用 beta.agents 命名空間。這個請求會建立工作階段、提交任務,並以串流方式傳回進度。

安裝或更新 Python SDK:

pip install --upgrade openai

將範例儲存為 quickstart.py:

建立並執行 tree.py
from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()
    print(result.output_text)
    session_id = result.session_id

在終端執行範例:

python quickstart.py

不需要沙盒嗎? 如果智慧體只需回答問題或呼叫外部工具,無須執行指令或處理本機檔案,請將 environment.type 設為 none。瞭解詳情。

2. 查看進度

終端會即時顯示串流傳來的事件。SDK 範例會輸出 JSON,cURL 則會顯示原始事件串流。任務順利執行時,智慧體會建立並執行 tree.py,然後以樹狀結構列出目錄內容,其中會包含該檔案。其他檔案與輸出內容會因沙盒而異。

看到 agent.session.turn.completed 事件後,請查看智慧體回報的執行結果。即使回合已完成,仍可能有工具執行失敗。事件名稱若以 turn.failed、turn.cancelled 或 session.failed 結尾,表示執行失敗或已取消。單憑 agent.session.idle 無法判定執行成功。如果串流提早中斷,請先擷取工作階段及其中已儲存的項目,再重試。

3. 繼續使用工作階段

儲存事件中的 session_id,用它來傳送後續訊息,例如「請在 tree.py 中加入設定最大深度的選項,執行程式並顯示輸出結果。」傳送後續訊息前,請先開啟事件串流,以免錯過最初的事件。

4. 清理工作階段

你可以保留工作階段以執行其他任務,也可以在使用完畢後刪除。刪除前請先儲存需要的檔案。

將範例中的 sess_123 替換為你先前儲存的工作階段 ID。

刪除工作階段
# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

後續步驟