웹훅 도구

도구를 사용하면 어시스턴트를 외부 데이터 및 시스템에 연결할 수 있습니다. 어시스턴트가 액세스할 수 있는 도구 세트를 정의하면, 대화에 따라 적절한 경우 어시스턴트가 이를 사용합니다.

개요

많은 애플리케이션에서는 어시스턴트가 실시간 정보를 얻기 위해 외부 API를 호출해야 합니다. 도구를 사용하면 어시스턴트가 타사 앱에 외부 함수 호출을 수행하여 실시간 정보를 가져올 수 있습니다.

도구가 유용한 몇 가지 예시는 다음과 같습니다.

• 데이터 가져오기: 어시스턴트가 사용자에게 응답하기 전에 REST를 지원하는 모든 데이터베이스 또는 타사 통합에서 실시간 데이터를 검색하도록 합니다.
• 작업 수행: 회의 일정 예약이나 주문 반품 시작과 같이 대화에 따라 어시스턴트가 인증된 작업을 실행하도록 합니다.

도구 구성

ElevenLabs 에이전트에는 외부 API와 상호작용할 수 있는 도구를 추가할 수 있습니다. 일반적인 요청과 달리 어시스턴트는 제공한 대화 및 매개변수 설명을 바탕으로 쿼리, 본문, 경로 매개변수를 동적으로 생성합니다.

모든 도구 구성과 매개변수 설명은 어시스턴트가 이러한 도구를 언제 그리고 어떻게 사용할지 결정하는 데 도움이 됩니다. 도구 사용을 효과적으로 오케스트레이션하려면 이러한 호출의 순서와 로직을 지정하도록 어시스턴트의 시스템 프롬프트를 업데이트하세요. 여기에는 다음이 포함됩니다.

• 어떤 도구를 어떤 조건에서 사용할지
• 도구가 정상적으로 작동하는 데 필요한 매개변수
• 응답을 처리하는 방법

가이드

이 가이드에서는 모든 위치의 실시간 날씨 정보를 제공할 수 있는 날씨 어시스턴트를 만듭니다. 어시스턴트는 지리 지식을 활용해 위치 이름을 좌표로 변환하고 정확한 날씨 데이터를 가져옵니다.

You are a helpful conversational agent with access to a weather tool. When users ask about
weather conditions, use the get_weather tool to fetch accurate, real-time data. The tool requires
a latitude and longitude - use your geographic knowledge to convert location names to coordinates
accurately.
Never ask users for coordinates - you must determine these yourself. Always report weather
information conversationally, referring to locations by name only. For weather requests:
1. Extract the location from the user's message
2. Convert the location to coordinates and call get_weather
3. Present the information naturally and helpfully
For non-weather queries, provide friendly assistance within your knowledge boundaries. Always be
concise, accurate, and helpful.
First message: "Hey, how can I help you today?"

지원되는 인증 방식

ElevenLabs Agents는 도구를 외부 API에 안전하게 연결할 수 있도록 여러 인증 방식을 지원합니다. 인증 방식은 에이전트 설정에서 구성한 후 필요에 따라 개별 도구에 연결합니다.

구성한 후 이러한 인증 방식을 도구에 연결하고 도구 구성에서 사용자 지정 헤더를 관리할 수 있습니다.

OAuth2 클라이언트 자격 증명

OAuth2 클라이언트 자격 증명 흐름을 자동으로 처리합니다. 클라이언트 ID, 클라이언트 시크릿, 토큰 URL(예: https://api.example.com/oauth/token)로 구성하세요. 선택적으로 쉼표로 구분한 값으로 범위와 추가 JSON 매개변수를 지정할 수 있습니다. 에이전트 설정 페이지의 Agent 섹션에 있는 Workspace Auth Connections에서 Add Auth를 클릭해 설정하세요.

OAuth2 JWT

OAuth 2.0 JWT Bearer 흐름에 JSON 웹 토큰 인증을 사용합니다. JWT 서명 시크릿, 토큰 URL, 알고리즘(기본값: HS256)이 필요합니다. 발급자, 대상, 주체를 포함한 JWT 클레임을 구성하세요. 선택적으로 키 ID, 만료 시간(기본값: 3600초), 범위 및 추가 매개변수를 설정할 수 있습니다. 에이전트 설정 페이지의 Agent 섹션에 있는 Workspace Auth Connections에서 Add Auth를 클릭해 설정하세요.

기본 인증

HTTP Basic Auth를 지원하는 API를 위한 간단한 사용자 이름 및 비밀번호 인증입니다. 에이전트 설정 페이지의 Agent 섹션에 있는 Workspace Auth Connections에서 Add Auth를 클릭해 설정하세요.

Bearer 토큰

요청 헤더에 bearer 토큰 값을 추가하는 토큰 기반 인증입니다. 도구 구성에 헤더를 추가하고 헤더 유형으로 Secret을 선택한 다음 Create New Secret을 클릭하여 구성하세요.

사용자 지정 헤더

독점 인증 방식을 위해 원하는 이름과 값으로 사용자 지정 인증 헤더를 추가하세요. 도구 구성에 헤더를 추가하고 name 및 value를 지정하여 구성하세요.

모범 사례

상세한 설명과 함께 직관적으로 도구 이름 지정

어시스턴트가 올바른 도구를 호출하지 않는다면, 각 도구를 선택해야 하는 시점을 더 명확히 이해하도록 도구 이름과 설명을 업데이트해야 할 수 있습니다. 도구 및 인수 이름을 줄이기 위해 약어나 두문자어를 사용하지 마세요.

도구를 호출해야 하는 시점에 관한 자세한 설명을 포함할 수도 있습니다. 복잡한 도구의 경우, 어시스턴트가 해당 인수를 수집하기 위해 사용자에게 무엇을 물어봐야 하는지 알 수 있도록 각 인수의 설명을 포함해야 합니다.

상세한 설명과 함께 직관적으로 도구 파라미터 이름 지정

도구 파라미터에는 명확하고 설명적인 이름을 사용하세요. 해당하는 경우 설명에 파라미터의 예상 형식을 지정하세요(예: 날짜의 경우 YYYY-mm-dd 또는 dd/mm/yy).

어시스턴트의 시스템 프롬프트에 도구를 호출하는 방법과 시점에 관한 추가 정보 제공 고려

시스템 프롬프트에 명확한 지침을 제공하면 어시스턴트의 도구 호출 정확도를 크게 향상할 수 있습니다. 예를 들어, 다음과 같은 지침으로 어시스턴트를 안내하세요.

Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.

복잡한 시나리오에는 컨텍스트를 제공하세요. 예를 들면 다음과 같습니다.

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

LLM 선택

함수 호출의 성공에는 LLM 선택이 중요합니다. 일부 LLM은 대화에서 관련 파라미터를 추출하는 데 어려움을 겪을 수 있습니다.

도구 호출 사운드

도구 실행 중 재생할 앰비언트 오디오를 구성하여 사용자 경험을 향상할 수 있습니다. 자세한 내용은 도구 호출 사운드를 참조하세요.