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

設定智慧體

定義智慧體、重複使用其設定,並依需求自訂每個工作階段。

智慧體的設定決定其行為。你可以在建立工作階段時提供設定,也可以儲存設定以供日後使用。工作階段保留對話與工作內容,已儲存的智慧體則保留可重複使用的設定。

定義智慧體的行為

先指定模型與指示,再依任務需求加入工具與控制選項:

  • 模型: 指定由哪個模型執行任務。
  • 指示: 說明智慧體應執行哪些任務,以及應如何行動。
  • 工具: 指定智慧體可執行的動作,例如搜尋網頁或呼叫你的函式。
  • 推理與輸出: 設定模型的推理強度,以及回應的格式與詳細程度。

建立工作階段時,請在 agent 中傳入這些設定。以下範例指定模型與指示,並提供使用者的第一則訊息:

為單一工作階段設定智慧體
from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer the user clearly and concisely.",
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "What can you help with?"}],
        }
    ],
)
print(session.to_json())

如需查閱設定欄位及其可用值,請參閱 Agents API 參考文件。如需設定步驟,請參閱函式、電腦、MCP 連線或多智慧體任務委派。

設定大小

指示與工具設定的總大小須小於 4 MiB(4,194,304 位元組),並為 Agents API 的中繼資料預留少許空間。如果設定過大導致工作階段無法啟動,請縮減指示與工具設定,再建立新的工作階段。

上傳至環境的檔案另有檔案限制。

在多個工作階段中重複使用智慧體

儲存智慧體後,即可在多個工作階段中重複使用其設定。只需建立一次智慧體,之後每次啟動工作階段時,將其 ID 傳入 agent_id 即可:

重複使用智慧體
from openai import OpenAI

client = OpenAI()
agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
    timeout=360,
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())

每個工作階段都有自己的對話與工作內容。若要列出、擷取、更新或刪除已儲存的智慧體,請參閱 Agents API 參考文件。認證資訊保存在保險庫中,與已儲存的設定分開存放。

更新已儲存的智慧體

對已儲存智慧體所做的更新僅適用於新的工作階段。每個工作階段在建立時都會複製已儲存的設定,後續回合會沿用這些設定。若要變更現有工作階段,請更新該工作階段的設定。

更新已儲存的智慧體時,請留意以下規則:

  • 省略的欄位會保留已儲存的值。若只變更 model,便會保留 reasoning、service_tier 和 text。
  • 傳入的物件會取代整個欄位的值。如果傳入的 reasoning 只包含 effort,也會清除已儲存的 summary。
  • null 可重設接受此值的欄位。例如,reasoning: null 會將推理強度恢復為模型的預設值。

如果新模型不支援某些現有設定,請在同一個請求中變更或重設這些設定。

覆寫單一工作階段的設定

建立工作階段時,同時提供 agent_id 和 agent,即可自訂已儲存智慧體的設定。對於省略的設定(包括模型),工作階段會在建立時從已儲存的智慧體複製其值。

執行以下範例前,請將範例值 agent_123 換成已儲存智慧體的 ID:

為單一工作階段覆寫智慧體設定
# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

agent_id = "agent_123"
session = client.beta.agents.sessions.create(
    agent_id=agent_id,
    agent={"instructions": "Answer this question in one concise paragraph."},
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain how an agent connects to an MCP server.",
                }
            ],
        }
    ],
)
print(session.to_json())

覆寫的設定僅適用於該工作階段,不會影響已儲存的智慧體或其他工作階段。傳入的物件與陣列會取代整個欄位的值,不會與已儲存的值合併。例如,傳入 tools 會取代已儲存的工具清單。

如需查閱請求欄位,請參閱建立工作階段的 API 參考文件。

更新現有工作階段的設定

傳送 POST /v1/agents/sessions/{session_id} 請求並附上 agent 物件,即可變更單一工作階段的 tools、model、reasoning.effort 或 service_tier。測試版與正式版 API 規格均支援這些設定。你也可以在同一個請求中更新 metadata。

變更模型、推理強度或服務層級後,只有在更新完成後傳送的訊息所啟動的新回合,才會套用這些變更。已送出且尚在處理中的訊息可能仍會使用先前的設定。進行中的回合會沿用原本的模型、推理強度與服務層級,即使你傳送訊息調整執行方向也一樣。工作階段會保留對話記錄。選取的模型必須支援更新後的設定,否則更新會失敗。

  • agent 和 reasoning 物件會將傳入的欄位合併至目前的設定。省略的欄位會保留原值,包括推理摘要。若只變更 model,工作階段會保留原有的推理強度與服務層級。
  • tools 會取代整份工具清單。函式與 MCP 伺服器的變更會在下次呼叫模型時生效。內建工具的變更最遲會在下一回合生效。省略 tools 可保留目前的工具,傳入 null 或 [] 則可清空工具清單。
  • reasoning.effort: null 會將推理強度重設為所選模型的預設值。
  • service_tier: null 會恢復自動選擇服務層級。
  • 工作階段必須指定模型,因此無法傳入 model: null。agent 和 reasoning 物件也不接受 null。
  • metadata 會取代整份鍵值對應表。省略此欄位可保留中繼資料,傳入 null 或 {} 則可將其清除。

例如,以下請求會變更推理強度,並讓 API 自動選擇服務層級:

{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

更新工作階段不會影響已儲存的智慧體或其他工作階段。之後更新已儲存的智慧體,也不會影響此工作階段。

無法透過此端點更新 reasoning.summary、text、instructions 或 multi_agent。若要變更這些設定,請建立新的工作階段。如需查閱請求欄位,請參閱更新工作階段的 API 參考文件。

自動審查動作

將工作階段層級的 review 欄位設為 "auto_review",即可自動審查支援此功能的核准請求。請將此欄位設在與 agent 或 agent_id 相同的層級,不要放在智慧體設定內。建立工作階段時若省略 review,預設值為 "none"。

自動審查也會變更執行權限。啟用前,請先確認環境符合先決條件。

等到主要任務處於閒置狀態,且所有輸入都已提交完畢,即可更新 review。後續執行與復原作業都會使用新設定。若在任一條件尚未滿足時要求變更模式,API 會傳回 409 Conflict,不會套用任何變更。請使用已啟用自動審查的專案,以及支援自動審查的工作階段。如需瞭解如何設定自動審查及處理核准請求,請參閱自動審查。

環境設定

建立工作階段時,請將 environment 設在與 agent 相同的層級。環境設定決定智慧體在哪裡執行指令與處理檔案。

可選擇 none、openai_hosted 或 self_hosted。架構說明各選項的適用情境,以及各環境由誰管理。

若使用由 OpenAI 託管的環境,請選擇容器大小,並設定任務所需的套件、初始檔案與網路存取權。你可以在多個工作階段中重複使用同一個環境範本。若使用自行託管的環境,請備妥運算資源並連接執行器。

如需查閱環境欄位,請參閱建立工作階段的 API 參考文件。如需瞭解技能、外掛程式與範本,請參閱外掛程式。若要在執行結束後保留檔案,請參閱工作階段產出檔案。