Deep Agent Builder 도구와 스킬 구성
도구는 에이전트가 외부 시스템과 통신하거나 작업을 실행하는 자원이고, 스킬은 작업 절차와 전문 지식을 참고하는 자료입니다. 이 페이지는 두 자원의 경계를 구분하고, 에이전트에 연결한 뒤 무엇을 확인해야 하는지 설명합니다.
도구와 스킬은 무엇이 다른가
도구는 검색, API 호출, 파일 처리처럼 에이전트 바깥의 결과를 가져오거나 동작을 실행합니다. 스킬은 에이전트가 그 결과를 어떤 순서와 기준으로 다룰지 정리합니다.
예를 들어 외부 서비스에서 데이터를 가져오는 일은 도구의 책임입니다. 가져온 데이터를 어떤 항목으로 비교하고 어떤 형식으로 보고할지는 지침이나 스킬에 적습니다. 도구와 스킬에 같은 절차를 중복해서 쓰면 수정할 때 두 내용이 어긋날 수 있습니다.
도구가 연결됐다는 사실만으로 업무가 끝난 것은 아닙니다. 사용 권한, 실행 설정, 시크릿, 입력 형식이 모두 맞아야 실제 호출이 성공합니다. 스킬도 저장됐다고 바로 원하는 답변을 보장하지 않으므로, 실제 업무 입력으로 결과를 확인해야 합니다.
도구 유형과 선택 기준
Deep Agent Builder에서 확인할 수 있는 도구는 연결 경로와 관리 주체에 따라 나뉩니다.
- 플랫폼이 제공하는 사전 제공 도구
- 사용자가 직접 등록한 개인 도구
- MCP stdio 도구
- MCP HTTP 도구
- 일반 HTTP 도구
- 커넥터 도구
- 지식 기반 도구
- MCP 하위 도구
같은 MCP 도구라도 stdio와 HTTP는 연결 유형과 실행 경계가 다릅니다. 도구 목록에서 MCP 유형을 확인하고, 실제 연결과 실행에 필요한 조건을 따로 점검하세요.
도구함과 지식함은 목록에서 분리해 표시됩니다. 에이전트 수정 화면에서 지식은 도구 선택 목록에 섞이지 않고 별도의 지식함에서 확인합니다. 도구 목록 조회 결과에 지식 항목이 보이지 않는 것은 오류가 아니라 이 분리 규칙 때문입니다. 지식함을 확인하려면 지식함 목록을 따로 여세요.
도구를 고를 때는 다음 질문에 답할 수 있어야 합니다.
- 이 에이전트가 해당 도구를 사용할 권한이 있는가
- 실행에 필요한 시크릿과 설정이 준비됐는가
- 업무에 필요한 입력과 출력 형식이 맞는가
- 외부 호출 실패나 시간 초과를 어떻게 판단할 것인가
- 연결 후 실제 업무 입력으로 시험할 수 있는가
도구를 많이 연결하면 선택지가 늘어나지만, 업무와 관계없는 도구가 섞이면 에이전트가 잘못된 자원을 선택할 가능성도 커집니다. 필요한 업무와 직접 연결되는 도구부터 추가하세요.
도구 등록 전에 확인할 항목
개인 HTTP 도구와 MCP HTTP 도구를 등록할 때는 이름, 유형, 변형, 설정 내용을 함께 검증합니다. HTTP 도구는 메서드, 엔드포인트, 인증 방식, 파라미터의 형식과 위치를 사용합니다. GET이나 DELETE 요청에 본문 파라미터를 넣는 것처럼 메서드와 맞지 않는 설정은 검증 단계에서 거부될 수 있습니다.
커넥터 도구는 연결 주소에 인증 값을 포함하는 방식과 헤더로 인증하는 방식 중 하나만 쓸 수 있습니다. 주소에 인증 값을 포함했다면 인증 헤더를 함께 보내지 마세요. 두 방식을 같이 쓰면 등록이 거부됩니다.
MCP 도구는 엔드포인트, 템플릿, 헤더, 환경 변수와 같은 연결 설정을 사용합니다. 등록 과정에서 자격 증명 값 자체를 일반 설정 문서에 남기지 않고 환경 키 참조로 관리하는 경우가 있으므로, 설정 저장과 실제 실행에 필요한 시크릿 준비를 따로 확인하세요.
이름에는 형식, 길이, 중복 검사가 적용됩니다. 중복 검사는 전역 카탈로그와 현재 사용자의 개인 도구 범위를 확인합니다. 등록 결과에서 오류가 나면 이름을 계속 바꾸기보다 검증 결과와 오류 원인을 먼저 확인하세요.
연결 프로브와 도구 실행 테스트는 같은 검사가 아닙니다. 연결 프로브는 엔드포인트 도달성과 응답 요약을 확인하고, 실행 테스트는 실제 인수와 시크릿을 사용해 호출 결과를 확인합니다. 두 검사가 성공해도 업무 결과의 적합성까지 확인한 것은 아닙니다.
실행 테스트와 독립 실행도 별개입니다. 독립 실행은 에이전트 대화를 거치지 않고 등록된 도구를 직접 호출하는 경로입니다. 이 경로를 쓰려면 도구 사용 권한이 필요하고, 목록 조회나 등록 권한만으로는 실행할 수 없습니다. 독립 실행에서는 실행할 도구와 버전, 호출 형식을 먼저 조회한 뒤 그 조회 결과에 담긴 버전과 이름으로 호출합니다. 조회한 뒤 도구가 갱신됐으면 버전이 일치하지 않아 실행이 거부될 수 있으므로, 다시 조회한 뒤 새 형식에 맞게 입력을 검토하세요. 실행 결과와 오류에는 시크릿 값이 표시되지 않습니다.
개인 도구에는 파라미터 기본값을 따로 저장할 수 있습니다. 기본값은 도구 메타데이터 수정과 별개 권한으로 관리되며, 본인이 보유한 도구에만 적용됩니다. 기본값을 저장해도 도구 원본이 바뀌지는 않습니다. 실행 시점에는 에이전트별 설정이 기본값보다 우선하고, 기본값은 도구가 요구하는 필수 입력이 빠지지 않도록 채우는 용도로 확인하세요.
도구 설정과 권한
도구 목록·상세 조회 결과에서는 유형, 표시 이름, 사용 가능 여부와 편집 가능 여부를 확인합니다. 상세 결과에는 파라미터 스키마, 필요한 환경 키, 하위 도구 같은 추가 정보가 포함될 수 있습니다. 시크릿 값과 연결 확인용 헤더 값은 상세 결과에서 제거되거나 가려져 표시될 수 있습니다.
개인 도구는 소유자가 연결과 수정을 직접 관리할 수 있습니다. 작업 공간이나 카탈로그에서 연결된 도구는 사용은 가능해도 일부 필드가 읽기 전용일 수 있습니다. 사용 가능 여부와 편집 가능 여부를 같은 권한으로 해석하지 마세요.
설정을 바꿀 때는 다음 순서로 확인합니다.
- 변경하려는 항목이 편집 가능한지 확인합니다.
- 메타데이터만 바꾸는지 실행 설정도 바꾸는지 구분합니다.
- 시크릿, 환경 설정, 외부 API가 필요한지 확인합니다.
- 저장 뒤 에이전트에 표시되는 자원과 권한 상태를 다시 확인합니다.
- 필요한 입력으로 도구 실행 테스트를 합니다.
MCP 도구는 설정 저장 뒤 연결 탐색과 목록 재조회가 실행될 수 있습니다. 연결 탐색에 필요한 시크릿이 없으면 설정 갱신이 중단될 수 있습니다. 저장 설정에서 실제 자격 증명 값이 제외되는지와 연결 탐색에 필요한 입력이 무엇인지는 별도로 확인하세요.
MCP 도구를 사용할 때
MCP stdio는 연결 대상 프로세스의 실행 상태를, MCP HTTP는 서버 연결과 인증 상태를 먼저 확인합니다. 그 다음 에이전트에 표시되는 도구 목록과 하위 도구를 확인하세요.
MCP 하위 도구를 지정할 때는 도구 호출 인수와 하위 도구 선택을 구분해야 합니다. 선택 필드가 누락되거나 파라미터 형식이 맞지 않으면 도구 자체가 연결돼 있어도 실행이 실패할 수 있습니다.
실행 결과는 정상, 오류, 시간 초과와 같은 상태로 반환될 수 있습니다. 하위 도구를 찾지 못한 경우와 잘못된 파라미터를 보낸 경우도 별도로 판단합니다. 오류가 발생하면 먼저 자원 사용 권한, 하위 도구 이름, 입력 스키마, 시크릿과 연결 상태를 순서대로 확인하세요.
도구 테스트와 삭제
도구 테스트는 연결 확인과 실행 확인으로 나눠 기록하는 편이 좋습니다.
| 확인 종류 | 확인할 내용 |
|---|---|
| 연결 확인 | 엔드포인트 도달 여부, 인증 설정, 응답 요약 |
| 실행 확인 | 실제 인수와 필요한 시크릿을 사용한 호출 결과, 상태, 오류 |
도구 사용처 조회로 해당 도구를 참조하는 에이전트를 먼저 확인합니다. 사용 중인 에이전트가 있다면 삭제가 실행에 미치는 영향을 판단한 뒤 진행하세요.
단건 삭제는 하나의 도구를 처리하고, 일괄 삭제는 여러 도구 ID를 한 번에 처리합니다. 단건 삭제에서 사용 중인 도구를 강제 옵션 없이 제거하면 충돌이 반환될 수 있습니다. 일괄 삭제에 소유하지 않은 ID가 섞이면 전체 작업이 중단될 수 있고, 사용 중인 도구 처리도 충돌 여부를 확인해야 합니다. 강제 삭제는 참조 관계와 함께 도구 자체를 제거할 수 있으므로, 강제 옵션의 범위를 먼저 확인해야 합니다.
일괄 삭제는 삭제가 일부만 적용될 수 있는 작업이 아닙니다. 다만 삭제 결과가 바깥의 다른 기록까지 즉시 정리된다는 보장은 없으므로, 삭제 뒤 목록에서 실제로 빠졌는지 확인하세요. 개인 도구를 삭제해도 다른 사용자가 사용하는 같은 도구나 카탈로그의 원본까지 함께 사라진다고 가정하지 마세요.
스킬을 만들고 관리하는 방법
스킬은 파일을 업로드하거나 편집기에서 작성하거나 대화로 초안을 만들 수 있습니다. 문서 작성용 스킬은 문서 파일 여러 개를 묶은 ZIP 압축 파일로 등록할 수도 있습니다. ZIP 등록에서는 압축 파일 안에 스킬 기준 문서가 정확히 하나 있어야 하고, 허용된 파일 형식만 담을 수 있습니다. 압축 파일이 크면 등록이 거부될 수 있고, 같은 이름의 스킬이 이미 있으면 덮어쓰기로 진행하지 않는 한 등록이 거부됩니다. 어떤 방식으로 만들었는지보다 스킬이 다루는 업무 범위와 참고 시점이 중요합니다.
스킬에는 에이전트가 반복해서 참고할 절차와 전문 지식을 적습니다. 업무와 무관한 내용을 한 스킬에 계속 추가하면 필요한 규칙을 찾기 어려워집니다. 하나의 스킬이 담당하는 업무 경계를 먼저 정하고, 관련 없는 절차는 별도 스킬이나 지침으로 나누세요.
스킬을 바꾼 뒤에는 다음을 확인합니다.
- 새 내용이 저장됐는지 확인합니다.
- 스킬의 사용처와 에이전트 연결 상태를 확인합니다.
- 스킬이 필요한 입력을 넣어 답변의 절차와 형식을 확인합니다.
- 기대와 다른 결과가 나오면 스킬 내용, 에이전트 지침, 도구 결과 중 원인을 분리합니다.
스킬을 삭제하기 전에도 사용처를 확인하세요. 사용 중인 에이전트가 있다면 삭제 뒤 어떤 지침을 잃는지 확인하고 대체 자원을 준비해야 합니다.
도구와 스킬을 함께 구성하는 순서
두 자원을 함께 쓸 때는 외부 결과를 가져오는 부분과 결과를 해석하는 부분을 나눠 적습니다.
- 에이전트의 업무와 필요한 외부 결과를 정합니다.
- 필요한 결과를 제공하는 도구의 유형, 권한, 시크릿, 입력 스키마를 확인합니다.
- 결과를 해석하고 답변으로 정리할 절차를 지침이나 스킬에 적습니다.
- 도구와 스킬을 에이전트에 연결하고 표시 상태를 확인합니다.
- 실제 업무와 비슷한 입력으로 연결, 실행, 답변 품질을 각각 확인합니다.
- 실패 원인이 도구 설정인지, 권한인지, 스킬과 지침인지 구분해 수정합니다.
연결 성공만 확인하고 끝내지 마세요. 외부 API가 응답해도 권한이나 입력이 틀리면 업무 결과가 달라질 수 있고, 스킬이 충분해도 필요한 도구가 없으면 에이전트는 외부 작업을 수행할 수 없습니다.
삭제와 변경 뒤에 남겨야 할 확인
도구나 스킬을 변경한 뒤에는 변경 대상의 이름과 상태, 에이전트 연결 상태, 사용 권한, 실제 실행 결과를 함께 기록합니다. 실행 결과가 기대와 다르면 이름이나 설명만 바뀐 것으로 결론 내리지 말고 다음 범위를 나눠 확인하세요.
- 자원이 에이전트에 실제로 연결됐는가
- 사용 권한과 편집 권한을 혼동하지 않았는가
- 시크릿과 환경 설정이 실행 시점에 준비됐는가
- 입력 파라미터와 MCP 하위 도구 선택이 맞는가
- 스킬이 현재 업무의 절차와 판단 기준을 설명하는가
공개 매뉴얼에서 확인할 범위
이 페이지는 공개 매뉴얼의 일반 Markdown 본문에서 도구와 스킬의 사용 조건을 설명합니다. 내부 코드 경로, 고객 정보, 시크릿과 실제 운영 접속 정보는 공개 본문에 포함하지 않습니다. 화면 캡처가 필요하면 비식별 데모 환경에서 별도로 검토하고, 촬영 전에는 실제 메뉴와 상태를 확인하세요.