클라이언트 도구

클라이언트 도구를 사용하면 어시스턴트가 클라이언트 측 함수를 실행할 수 있습니다. 웹훅 도구와 달리 클라이언트 도구를 사용하면 어시스턴트가 브라우저 이벤트 트리거, 클라이언트 측 함수 실행, UI에 알림 전송 등의 작업을 수행할 수 있습니다.

개요

애플리케이션에서는 어시스턴트가 사용자의 환경과 직접 상호작용해야 할 수 있습니다. 클라이언트 측 도구는 어시스턴트가 클라이언트 측 작업을 수행할 수 있게 해 줍니다.

클라이언트 도구가 유용한 몇 가지 예시는 다음과 같습니다:

• UI 이벤트 트리거: 어시스턴트가 알림, 모달 또는 알림 메시지와 같은 브라우저 이벤트를 트리거할 수 있도록 합니다.
• DOM과 상호작용: 어시스턴트가 동적 콘텐츠 업데이트를 위해 또는 복잡한 인터페이스에서 사용자를 안내하기 위해 문서 객체 모델(DOM)을 조작할 수 있도록 합니다.

가이드

사전 요구 사항

• ElevenLabs 계정
• 구성된 ElevenLabs 대화형 에이전트(여기에서 생성)

from elevenlabs import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
def log_message(parameters):
    message = parameters.get("message")
    print(message)
client_tools = ClientTools()
client_tools.register("logMessage", log_message)
conversation = Conversation(
    client=ElevenLabs(api_key="your-api-key"),
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    requires_auth=True,
    client_tools=client_tools,
    # ...
)
conversation.start_session()

클라이언트 도구 결과를 대화 컨텍스트에 전달하기

에이전트가 클라이언트 도구에서 데이터를 다시 받도록 하려면 도구 구성에서 응답 대기 옵션을 선택하세요.

클라이언트 도구가 추가되면 함수가 호출될 때 에이전트는 응답을 기다리고 해당 응답을 대화 컨텍스트에 추가합니다.

def get_customer_details():
    # Fetch customer details (e.g., from an API or database)
    customer_data = {
        "id": 123,
        "name": "Alice",
        "subscription": "Pro"
    }
    # Return the customer data; it can also be a JSON string if needed.
    return customer_data
client_tools = ClientTools()
client_tools.register("getCustomerDetails", get_customer_details)
conversation = Conversation(
    client=ElevenLabs(api_key="your-api-key"),
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    requires_auth=True,
    client_tools=client_tools,
    # ...
)
conversation.start_session()

이 예시에서 에이전트가 getCustomerDetails를 호출하면 함수가 클라이언트에서 실행되고 에이전트는 반환된 데이터를 받으며, 이 데이터는 대화 컨텍스트의 일부로 사용됩니다. 응답의 값은 웹훅 도구와 마찬가지로 선택적으로 동적 변수에 할당할 수도 있습니다. 시스템 도구는 동적 변수를 업데이트할 수 없습니다.

문제 해결

모범 사례

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

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

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

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

도구 파라미터에는 명확하고 설명적인 이름을 사용하세요. 해당하는 경우 설명에 파라미터의 예상 형식을 지정하세요(예: 날짜의 경우 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은 대화에서 관련 파라미터를 추출하는 데 어려움을 겪을 수 있습니다.