파일 추가하기

Files API를 통해 파일을 업로드하고 세션의 샌드박스에 마운트하여 에이전트에 파일을 제공할 수 있습니다.

파일 업로드하기

먼저 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가 있으며, 삭제 시 이 값을 사용합니다.

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 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를 통해 사용할 수 있습니다. 세션 파일 조회 및 다운로드하기를 참조하세요