---
title: "Etapas e transferências entre agentes"
description: "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](/api-reference/agents). 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.

<Tip>
  [Zeus](/pt/guides/ask-the-copilot) pode criar etapas a partir de uma descrição
  ("adicionar uma etapa que verifica a data de nascimento antes de fazer uma reserva") e editar uma etapa
  sem alterar as outras.
</Tip>

### 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](/pt/guides/call-variables) `{{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](#webhook-steps). |
| `transitions` | Lista ordenada de destinos para os quais a etapa pode seguir. Consulte [Transições](#transitions). |
| `global_when` | Opcional. Torna a etapa acessível a partir de qualquer etapa. Consulte [Etapas globais](#global-steps). |
| `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 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>}`:

| `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`:

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](#global-steps) é 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](#where-to-see-it-on-a-call).

## 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:

```json
[{"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](/api-reference/calls#retrieve-a-call) e o webhook de conclusão
da chamada ([`telephony.complete` / `web.complete`](/pt/webhooks/call-complete)) incluem
os mesmos dados em `steps_trace` e `collected_values`. Ambos estão ausentes em chamadas
sem etapas.

```json
"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](/pt/guides/use-with-openai-realtime), incluindo sessões
  de um agente salvo;
- configurações inline retornadas por um webhook de [configuração dinâmica de chamada](/pt/guides/dynamic-call-config).
  Um webhook que retorna um `agent_id` usa 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](/pt/guides/import-agents) 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.

```json
{
  "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.

```json
{
  "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.

```json
[
  {
    "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

<CardGroup cols={2}>
  <Card title="Guia de prompting" icon="pen" href="/pt/guides/prompting">
    Escreva instruções compartilhadas e instruções de etapas que funcionem bem ao telefone.
  </Card>
  <Card title="Criar uma integração de ferramenta" icon="code" href="/pt/guides/build-tool-integration">
    Crie as ferramentas chamadas pelas suas etapas e etapas de webhook.
  </Card>
  <Card title="Testar seus agentes" icon="flask" href="/pt/guides/test-agents">
    Execute os mesmos cenários em todas as ramificações antes de implantar.
  </Card>
  <Card title="API de agentes" icon="robot" href="/api-reference/agents">
    Todos os campos do agente, rascunho e implantação.
  </Card>
</CardGroup>
