開始工作階段

建構將工作委派給代理

開始一個工作階段

建立一個工作階段來執行您的代理程式並開始執行任務。

工作階段是在環境中執行的代理程式實例。每個工作階段都參考一個代理程式和一個環境（兩者都是分別建立的），並在多次互動中維持對話歷史。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

建立工作階段

工作階段需要一個 agent ID 和一個 environment ID。代理程式是版本化資源；將 agent ID 作為字串傳入會使用最新的代理程式版本啟動工作階段。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

若要將工作階段固定到特定的代理程式版本，請傳入一個物件。這可讓您精確控制執行的版本，並獨立地分階段推出新版本。

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

代理程式定義了 Claude 在工作階段中的行為方式，包括模型、系統提示、工具和 MCP 伺服器。詳見代理程式設定。

透過保管庫進行 MCP 認證

如果您的代理程式使用需要認證的 MCP 工具，請在工作階段建立時傳入 vault_ids 以參考包含已儲存 OAuth 認證的保管庫。Anthropic 會代您管理令牌刷新。詳見使用保管庫進行認證以了解如何建立保管庫和註冊認證。

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

啟動工作階段

建立工作階段會佈建環境和代理程式，但不會啟動任何工作。若要委派任務，請使用使用者事件將事件傳送到工作階段。工作階段充當狀態機器，追蹤進度，而事件驅動實際執行。

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

詳見事件和串流以了解如何串流代理程式的回應和處理工具確認。

工作階段狀態

工作階段會經歷這些狀態：

狀態	描述
`idle`	代理程式正在等待輸入，包括使用者訊息或工具確認。工作階段以 `idle` 開始。
`running`	代理程式正在主動執行
`rescheduling`	發生暫時性錯誤，自動重試
`terminated`	工作階段因無法恢復的錯誤而結束

其他工作階段操作

檢索工作階段

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

列出工作階段

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

封存工作階段

封存工作階段以防止傳送新事件，同時保留其歷史記錄：

client.beta.sessions.archive(session.id)

刪除工作階段

刪除工作階段以永久移除其記錄、事件和相關容器。無法刪除 running 工作階段；如果您需要立即刪除它，請傳送中斷事件。

檔案、記憶體存放區、環境和代理程式是獨立資源，不受工作階段刪除的影響。

client.beta.sessions.delete(session.id)

Was this page helpful?

建構將工作委派給代理

開始一個工作階段

建立一個工作階段來執行您的代理程式並開始執行任務。

工作階段是在環境中執行的代理程式實例。每個工作階段都參考一個代理程式和一個環境（兩者都是分別建立的），並在多次互動中維持對話歷史。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 beta 標頭。SDK 會自動設定 beta 標頭。

建立工作階段

工作階段需要一個 agent ID 和一個 environment ID。代理程式是版本化資源；將 agent ID 作為字串傳入會使用最新的代理程式版本啟動工作階段。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

若要將工作階段固定到特定的代理程式版本，請傳入一個物件。這可讓您精確控制執行的版本，並獨立地分階段推出新版本。

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

代理程式定義了 Claude 在工作階段中的行為方式，包括模型、系統提示、工具和 MCP 伺服器。詳見代理程式設定。

透過保管庫進行 MCP 認證

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

啟動工作階段

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

詳見事件和串流以了解如何串流代理程式的回應和處理工具確認。

工作階段狀態

工作階段會經歷這些狀態：

狀態	描述
`idle`	代理程式正在等待輸入，包括使用者訊息或工具確認。工作階段以 `idle` 開始。
`running`	代理程式正在主動執行
`rescheduling`	發生暫時性錯誤，自動重試
`terminated`	工作階段因無法恢復的錯誤而結束

其他工作階段操作

檢索工作階段

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

列出工作階段

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

封存工作階段

封存工作階段以防止傳送新事件，同時保留其歷史記錄：

client.beta.sessions.archive(session.id)

刪除工作階段

刪除工作階段以永久移除其記錄、事件和相關容器。無法刪除 running 工作階段；如果您需要立即刪除它，請傳送中斷事件。

檔案、記憶體存放區、環境和代理程式是獨立資源，不受工作階段刪除的影響。

client.beta.sessions.delete(session.id)

Was this page helpful?