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

執行與接續工作階段

開始工作、追蹤進度並接續對話。

工作階段會持續保留智慧體的設定、對話和已儲存的工作成果。使用同一個工作階段傳送後續訊息,即可接續先前的工作。

工作階段與回合

回合是智慧體在工作階段中執行一次工作的週期。傳送訊息時,如果工作階段處於閒置狀態,就會開始新回合。如果回合正在執行,訊息就會引導該回合的工作方向。

回合會以非同步方式執行。應用程式可以透過串流追蹤進度,也可以透過 webhook 接收工作階段狀態變更通知。

使用排程自動化,即可在指定的未來時間開始工作,或定期執行工作。自動化可以在每次執行時建立新的工作階段,也可以接續現有對話。

開始工作

使用智慧體設定和初始 input 建立工作階段。將 stream 設為 true,即可透過同一個請求接收第一個回合的事件。

設定好 API 金鑰和 SDK 後,執行下列範例即可建立並執行指令碼。指令碼的執行環境由 OpenAI 管理:

建立工作階段並以串流方式接收第一個回合的事件
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

將 session_id 與應用程式的對話狀態一併儲存。使用這個 ID 傳送後續訊息,並擷取該對話已儲存的工作成果。

若要自動審查智慧體的動作,請在已啟用自動審查的專案中建立符合條件的工作階段時,將 review 設為 "auto_review"。等到主要任務處於閒置狀態,且所有輸入提交作業都已結束後,即可變更這項設定。如需瞭解審查模式、環境先決條件及核准方式,請參閱自動審查。

如需瞭解可重複使用的智慧體設定,請參閱設定智慧體。如需瞭解有哪些環境可供選擇,請參閱架構。使用 environment.type: "none" 的工作階段必須提供初始輸入。建立工作階段的 API 參考文件列出了請求欄位。

如果工作階段使用 Files API 附件,檢查檔案時可能會收到 HTTP 429 回應,錯誤碼為 files_api_rate_limit_exceeded。如需復原步驟,請參閱 Files API 速率限制。

輸入大小

智慧體執行環境接受的請求大小上限為 4 MiB(4,194,304 位元組)。請讓 input 與輸出結構描述(agent.text.format.schema)的合計大小低於此上限,並為 Agents API 新增的中繼資料預留空間。上傳到環境的檔案另有檔案限制。

追蹤進度並處理回合結果

智慧體執行工作時,事件會回報輸出和變更。請確認回合的結果是完成、失敗或取消。僅憑工作階段處於閒置狀態,無法判定回合是否成功。

請查看是否收到 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled 事件。也請檢查智慧體的輸出,因為回合完成並不保證每次工具呼叫都成功。

如果工作階段需要函式結果或需要連接環境,請擷取工作階段並檢查 required_actions。程式碼必須處理函式呼叫或連接環境,才能繼續工作。

如需瞭解事件類型和承載資料,請參閱事件與項目。

接續工作或調整工作方向

向同一個工作階段再傳送一則 agent.session.input.message。如果智慧體正在工作,這則訊息會引導目前回合的工作方向。如果工作階段處於閒置狀態,這則訊息就會在現有對話中開始新回合。

後續訊息也適用相同的輸入大小限制。

對已儲存智慧體所做的更新只會套用到新的工作階段。若要變更此工作階段後續回合使用的模型、推理強度或服務層級,請更新工作階段設定。

使用對話所屬的工作階段 ID 傳送輸入。請在傳送訊息前訂閱該工作階段的事件串流,讓應用程式能收到回合剛開始時的事件。

為每次獨立的訊息提交建立一個冪等性金鑰。傳送輸入前,先將金鑰與訊息一併儲存。提交訊息時,使用已儲存的金鑰:

傳送後續訊息
from uuid import uuid4


# Reuse the same submission key when retrying this message.
def send_message(
    client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
    client.beta.agents.sessions.events.create(
        session_id,
        idempotency_key=submission_key,
        events=[
            {
                "type": "agent.session.input.message",
                "input": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "input_text",
                                "text": text,
                            }
                        ],
                    }
                ],
            }
        ],
    )


submission_key = str(uuid4())
# Save this key with the message before submitting it.

透過 Idempotency-Key 標頭傳送金鑰,並在自動重試時沿用該金鑰。如果應用程式因請求逾時或回應遺失而重試,請使用相同的金鑰、工作階段 ID 和訊息。每次獨立提交都要產生不同的金鑰,即使訊息文字完全相同也一樣。

如需同時傳送訊息並接收串流事件的範例,請參閱事件與項目。

擷取已儲存的工作成果

事件會顯示即時進度。工作階段儲存的項目包含訊息、工具呼叫及已完成的回應。擷取這些項目,即可顯示先前的工作成果,或在回合結束後檢查結果:

擷取工作階段項目
# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)

如需檢查工作階段狀態和回合結果,請參閱管理工作階段。如需擷取檔案,請參閱檔案與產出物。

串流不會重播錯過的事件。連線中斷後,請擷取工作階段及其已儲存的項目,以取回工作成果。如需重新連線的步驟,請參閱恢復中斷的串流。

取消執行中的回合

若要讓智慧體停止工作,請取消目前的回合。取消後,仍可存取該工作階段和先前的工作成果:

取消執行中的回合
# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id, events=[{"type": "agent.session.input.cancel"}]
    )