도구란
도구는 에이전트가 통화 중에 호출하는 실제 작업이에요. AI는 말만 할 수 있지만, 도구를 연결하면 예약을 저장하고, 배송 상태를 조회하고, 통화를 끊고, 상담사에게 넘길 수 있어요. 통화 중 이런 일이 벌어져요. AI가 언제 도구를 부를지는 **설명(description)**을 보고 판단해요. 설명이 부실하면 도구가 있어도 부르지 않아요.도구 종류
도구는 크게 두 묶음이에요. 밖으로 요청을 보내는 외부 연동 세 가지와, 통화에 직접 붙는 내부 도구 여섯 가지예요.외부 연동
내부 도구
나가는 요청이 없어서 주소와 인증 칸이 아예 없어요. 통화 자체를 다루는 동작이에요.
자세한 내용은 아래 내부 도구에서 다뤄요.
어느 종류든 등록하고 발행해야 통화에 나가요. 아래 발행하기를 꼭 읽어 주세요.
API Request 도구 만들기
가장 많이 쓰는 종류예요. 이미 있는 REST API를 그대로 등록해요. 서버에 새로 만들 것이 없어요. 설정은 접었다 펴는 묶음으로 나뉘어 있어요. 처음엔 기본 설정과 요청 스키마만 채워도 돼요.
기본 설정
도구 이름과 나갈 주소를 정해요.1
도구 추가 열기
도구 모음 화면 오른쪽 위 
+ 도구 추가를 누르면 만들 종류를 먼저 골라요.
API 를 눌러요.2
이름·주소 넣기
- 도구명: 포털 목록에 보이는 이름이에요.
- Function Name: AI가 호출할 때 쓰는 함수 이름이에요. 영소문자로 시작하고
영소문자, 숫자, 밑줄만 써요.
이름 생성버튼으로 도구명에서 만들어 줘요. - 설명: AI가 이 도구를 언제 부를지 판단하는 유일한 근거예요. 구체적으로 적어요.
- 엔드포인트 URL: 메서드(GET, POST, PUT, PATCH, DELETE)와 주소를 넣어요.
파라미터가 전달되는 방식이 메서드에 따라 달라요. GET이면 쿼리스트링,
나머지는 JSON 본문으로 보내요.
3
응답 대기 상한 정하기
이 시간 안에 응답이 없으면 실패로 처리해요. 1초에서 60초, 기본 15초예요.통화 중에는 침묵이 길게 느껴지니 응답이 빠른 API일수록 짧게 잡으세요. 서버에 접속조차
안 되는 경우는 이 값과 무관하게 곧바로 실패로 처리해요.
인증
API를 부를 때 붙일 자격증명을 정해요. 값은 암호화되어 저장되고, 수정할 때 비워 두면 기존 값이 유지돼요.요청 스키마
AI가 채워 보낼 파라미터를 정의해요. 칸을 하나씩 추가하는 편집기로 만들고, 저장될 JSON을 바로 아래 미리보기로 보여줘요.
인자마다 값 변환을 걸 수 있어요. AI가 받아 온 값을 API가 받는 모양으로 바꿔서 보내요.
아래 값 변환을 보세요.
필요한 데이터를 한국어로 나열하고 한글로 적어도 영문 snake_case 이름으로 바꿔 주고(“상품명”을
AI 자동 생성을 누르면 초안이 채워져요.item_name으로), 금액이나
수량은 number, 예와 아니오는 boolean으로 잡아요. (선택)이라고 적은 항목만 선택
항목이 돼요.만들어진 것은 초안이에요. 이름과 타입이 실제 API와 맞는지 확인하고 고쳐서 저장해요.요청 헤더
인증 말고 더 붙일 헤더가 있으면 적어요. 이름과 값을 한 줄씩 넣어요.고정 필드
모델이 뭐라고 하든 이 값으로 보내요. 발신번호처럼 틀리면 안 되는 값은 반드시 여기에 두세요. 이름은 상대 API가 받는 그대로 적어요. 한글 키를 쓰는 API면 한글로 적으면 돼요.응답 변수
응답에서 꺼내 뒤 단계로 넘길 값을 정해요.응답 변수 별칭
꺼낸 값을 프롬프트에서 부를 이름을 정해요. 응답 변수 이름과 그 값을 꺼내는 추출 식(예:{{ $.data.status }})을 짝으로 적어요.
이름에 한글을 써도 돼요. 이 이름은 통화 중에 값으로 바뀌어 사라지니 AI가 볼 일이
없거든요. 다만 점이 든 이름은 쓸 수 없어요 — 점은 서버가 채우는 값의 표시예요.
자세한 규칙은 도구 응답 별칭을 보세요.
값 변환
고객이 말한 값과 API가 받는 값의 모양이 다를 때, 가운데서 바꿔 줘요. 요청 인자와 응답 변수 별칭 양쪽에 걸 수 있어요. 예를 들어 고객이 주민등록번호를 말하면, 그중 생년월일만 뽑아1990-01-01 모양으로 바꿔
보낼 수 있어요. 반대로 API가 20260914 를 돌려주면 「2026년 9월 14일」로 바꿔 담을 수
있어요.
변환은 스무 가지가 다섯 묶음으로 나뉘어 있어요.
여러 개를 이어 붙일 수 있어요. 위에서 아래 순서로 차례대로 적용돼요.
샘플 값으로 미리보기에 실제 값을 넣어 보면 결과가 바로 보여요. 저장하기 전에 한 번
확인하세요.
값 매핑표는 「표에 없으면 그대로」와 「표에 없으면 오류」 중에 고를 수 있어요. 코드값을
사람이 읽는 말로 바꿀 때(예:
01 → 「접수 완료」) 써요.실행 안내 문안
도구가 도는 동안 무슨 말을 할지 정해요. 응답이 늦어질 때 침묵 대신 내보낼 말을 적고, 몇 초 뒤에 말할지도 정할 수 있어요.MCP 도구 만들기
MCP 서버 하나를 연결하면 그 서버가 노출하는 원격 도구 전부가 자동으로 등록돼요. 도구를 하나씩 만들 필요가 없어요.1
종류를 MCP로 고르기
+ 도구 추가 › 종류 MCP를 눌러요. 요청 스키마 입력란이 사라져요.스키마를 쓰지 않는 이유는 MCP 서버가 자기 도구 목록과 파라미터를 스스로 알려주기
때문이에요. 통화가 시작될 때 서버에 접속해 목록을 받아 각각을 AI 함수로 등록해요.
2
서버 URL과 인증 넣기
- MCP Server URL: MCP 서버의 Streamable HTTP 주소
- 인증: 서버가 요구하는 방식(대개 Bearer 토큰)
3
설명 쓰고 추가하기
설명은 이 서버 묶음이 무엇을 다루는지 적어요. 개별 도구의 설명은 서버가 주는 것을 써요.
A2A 도구 만들기
다른 AI 에이전트에게 일을 맡겨요. 우리 봇이 통화를 하면서, 판단이 필요한 부분만 상대 에이전트에게 물어보고 답을 받아 이어서 말해요.1
종류를 A2A로 고르기
+ 도구 추가 › 종류 A2A를 눌러요.2
Agent Card URL 넣기
상대 에이전트의 Agent Card 주소를 넣어요. 서비스 주소가 아니라 카드 주소예요.
3
이름·설명·인증 넣고 추가하기
상대가 요구하는 인증 방식을 골라요. Basic 인증은 아이디와 비밀번호를 따로 입력해요.
이름과 설명, 인증은 직접 입력해요. 포털이 Agent Card를 미리 읽어 채워 주지는
않아요.
카드를 못 읽거나 스킬 목록이 비어 있으면 단일 함수로 내려가서 도구가 통째로 사라지는 일은
없어요. 상대가 잠시 죽어도 통화는 계속돼요. 호출 제한 시간은 20초예요(외부 에이전트 왕복 포함).
내부 도구 자세히
나가는 요청이 없는 도구예요. 주소와 인증 칸이 없고, 종류마다 필요한 설정만 받아요.통화 종료
봇이 스스로 통화를 끊어요. 이 도구를 붙이면 수신 통화에서도 끊을 수 있어요. 이때는 종료할지 먼저 확인하고 고객이 그렇다고 답한 뒤에만 끊어요. 마지막 인사말을 고정 문구로 정하거나, 모델이 그때그때 짓게 하거나, 아예 말하지 않게 할 수 있어요.시간 초과나 무음으로 강제로 끊을 때 나가는 말은 여기가 아니라
대화 설정에서 정해요.
상담사 전환
고객을 사람 상담사에게 넘겨요. 전화로 넘길지(SIP), 브라우저로 넘길지(WebRTC)를 여기서 정해요. 상담사가 쓰는 앱의 주소와 로그인 계정은 상담APP에서 관리해요.키패드 전송
봇이 상대편 ARS 안내를 듣고 키패드 번호를 눌러요. 누를 번호는 통화 중에 모델이 고르므로 미리 정할 설정이 없어요. SIP로 연결된 통화에서만 톤이 전달돼요. 웹콜에는 받을 상대가 없어요.문자 발송
통화 상대에게 문자를 보내요. 문안은 등록할 때 정하고 모델은 변수만 채워요. 수신번호는 SIP 수신 통화에만 있어요. 웹콜이나 발신 통화에는 상대 번호가 없어요.지식 검색
골라 둔 지식에서 답을 찾아요. 에이전트에 붙이는 지식이 매 발화마다 자동으로 도는 것과 달리, 이 도구는 모델이 필요하다고 판단할 때만 호출해요. 도구마다 지식을 갈라 두면 프롬프트가 어느 쪽을 뒤질지 지목할 수 있어요. 에이전트 크루에서만 동작해요.스피커
적어 둔 고지나 안내 문구를 원문 그대로 읽어요. 읽는 동안에는 고객이 말하거나 키패드를 눌러도 끊기지 않아요. 고객에게 물을 말(예: 동의 여부)은 문구 끝에 함께 적으세요.발행하기
도구를 저장하는 것과 통화에 내보내는 것은 다른 동작이에요.1
저장
편집 창에서 고친 내용이 도구 행에 저장돼요. 아직 통화에는 영향이 없어요.
2
발행
목록에서
발행을 누르면 지금 저장된 설정이 v1, v2 처럼 판으로 굳어요.
통화는 이 판을 읽어요.버전 기록
버전 기록을 열면 지금까지 발행한 판이 보여요. 과거 판을 불러오기 하면 그 내용이
편집 폼으로 되살아나요. 고객에게 나가는 판이 바로 바뀌지는 않아요. 반영하려면 다시
발행해야 해요.
에이전트에는 운영 반영이라는 관문이 하나 더 있지만, 도구에는 없어요. 발행하는 순간
그 판이 통화에 쓰여요.
에이전트에 연결하기
도구를 등록하고 발행했다고 바로 쓰이지 않아요. 에이전트에 연결해야 통화에 나가요. 에이전트 관리 › 도구 탭에서 연결해요. 탭 안이 세 갈래예요.- 지식: 등록한 지식 중 이 에이전트가 참조할 항목
- 도구 연결: 만들어 둔 도구를 직접 붙여요
- 도구 시나리오: 정해진 순서로 진행되는 통화 흐름
시나리오에서 쓸 때
시나리오의 Tool 호출 노드에 연결할 수 있는 종류는 API Request 하나뿐이에요. MCP나 A2A를 연결하면 통화 중 호출이 실패해요. 원격 도구가 여러 개 노출될 때 어느 것을 부를지 정할 방법이 없기 때문이에요. MCP와 A2A는 도구 연결에서 그대로 쓸 수 있어요. 시나리오의 수집 항목은 도구의 요청 스키마에서 그대로 만들어져요. 파라미터를 바꾸면 시나리오도 새로 만들어야 해요. 자세한 사용법은 도구 시나리오와 도구 시나리오 예제를 보세요.어떤 종류를 고를까요
관리하기
내보내기 / 가져오기 (Export / Import)
도구를 파일로 내보내고, 파일에서 도구를 만들어요. 고객사가 준 API 규격 파일을 그대로 올리면 그 안의 API 하나하나가 도구가 돼요. 손으로 하나씩 등록할 필요가 없어요.가져올 수 있는 파일 (Import)
형식은 파일을 열어 자동으로 알아봐요. 무엇인지 고를 필요가 없어요. 무엇으로 읽었는지는 미리보기 제목 밑에
감지된 형식: OpenAPI 3.1.0 처럼 보여요. 의도한 형식이 아니면 파일을 다시 확인해요.
JSON만 받아요. YAML로 된 OpenAPI 문서는 JSON으로 바꿔서 올려요. 시나리오 묶음 파일은 이 화면이
아니라 에이전트 › 도구 탭의
시나리오 가져오기에서 올려요.가져오기 순서
1
파일 고르기
도구 모음 오른쪽 위
가져오기를 누르면 가져올 수 있는 형식과 주의할 점이 먼저 나와요. 그 창에
.json 파일을 끌어다 놓거나 파일 선택으로 골라요. JSON이 아닌 파일은 받지 않아요.2
출처 확인
미리보기 맨 위 출처 칸에 파일 제목(OpenAPI
info.title, Postman info.name)이 미리 들어 있어요.
주문 API v2 처럼 알아보기 쉬운 이름으로 고쳐도 돼요. 같은 계정에서 쓴 출처가 제안으로 떠요.
가져온 도구마다 이 출처가 붙어서 도구 모음에서 출처로 거를 수 있어요. 80자까지예요.3
미리보기에서 고르기
파일 안의 도구가 목록으로 나와요. 체크박스로 원하는 것만 골라요. 목록 머리의
전체 선택으로 한 번에
켜고 끌 수 있어요. 한 번에 50개까지 가져올 수 있어요.
도구마다 이름, 메서드 주소, 그리고 확인이 필요한 경고가 붙어요. 인증이 필요한 도구에는
자격증명 필요 표시가 있어요.
규격 파일(OpenAPI, Swagger, Postman)이면 목록 위에 이 파일에서 자동으로 만든 것 카드가 나와요.
도구 수, 인자 수, 응답 변수 수, 인증 방식별 수, 그리고 손으로 할 것(서버 주소, 자격증명)이 한눈에 보여요.
도구마다 자동: 인자 N · 응답 변수 N · 인증 X 한 줄이 붙고, 문서에 성공 응답이 적힌 도구에는
응답 변수 N개 자동 아래에 만들어질 응답 변수 별칭의 이름과 경로가 펼쳐져 있어요.
누르면 접을 수 있어요.4
자격증명과 서버 주소는 파일당 한 번
인증이 필요한 도구가 있으면 자격증명 칸이 인증 방식별로 하나씩 나와요(
Bearer 토큰, API 키,
Basic 아이디와 비밀번호). 여기 넣으면 고른 도구 전부에 저장돼요. 비워 두면 가져온 뒤 도구마다 입력해요.
파일 안의 값은 읽지 않아요.
호스트 없는 도구(/api/v3/pet 처럼 경로만 있는 주소)가 있으면 서버 주소 칸이 나와요.
https://api.example.com 처럼 호스트까지만 넣으면 그 도구들 주소 앞에 붙고, 상대 경로 경고는 사라져요.5
같은 이름이 이미 있으면
같은 Function Name의 도구가 계정에 이미 있으면
이미 있음 표시와 함께 그 기존 도구가 부르는 주소가
기존: GET https://... 로 보여요. 같은 API면 기존 도구 재사용, 이름만 같은 다른 API면 새로 만들기를 골라요.6
가져오기
가져오기를 누르면 고른 도구가 발행된 상태(v1) 로 도구 모음에 추가돼요. 바로 에이전트에 연결할 수 있어요.
자격증명 칸을 비워 둔 채 가져왔으면 완료 문구에 자격증명을 다시 넣어야 하는 도구가 나와요. 도구를 열어
토큰이나 키를 입력해요.
규격 파일에서 가져온 도구는 편집 창 첫 줄에 OpenAPI 3.0.4 파일에서 가져온 도구예요 안내가 있고,
인증, 요청 스키마, 응답 변수 별칭 묶음 제목에 가져올 때 자동 생성 표식이 붙어요. 고치면 고친
대로 저장되고 표식은 그대로 남아요. 내보내기 파일에는 이 표식이 들어가지 않아요.규격 파일이 도구로 바뀌는 규칙
OpenAPI와 Swagger는 같은 규칙이에요.
Postman은 규격이 아니라 예시 요청 모음이라 몇 가지를 추정해요.
미리보기 경고 읽는 법
경고는 가져오기를 막지 않아요. 도구는 만들어지지만 그대로 두면 통화에서 호출이 실패할 수 있는 것을 알려줘요.직접 해 보기
공개된 예제 규격으로 흐름을 확인할 수 있어요. 아래 주소를 브라우저로 열어.json 으로 저장한 뒤 가져와요.
내보내기 (Export)
카드의내보내기를 누르면 파일이 내려와요. 종류에 따라 형식이 달라요.
내보낸 파일을 다시 가져오면 헤더, 고정 필드, 응답 변수, 문안, 값 변환까지 그대로 돌아와요. 빠지는 것은
인증 값 하나예요. 지금은 도구 한 개씩 내보내요.
주소가
/api/v3 처럼 상대 경로인 도구는 OpenAPI로 내보낼 수 없어요. 먼저 절대 주소로 고쳐요.
주의사항
- 발행하지 않으면 통화에 나가지 않아요. 도구가 안 불릴 때 가장 먼저 볼 곳이에요.
- 도구를 저장한 뒤에는 종류를 바꿀 수 없어요. 삭제하고 다시 등록해요.
- 도구를 삭제하면 그 도구를 연결한 에이전트에서도 함께 빠져요.
가져오기할 때 토큰이나 키 같은 자격증명은 어떤 파일에서도 읽지 않아요. 가져온 뒤 다시 입력해요.- 인증 값은 암호화되어 저장돼요. 수정할 때 비워 두면 기존 값이 유지돼요.
- Function Name 은 영소문자로 시작하고 영소문자·숫자·밑줄만 써요. 대문자와 하이픈, 한글은 안 돼요. API Request 는 64자, 나머지 종류는 40자까지예요.
- AI가 도구를 안 부른다면 설명을 구체적으로 고쳐요. 설명이 판단의 유일한 근거예요.