Deep Agent Builder 명령과 재사용
반복해서 입력하는 요청을 명령으로 저장하고, 필요한 워크스페이스에서 다시 찾아 사용할 때 참고하는 페이지입니다. 이 문서에서는 명령을 만들고 재사용할 때 확인할 권한, 입력 조건, 검색 범위와 실패 원인을 설명합니다. 명령 관리 API와 에이전트 복제·내보내기 계약을 근거로 작성했으며, 화면의 메뉴명과 배치는 촬영 전 확인이 필요합니다.
명령과 에이전트 재사용의 차이
명령은 반복 입력할 prompt와 이름을 저장하는 단위입니다. 에이전트는 모델, 지침, 도구, 스킬처럼 업무 실행에 필요한 구성을 함께 보관하는 단위입니다. 짧은 요청을 여러 에이전트에서 반복하려면 명령을 사용하고, 업무 규칙과 연결 자원까지 같은 형태로 다시 쓰려면 에이전트를 복제하거나 내보내기·가져오기 경로를 검토합니다.
저장됐다는 사실만으로 실행 권한이나 결과 품질이 보장되지는 않습니다. 명령을 만든 뒤에는 목록에 남았는지, 실행할 워크스페이스에서 검색되는지, 실제 입력에 적용됐는지를 따로 확인합니다.
명령을 만들기 전에 확인할 것
명령을 만들려면 명령 생성 권한이 필요합니다. 저장할 이름은 영문 소문자로 시작해야 하며, 소문자와 숫자, 밑줄을 조합해 최대 32자까지 작성합니다. 앞뒤 공백은 제거된 뒤 검사됩니다.
prompt는 앞뒤 공백을 제거한 뒤 비어 있지 않아야 하고 최대 2,000자입니다. 설명은 선택 사항이지만, 비슷한 명령을 구분할 수 있도록 사용 목적을 적는 편이 좋습니다. 실제 고객 자료, 인증값, 호스트 주소와 같은 민감한 정보를 prompt나 설명에 넣지 마세요.
명령 만들기와 저장 확인
- 명령 관리 화면에서 새 사용자 명령을 시작합니다. 실제 메뉴와 버튼 이름은 제품 화면에서 확인합니다.
- 이름, 선택 사항인 설명, 반복해서 사용할 prompt를 입력합니다.
- 저장을 실행합니다.
- 저장 결과를 확인합니다. 정상 생성은 사용자 명령 목록에 새 항목이 추가된 상태로 판단하며, API 계약상 생성 응답은 201입니다.
- 같은 목록을 다시 조회해 이름과 prompt가 의도한 값으로 남았는지 확인합니다.
이름이 형식에 맞지 않거나 prompt가 비어 있거나 2,000자를 넘으면 서버는 값을 잘라 저장하지 않고 validation error로 거부합니다. 같은 사용자의 사용자 명령과 이름이 겹치면 conflict가 발생합니다. 내장 명령과 이름이 같다는 이유만으로 사용자 명령 생성이 막히는 계약은 확인되지 않았습니다.
워크스페이스에서 명령 다시 찾기
워크스페이스의 명령 검색은 내장 명령과 사용자가 만든 명령을 함께 조회하는 읽기 전용 동작입니다. 검색어를 입력하면 이름 또는 설명의 대소문자를 구분하지 않는 부분 일치로 찾습니다. 검색어는 1자 이상 64자 이하여야 하며, 검색어를 생략하는 것과 빈 문자열을 명시하는 것은 다릅니다. 빈 문자열을 보내면 검증 오류가 발생합니다.
검색 결과는 내장 명령과 사용자 명령을 분리해 보여주는 형태입니다. 검색 한도 기본값은 각 그룹마다 30개이고, 1부터 100 사이에서 조정할 수 있습니다. 검색에는 명령 조회 권한과 워크스페이스 조회 권한이 모두 필요합니다.
재사용 전에 다음 순서로 확인합니다.
- 현재 에이전트와 워크스페이스가 의도한 대상인지 확인합니다.
- 명령 이름 또는 설명으로 검색합니다.
- 내장 명령인지 사용자 명령인지 확인합니다.
- prompt의 대상, 입력 형식과 필요한 도구를 확인합니다.
- 명령을 적용한 뒤 결과가 저장된 명령의 의도와 맞는지 확인합니다.
검색 결과가 없으면 이름의 철자와 설명의 검색어를 바꿔 다시 확인합니다. 그래도 결과가 없으면 현재 사용자가 워크스페이스 구성원인지, 명령 조회 권한이 있는지, 해당 명령이 삭제되거나 다른 범위에 저장되지 않았는지 순서대로 확인합니다.
에이전트를 복제해 다른 용도로 쓰기
명령보다 더 큰 구성을 재사용하려면 기존 에이전트를 복제하는 경로를 검토합니다. 복제본은 원본과 구분되는 이름을 먼저 정하고, 지침, 모델, 도구, 스킬, 파일과 실행 설정을 새 업무에 맞게 다시 확인합니다.
복제 후에는 원본과 복제본을 같은 입력으로 비교합니다. 원본의 지침이나 연결 자원이 복제본에서 자동으로 같은 권한을 갖는다고 가정하지 마세요. 저장 권한, 자원 사용 권한, 실행 권한은 서로 다를 수 있습니다.
내보내기·가져오기를 사용할 때는 파일이 만들어졌다는 사실과 새 에이전트에 구성이 적용됐다는 사실을 나눠 확인합니다. 가져온 뒤에는 이름과 설명, 지침, 모델, 자원 연결 상태를 다시 열어 보고 테스트 입력을 보내야 합니다.
삭제와 변경의 경계
내장 명령은 사용자 명령 삭제 대상으로 보지 않습니다. 사용자 명령 삭제는 소유자와 대상이 모두 맞는 경우에만 수행되며, 성공하면 본문 없는 응답으로 끝납니다. 대상이 없거나 다른 사용자의 명령이면 같은 not found 범위로 처리됩니다.
삭제하기 전에 해당 명령을 사용하는 에이전트와 업무를 확인하세요. 삭제 후에도 이미 진행 중인 대화나 과거 실행의 표시가 어떻게 남는지는 이 명령 관리 계약만으로 확정할 수 없습니다. 화면과 실제 실행 결과를 별도로 확인합니다.
대표 실패와 다음 판단
| 증상 | 먼저 확인할 것 | 다음 판단 |
|---|---|---|
| 저장 버튼을 눌러도 생성되지 않음 | 이름 형식, prompt 공백, prompt 길이, 생성 권한 | validation error인지 권한 거부인지 구분합니다. |
| 같은 이름을 저장할 수 없음 | 같은 사용자가 만든 명령 목록 | 기존 명령을 수정할지 이름을 바꿀지 결정합니다. |
| 검색 결과가 비어 있음 | 검색어 길이, 빈 문자열 여부, 워크스페이스 소속, 조회 권한 | 다른 워크스페이스에서 찾는 것이 아닌지 확인합니다. |
| 검색이 잠시 후 거부됨 | 반복 조회 횟수와 rate limit | 잠시 재시도하기 전에 검색 요청을 줄이고 제한 초과 여부를 확인합니다. |
| 복제본의 실행 결과가 다름 | 모델, 지침, 도구·스킬 연결, 실행 권한 | 저장 상태와 실행 상태를 각각 다시 확인합니다. |
워크스페이스 명령 검색에는 사용자와 client IP를 기준으로 한 fixed-window rate limit이 적용됩니다. 기본 설정은 60초 동안 60회이며, 실제 환경에서 값이 바뀔 수 있습니다. 429가 발생하면 검색 요청을 반복하지 말고 제한과 호출 빈도를 확인합니다.
완료 기준
명령 재사용은 다음 네 가지를 모두 확인했을 때 완료로 판단합니다.
- 명령 또는 복제본이 목록에 저장되어 있습니다.
- 현재 워크스페이스에서 필요한 명령과 자원이 검색됩니다.
- 현재 사용자에게 조회, 사용과 실행에 필요한 권한이 있습니다.
- 비식별 테스트 입력으로 결과가 기대한 업무와 맞는지 확인했습니다.
화면의 실제 메뉴명, 저장 성공 메시지, 명령을 입력하는 위치와 모바일 배치는 이번 근거에서 확정하지 않았습니다. 화면 안내가 필요하면 비식별 테스트 환경에서 해당 상태를 먼저 촬영하고 본문 절차를 다시 대조해야 합니다.