Deep Agent Builder 에이전트 가져오기와 내보내기
이 페이지는 에이전트를 ZIP schema v2로 내보내고 다른 워크스페이스에서 가져올 때 확인할 범위와 실패 원인을 설명합니다. 내보내기 미리보기, 실제 다운로드, 가져오기는 서로 다른 단계이며, 파일을 올렸다는 사실만으로 새 에이전트가 완전히 복원됐다고 판단하면 안 됩니다.
이 작업의 범위
내보내기는 세 단계로 나뉩니다.
- export-preview로 내보낼 에이전트와 리소스, 첨부파일 메타데이터, blocker를 확인합니다.
- export를 호출해 schema v2 ZIP을 다운로드합니다.
- import에 ZIP을 multipart file로 전달하고 생성된 에이전트와 요약을 확인합니다.
내보내기에는 USER_AGENT_VIEW와 USER_AGENT_EXPORT 권한이 모두 필요합니다. 가져오기는 USER_AGENT_IMPORT와 USER_AGENT_CREATE가 필요합니다. 원본 리소스를 새 fork로 만들어야 하면 도구, 모델, 스킬별 CREATE 권한도 추가로 검사합니다. 기존 name이나 master link를 그대로 연결할 때는 이 category CREATE 권한이 필요하지 않지만, origin을 새로 설치하면 master 리소스의 RESOURCE_CAN_INSTALL 권한이 추가로 필요합니다. 이름이 비슷한 USER_*_INSTALL 권한을 이 흐름의 기본 권한으로 가정하지 마세요.
내보내기 전에 확인하기
내보내기 전에 다음 조건을 확인합니다.
- 대상 에이전트를 조회할 수 있고 내보내기 권한이 있습니다.
- 에이전트와 하위 에이전트의 순환 참조가 없습니다.
- 각 에이전트 정의에 config.yaml이 있습니다.
- 첨부파일과 secret 값이 ZIP에 포함되지 않는다는 점을 알고 있습니다.
- 가져올 워크스페이스에서 필요한 origin 리소스를 연결하거나 새 fork로 만들 권한이 있습니다.
세부 정보를 볼 수 있는 권한이 없으면 preview의 일부 항목이 마스킹될 수 있습니다. 마스킹된 preview를 완전한 리소스 목록으로 해석하지 말고, 현재 권한으로 확인할 수 있는 범위를 기록하세요.
미리보기 확인
미리보기 주소는 GET /user/agents/{agent_public_uid}/export-preview입니다. 응답에는 에이전트, tools·middlewares·models·skills 리소스, 하위 에이전트, 첨부파일 메타데이터, secret_keys, blocker가 포함됩니다.
미리보기에서 먼저 blocker를 확인합니다.
- CYCLE_DETECTED는 에이전트 또는 하위 에이전트 연결에 순환이 있다는 뜻입니다.
- MISSING_DEFINITION_FILE은 필요한 config.yaml이 없다는 뜻입니다.
blocker가 하나라도 남아 있으면 실제 export는 409 EXPORT_BLOCKED로 거절됩니다. preview를 다시 호출하는 것만으로 이 상태가 해소되지는 않습니다. 순환 참조를 끊거나 누락된 정의 파일을 복구한 뒤 preview를 다시 확인하세요.
첨부파일은 이름, 크기, MIME metadata와 has_attachments 상태로만 확인됩니다. 실제 binary와 secret 값은 내보내기 대상에 포함되지 않습니다. 따라서 가져온 뒤 첨부파일이 자동으로 복원된다고 기대하지 마세요.
ZIP v2를 다운로드하고 보관하기
내보내기 주소는 POST /user/agents/{agent_public_uid}/export입니다. 성공하면 application/zip 응답과 X-Schema-Version: 2 헤더를 받습니다. Content-Disposition에는 ASCII filename과 UTF-8 filename*이 함께 포함될 수 있으며 파일명은 정제된 에이전트 이름과 날짜로 구성됩니다.
ZIP에는 다음 항목이 들어갑니다.
- manifest.yaml
- agents/{agent_uid}/config.yaml
- 선택 항목인 system_prompt.md
- 선택 항목인 chat-opener.yaml
manifest.yaml에는 schema_version, exported_at, exporter, agent, subagents, resources, secret_keys, files_count가 포함됩니다. config에 있던 리소스 식별자는 워크스페이스 안에서 유일한 이름으로 치환될 수 있습니다. 원본 EFS 파일은 export 과정에서 수정하지 않습니다.
내보내기 파일에는 encrypted_value, 첨부파일 binary와 metadata, origin 아래의 정의가 포함되지 않습니다. 개인 리소스 정의도 현재 exporter가 만드는 아카이브에서는 제외되고 origin 참조만 남습니다. 레거시 입력이 personal 항목을 허용할 수 있다는 사실과 현재 exporter가 personal 항목을 생성한다는 사실을 혼동하지 마세요.
다른 워크스페이스로 가져오기
가져오기는 POST /user/agents/import에 multipart file 필드로 ZIP을 전달합니다. 성공 응답은 201 ImportResponse이며 새 에이전트 UID가 발급됩니다. 원본 EFS 경로에 덮어쓰지 않고 가져오기 사용자의 에이전트 경로에 새 버전을 씁니다.
가져오기 검증은 다음 순서로 진행됩니다.
- 인증과 RBAC를 확인합니다.
- Idempotency-Key replay 여부를 확인합니다.
- multipart 형식과 ZIP signature를 확인합니다.
- ZIP 안전성과 크기·개수 제한을 확인합니다.
- manifest와 schema v2를 확인합니다.
- tree, cycle, 참조, config를 확인합니다.
- origin과 조건부 리소스 권한을 확인합니다.
- cross-workspace 여부를 계산합니다.
origin이 기존 사용자 fork와 일치하면 연결하고, 허용되는 경우 새 fork를 만듭니다. 설치되지 않았거나 ABAC 권한이 거부됐거나 값이 맞지 않는 origin은 import 실패로 처리하지 않고 건너뛸 수 있습니다. 이때 ImportResponse의 origin_unmatched_skipped가 증가합니다.
가져오기 결과에서는 agent, subagents, created_resources, source, summary를 확인합니다. summary의 agents_created와 각 리소스 생성 수를 실제 기대 범위와 비교하세요. has_attachments_excluded가 true라면 첨부파일은 제외된 상태로 가져온 것입니다. missing_secret_keys는 현재 계약에서 secret이 실제로 등록됐는지를 검사하지 않으므로 항상 빈 배열 []로 반환됩니다. 이 값만으로 실제 secret 등록 여부를 확인했다고 판단하지 마세요.
subagent는 가져올 때 새 UID를 받습니다. 여러 곳에서 공유되는 child는 하나의 행으로 합쳐질 수 있고, source.is_cross_workspace로 원본과 다른 워크스페이스에서 온 것인지 확인할 수 있습니다. 가져온 뒤에는 원본 UID가 그대로 유지된다고 가정하지 말고 새 parent_uid와 생성된 리소스 UID를 사용하세요.
제한값과 오류 판단
각 한도는 초과할 때 거절됩니다. 한도와 정확히 같은 값은 통과할 수 있습니다.
| 검사 대상 | 제한 |
|---|---|
| 압축 아카이브 | 50 MiB 초과 시 거절 |
| 압축 해제 전체 크기 | 500 MiB 초과 시 거절 |
| 단일 entry | 50 MiB 초과 시 거절 |
| entry 개수 | 5,000개 초과 시 거절 |
| 디렉터리 깊이 | 10 초과 시 거절 |
오류 코드는 다음 기준으로 구분합니다.
- 400 IMPORT_FILE_CORRUPT: ZIP, manifest, YAML, 참조, cycle, config 형식을 확인합니다.
- 413 PAYLOAD_TOO_LARGE: detail의 limit_kind가 archive, decompressed, entry, entries 중 무엇인지 확인합니다.
- 415 UNSUPPORTED_MEDIA_TYPE: schema version이 지원 버전 2인지 확인합니다.
- 422 UNPROCESSABLE_ENTITY: multipart 자체의 형식을 확인합니다.
- 503 IMPORT_FILESYSTEM_ERROR: 파일 반영과 보상 처리 경계를 확인합니다.
503이 반환되면 단순히 ZIP을 다시 올리지 마세요. 파일 반영이 어디까지 진행됐는지와 결과 조회 방법을 먼저 확인해야 합니다. 현재 문서는 안전한 자동 재시도를 보장하지 않습니다.
멱등키의 한계
Idempotency-Key가 있으면 성공 응답과 replay 가능한 4xx 응답이 Redis에 24시간 동안 best-effort로 저장됩니다. Redis 읽기나 쓰기가 실패하면 같은 키를 사용해도 새 import가 진행될 수 있습니다. 따라서 멱등키가 중복 생성을 절대적으로 막는다고 가정하지 말고, 요청 결과가 불명확할 때 먼저 생성된 에이전트와 summary를 조회할 수 있는지 확인하세요.
키가 없으면 같은 ZIP을 다시 올릴 때마다 새 에이전트가 생성될 수 있습니다. timeout이나 네트워크 오류 뒤에는 실패로 단정하기 전에 생성 여부를 확인하고, 확인 경로가 없으면 반복 요청을 멈춘 뒤 승인된 지원 절차를 따르세요.
완료 확인
가져오기가 끝났다고 판단하려면 다음 항목을 순서대로 확인합니다.
- 응답의 새 agent UID와 lifecycle_status를 확인합니다.
- subagents와 created_resources의 수가 기대 범위와 맞는지 비교합니다.
- origin_unmatched_skipped와 has_attachments_excluded를 확인합니다.
- 다른 워크스페이스에서 온 작업인지 source.is_cross_workspace를 확인합니다.
- 가져온 에이전트를 열어 필요한 리소스와 설정이 연결됐는지 확인합니다.
- 비식별 테스트 입력으로 실제 실행 결과를 확인합니다.
ZIP 수락, 201 응답, 새 에이전트 생성은 서로 다른 확인점입니다. 첨부파일, secret, origin 매칭, 실행 권한이 모두 복원됐다는 뜻은 아닙니다.