ThunderPhone v3 já está no ar.Contrate online, a partir de 2¢/min.Leia o anúncio

Using the dashboard

Etapas e transferências entre agentes

Divida um agente em etapas com suas próprias instruções, ferramentas e valores coletados e transfira chamadas entre agentes durante a chamada.

Um único prompt dá ao modelo todo o trabalho de uma vez. Etapas dão a ele uma fase da chamada por vez: cada etapa tem suas próprias instruções, suas próprias ferramentas, uma frase opcional falada literalmente e valores que ele precisa coletar antes de avançar. Transferências permitem que outro agente da sua organização assuma no meio da chamada, com a transcrição intacta, para que quem liga nunca precise se repetir.

Todo agente começa como um único prompt. Nada nele muda até que você adicione etapas ou transferências.

Etapas ou um único prompt?

Use etapas quandoMantenha um único prompt quando
A chamada tem fases que precisam acontecer em ordem: verificar e depois agendar.A conversa é aberta: perguntas frequentes, recepção, suporte geral.
Um valor precisa ser coletado antes de o agente avançar.Nada precisa ser coletado em uma ordem fixa.
Uma regra nunca pode ser flexibilizada, como "quem liga com menos de 18 anos vai para um responsável".O julgamento do modelo é bom o bastante para todas as ramificações.
Uma consulta precisa ser executada em um ponto fixo da chamada.As ferramentas podem ser chamadas sempre que quem liga solicitar.
Parte da chamada pertence a outro agente, com seu próprio prompt e voz.Uma persona cuida de tudo.

As etapas não são uma árvore telefônica roteirizada. Dentro de uma etapa, o modelo conduz a conversa como faria com um único prompt. A etapa define no que ele está trabalhando, quais ferramentas pode usar e o que precisa antes de poder sair dela.

Como um agente com etapas é criado

Quando um agente tem etapas, seu prompt contém as instruções compartilhadas: a persona e as regras que se aplicam em todas as etapas. Cada etapa adiciona suas próprias instruções. A cada turno, o modelo vê as instruções compartilhadas, o nome e as instruções da etapa atual, além dos valores coletados até o momento.

No Editor do agente, abra Instruções e selecione Dividir em etapas nos títulos do prompt. Zeus propõe as etapas, mostrando cada seção do prompt ao lado da etapa em que ela se transforma; Usar estas etapas as mantém e Manter um único prompt volta atrás. Depois disso, a estrutura lista Instruções compartilhadas e cada etapa. A página de uma etapa contém seu nome, sua primeira linha palavra por palavra, suas instruções, os valores que coleta e as ferramentas que pode usar, além de para onde ela vai em seguida e de onde vem. Fluxo mostra as etapas como um grafo. As transferências para outros agentes ficam em Ferramentas e transferências.

Salvar uma etapa prepara as etapas no rascunho; quem liga as recebe quando você seleciona Implantar no cabeçalho do agente. O seletor Um prompt / Etapas em Instruções compartilhadas transforma um agente novamente em um único prompt que combina as instruções compartilhadas e todas as etapas. Na visualização antiga, o seletor Prompt único / Etapas do construtor faz o mesmo.

Pela API, steps e handoffs são campos do agente. Como qualquer campo do agente, um PATCH os prepara no rascunho; POST /v1/agents/{agent_id}/deploy os torna ativos. Enviar "steps": null transforma o agente novamente em um único prompt. As chamadas de teste usam o rascunho.

Campos da etapa

CampoSignificado
idObrigatório. Letras minúsculas, dígitos e sublinhados, começando com uma letra, com até 40 caracteres. Exclusivo dentro do agente.
nameNome de exibição obrigatório, de 1 a 80 caracteres.
instructionsObrigatório, com até 20.000 caracteres. Compatível com variáveis de chamada {{var}}, assim como prompt.
sayFrase opcional falada literalmente ao entrar na etapa, com até 1.000 caracteres. Compatível com {{var}}.
toolsnull dá à etapa todas as ferramentas associadas ao agente. Uma lista limita a etapa a essas ferramentas, por nome. Ações integradas, como end_call e transfer_call, seguem as configurações do agente em todas as etapas.
collectAté 20 valores que a etapa coleta. Cada um tem name, type, description e required (o padrão é true).
on_enter_toolNome opcional de ferramenta, chamada automaticamente ao entrar na etapa. Consulte Etapas de webhook.
transitionsLista ordenada de destinos para os quais a etapa pode seguir. Consulte Transições.
global_whenOpcional. Torna a etapa acessível a partir de qualquer etapa. Consulte Etapas globais.
voiceID de voz opcional para esta etapa. Ignorado quando o agente usa uma configuração de voz personalizada.

