Open in
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 quando | Mantenha 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
| Campo | Significado |
|---|---|
id | Obrigatório. Letras minúsculas, dígitos e sublinhados, começando com uma letra, com até 40 caracteres. Exclusivo dentro do agente. |
name | Nome de exibição obrigatório, de 1 a 80 caracteres. |
instructions | Obrigatório, com até 20.000 caracteres. Compatível com variáveis de chamada {{var}}, assim como prompt. |
say | Frase opcional falada literalmente ao entrar na etapa, com até 1.000 caracteres. Compatível com {{var}}. |
tools | null 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. |
collect | Até 20 valores que a etapa coleta. Cada um tem name, type, description e required (o padrão é true). |
on_enter_tool | Nome opcional de ferramenta, chamada automaticamente ao entrar na etapa. Consulte Etapas de webhook. |
transitions | Lista ordenada de destinos para os quais a etapa pode seguir. Consulte Transições. |
global_when | Opcional. Torna a etapa acessível a partir de qualquer etapa. Consulte Etapas globais. |
voice | ID 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 integradago_to_stepque lista as etapas para as quais ele pode avançar, com cadawhencomo 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çãoconditionoualwayscorrespondente prevalece, antes que o modelo possa escolher umwhen. Portanto, coloquealwaysapós as condições como alternativa, ou sozinho para encadear uma etapa diretamente à próxima. Uma etapa comalwaysnunca espera uma escolha dewhen.
Uma condition é {"value": <collected name or dotted path>, "op": <op>, "target": <literal>}:
op | Verdadeiro 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, missing | foi 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:
- Cada valor
requiredna etapa deve estar presente. Se algum estiver ausente, o modelo é informado qual é e pede esse valor a quem liga. - Os valores são armazenados.
- As transições
conditionealwayssão verificadas em ordem. A primeira correspondência prevalece. - Caso contrário, o agente avança para a etapa escolhida pelo modelo.
- 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.
type | Armazena |
|---|---|
string | Qualquer texto |
number | Um número |
boolean | true ou false |
date | Uma 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:
| Campo | Contém |
|---|---|
status | O código de status HTTP retornado pelo seu endpoint. |
response | O 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:
via | Significado |
|---|---|
start | A chamada começou nesta etapa. |
model | O modelo escolheu a etapa por meio de go_to_step, um when ou um global_when. |
condition | Uma transição condition ou always correspondeu. |
on_enter | Uma transição correspondeu ao resultado de uma etapa de webhook. |
handoff | Outro 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:
- sessões do Realtime, incluindo sessões de um agente salvo;
- configurações inline retornadas por um webhook de configuração dinâmica de chamada.
Um webhook que retorna um
agent_idusa as etapas desse agente.
Limites
| Limite | Valor |
|---|---|
| Etapas por agente | 100 |
| Valores coletados por etapa | 20 |
| Destinos de transferência por agente | 8 |
| Agentes acessíveis em uma chamada | 8 |
Tamanho do JSON steps | 200 KB |
instructions da etapa | 20.000 caracteres |
Linha say | 1.000 caracteres |
Resultado armazenado de on_enter_tool | 4 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
Escreva instruções compartilhadas e instruções de etapas que funcionem bem ao telefone.
Crie as ferramentas chamadas pelas suas etapas e etapas de webhook.
Execute os mesmos cenários em todas as ramificações antes de implantar.
Todos os campos do agente, rascunho e implantação.