.png&blockId=2f5c0b11-04dd-81c7-b7a4-c1cf5f0b414b&width=3600)
1. 도구 관리란?
AI가 실제 업무를 수행할 수 있도록 외부 시스템(API)과 연동하는 기능으로
외부 서버의 데이터를 조회하거나, 특정 작업을 실행하는 등 실제 업무 행동을 수행할 수 있습니다.
기능 설명
•
API(Application Programming Interface)를 등록하고 설정하여 AI가 외부 시스템과 통신할 수 있도록 합니다.
•
등록된 도구는 챗봇 시나리오의 AI 에이전트 블록에서 선택해 사용할 수 있습니다.
2. 폴더 관리
도구를 성격이나 용도에 따라 폴더로 분류해 관리할 수 있습니다.
2-1. 폴더 구조
.png&blockId=2f5c0b11-04dd-81a5-8357-dc4d6cfd0cbf)
No. | 구분 | 설명 |
1 | 기본 폴더 | - 시스템에서 기본으로 제공하는 폴더
- 삭제하거나 이름 변경 불가능
- 별도 폴더를 지정하지 않고 지식을 추가하면 기본 폴더에 저장 |
2 | 일반 폴더 (사용자 정의) | - 사용자가 직접 생성한 폴더
- 폴더 추가 버튼을 통해 생성할 수 있으며, 이름 수정 및 삭제 가능 |
주의
일반 폴더를 삭제하면 폴더 안에 포함된 모든 도구가 함께 삭제됩니다.
삭제 전에 중요한 도구가 포함되어 있는지 반드시 확인하세요.
3. 도구 목록 및 조회
등록된 전체 도구를 한눈에 확인하고 관리할 수 있습니다.
.png&blockId=2f5c0b11-04dd-81a4-a177-e31728e49f5e)
3-1. 필터 및 정렬
상단 필터를 통해 원하는 도구를 빠르게 찾을 수 있습니다.
.png&blockId=2f5c0b11-04dd-8170-8d42-f183626de828)
No. | 구분 | 설명 |
1 | 폴더 | - 전체 또는 특정 폴더 기준으로 도구 조회 |
2 | 메소드 | -HTTP 메소드(GET, POST, PUT, PATCH, DELETE) 기준 조회 |
3 | 사용 상태 | - 활성(ON) / 비활성(OFF) 상태별 조회 |
4 | 정렬 | - 업데이트 일자 컬럼을 선택해 내림차순/오름차순 정렬 가능 |
3-2. 일괄 관리 기능 (체크박스 활용)
체크박스를 활용해 여러 도구를 한 번에 관리할 수 있습니다.
No. | 구분 | 설명 |
1. | 지식 선택 (단일 / 다중) | - 체크박스를 통해 지식을 단일 또는 다중 선택할 수 있음 |
3. | 체크박스 선택 시 버튼 노출 | - 하나 이상의 지식을 선택하면 폴더 이동 / 활성화 / 비활성화 / 삭제 버튼 노출
- 단일·다중 선택 여부와 관계없이 선택된 모든 지식에 동일한 액션이 일괄 적용됨 |
2. | 지식 활성 / 비활성 | -선택한 지식의 사용 상태를 ON / OFF로 한 번에 설정 가능 |
TIP : 사용 중인 도구 삭제
•
선택한 도구가 시나리오에서 사용 중인 경우, 삭제 시 경고 팝업이 노출됩니다.
•
안정적인 서비스 운영을 위해 삭제 전 도구 상세 화면에서 사용처를 확인하고 연결을 해제한 후 삭제 하는 것을 권장합니다.
4. 도구 추가 및 상세 설정
새로운 API 도구를 등록하는 과정입니다.
[경로]
개발자 도구 → 새 도구 추가
4-1. 기본 정보 입력
No. | 구분 | 설명 |
1 | 도구명 | - AI가 도구를 식별하는 이름
- 중복 불가, 최대 20자 입력 가능 |
2 | 폴더 | - 도구가 저장될 폴더 선택 |
3 | 설명 | - 도구의 용도나 기능을 간단히 메모 |
4-2. API 설정
외부 서버와 통신하기 위한 API 연동 정보를 입력합니다.
.png&blockId=2f5c0b11-04dd-81a7-bed8-eb643a125b8b)
No. | 구분 | 설명 |
1 | HTTP 메소드 | - 호출 방식 선택: GET, POST, PUT, PATCH, DELETE
※ GET 선택 시 요청 본문(Body)은 사용할 수 없음 |
2 | API URL | - http:// 또는 https://로 시작하는 전체 API 주소 입력
- 경로 변수(Path Variable) 사용
1) URL 경로 중 동적으로 변경되는 값은 {{variableName}} 형식으로 입력
2) 예시: http://api.shop.com/orders/{{orderId}}
- 자동 변수 추가 기능
1) URL에 {{variableName}} 형식이 포함된 경우
2) 하단 ‘파라미터 설정’ 영역에서 해당 변수를 URL 변수로 추가할 수 있는 ‘모두 추가’ 버튼이 활성화됨 |
3 | 인증 방법 | - 인증 관리 메뉴에 등록된 인증 정보(API Key, Token 등) 선택 |
4 | 헤더 추가 | - API 호출 시 필요한 공통 헤더 설정 |
4-3. 파라미터 설정
AI가 API를 호출할 때 어떤 데이터를 전달하고, 어떤 데이터를 받을지 데이터를 설정합니다.
.png&blockId=2f5c0b11-04dd-81de-b722-f6be294eeeff)
No. | 구분 | 설명 |
1 | 변수 구분 | - URL 변수: API 경로 또는 쿼리 스트링에 포함되는 변수
- 요청 파라미터: API 호출 시 함께 전달되는 데이터
- 응답 파라미터: API 호출 결과로 반환되는 데이터 구조 |
2 | 변수 타입과 구조 | - 지원 타입: string, number, boolean, datetime, array, object
- 단순 값뿐만 아니라 object, array 형태의 계층 구조도 설정 가능 |
3 | 변수 타입과 구조
- Object / Array 구조 설정 | - Object와 Array는 최대 10단계(depth)까지 하위 구조 설정 가능
- object: 여러 변수를 하나의 그룹으로 묶을 때 사용
- array: 리스트 형태의 데이터를 정의할 때 사용
1) array 선택 시 하위 변수명이 arrayValue로 자동 생성되며, 해당 타입 설정을 통해 리스트 내부 아이템 구조를 정의 |
4 | 주요 설정 옵션
(필수/시스템 변수) | - 각 파라미터 우측 토글을 통해 옵션을 설정할 수 있음
- 필수: API 호출 시 반드시 값이 필요한 변수
- 시스템 변수: AI(LLM)가 개입하지 않는 변수로, 봇 내부에 설정된 값이 그대로 API에 전달 |
단순화 필요
상세설정 TIP
•
변수 설명은 AI가 값을 판단하는 기준이 됩니다. 가능한 한 구체적으로 작성하세요.
◦
예) 도시별 날씨 정보를 호출하는 API라면city 변수 설명에 “사용자가 날씨를 문의한 도시 이름”과 같이 입력해야 합니다.
•
변수명 제약
◦
변수명은 영문 대소문자로 시작해야 하며, 공백은 사용할 수 없습니다.
◦
특수문자는 _, -만 허용되며 최대 20자까지 입력할 수 있습니다.
5. 사용처 관리 및 유효성 검사
5-1. 사용처 확인
도구 상세 화면 하단의 ‘사용처 관리’ 탭에서 해당 도구를 사용 중인 봇 → 시나리오 → 블록 정보를 확인할 수 있습니다.
.png&blockId=2f5c0b11-04dd-8149-894f-caa6ec320a78)
No. | 구분 | 설명 |
1 | 멀티봇 지원 | - 하나의 도구를 여러 봇에서 사용하는 경우, 봇 단위로 탭을 구분하여 사용 중인 시나리오와 블록 목록 확인 가능 |
2 | 시나리오 편집
바로가기 | - 각 사용처 항목의 ‘시나리오 편집’ 버튼을 클릭하면, 해당 도구를 사용 중인 블록 위치로 즉시 이동하여 시나리오 수정 가능 |
6. API 테스트
설정한 API 정보가 정상적으로 동작하는지 사전에 검증하는 기능입니다.
도구 선택 후 ‘API 테스트’ 버튼을 통해, 해당 도구에 설정한 API 정보(URL, 파라미터, 인증 등)가 정상적으로 호출되는지 확인하는 테스트 기능입니다.
[경로]
개발자 도구 목록 → 도구 선택 → API 테스트
6-1. 요청 설정 (좌측)
API를 호출하기 위한 사전 정보를 입력하는 영역
No. | 항목 | 설명 |
1 | 요청 URL | - 설정한 URL과 HTTP 메소드 표시 |
2 | 인증 방법 | - 현재 적용된 인증 정보 표시 |
3 | 헤더 | - 설정한 공통 헤더 정보 표시 (수정 불가) |
4 | 파라미터 설정 | - URL / Query 파라미터: URL 경로 변수({{id}}) 또는 쿼리 스트링(?key=value) 값 입력
- 필수 항목은 ‘필수’ 배지로 표시되며, 입력한 값은 API 호출 시 자동으로 치환되어 적용
- JSON 본문: POST / PUT / PATCH 메소드 사용 시, 전송할 데이터를 JSON 형식으로 직접 입력하거나 수정할 수 있음 |
5 | 실행 버튼 | ‘API 테스트’ 버튼 클릭 시 요청 전송 |
6-2. 결과 확인 (우측)
API 호출 후 서버로부터 받은 응답 결과를 보여주는 영역
.png&blockId=2f5c0b11-04dd-8152-b36a-f5481a6dff64)
No. | 구분 | 설명 |
1 | 실행된 요청 정보 | - 실제 호출된 완성된 요청 URL 표시 (보안 정보 제외) |
2 | 응답 상태 | - Status Code: 200 OK(성공), 400 Bad Request(오류) 등 HTTP 상태 코드 표시
- Response Time: 요청 후 응답까지 소요된 시간(ms)을 표시해 성능 확인 가능 |
3 | 응답 헤더 | 서버에서 반환한 헤더 정보 |
4 | 응답 데이터 | 서버에서 반환된 JSON 데이터 출력 |
주의
응답 데이터는 JSON 형식인 경우에만 정상 처리됩니다.
6-3. 자주 발생하는 오류
API 테스트 실행 시 200 OK가 반환되지 않는 경우, 아래 항목을 확인해주세요.
에러코드 | 설명 |
400 Bad Request | - 필수 파라미터가 누락되었거나, 파라미터 타입(숫자/문자 등)이 API 명세와 다를 경우 발생 |
401 Unauthorized | - 인증 정보가 올바르지 않은 경우입니다. 인증 관리 메뉴에서 API Key 또는 토큰 값이 정확한지, 만료된 값은 아닌지 확인 필요 |
404 Not Found | - 요청한 URL이 잘못되었거나, 입력한 경로 변수에 해당하는 데이터가 서버에 존재하지 않는 경우 |