Transferência de agente

Visão geral

A transferência de agente para agente permite que um agente da ElevenLabs encaminhe a conversa em andamento para outro agente designado quando condições específicas são atendidas. Isso possibilita fluxos de trabalho conversacionais em várias camadas, nos quais diferentes agentes lidam com tarefas específicas ou níveis de complexidade distintos.

Por exemplo, um agente inicial (Orquestrador) pode lidar com consultas gerais e, em seguida, transferir a chamada para um agente especializado com base no contexto da conversa. As transferências também podem ser aninhadas:

Orchestrator Agent (Initial Qualification)
│
├───> Agent 1 (e.g., Availability Inquiries)
│
├───> Agent 2 (e.g., Technical Support)
│     │
│     └───> Agent 2a (e.g., Hardware Support)
│
└───> Agent 3 (e.g., Billing Issues)

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.

Como ativar a transferência de agente

A transferência de agente é configurada usando a ferramenta de sistema transfer_to_agent.

1

Adicione a ferramenta de transferência

Ative a transferência de agente selecionando a ferramenta de sistema transfer_to_agent na configuração do seu agente, na aba Agent. Ao adicionar uma ferramenta, escolha “Transfer to AI Agent”.

2

Configure a descrição da ferramenta (opcional)

Você pode fornecer uma descrição personalizada para orientar o LLM sobre quando acionar uma transferência. Se for deixado em branco, será usada uma descrição padrão que abrange as regras de transferência definidas.

3

Defina as regras de transferência

Configure as regras específicas para transferir para outros agentes. Para cada regra, especifique:

• Agente: o agente de destino para o qual a conversa será transferida.
• Condição: uma descrição em linguagem natural das circunstâncias em que a transferência deve ocorrer (por exemplo, “O usuário pergunta sobre detalhes de cobrança”, “O usuário solicita suporte técnico para o produto X”).
• Atraso antes da transferência (milissegundos): o atraso mínimo, em milissegundos, antes que a transferência ocorra. O padrão é 0 para transferência imediata.
• Mensagem de transferência: uma mensagem personalizada opcional para reproduzir durante a transferência. Se for deixada em branco, a transferência ocorrerá silenciosamente.
• Ativar primeira mensagem: define se o agente transferido deve reproduzir sua primeira mensagem após a transferência. Desativado por padrão.

O LLM usará essas condições, junto com a descrição da ferramenta, para decidir quando e para qual agente (pelo número) transferir.

Verifique se a conta de usuário que cria o agente tem pelo menos permissões de visualizador para todos os agentes de destino especificados nas regras de transferência.

Comportamento da transferência

Quando ocorre uma transferência, o agente pai (aquele que inicia a transferência) passa determinados valores de configuração ao agente filho (aquele que recebe a conversa), enquanto outros são completamente redefinidos.

Herança de configuração

O agente pai substitui os seguintes valores em todos os agentes filhos, independentemente da configuração do próprio agente filho:

Além disso, o idioma atual do agente pai é mantido — se o agente filho não tiver suporte a ele, será usado o próprio idioma padrão do agente filho. A configuração de webhook e análise pós-chamada (incluindo critérios de avaliação e itens de coleta de dados) também se aplica à conversa inteira.

Não herdado

Todas as outras configurações são definidas pelo agente filho, incluindo, entre outras:

• Prompt, primeira mensagem, LLM, workflow, voz, ferramentas e base de conhecimento
• Voz do TTS, modelo, estabilidade e outras configurações de voz (exceto agent_output_audio_format)
• Modelo, qualidade e palavras-chave de ASR (exceto user_input_audio_format)
• Turno/tempo limite, predefinições de idioma, duração máxima etc.

Transcrição e histórico do chat

A transcrição completa é preservada durante toda a conversa. As mensagens do usuário e do agente de todos os agentes anteriores permanecem no histórico do chat.

Durante uma transferência, as chamadas da ferramenta transfer_to_agent são removidas do histórico visível ao LLM do agente filho, para que ele continue a conversa sem mencionar o encaminhamento.

Avaliação pós-chamada

O LLM avaliador pós-chamada recebe a transcrição completa e não filtrada — todas as mensagens do usuário e do agente, além de todas as chamadas de ferramentas, incluindo a transferência.

As mensagens individuais não contêm um campo agent_id. Para determinar qual agente produziu cada mensagem, o avaliador usa a chamada da ferramenta transfer_to_agent como um marcador de limite na transcrição.

Implementação da API

Você pode configurar a ferramenta de sistema transfer_to_agent ao criar ou atualizar um agente pela API.

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Define transfer rules with new options
transfer_rules = [
    {
        "agent_id": "AGENT_ID_1",
        "condition": "When the user asks for billing support.",
        "delay_ms": 1000,  # 1 second delay
        "transfer_message": "I'm connecting you to our billing specialist.",
        "enable_transferred_agent_first_message": True,
    },
    {
        "agent_id": "AGENT_ID_2",
        "condition": "When the user requests advanced technical help.",
        "delay_ms": 0,  # Immediate transfer
        "transfer_message": None,  # Silent transfer
        "enable_transferred_agent_first_message": False,
    },
]
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, how can I help you today?",
            prompt={
                "prompt": "You are a helpful assistant.",
                "built_in_tools": {
                    "transfer_to_agent": {
                        "type": "system",
                        "name": "transfer_to_agent",
                        # Optional custom description
                        "description": "Transfer the user to a specialized agent based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_agent",
                            "transfers": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)
print(response)