O próprio gráfico é {"start_step": "<step id>", "steps": [...]}. A chamada começa em start_step.

Transições

Cada transição tem to, um ID de etapa, e exatamente um destes:

  • when: linguagem simples, e o modelo decide. O agente recebe uma ferramenta integrada go_to_step que lista as etapas para as quais ele pode avançar, com cada when como o motivo para escolhê-la.
  • condition: uma regra sobre valores coletados, e o código decide. O modelo não pode ignorá-la nem contorná-la conversando.
  • "always": true: avance sem uma verificação. O código decide primeiro: assim que uma etapa é iniciada, ou quando seus valores obrigatórios são coletados, a primeira transição condition ou always correspondente prevalece, antes que o modelo possa escolher um when. Portanto, coloque always após as condições como alternativa, ou sozinho para encadear uma etapa diretamente à próxima. Uma etapa com always nunca espera uma escolha de when.

Uma condition é {"value": <collected name or dotted path>, "op": <op>, "target": <literal>}:

opVerdadeiro quando o valor
eq, neé igual ou diferente de target
lt, lte, gt, gteé menor que, no máximo, maior que ou no mínimo target
in, not_iné ou não é um dos valores na lista target
exists, missingfoi ou não foi coletado (sem target)

eq, ne, in e not_in comparam texto sem diferenciar maiúsculas de minúsculas após remover espaços. Números são comparados como números e datas como strings YYYY-MM-DD. Um valor que nunca foi coletado torna todos os operadores falsos, exceto missing.

Escreva when e global_when como uma condição, por exemplo, "Quem liga quer agendar um horário", e não como algo a dizer. O agente os vê como notas internas de roteamento e recebe a instrução de nunca lê-los em voz alta nem mencionar que está mudando de etapa.

Quando o modelo chama go_to_step:

  1. Cada valor required na etapa deve estar presente. Se algum estiver ausente, o modelo é informado qual é e pede esse valor a quem liga.
  2. Os valores são armazenados.
  3. As transições condition e always são verificadas em ordem. A primeira correspondência prevalece.
  4. Caso contrário, o agente avança para a etapa escolhida pelo modelo.
  5. Se nada corresponder e o modelo não nomear nenhuma etapa, o agente permanece onde está.

Um salto para uma etapa global é a exceção: quem liga mudou de assunto, então ele avança mesmo quando a etapa atual ainda tem valores obrigatórios ausentes e antes que as condições dessa etapa sejam verificadas.

As transições condition e always também são verificadas sempre que uma etapa é iniciada, portanto uma sequência de etapas decididas por código é executada de uma só vez. A cadeia para:

  • em uma etapa que já visitou nesta execução;
  • após 8 saltos;
  • em uma etapa que ainda tem valores obrigatórios para coletar, a menos que a etapa tenha uma on_enter_tool (uma etapa de webhook sempre roteia com base no resultado).

Apenas a linha say da etapa em que a cadeia para é falada.

Uma etapa sem transições é terminal. O agente termina nela e encerra ou transfere a chamada com suas ações integradas normais.

Coleta de valores

Liste o que uma etapa precisa em collect. O modelo passa os valores quando chama go_to_step, e eles permanecem disponíveis pelo restante da chamada.

typeArmazena
stringQualquer texto
numberUm número
booleantrue ou false
dateUma data como YYYY-MM-DD

Os valores coletados são conteúdo da chamada. Eles aparecem na chamada ao lado da transcrição e seguem as mesmas regras de retenção, exclusão e redação. Quando a gravação de chamadas do agente está desativada, os valores coletados não são armazenados nem enviados em webhooks; a linha do tempo da etapa permanece disponível. Consulte Onde ver isso em uma chamada.

Linhas de fala

say é falado exatamente como está escrito quando o agente entra na etapa. O modelo então continua na nova etapa na mesma resposta, sabendo que a linha acabou de ser falada, para não repeti-la. Use say para saudações, avisos obrigatórios e textos fixos, e deixe o restante da resposta para o modelo.

