Ferramentas do sistema | ElevenLabs Documentation

Ferramentas do sistema permitem que seu assistente atualize o estado interno de uma conversa. Ao contrário das ferramentas de webhook ou ferramentas de cliente, as ferramentas do sistema não fazem chamadas de API externas nem acionam funções no cliente — elas modificam o estado interno da conversa sem fazer chamadas externas.

Visão geral

Alguns aplicativos exigem que os agentes controlem o fluxo ou o estado de uma conversa. As ferramentas do sistema oferecem esse recurso, permitindo que o assistente execute ações relacionadas ao estado da chamada sem precisar se comunicar com servidores externos ou com o cliente.

Ferramentas do sistema disponíveis

Encerrar chamada

Permita que seu agente encerre automaticamente uma conversa quando as condições adequadas forem atendidas.

Detecção de idioma

Permita que seu agente mude automaticamente para o idioma do usuário durante as conversas.

Transferência de agente

Transfira conversas sem interrupções entre agentes de IA com base em condições definidas.

Transferir para número

Transfira chamadas para números de telefone externos ou URIs SIP.

Pular turno

Permita que o agente pule seus turnos se o LLM detectar que ele ainda não deve falar.

Reproduzir tom do teclado

Permita que os agentes reproduzam tons DTMF para interagir com sistemas telefônicos automatizados e navegar por menus.

Detecção de caixa postal

Permita que os agentes detectem automaticamente sistemas de caixa postal e, opcionalmente, deixem mensagens.

Atualizar estado

Permita que seu agente atualize variáveis dinâmicas durante a conversa usando expressões.

Implementação

Ao criar um agente pela API, você pode adicionar ferramentas do sistema à configuração do agente. Veja como implementar as ferramentas de encerrar chamada e detecção de idioma:

Integração com LLM personalizado

Ao usar um LLM personalizado com os agentes da ElevenLabs, as ferramentas do sistema são expostas como definições de função que seu LLM pode chamar. Cada ferramenta do sistema tem parâmetros e condições de acionamento específicos:

Ferramentas do sistema disponíveis

Encerrar chamada

Objetivo: Encerrar conversas automaticamente quando as condições apropriadas forem atendidas.

Condições de acionamento: o LLM deve chamar esta ferramenta quando:

A tarefa principal tiver sido concluída e o usuário estiver satisfeito
A conversa tiver chegado a uma conclusão natural, com concordância mútua
O usuário indicar explicitamente que deseja encerrar a conversa

Parâmetros:

reason (string, obrigatório): o motivo para encerrar a chamada
message (string, opcional): uma mensagem de despedida para enviar ao usuário antes de encerrar a chamada

Formato da chamada de função:

{
  "type": "function",
  "function": {
    "name": "end_call",
    "arguments": "{\"reason\": \"Task completed successfully\", \"message\": \"Thank you for using our service. Have a great day!\"}"
  }
}

Implementação: configure como uma ferramenta de sistema nas configurações do seu agente. O LLM receberá instruções detalhadas sobre quando chamar esta função.

Saiba mais: Ferramenta de encerrar chamada

Detecção de idioma

Objetivo: Mudar automaticamente para o idioma detectado do usuário durante as conversas.

Condições de acionamento: O LLM deve chamar esta ferramenta quando:

O usuário falar em um idioma diferente do idioma atual da conversa
O usuário solicitar explicitamente a mudança de idioma
Houver necessidade de suporte a vários idiomas na conversa

Parâmetros:

reason (string, obrigatório): O motivo para a mudança de idioma
language (string, obrigatório): O código do idioma para o qual mudar (deve estar na lista de idiomas compatíveis)

Formato da chamada de função:

{
  "type": "function",
  "function": {
    "name": "language_detection",
    "arguments": "{\"reason\": \"User requested Spanish\", \"language\": \"es\"}"
  }
}

Implementação: Configure os idiomas compatíveis nas configurações do agente e adicione a ferramenta de sistema de detecção de idioma. O agente mudará automaticamente a voz e as respostas para corresponder aos idiomas detectados.

Saiba mais: Ferramenta de detecção de idioma

Transferência de agente

Objetivo: Transferir conversas entre agentes de IA especializados de acordo com as necessidades do usuário.

Condições de acionamento: O LLM deve chamar esta ferramenta quando:

A solicitação do usuário exige conhecimento especializado ou recursos de outro agente
O agente atual não consegue lidar adequadamente com a consulta
O fluxo da conversa indica a necessidade de outro tipo de agente

Parâmetros:

reason (string, opcional): O motivo da transferência do agente
agent_number (integer, obrigatório): Número indexado a partir de zero do agente para o qual transferir (com base nas regras de transferência configuradas)

Formato da chamada de função:

{
  "type": "function",
  "function": {
    "name": "transfer_to_agent",
    "arguments": "{\"reason\": \"User needs billing support\", \"agent_number\": 0}"
  }
}

Implementação: Defina regras de transferência que mapeiem condições para IDs específicos de agentes. Configure para quais agentes o agente atual pode transferir. Os agentes são referenciados por números indexados a partir de zero na configuração de transferência.

Saiba mais: Ferramenta de transferência de agente

Transferir para número

