Deep Agent Builder 첨부파일 지원
첨부파일은 에이전트 생성 세션, Thread 입력, 커뮤니티 게시물에서 서로 다른 경로로 처리됩니다. 이 페이지에서는 어떤 파일을 어디에 붙일 수 있는지, 저장·실행·삭제 결과를 어떻게 확인할지 정리합니다. 파일이 화면에 보인다는 사실과 실행에 사용됐다는 사실, 삭제됐다는 사실을 서로 바꿔 판단하지 마세요.
시작하기 전에 확인할 것
다음 조건을 먼저 확인합니다.
- 에이전트와 Thread 또는 게시물을 조회하고 수정할 권한이 있습니다.
- 테스트에는 고객 자료가 아닌 승인된 비식별 파일을 사용합니다.
- 파일의 MIME 타입과 크기를 확인할 수 있습니다.
- 삭제하거나 다시 올리기 전에 원본과 실행 결과를 보존해야 하는지 확인했습니다.
파일을 올릴 수 있는 권한과 파일을 실제 실행 입력으로 사용할 권한은 다를 수 있습니다. 목록에 파일이 보인다고 해서 에이전트가 그 파일을 읽었거나 결과에 반영했다고 단정하지 마세요.
첨부파일이 사용되는 세 가지 경로
| 경로 | 파일의 역할 | 확인할 결과 |
|---|---|---|
| 에이전트 생성 세션 | 생성 요청 또는 후속 intent 입력 | 세션의 attached_files와 content URL, 세션 상태 |
| Thread와 메시지 | 현재 대화의 실행 입력 | 파일과 메시지·run의 연결, 실행 결과와의 관계 |
| 커뮤니티 게시물 | 게시물에 연결된 이미지 또는 파일 | 업로드 응답, 게시물 연결, 조회·삭제 권한 |
에이전트 생성 세션의 첨부는 image/png, image/jpeg, image/gif, image/webp만 허용됩니다. 요청 하나에 최대 10개까지 올릴 수 있고, 개별 파일과 전체 합산 크기는 설정값 storage_attachment_max_bytes를 따릅니다. 이 값은 고정된 바이트 상수로 문서에 옮기지 마세요.
커뮤니티 첨부는 단일 업로드와 배치 업로드를 구분합니다. 배치 업로드는 일부 파일이 실패하면 같은 요청에서 이미 만들어진 row를 정리합니다. 업로드 응답에는 파일 이름, 크기, MIME 타입, content hash와 상태 확인에 필요한 식별자가 포함됩니다.
생성 세션에 이미지 첨부하기
1. 테스트 입력과 파일을 준비합니다
이미지에 포함된 내용으로 확인할 질문을 하나 정합니다. 파일 이름, MIME 타입, 실제 바이트가 서로 맞는지 확인할 수 있는 비식별 테스트 이미지를 사용합니다. 이미지가 아닌 파일을 생성 세션 첨부로 보내지 마세요.
2. 세션을 시작하거나 후속 입력을 보냅니다
생성 세션을 시작할 때는 files를 포함한 multipart 요청을 사용합니다. 후속 intent 입력도 files와 응답 내용을 함께 보낼 수 있습니다. 이미지 파일만 보내고 응답 내용을 생략하면 AGENT_CREATE_IMAGE_RESPONSE_REQUIRED가 반환될 수 있습니다.
요청이 성공하면 세션 상세의 attached_files[]에서 id, uid, filename, mime_type, file_size_bytes, content_url, auth_required를 확인합니다. auth_required는 항상 true이므로 content URL을 공개 URL처럼 공유하지 마세요.
3. 저장 결과와 실행 결과를 따로 확인합니다
세션 상세에 파일이 남았는지 확인한 뒤, 이미지가 생성 흐름의 입력으로 실제 사용됐는지 실행 상태와 결과를 대조합니다. 파일이 저장됐다는 응답만으로 이미지 해석이 성공했다고 기록하지 않습니다.
content URL을 조회할 때는 현재 사용자, 세션, 파일이 모두 같은 범위에 있는지 확인됩니다. 세션이 active 또는 completed일 때만 조회할 수 있으며, 삭제·폐기·만료된 파일이나 다른 세션의 파일은 ATTACHMENT_NOT_FOUND로 처리됩니다.
Thread 입력과 결과를 구분합니다
Thread에 넣은 파일은 해당 메시지의 입력 Attachment입니다. 실행이 만든 Artifact나 답변에 다시 표시된 파일과 같은 자원으로 취급하지 마세요. 다음 순서로 확인합니다.
- 파일이 현재 Thread와 메시지에 연결돼 있는지 확인합니다.
- 파일 상태와 실행 입력 목록을 확인합니다.
- run이 그 파일을 사용했다는 실행 정보가 있는지 대조합니다.
- 답변, Artifact, 원본 Attachment를 각각 구분해 기록합니다.
- 보존 또는 삭제 범위를 결정합니다.
자세한 Thread 상태, run 결과, 삭제 범위는 Thread와 첨부파일 보관에서 확인합니다.
커뮤니티 게시물의 첨부를 관리합니다
커뮤니티 첨부에는 다음 경로가 사용됩니다.
- 단일 업로드: POST /community/attachments
- 배치 업로드: POST /community/attachments/upload
- 다운로드: GET /community/attachments/{attachment_id}
- 이미지 inline 조회: GET /community/images/{attachment_uid}
- 파일 inline 조회: GET /community/files/{attachment_uid}
- 직접 표시용 URL: GET /community/attachments/{attachment_id}/view-url
- UID 기준 직접 표시용 URL: GET /community/attachments/by-uid/{attachment_uid}/view-url
- 삭제: DELETE /community/attachments/{attachment_id}
업로드와 삭제에는 COMMUNITY_ATTACHMENT_UPLOAD|DELETE 권한이 적용됩니다. 읽기 계열 endpoint는 로그인 여부를 확인합니다. 예약 게시물에 연결된 첨부는 작성자 또는 COMMUNITY_MODERATE 권한 보유자만 다운로드, inline 조회, view URL 발급을 사용할 수 있습니다.
다운로드는 Content-Disposition: attachment, 이미지와 파일의 inline 경로는 Content-Disposition: inline으로 동작합니다. 삭제 응답을 확인할 때는 deleted_at을 보고 soft delete 여부를 구분합니다. 삭제 성공만으로 모든 저장소와 게시물 본문에서 즉시 사라졌다고 확대하지 마세요.
결과를 판정하는 기준
첨부파일 작업은 다음 조건을 모두 확인했을 때 완료로 기록합니다.
- 올린 경로가 생성 세션, Thread, 커뮤니티 게시물 중 어디인지 확인했습니다.
- 업로드 응답에서 파일 식별자, 크기, MIME 타입과 상태를 확인했습니다.
- 생성 세션에서는 attached_files[]와 content 조회 권한 범위를 확인했습니다.
- Thread에서는 Attachment와 run, Artifact를 구분하고 실행 입력 연결을 대조했습니다.
- 커뮤니티에서는 게시물 연결, 조회 방식, 삭제 주체와 deleted_at을 확인했습니다.
- 비식별 테스트 파일만 사용했고, content URL·고객 자료·비밀값을 공개하지 않았습니다.
대표적인 실패와 다음 판단
이미지 첨부가 거절됨
MIME 타입, magic bytes, 파일 개수와 설정된 크기를 먼저 확인합니다. 지원 형식과 설정값을 확인한 뒤 파일을 줄여 다시 준비합니다.
이미지 없이 질문만 처리됨
attached_files[], 메시지 입력, run의 입력 정보를 대조합니다. 파일 저장과 실제 사용을 분리해 기록하고 실행 근거를 다시 조회합니다.
content URL이 열리지 않음
현재 사용자, 세션, 파일의 소유 범위와 세션 상태를 확인합니다. 다른 사용자의 파일로 바꾸지 말고 owner·session·file 조건을 다시 확인합니다.
커뮤니티 배치 업로드 일부 실패
응답 오류와 row 정리 결과를 함께 확인합니다. 일부 성공으로 기록하지 말고 해당 요청의 전체 상태를 다시 조회합니다.
삭제 뒤 파일이 계속 보임
soft delete, 본문 URL 역참조, 캐시 또는 별도 저장소를 나눠 확인합니다. deleted_at과 게시물 연결을 대조하고 전체 삭제를 단정하지 않습니다.
가져온 에이전트에 첨부가 없음
export preview의 has_attachments와 import summary를 확인합니다. 첨부 binary는 export/import 대상이 아니므로 원본 파일을 별도로 준비합니다.
파일 형식이나 권한 오류를 피하려고 관리자 권한을 임의로 부여하지 마세요. 오류 코드, 파일 식별자, 현재 상태와 사용한 비식별 입력만 승인된 지원 경로에 전달합니다.