Deep Agent Builder 즐겨찾기, Workspace, 다운로드
에이전트와 도구를 다시 찾거나 다른 Workspace에서 쓰고, 파일과 에이전트 구성을 내려받을 때 확인하는 페이지입니다. 즐겨찾기는 개인 목록이고 Workspace 자원은 별도 권한 범위를 가지며, 다운로드는 파일 다운로드와 에이전트 Export를 구분해야 합니다.
즐겨찾기와 개인 목록을 구분하기
즐겨찾기 대상은 skill, command, agent 세 종류입니다. 등록 정보는 사용자별로 저장되므로 다른 사용자의 즐겨찾기가 섞이지 않습니다.
즐겨찾기 API의 목록 조회에는 USER_FAVORITE_READ 권한이 필요합니다. 등록과 해제에는 USER_FAVORITE_REGISTER 권한이 필요합니다. 등록 요청은 target_kind와 target_id를 보내며, 이미 같은 대상이 등록돼 있으면 새 행을 만들지 않고 기존 항목을 돌려줍니다. 해제는 대상이 이미 없어도 본문 없는 성공 응답을 반환하는 멱등 동작입니다.
에이전트의 즐겨찾기 상태만 PATCH할 때는 USER_AGENT_VIEW만 필요합니다. 이름, 지침, 도구처럼 다른 필드를 함께 바꾸면 USER_AGENT_EDIT도 필요합니다. 따라서 목록에서 즐겨찾기 상태만 바꾸는 작업과 에이전트 구성을 저장하는 작업을 같은 권한으로 판단하지 마세요.
Workspace에서 자원 범위 확인하기
Workspace 목록과 상세 정보는 현재 사용자의 활성 멤버십 범위에서 조회합니다. Workspace에서 자원을 조회할 때는 개인 READ 권한과 Workspace READ 권한이 함께 필요할 수 있습니다. 자원을 설치할 때는 유형별 Workspace 권한, 자원의 ABAC 조건, 소유자와 Workspace 경계를 확인하며, 설치 요청 자체에 개인 READ 권한이 항상 필요한 것은 아닙니다. 화면에 보이는 권한 정보는 참고값이고, 실제 허용 여부는 서버가 판정합니다.
Workspace 자원을 사용하기 전에 다음을 확인합니다.
- 현재 선택한 Workspace와 사용자의 멤버십이 의도한 대상인지 확인합니다.
- 자원 종류가 tool, skill, model 중 무엇인지 확인합니다. Workspace 설치 계약에서 지원하는 유형은 이 세 가지입니다.
- 해당 유형의 Workspace READ 권한과 자원의 설치 조건을 확인합니다.
- 개인 자원이나 개인 에이전트를 Workspace에 등록하는 경우 등록 요청인지 즉시 승인인지 확인합니다. 자동 승인 권한이 없으면 요청이 pending 상태로 남을 수 있습니다.
- 이미 설치된 개인 fork를 덮어쓰는 작업이라면 수정된 fork인지 확인합니다. force_overwrite 없이 수정된 fork를 덮어쓰는 요청은 충돌로 거부될 수 있습니다.
Workspace의 /me/privileges 응답은 화면을 그리는 데 참고할 수 있지만, 서버 권한 검사를 대신하지 않습니다. Workspace 전환 UI와 기본 Workspace 변경은 이 근거만으로 지원 범위를 확정할 수 없으므로, 화면에서 보이는 선택 상태를 저장 완료로 해석하지 마세요.
개인 에이전트 파일을 다운로드하기
개인 에이전트 파일 목록은 USER_AGENT_VIEW 권한으로 조회합니다. 목록에는 파일 식별자, 이름, 크기, MIME type, 업로드 시각, 다운로드 URL과 처리 상태가 포함될 수 있습니다. 특정 파일 다운로드는 에이전트 공개 식별자와 파일 UID를 사용합니다.
파일을 확인할 때는 다음 순서를 지킵니다.
- 현재 에이전트가 의도한 대상인지 확인합니다.
- 파일 목록에서 이름, 크기, MIME type, processing_status를 확인합니다.
- 다운로드 URL이 가리키는 파일과 목록의 UID가 같은지 확인합니다.
- 처리 중이거나 실패한 파일은 즉시 다운로드 성공으로 판단하지 않습니다. status와 failure_reason을 먼저 확인합니다.
- 내려받은 파일의 내용과 파일명을 비식별 테스트 자료 기준으로 확인합니다.
파일 목록·조회·다운로드는 USER_AGENT_VIEW 범위이고, 업로드·삭제·short-link 생성은 USER_AGENT_EDIT 범위입니다. 다운로드 권한이 있다고 해서 파일을 수정하거나 삭제할 수 있는 것은 아닙니다.
에이전트 구성을 ZIP으로 내보내기
에이전트 구성을 다른 Workspace로 옮기려면 파일 다운로드와 별도로 Export 절차를 사용합니다. 먼저 Export preview에서 에이전트, 자원, subagent, 파일, blocker를 확인한 뒤 실제 Export를 요청합니다.
- Export preview를 조회해 첨부파일 포함 여부, 자원 참조, 순환 참조와 정의 파일 누락을 확인합니다.
- USER_AGENT_VIEW와 USER_AGENT_EXPORT 권한이 모두 있는지 확인합니다.
- blocker가 없을 때만 실제 Export를 실행합니다. 순환 참조나 필수 정의 파일 누락이 있으면 CYCLE_DETECTED 또는 MISSING_DEFINITION_FILE blocker로 다운로드가 막힙니다.
- 내려받은 ZIP에 manifest.yaml과 에이전트 config.yaml이 있는지 확인합니다. system_prompt.md와 chat-opener.yaml은 있을 때만 포함됩니다.
- secret 값과 첨부파일 binary가 Export에 포함되지 않는다는 점을 확인합니다. Export된 파일만으로 새 Workspace의 연결 권한이나 secret 등록이 끝났다고 판단하지 않습니다.
Export 응답은 application/zip이며 schema version 2를 표시합니다. Import는 별도 작업으로, USER_AGENT_IMPORT와 USER_AGENT_CREATE가 필요하고 새 fork가 필요한 tool, model, skill에는 추가 생성 권한이 필요할 수 있습니다. 원본 Workspace와 다른 Workspace로 가져왔는지는 결과의 cross-workspace 정보를 다시 확인합니다.
대표 실패와 다음 판단
| 증상 | 먼저 확인할 것 | 다음 판단 |
|---|---|---|
| 즐겨찾기 등록이 거부됨 | USER_FAVORITE_REGISTER, target_kind, 대상 소유권 | 권한 거부인지 대상 없음인지 구분합니다. |
| 즐겨찾기 목록이 비어 있음 | USER_FAVORITE_READ, 현재 사용자 범위, limit | 다른 사용자의 목록이나 다른 Workspace 목록으로 잘못 조회한 것은 아닌지 확인합니다. |
| Workspace 자원이 보이지 않음 | 멤버십, 유형별 READ 권한, ABAC 조건 | 서버 권한 범위와 화면 필터를 분리해 확인합니다. |
| 파일을 내려받을 수 없음 | USER_AGENT_VIEW, 파일 UID, processing_status | 처리 실패나 만료된 링크인지 status와 응답을 확인합니다. |
| Export가 409로 막힘 | preview의 blockers, cycle, config.yaml | 원인을 해결한 뒤 preview를 다시 조회하고 Export를 재시도합니다. |
| Import 후 자원이 달라짐 | origin 매칭, 새 fork 생성, cross-workspace 결과 | 원본 연결과 새 fork를 구분하고 필요한 권한을 다시 확인합니다. |
완료 기준
즐겨찾기, Workspace 사용, 다운로드를 각각 다음 상태로 확인하면 작업이 끝난 것입니다.
- 즐겨찾기 대상과 현재 사용자 범위가 일치합니다.
- Workspace 멤버십과 자원별 사용 권한이 확인됐습니다.
- 파일 다운로드라면 파일 UID, 처리 상태, 실제 파일을 대조했습니다.
- 에이전트 Export라면 preview blocker가 없고 ZIP 구조와 제외된 secret·첨부 범위를 확인했습니다.
- Import까지 했다면 새 에이전트, 자원 연결, cross-workspace 결과를 별도로 확인했습니다.
화면의 실제 메뉴명, 즐겨찾기 아이콘, Workspace 전환 위치와 다운로드 버튼 문구는 현재 근거에서 확정하지 않았습니다. 해당 절차를 화면 안내로 제공하려면 비식별 테스트 환경에서 먼저 촬영하고 본문과 대조해야 합니다.