음성 에이전트가 호출할 수 있는 커스텀 함수를 생성할 수 있습니다. 호출 시, 에이전트는 함수 이름과 매개변수를 포함한 POST 요청을 지정된 URL로 보냅니다.

이 문서에서는 커스텀 함수 구현에 대한 예제와 가이드를 제공합니다. 예제 함수 문서를 참고하여 커스텀 함수 호출 기능을 구현하고 테스트 해보세요.

​
1. 커스텀 함수 설정하기

1

대시보드에서 커스텀 함수 추가

  1. 함수 섹션에서 “+추가” 버튼을 클릭합니다.
  2. 드롭다운 메뉴에서 API 호출을 선택합니다.
2

함수 세부정보 구성

  • 커스텀 함수의 이름과 설명을 추가합니다.
  • 이름은 고유해야 하며, 알파벳으로 작성되어야 합니다.

예시:

  • 이름: get_weather
  • 설명: 도시의 날씨 정보를 가져옵니다.
3

엔드포인트 URL 추가

POST 요청을 보낼 URL을 입력합니다.
4

Parameters 정의

JSON 스키마 형식을 사용해 함수의 parameters를 정의합니다.

참고 자료:

예시 parameters 스키마:

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "날씨 정보를 조회할 도시"
    }
  },
  "required": ["city"]
}
5

음성 동작 구성

함수 실행 중 에이전트의 음성 동작을 설정합니다.

​
실행 중 음성 활성화

  • 함수 실행 중 에이전트가 응답하도록 설정 (e.g. “잠시만요, 바로 확인해드리겠습니다”)
6

에이전트 테스트

설정이 완료되면 에이전트와 대화하며 커스텀 함수를 테스트합니다.

  1. 에이전트와 대화를 시작합니다
  2. 함수와 관련된 질문을 해봅니다 (예: “서울의 날씨는 어때요?”)
  3. 에이전트의 응답과 함수 실행이 의도한 대로 작동하는지 확인합니다

​
2. 문제 해결

​
2-1. 커스텀 함수 저장 실패

커스텀 함수 저장에 실패한 경우, Parameters가 올바르지 않을 가능성이 높습니다.

자주 발생하는 실수:

  • JSON 스키마 최상단에 "type": "object" 누락

    Tip: 제공된 Example 1~3를 참고하여 수정하세요

​
3. API 서버 설정 방법

커스텀 함수를 처리하는 API 서버는 다음 사항을 준수해야 합니다:

  • POST 요청의 body의 형태는 {"args": {"city": "서울"}} 형태로 전달 되어야 합니다.
  • 응답은 반드시 {"result": "결과값"}의 형식으로 반환해야 합니다

[ Whitelist IP 주소 = 34.123.198.226 ] vox.ai IP 주소를 확인하고 허용 목록에 추가하여 보안을 강화할 수 있습니다.

from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.post("/get-weather")
async def get_weather(post_body: dict):
    try:
        args = post_body["args"]
        if args["city"] == "서울":
            return {"result": "섭씨 25도"}
        elif args["city"] == "부산":
            return {"result": "섭씨 20도"}
        else:
            return {"result": "섭씨 15도"}
    except Exception as err:
        return {"result": "날씨 정보 없음"}

​
도움이 필요하신가요?