Ferramentas do cliente

As ferramentas do cliente permitem que seu assistente execute funções no lado do cliente. Ao contrário das ferramentas de webhook, as ferramentas do cliente permitem que o assistente realize ações como acionar eventos do navegador, executar funções no lado do cliente ou enviar notificações para uma UI.

Visão geral

As aplicações podem exigir que os assistentes interajam diretamente com o ambiente do usuário. As ferramentas no lado do cliente dão ao seu assistente a capacidade de executar operações nesse lado.

Veja alguns exemplos em que as ferramentas do cliente podem ser úteis:

• Acionamento de eventos da UI: permite que um assistente acione eventos do navegador, como alertas, modais ou notificações.
• Interação com o DOM: permite que um assistente manipule o Document Object Model (DOM) para atualizações dinâmicas de conteúdo ou para orientar usuários em interfaces complexas.

Guia

Pré-requisitos

• Uma conta da ElevenLabs
• Um Agente Conversacional da ElevenLabs configurado (crie um aqui)

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()

Como enviar resultados de ferramentas do cliente ao contexto da conversa

Quando quiser que seu agente receba dados de volta de uma ferramenta do cliente, marque a opção Wait for response na configuração da ferramenta.

Depois que a ferramenta do cliente for adicionada, quando a função for chamada, o agente aguardará a resposta e a incluirá no contexto da conversa.

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()

Neste exemplo, quando o agente chama getCustomerDetails, a função é executada no cliente e o agente recebe os dados retornados, que são usados como parte do contexto da conversa. Os valores da resposta também podem, opcionalmente, ser atribuídos a variáveis dinâmicas, de forma semelhante às ferramentas de webhook. Observe que as ferramentas do sistema não podem atualizar variáveis dinâmicas.

Solução de problemas

Boas práticas

Nomeie as ferramentas de forma intuitiva e com descrições detalhadas

Se o assistente não estiver fazendo chamadas às ferramentas corretas, talvez seja necessário atualizar os nomes e as descrições das ferramentas para que ele entenda com mais clareza quando deve selecionar cada uma. Evite usar abreviações ou siglas para encurtar os nomes das ferramentas e dos argumentos.

Você também pode incluir descrições detalhadas sobre quando uma ferramenta deve ser chamada. Para ferramentas complexas, inclua descrições de cada argumento para ajudar o assistente a saber o que precisa perguntar ao usuário para coletar esse argumento.

Nomeie os parâmetros das ferramentas de forma intuitiva e com descrições detalhadas

Use nomes claros e descritivos para os parâmetros das ferramentas. Quando aplicável, especifique na descrição o formato esperado para um parâmetro (por exemplo, YYYY-mm-dd ou dd/mm/yy para uma data).

Considere fornecer informações adicionais sobre como e quando chamar ferramentas no prompt do sistema do seu assistente

Fornecer instruções claras no prompt do sistema pode melhorar significativamente a precisão das chamadas de ferramentas do assistente. Por exemplo, oriente o assistente com instruções como estas:

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?'.

Forneça contexto para cenários complexos. Por exemplo:

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

Seleção de LLM

É importante observar que a escolha do LLM influencia o sucesso das chamadas de função. Alguns LLMs podem ter dificuldade para extrair os parâmetros relevantes da conversa.