API 도구 란?
API 도구는 AI 에이전트가 호출할 외부 API를 미리 등록해 두는 메뉴입니다. 등록된 API 하나하나를 도구라고 하며, AI 에이전트는 대화 상황에 맞는 도구를 스스로 판단해 호출합니다.
주문 조회, 배송 상태 확인처럼 외부 시스템의 정보가 필요한 업무를 AI 에이전트에게 맡길 수 있습니다.
1. API 도구 목록 확인하기
메뉴에 진입하면 등록된 도구 목록이 표시됩니다.
•
폴더별로 조회하기
좌측 상단의 전체 도구 를 눌러 원하는 폴더를 선택하면, 해당 폴더에 속한 도구만 확인할 수 있습니다.
•
원하는 도구 찾기
◦
우측 상단 검색창에 도구명을 입력해 검색합니다.
◦
메서드 또는 사용 상태 필터를 사용하면 조건에 맞는 도구만 볼 수 있습니다.
◦
목록은 업데이트 최신순으로 정렬되어 표시됩니다.
•
목록에서 확인할 수 있는 정보
항목 | 내용 |
폴더명 | 도구가 속한 폴더입니다. 지정하지 않은 경우 '기본 폴더' 또는 '없음'으로 표시됩니다. |
도구명 | 도구를 구분하는 이름입니다. |
도구 프롬프트 | 도구에 대한 설명입니다. 내용이 길면 뒷부분이 생략되어 표시됩니다. |
메서드 | 해당 API의 HTTP 메서드입니다. |
인증명 | 적용된 인증 정보입니다. 설정하지 않은 경우 '없음'으로 표시됩니다. |
사용 여부 | 이 도구를 사용 중인 노드의 개수입니다. 사용하는 노드가 없으면 '미사용'으로 표시됩니다. |
업데이트 일자 | 도구를 마지막으로 수정한 일시입니다. |
사용 상태 | 도구의 사용 여부를 켜고 끌 수 있습니다. |
참고
사용 상태를 끄면 AI 에이전트가 해당 도구를 호출하지 않습니다. 사용 중인 노드가 있는 도구를 끌 경우 노드 동작에 영향을 줄 수 있으니 확인 후 변경해 주세요.
2. API 도구 추가하기
목록 우측 상단의 + API 도구 추가 버튼을 누르면 등록 화면으로 이동합니다.
1단계. 기본 정보 입력
먼저 도구를 어떻게 부를지, 어떤 역할을 하는지 입력합니다.
•
도구명 (필수)
도구를 구분할 이름을 20자 이내로 입력합니다.
•
폴더
도구를 저장할 폴더를 선택합니다. 선택하지 않으면 기본 폴더에 저장됩니다.
•
도구 프롬프트 (필수)
이 도구가 어떤 상황에서 무엇을 하는지 200자 이내로 설명합니다.
◦
예시: 고객 ID로 상세 정보를 조회합니다.
◦
참고
도구 프롬프트는 AI가 도구를 사용할 시점을 판단하는 기준이 됩니다.
설명이 모호하면 의도하지 않은 상황에서 도구가 호출될 수 있으니, 어떤 경우에 사용하는지 구체적으로 작성해 주세요.
2단계. API 설정
호출할 API의 주소와 인증 정보를 설정합니다.
•
HTTP 메서드 (필수)
API에 맞는 메서드를 선택합니다. GET, POST, PUT, PATCH, DELETE 중에서 선택할 수 있습니다.
•
인증 방법
사전에 등록해 둔 인증 정보를 선택합니다. 인증이 필요 없는 API라면 '없음'으로 두면 됩니다.
•
API URL (필수)
호출할 API 주소를 입력합니다. 주소에 상황에 따라 달라지는 값이 포함된다면 {{변수명}} 형식으로 입력합니다.
◦
예시: https://api.example.com/customer/{{customerId}}/orders
•
헤더 추가
API 호출 시 함께 전달할 헤더가 있다면 + 헤더 추가 를 눌러 등록합니다.
등록된 헤더가 없으면 '헤더가 없습니다'라고 표시됩니다.
3단계. 파라미터 설정
API에 전달하거나 응답에서 받아올 값을 설정합니다. 실제 값은 실행 시 AI가 채우므로, 여기에서는 이름과 설명, 속성만 입력하면 됩니다.
•
URL 변수
API URL에 {{변수명}} 형태로 입력한 동적 변수를 등록합니다. 추가 버튼을 눌러 항목을 추가합니다.
◦
참고
API URL에 입력한 변수명과 URL 변수에 등록한 이름이 같아야 정상적으로 값이 전달됩니다.
•
응답 파라미터
API 응답 중에서 다음 노드로 전달할 필드를 등록합니다.
여기에 등록한 필드만 후속 노드에서 사용할 수 있습니다.
4단계. 테스트 및 저장
필수 항목을 모두 입력하면 상단의 API 테스트 와 저장하기 버튼이 활성화됩니다.
•
API 불러오기: 기존에 정의된 API 정보를 가져와 입력값을 자동으로 채웁니다.
•
API 테스트: 설정한 내용으로 실제 API를 호출해 응답을 확인합니다.
•
저장하기: 입력한 내용을 저장하고 도구 등록을 완료합니다.
참고
저장하기 전에 API 테스트로 응답이 정상적으로 돌아오는지 확인해 주세요. 설정 오류를 미리 발견할 수 있습니다.
3. 인증 관리
인증 관리는 외부 API를 호출할 때 필요한 인증 정보를 미리 등록해 두는 메뉴입니다.
여기에 등록한 인증 정보는 API 도구에서 도구를 만들 때 선택하여 사용할 수 있습니다.
인증 정보를 한 번 등록해 두면 여러 도구에서 공통으로 사용할 수 있어, 토큰이나 키가 변경되어도 이곳에서 한 번만 수정하면 됩니다.
1. 인증 정보 목록 확인하기
원하는 인증 정보 찾기
•
우측 상단 검색창에 인증명을 입력해 검색합니다.
•
인증명, 인증 방법, 업데이트 일자 항목을 눌러 정렬 기준을 변경할 수 있습니다.
목록에서 확인할 수 있는 정보
항목 | 내용 |
인증명 | 인증 정보를 구분하는 이름입니다. |
설명 | 인증 정보에 대한 설명입니다. |
인증 방법 | 적용된 인증 방식입니다. Bearer Token, JWT, API Key, Basic auth 중 하나로 표시됩니다. |
업데이트 일자 | 인증 정보를 마지막으로 수정한 일시입니다. |
2. API 도구 인증 추가하기
목록 우측 상단의 + API 도구 인증 등록 버튼을 누르면 등록창이 열립니다.
1단계. 기본 정보 입력
•
인증명 (필수)
인증 정보를 구분할 이름을 입력합니다.
도구를 만들 때 이 이름으로 선택하게 되므로, 어떤 시스템의 인증인지 알아볼 수 있도록 작성해 주세요.
•
설명
인증 정보에 대한 설명을 입력합니다.
어떤 연동에 사용하는 인증인지 적어두면 나중에 구분하기 쉽습니다.
◦
예시: 사내 OMS 연동에 사용하는 인증
2단계. 인증 방법 선택
연동할 API가 요구하는 인증 방식을 선택합니다. 선택한 방식에 따라 아래에 입력할 항목이 달라집니다.
인증 방법 | 입력 항목 |
Bearer Token | Token |
JWT | JWT 토큰 정보 |
API Key | 키 이름 및 키 값 |
Basic auth | 아이디 및 비밀번호 |
3단계. 인증 값 입력 및 저장
인증 방법을 선택하면 해당 방식에 필요한 입력란이 나타납니다. 값을 입력한 뒤 저장하기 를 누르면 등록이 완료됩니다.
•
입력한 값은 보안을 위해 가려진 상태로 표시됩니다. 눈 모양 아이콘을 누르면 입력한 값을 확인할 수 있습니다.
•
복사 아이콘을 누르면 입력한 값을 복사할 수 있습니다.
•
필수 항목을 모두 입력해야 저장하기 버튼이 활성화됩니다.
•
등록을 취소하려면 닫기 를 누릅니다.
참고
등록한 인증 정보를 사용 중인 도구가 있는 경우, 인증 값을 수정하면 해당 도구의 API 호출에 바로 반영됩니다.