O say da etapa inicial é a fala de abertura do agente quando ele fala primeiro, após qualquer anúncio de consentimento. Quando quem liga fala primeiro, ele abre a primeira resposta do agente para uma pessoa, nunca para uma URA ou uma saudação de caixa postal.

O say de uma etapa não é falado novamente quando a chamada retorna a ela por meio de __previous__ ou de uma transferência de volta. Escreva-o da forma como deve soar: escreva por extenso tudo o que a voz possa ler incorretamente. As linhas de fala aceitam variáveis de chamada {{var}}, mas não valores coletados.

Etapas de webhook

Defina on_enter_tool como uma das ferramentas do agente, e ela será executada assim que a etapa for acessada, sem esperar pelo modelo. Os argumentos dela são os valores coletados cujos nomes correspondem aos nomes dos parâmetros da ferramenta. O resultado é armazenado como um valor coletado chamado <tool>_result, truncado para 4 KB, e as transições de condition e always da etapa são verificadas imediatamente, para que a consulta possa encaminhar a chamada com base no próprio resultado.

O valor armazenado tem dois campos:

CampoContém
statusO código de status HTTP retornado pelo seu endpoint.
responseO corpo da resposta.

Encaminhe com base em um campo do corpo usando lookup_account_result.response.<field> e com base no código de status usando lookup_account_result.status.

A consulta é executada por até 8 segundos, ou pelo tempo limite da própria ferramenta, se for menor. Se demorar mais de 3 segundos, o agente diz uma frase curta para que quem liga não fique em silêncio. Se o seu endpoint retornar um status de 400 ou superior, ou não responder a tempo, o agente informa a quem liga que não conseguiu verificar isso naquele momento e continua com o que puder fazer.

Etapas globais

Uma etapa com global_when pode ser acessada de qualquer etapa sempre que essa descrição for válida. O modelo decide, como em when. Use-a para assuntos que quem liga pode levantar a qualquer momento: dúvidas sobre cobrança, um pedido para falar com uma pessoa, uma reclamação.

Uma transição com "to": "__previous__" em uma etapa global retorna a chamada para a etapa que estava ativa antes dela, para que quem liga retome de onde parou. A etapa é retomada: seu on_enter_tool não é executado novamente, seu say não é repetido, e o agente continua nela sem recomeçar.

Transferências

handoffs lista outros agentes da sua organização que podem assumir a chamada:

[{"agent_id": 413, "when": "The caller asks about billing or a refund"}]

O agente recebe uma ferramenta integrada hand_off com esses agentes e motivos. Assim como nas transições, cada when é uma observação interna de roteamento, nunca lida em voz alta.

Quando transfere, o agente diz uma frase curta informando a quem liga para onde ela será direcionada, como "Claro, vou transferir você para nossa equipe de faturamento", com sua própria voz. Em seguida, o prompt, as etapas, as ferramentas e a voz do agente de destino assumem, e a chamada continua com a mesma transcrição. O novo agente se apresenta brevemente e responde à última solicitação de quem liga; ele não anuncia uma transferência. A base de conhecimento do destino fica disponível a partir desse momento.

Na primeira vez que uma chamada chega a um agente, ela começa na start_step desse agente: o on_enter_tool da etapa é executado e seu say é falado. Quando a chamada é transferida de volta para um agente que ela já visitou, esse agente retoma a etapa em que estava, sem executar o on_enter_tool, repetir seu say ou se apresentar novamente. Os valores coletados são compartilhados por todos os agentes na chamada.

  • Um destino deve ser um agente da mesma organização, e um agente não pode transferir uma chamada para si mesmo.
  • Tudo no nível da chamada permanece com o agente que atendeu: produto, idiomas, quem fala primeiro, correio de voz, aviso de consentimento e todas as outras configurações da chamada.
  • Os destinos podem transferir a chamada adiante e de volta. Uma chamada pode chegar a até 8 agentes.
  • Uma chamada de teste executa o rascunho do agente que você está testando. Os agentes para os quais ele transfere executam suas versões implantadas.
  • Se dois agentes tiverem uma ferramenta com o mesmo nome e definições diferentes, apenas uma será mantida para a chamada, e a do agente que atendeu sempre prevalece. O aplicativo avisa você ao salvar.
  • Um agente pode ter transferências sem etapas. Todo o seu prompt é usado como está.

