Transferência de agente

Visão geral

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

Por exemplo, um agente inicial (Orquestrador) pode lidar com dúvidas gerais e depois 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 entre agentes

A transferência entre agentes é configurada com a ferramenta de sistema transfer_to_agent.

1

Adicione a ferramenta de transferência

Ative a transferência entre agentes selecionando a ferramenta de sistema transfer_to_agent na configuração do seu agente, na aba Agent. Escolha “Transferir para agente de IA” ao adicionar uma ferramenta.

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 ficar 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 de a transferência ocorrer. O padrão é 0 para transferência imediata.
• Mensagem de transferência: uma mensagem personalizada opcional para reproduzir durante a transferência. Se ficar em branco, a transferência ocorrerá silenciosamente.
• Ativar primeira mensagem: define se o agente que recebeu a transferência 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 (por número) transferir.

Verifique se a conta de usuário que cria o agente tem, no mínimo, permissões de visualização para todos os agentes de destino especificados nas regras de transferência.

Comportamento da transferência

Quando ocorre uma transferência, o agente pai (que inicia a transferência) repassa determinados valores de configuração ao agente filho (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 agente filho:

Além disso, o idioma atual do agente pai é mantido — se o agente filho não for compatível com ele, será usado o idioma padrão dele. 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 herdadas

Todas as outras configurações são definidas pelo agente filho, incluindo, mas não se limitando a:

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

Um agente que usa um modelo Realtime só pode transferir para e receber transferências de outros agentes que usam um modelo Realtime.

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 para o LLM do agente filho, para que ele continue a conversa sem mencionar a transferência.

Avaliação pós-chamada

O LLM avaliador pós-chamada recebe a transcrição completa, sem filtros — 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 têm um campo agent_id. Para determinar qual agente produziu cada mensagem, o avaliador usa a chamada da ferramenta transfer_to_agent como 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)