Objetivo: Transferir conversas sem interrupções para atendentes humanos quando a assistência de IA for insuficiente.

Condições de acionamento: o LLM deve chamar esta ferramenta quando:

Houver problemas complexos que exijam julgamento humano
O usuário solicitar explicitamente assistência humana
A IA atingir os limites de sua capacidade para a solicitação específica
Os protocolos de escalonamento forem acionados

Parâmetros:

reason (string, opcional): o motivo da transferência
transfer_number (string, obrigatório): o número de telefone para o qual transferir (deve corresponder aos números configurados)
client_message (string, obrigatório): mensagem lida ao cliente enquanto aguarda a transferência
agent_message (string, obrigatório): mensagem para o atendente humano que receberá a chamada

Formato da chamada de função:

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}

Implementação: configure os números de telefone e as condições de transferência. Defina mensagens tanto para o cliente quanto para o atendente humano que receberá a chamada. Funciona com Twilio e troncos SIP.

Saiba mais: Ferramenta de transferir para número

Pular turno

Objetivo: Permitir que o agente pause e aguarde a entrada do usuário sem falar.

Condições de acionamento: o LLM deve chamar esta ferramenta quando:

O usuário indicar que precisa de um momento (“Me dê um segundo”, “Deixe-me pensar”)
O usuário solicitar uma pausa no fluxo da conversa
O agente detectar que o usuário precisa de tempo para processar informações

Parâmetros:

reason (string, opcional): motivo de formato livre explicando por que a pausa é necessária

Formato de chamada da função:

{
  "type": "function",
  "function": {
    "name": "skip_turn",
    "arguments": "{\"reason\": \"User requested time to think\"}"
  }
}

Implementação: nenhuma configuração adicional é necessária. A ferramenta simplesmente sinaliza ao agente para permanecer em silêncio até que o usuário fale novamente.

Saiba mais: Ferramenta de pular turno

Reproduzir tom do teclado

Parâmetros:

reason (string, opcional): O motivo para reproduzir os tons DTMF (por exemplo, “navegando até a extensão”, “inserindo PIN”)
dtmf_tones (string, obrigatório): A sequência DTMF a ser reproduzida. Caracteres válidos: 0-9, *, #, w (pausa de 0,5 s), W (pausa de 1 s)

Formato da chamada de função:

{
  "type": "function",
  "function": {
    "name": "play_keypad_touch_tone",
    "arguments": "{"reason": "Navigating to customer service", "dtmf_tones": "2"}"
  }
}

Saiba mais: Ferramenta de reproduzir tom do teclado

Detecção de caixa postal

Parâmetros:

reason (string, obrigatório): o motivo para detectar a caixa postal (por exemplo, “saudação automática detectada”, “nenhuma resposta humana”)

Formato de chamada da função:

{
  "type": "function",
  "function": {
    "name": "voicemail_detection",
    "arguments": "{\"reason\": \"Automated greeting detected with request to leave message\"}"
  }
}

Saiba mais: Ferramenta de detecção de caixa postal

Atualizar estado

Objetivo: Permitir que o agente atualize uma ou mais variáveis dinâmicas com base na conversa, sem chamar uma API externa.

Condições de acionamento: o LLM deve chamar esta ferramenta quando:

A conversa fornecer informações que devem ser registradas (por exemplo, um indicador de escalonamento, uma opção escolhida ou um valor fornecido pelo usuário)
Uma atualização de estado configurada depender de um valor que o LLM precisa avaliar ou extrair da conversa

Parâmetros:

Os parâmetros da função dependem de como a ferramenta foi configurada. Cada atualização de estado configurada que usa um valor extraído pelo LLM adiciona uma propriedade ao esquema, nomeada de acordo com a variável dinâmica dessa atualização e tipada como string, number ou boolean. Atualizações de estado criadas apenas com constantes ou outras variáveis dinâmicas não adicionam parâmetros.

Formato de chamada da função:

{
  "type": "function",
  "function": {
    "name": "update_state",
    "arguments": "{\"should_escalate\": true}"
  }
}

Implementação: o agente avalia cada expressão configurada usando os parâmetros extraídos e as variáveis dinâmicas atuais da conversa e, em seguida, atribui os resultados às variáveis dinâmicas correspondentes. Nenhuma solicitação externa é feita.

Saiba mais: Ferramenta de atualizar estado

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Each system tool is keyed by name under built_in_tools.
# Leave "description" blank to use the default, tool-specific prompt.
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt={
                "built_in_tools": {
                    "end_call": {
                        "type": "system",
                        "name": "end_call",
                        "description": "",
                        "params": {"system_tool_type": "end_call"},
                    },
                    "language_detection": {
                        "type": "system",
                        "name": "language_detection",
                        "description": "",
                        "params": {"system_tool_type": "language_detection"},
                    },
                }
            },
        ),
    ),
)

Perguntas frequentes

As ferramentas do sistema podem ser combinadas com outros tipos de ferramentas?

Sim, as ferramentas do sistema podem ser usadas junto com ferramentas de webhook e ferramentas de cliente no mesmo assistente. Isso permite uma funcionalidade abrangente que combina o gerenciamento do estado interno com interações externas.