go_to_step e hand_off são reservados em agentes com etapas ou transferências, portanto suas próprias ferramentas não podem usar esses nomes.

Onde ver isso em uma chamada

Abra a chamada no Histórico de chamadas. Uma linha do tempo de etapas ao lado da transcrição mostra cada etapa que a chamada acessou e o motivo, e os valores coletados são listados junto dela.

O objeto de chamada e o webhook de conclusão da chamada (telephony.complete / web.complete) incluem os mesmos dados em steps_trace e collected_values. Ambos estão ausentes em chamadas sem etapas.

"steps_trace": [
  {"t_ms": 0, "agent": "a412", "step": "greet", "via": "start"},
  {"t_ms": 51230, "agent": "a412", "step": "verify", "via": "model"},
  {"t_ms": 98410, "agent": "a412", "step": "minor", "via": "condition"}
],
"collected_values": {"full_name": "Dana Reyes", "dob": "2010-04-02", "age": 15}

agent é a seguido pelo ID do agente. via informa o que moveu a chamada:

viaSignificado
startA chamada começou nesta etapa.
modelO modelo escolheu a etapa por meio de go_to_step, um when ou um global_when.
conditionUma transição condition ou always correspondeu.
on_enterUma transição correspondeu ao resultado de uma etapa de webhook.
handoffOutro agente assumiu.

Onde as etapas são executadas

As etapas são executadas nativamente em cada agente (e nos valores de produto mais antigos), em chamadas recebidas, realizadas e de campanha, chamadas de teste e chamadas pela web e por widget.

Em todos os outros lugares, o agente continua funcionando, apenas sem a estrutura: ele executa um prompt consolidado que mescla as instruções compartilhadas e todas as etapas, em ordem. Isso abrange:

Limites

LimiteValor
Etapas por agente100
Valores coletados por etapa20
Destinos de transferência por agente8
Agentes acessíveis em uma chamada8
Tamanho do JSON steps200 KB
instructions da etapa20.000 caracteres
Linha say1.000 caracteres
Resultado armazenado de on_enter_tool4 KB

Um salvamento que viola uma regra retorna 400 com o caminho do campo incorreto, como steps.steps[2].transitions[0].to. Os nomes das ferramentas em tools e on_enter_tool devem ser ferramentas vinculadas ao agente.

Idiomas por etapa, etapas com script que ignoram o modelo e valores coletados em linhas say não são compatíveis.

Agentes importados

A importação do Retell, Bland, Vapi ou ElevenLabs transfere agentes com múltiplos prompts, fluxos, caminhos e workflows como etapas, e equipes e transferências de agentes como transferências entre os agentes importados. A página de revisão mostra ambos antes da importação.

Exemplo: triagem odontológica

Três etapas em ordem: cumprimentar, coletar os dados do paciente, agendar.

{
  "prompt": "You are Ava, the front desk assistant at Acme Dental. Be warm and brief. Ask one question at a time.",
  "steps": {
    "start_step": "greet",
    "steps": [
      {
        "id": "greet",
        "name": "Greeting",
        "instructions": "Greet the caller and ask how you can help.",
        "say": "Thanks for calling Acme Dental, this is Ava. How can I help you today?",
        "tools": null,
        "collect": [],
        "transitions": [
          {"to": "details", "when": "The caller wants to book an appointment"}
        ]
      },
      {
        "id": "details",
        "name": "Patient details",
        "instructions": "Ask for the caller's full name, date of birth and the reason for the visit. Read the date of birth back and ask the caller to confirm it.",
        "tools": null,
        "collect": [
          {"name": "full_name", "type": "string", "description": "Caller's full name", "required": true},
          {"name": "dob", "type": "date", "description": "Date of birth", "required": true},
          {"name": "reason", "type": "string", "description": "Reason for the visit", "required": true},
          {"name": "new_patient", "type": "boolean", "description": "First visit to the practice", "required": false}
        ],
        "transitions": [
          {"to": "book", "when": "The caller has confirmed their details"}
        ]
      },
      {
        "id": "book",
        "name": "Book",
        "instructions": "Offer the two earliest open slots from book_slot and book the one the caller picks. Confirm the date and time, then say goodbye and end the call.",
        "tools": ["book_slot"],
        "collect": [],
        "transitions": []
      }
    ]
  }
}

