Claude Platform Docs
Managed Agents管理代理上下文

新增檔案

上傳檔案並將其掛載到您的沙箱中，以供讀取和處理。

您可以透過 Files API 上傳檔案，並將其掛載至工作階段的「sandbox」（沙箱）中，藉此將檔案提供給您的代理程式。

上傳檔案

首先，使用 Files API 上傳檔案：

file = client.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

在工作階段中掛載檔案

建立工作階段時，將已上傳的檔案加入 resources 陣列，即可將其掛載至沙箱中：

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/data.csv",
        },
    ],
)

使用上述的 mount_path，代理程式會在 /mnt/session/uploads/data.csv 讀取該檔案（請參閱檔案路徑）。

系統會建立一個新的 file_id，用以參照該檔案在工作階段中的實例。這些副本不會計入您的儲存空間限制。

多個檔案

在 resources 陣列中加入多個項目，即可掛載多個檔案：

resources = [
    {"type": "file", "file_id": "file_abc123", "mount_path": "/data.csv"},
    {"type": "file", "file_id": "file_def456", "mount_path": "/config.json"},
    {"type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py"},
]

每個工作階段最多支援 500 個檔案。

管理執行中工作階段的檔案

您可以在工作階段建立後，使用工作階段資源 API 新增或移除檔案。每個資源在新增（或列出）時都會回傳一個 id，您可使用該 id 進行刪除。

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

使用 resources.list 列出工作階段中的所有資源。若要移除檔案，請以資源 ID 呼叫 resources.delete：

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

列出與下載工作階段檔案

使用 Files API 列出範圍限定於某個工作階段的檔案並下載它們。代理程式寫入 /mnt/session/outputs/ 的檔案會在代理程式完成寫入後不久出現在清單中，有時會在工作階段進入閒置狀態後數秒才出現。如果您預期的輸出檔案尚未出現，請稍候片刻後再次列出；一旦檔案出現在清單中，即表示其上傳已完成。

依 scope_id 篩選需要 managed-agents-2026-04-01 beta 標頭，因此列出範例使用 beta files 命名空間，並明確傳遞該標頭。

# 列出與工作階段相關聯的檔案
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for file in files:
    print(file.id, file.filename)

# 下載檔案
content = client.files.download(files.data[0].id)
content.write_to_file("output.txt")

支援的檔案類型

代理程式可以處理任何檔案類型，包括：

  • 原始碼（.py、.js、.ts、.go、.rs 及其他）
  • 資料檔案（.csv、.json、.xml、.yaml）
  • 文件（.txt、.md）
  • 壓縮檔（.zip、.tar.gz）- 代理程式可使用 bash 解壓縮這些檔案
  • 二進位檔案 - 代理程式可使用適當的工具處理這些檔案

檔案路徑

  • 您指定的路徑以工作階段的 uploads 目錄為根目錄：mount_path 為 /data.csv 時，檔案會放置於沙箱中的 /mnt/session/uploads/data.csv
  • 若您省略 mount_path，檔案會放置於 /mnt/session/uploads/<file_id>
  • 父目錄會自動建立
  • 路徑應為絕對路徑（以 / 開頭）
  • 代理程式寫入 /mnt/session/outputs/ 的檔案可透過 Files API 取得，範圍限定於該工作階段；請參閱列出與下載工作階段檔案

Was this page helpful?