Prepare com PATCH /v1/agents/{agent_id}, teste com uma chamada de teste e depois implante. A etapa details não pode transferir para o agendamento até que o nome, a data de nascimento e o motivo sejam coletados; new_patient é opcional.

Exemplo: uma ramificação com restrição de idade

O modelo pode conversar com qualquer pessoa, mas o código decide quem pode agendar. Colete a idade e encaminhe com base nela antes que a própria escolha do modelo seja considerada.

{
  "id": "verify",
  "name": "Verify age",
  "instructions": "Ask for the caller's age.",
  "tools": null,
  "collect": [
    {"name": "age", "type": "number", "description": "Caller's age in years", "required": true}
  ],
  "transitions": [
    {"to": "guardian", "condition": {"value": "age", "op": "lt", "target": 18}},
    {"to": "book", "when": "The caller has given their age"}
  ]
}

Quem liga e diz quinze vai para guardian, independentemente do que o modelo decidir. Todas as outras pessoas vão para book. Ambas são etapas comuns em outra parte do grafo.

Exemplo: etapa de webhook de consulta de conta

Quem liga fornece um número de conta, a consulta é executada ao entrar na próxima etapa, e o resultado escolhe a rota. As etapas not_found, collections e support foram omitidas por brevidade.

[
  {
    "id": "identify",
    "name": "Identify",
    "instructions": "Ask for the caller's account number and read it back digit by digit.",
    "tools": null,
    "collect": [
      {"name": "account_number", "type": "string", "description": "Account number", "required": true}
    ],
    "transitions": [
      {"to": "lookup", "when": "The caller has confirmed their account number"}
    ]
  },
  {
    "id": "lookup",
    "name": "Look up account",
    "instructions": "Tell the caller what you found on their account and ask how you can help.",
    "tools": ["lookup_account"],
    "collect": [],
    "on_enter_tool": "lookup_account",
    "transitions": [
      {"to": "not_found", "condition": {"value": "lookup_account_result.response.found", "op": "eq", "target": false}},
      {"to": "collections", "condition": {"value": "lookup_account_result.response.account_status", "op": "in", "target": ["past_due", "suspended"]}},
      {"to": "support", "when": "The caller needs help with an active account"}
    ]
  }
]

lookup_account recebe account_number porque o parâmetro tem esse nome. Se o corpo da resposta tiver "found": false, a chamada segue para not_found. Se o account_status for past_due ou suspended, segue para collections. Uma conta ativa permanece em lookup, onde o modelo ajuda e avança para support. Para enviar uma consulta com falha para uma etapa própria, adicione primeiro condições de status: uma resposta de erro armazena seu código de status, então {"value": "lookup_account_result.status", "op": "gte", "target": 400} a captura, e um tempo limite ou ausência de resposta armazena "error", então {"value": "lookup_account_result.status", "op": "eq", "target": "error"} captura esse caso.

Exemplo: recepção para cobrança

Dois agentes. A recepção (agente 412) atende todas as chamadas e encaminha perguntas sobre cobrança para um agente de cobrança (agente 413) com seu próprio prompt, ferramentas e voz.

Na recepção:

{
  "handoffs": [
    {"agent_id": 413, "when": "The caller asks about a bill, a payment or a refund"}
  ]
}

No agente de cobrança, para que ele possa transferir quem liga de volta:

{
  "handoffs": [
    {"agent_id": 412, "when": "The billing question is resolved and the caller needs something else"}
  ]
}

A recepção diz uma frase curta, como "Vou transferir você para nossa equipe de cobrança", e o agente de cobrança se apresenta e retoma a conversa de onde a recepção a deixou. Quando a cobrança transfere de volta, a recepção retoma de onde estava, sem cumprimentar quem liga novamente. O produto, os idiomas, o anúncio de consentimento e outras configurações da chamada permanecem com a recepção, porque ela atendeu.

Se a cobrança precisar apenas de suas próprias instruções, e não de seu próprio agente, use uma etapa global na recepção. Quando a pergunta for respondida, a chamada volta para qualquer etapa em que quem liga estava:

{
  "id": "billing",
  "name": "Billing questions",
  "instructions": "Answer questions about bills and payments. Offer to send a payment link by email.",
  "tools": null,
  "collect": [],
  "transitions": [
    {"to": "__previous__", "when": "The billing question is answered"}
  ],
  "global_when": "The caller asks about a bill or payment at any point"
}

Próximas etapas