Procedimentos estruturados

Visão geral

Um procedimento estruturado é um procedimento que executa uma sequência fixa de etapas. Um procedimento de formato livre é uma orientação em linguagem natural que o agente interpreta e adapta à situação. Um procedimento estruturado é uma lista ordenada de etapas tipadas que o agente executa em ordem sempre que o procedimento se aplica.

Use um procedimento estruturado quando etapas específicas precisarem ocorrer da mesma forma em todas as chamadas: verificar a identidade de quem ligou, escalar um ticket ou receber um pagamento. Você o cria como uma lista curta de etapas em linguagem simples.

Como todo procedimento, um procedimento estruturado tem um gatilho que descreve quando ele se aplica. Quando uma conversa corresponde ao gatilho, o agente executa as etapas do procedimento em ordem e depois retorna ao restante da conversa.

Quando usar um procedimento estruturado

Use um procedimento estruturado quando etapas específicas precisarem ser executadas da mesma forma sempre, mas você ainda quiser criar rapidamente usando etapas simples. Procedimentos estruturados são mais fáceis de escrever do que um workflow, mas menos expressivos. Para saber como eles se comparam a procedimentos de formato livre, workflows e ao prompt do sistema, consulte Quando usar procedimentos.

Anatomia de um procedimento estruturado

Um procedimento estruturado tem três partes: um nome, um gatilho e uma lista ordenada de etapas.

Nome

Um rótulo curto que identifica o procedimento no painel. O nome nunca é enviado ao LLM, portanto não afeta o comportamento do agente.

Gatilho

Uma descrição em linguagem simples de quando o agente deve executar este procedimento, por exemplo, Quando o usuário pedir o reembolso de um pedido. O agente compara a intenção do usuário com o gatilho de cada procedimento e executa o correspondente, portanto os gatilhos devem ser concretos e distintos. O agente vê apenas o texto do gatilho, nunca o nome ou o ID do procedimento. Um gatilho funciona da mesma forma que em qualquer procedimento; consulte Como escrever gatilhos.

Deixe o gatilho vazio para tornar o procedimento um subprocesso que só é executado quando outro procedimento o chama.

Etapas

O corpo do procedimento é uma lista ordenada de etapas tipadas. Há vários tipos de etapa, que você combina para descrever a tarefa.

Nem todas as etapas podem aparecer em qualquer lugar. Dentro de uma ramificação Se, você pode usar qualquer etapa, exceto outro Se ou Tentar novamente. Dentro do manipulador de falha de uma etapa Ferramenta, você pode usar qualquer etapa, exceto Se ou outra Ferramenta.

Referência de etapas da API

O content de um procedimento estruturado é um documento codificado em JSON que contém uma matriz steps. Cada etapa é um objeto identificado por seu type. O gatilho é um campo separado de nível superior no procedimento, não faz parte de content. As cargas úteis da API e do SDK usam type: "deterministic" para o próprio procedimento.

Perguntar

Uma etapa Perguntar instrui o agente a solicitar informações e aguardar até que o usuário forneça uma resposta adequada.

• Tipo da API: ask
• instruction: string obrigatória e não vazia.

{
  "type": "ask",
  "instruction": "Ask the user for their order ID."
}

Informar

Uma etapa Informar instrui o agente a gerar uma única mensagem com suas próprias palavras. Ela não aguarda uma resposta do usuário antes de continuar.

• Tipo da API: tell
• instruction: string obrigatória e não vazia.

{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Dizer

Uma etapa Dizer fala o texto fornecido exatamente como está escrito e depois continua. Forneça message_translations para dar ao agente uma mensagem exata para cada idioma adicional compatível, identificada pelo código do idioma.

• Tipo da API: say
• message: string obrigatória e não vazia.
• message_translations: objeto opcional que mapeia um código de idioma para { "value": "..." }.

{
  "type": "say",
  "message": "Your refund has been submitted.",
  "message_translations": {
    "es": { "value": "Su reembolso ha sido enviado." }
  }
}

Se, senão se e senão

Uma etapa Se contém uma ou mais ramificações condicionais ordenadas. A primeira ramificação correspondente é executada. A matriz opcional fallback é a ramificação Senão.

• Tipo da API: branch
• branches: lista obrigatória e não vazia de ramificações condicionais.
• fallback: lista opcional de etapas Senão.
• Cada ramificação exige uma condition e uma lista steps não vazia.

{
  "type": "branch",
  "branches": [
    {
      "condition": {
        "type": "llm",
        "condition": "The user is on an annual plan."
      },
      "steps": [
        {
          "type": "say",
          "message": "Your annual plan is eligible for a prorated refund."
        }
      ]
    }
  ],
  "fallback": [
    {
      "type": "tell",
      "instruction": "Explain that the account's plan could not be determined."
    }
  ]
}

Isso funciona como if/else-if/else:

1. As condições são avaliadas em ordem.
2. A primeira ramificação correspondente é executada.
3. Se nenhuma condição corresponder, fallback é executado.
4. Depois que uma ramificação termina, o procedimento retorna à sequência principal.

O exemplo acima usa uma condição de texto, que o modelo avalia em linguagem natural. As condições também podem ser expressões sobre variáveis dinâmicas:

{
  "type": "expression",
  "expression": {
    "type": "eq_operator",
    "left": {
      "type": "dynamic_variable",
      "name": "plan_tier"
    },
    "right": {
      "type": "string_literal",
      "value": "annual"
    }
  }
}

Uma condição de expressão testa variáveis dinâmicas, que são preenchidas por resultados de ferramentas ou definidas quando a conversa começa. Ela não pode ler a resposta mais recente do usuário. Para criar uma ramificação com base no que o usuário disse, use uma condição de texto.

Todas as ramificações em uma etapa Se devem usar o mesmo tipo de condição: llm ou expression.

Ferramenta

Uma etapa Ferramenta chama uma ferramenta específica.

• Tipo da API: tool_call
• tool_id: ID de ferramenta obrigatório e não vazio. A ferramenta deve estar vinculada ao agente.
• tool_name: nome obrigatório da ferramenta, correspondente à ferramenta.
• instruction: instrução opcional que descreve como chamar a ferramenta.
• schema_overrides: valores fixos opcionais para os parâmetros da ferramenta.
• on_failure: manipulador de falha opcional.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Valores fixos de parâmetros

Use schema_overrides quando um parâmetro sempre precisar assumir um valor específico. O modelo não vê nem escolhe um parâmetro substituído. As chaves são caminhos de parâmetros no esquema da ferramenta; cada valor indica uma origem:

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "update_ticket",
  "schema_overrides": {
    "request_body.status": { "source": "constant", "constant_value": "pending" },
    "request_body.ticket_id": { "source": "dynamic_variable", "dynamic_variable": "ticket_id" }
  }
}

Tratamento de falhas

Sem on_failure, uma chamada de ferramenta com falha encerra a conversa. Adicione on_failure para executar etapas de recuperação.

• fallback: lista obrigatória e não vazia de etapas executadas quando a ferramenta falha.
• branches: reservado para tratamento condicional de falhas. Deixe vazio.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "on_failure": {
    "branches": [],
    "fallback": [
      {
        "type": "tell",
        "instruction": "Explain that the order could not be retrieved and offer to connect the user with support."
      }
    ]
  }
}

Um manipulador de falha pode conter etapas Perguntar, Informar, Dizer, Subprocesso, Ferramenta do sistema e Tentar novamente. Ele não pode conter etapas Ferramenta ou Se. Depois que o manipulador é executado, o procedimento continua com a etapa após a etapa Ferramenta.

Tentar novamente

Uma etapa Tentar novamente executa novamente o manipulador de falha que a contém, incluindo a chamada da ferramenta. Cada tentativa chama a ferramenta novamente e, se ela falhar outra vez, executa todas as etapas do manipulador novamente. Quando as tentativas se esgotam, a conversa é encerrada.

• Tipo da API: retry
• max_retries: inteiro opcional de 1 a 3. O padrão é 1.
• O valor conta as tentativas após a chamada original da ferramenta.
• Tentar novamente é válido apenas dentro de on_failure.
• Tentar novamente deve ser a etapa final em seu manipulador de falha, pois as etapas posteriores seriam inalcançáveis.

{
  "type": "retry",
  "max_retries": 2
}

Subprocesso

Uma etapa Subprocesso executa outro procedimento estruturado. Quando as etapas desse procedimento terminam, a execução retorna à etapa após a etapa Subprocesso.

• Tipo da API: sub_procedure
• procedure_id: ID de procedimento obrigatório e não vazio.
• O destino deve existir no mesmo agente.
• O destino deve ser um procedimento estruturado.
• Um procedimento não pode chamar a si mesmo.

{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

Ferramenta do sistema

Uma etapa Ferramenta do sistema executa uma ação integrada do sistema.

• Tipo da API: system_tool
• system_tool_name: nome obrigatório da ferramenta do sistema.
• No momento, apenas end_call é compatível. Mais ferramentas do sistema poderão ser adicionadas futuramente.
• Como end_call é terminal, ele deve ser a etapa final na sequência, ramificação ou manipulador de falha que o contém.

{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Regras de validação

Publicar o agente ou salvar o rascunho do agente rejeita um procedimento estruturado que viole qualquer uma destas regras. O erro nomeia a etapa com problema por seu caminho.

• Duas etapas Se não podem ser colocadas consecutivamente.
• Etapas Se não podem ser aninhadas.
• Uma etapa Se com condições de expressão não pode vir diretamente após uma etapa Perguntar.
• Todas as condições em uma etapa Se devem ser do mesmo tipo: llm ou expression.
• Tentar novamente pode aparecer apenas dentro de on_failure e deve ser a última etapa ali.
• end_call deve ser a última etapa em qualquer lista em que apareça.
• O fallback de um manipulador de falha deve conter pelo menos uma etapa.
• Um Subprocesso deve apontar para um procedimento estruturado existente no mesmo agente e não para si mesmo.
• tool_id deve ser uma ferramenta do agente, tool_name deve corresponder, e schema_overrides deve corresponder ao esquema da ferramenta.
• A lista steps, toda instruction e toda message devem ser não vazias.

Para saber como reestruturar um procedimento que encontra uma destas regras, consulte Boas práticas.

Exemplo completo da API

Este exemplo processa o cancelamento de um pedido com base no status de envio. Ele fixa um parâmetro de ferramenta, recupera-se de uma chamada de ferramenta com falha, chama outro procedimento estruturado e então encerra a chamada.

{
  "steps": [
    {
      "type": "ask",
      "instruction": "Ask the user for their order ID."
    },
    {
      "type": "branch",
      "branches": [
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has already shipped."
          },
          "steps": [
            {
              "type": "tell",
              "instruction": "Explain that shipped orders must be returned before they can be refunded."
            }
          ]
        },
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has not shipped."
          },
          "steps": [
            {
              "type": "tool_call",
              "tool_id": "tool_abc123",
              "tool_name": "cancel_order",
              "instruction": "Cancel the order using the order ID provided by the user.",
              "schema_overrides": {
                "request_body.notify_customer": { "source": "constant", "constant_value": true }
              },
              "on_failure": {
                "branches": [],
                "fallback": [
                  {
                    "type": "tell",
                    "instruction": "Apologize that the cancellation did not go through and say you will try once more."
                  },
                  {
                    "type": "retry",
                    "max_retries": 1
                  }
                ]
              }
            }
          ]
        }
      ],
      "fallback": [
        {
          "type": "ask",
          "instruction": "Ask whether the order has already shipped."
        }
      ]
    },
    {
      "type": "sub_procedure",
      "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
    },
    {
      "type": "say",
      "message": "Thank you for contacting us. Goodbye.",
      "message_translations": {
        "es": { "value": "Gracias por contactarnos. Adiós." }
      }
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Como um procedimento estruturado é executado

Transformar as etapas de um procedimento estruturado no formato que o agente executa é chamado de compilação. A plataforma compila todos os procedimentos estruturados quando você publica; você não precisa compilar nada. Atualmente, o resultado compilado fica visível como nós somente leitura na aba Workflow.

Quando a solicitação do usuário corresponde ao gatilho de um procedimento, o agente entra no procedimento e executa suas etapas em ordem. Enquanto está dentro do procedimento estruturado, o agente se concentra em cada etapa isoladamente. Ao chegar ao fim, ele retorna ao restante da conversa.

As regras a seguir descrevem como as etapas se comportam durante a execução.

Gerenciar um procedimento estruturado

Práticas recomendadas

Cada tipo de etapa já impõe seu próprio comportamento, então você raramente precisa especificá-lo. Escreva a intenção de cada etapa e deixe o tipo de etapa fazer o resto. As orientações abaixo abordam os casos que vale a pena acertar.

Para testar um procedimento estruturado, siga Iteração em um procedimento.

Como escolher tipos de etapa

Como estruturar o procedimento

Como trabalhar com ferramentas

Como escrever instruções

Como compor procedimentos

As orientações gerais para compor procedimentos também se aplicam a procedimentos estruturados; consulte Como compor procedimentos na página de procedimentos de formato livre.

Um padrão é específico para combinar tipos: um procedimento de formato livre pode fazer referência a um estruturado. Mantenha o tratamento de situações abertas em um procedimento de formato livre e delegue as partes que precisam ser executadas da mesma forma todas as vezes, como verificação de identidade ou encaminhamento, a um procedimento estruturado.

Limitações

• Etapas If não podem ser aninhadas, e duas etapas If não podem ser colocadas uma após a outra.
• A única ferramenta de sistema compatível é end_call.
• Procedimentos estruturados não podem fazer referência a documentos da base de conhecimento.
• Não há como encerrar o turno atual quando um procedimento é concluído; o agente mantém o turno aberto e pode continuar falando.
• Não é possível iniciar um procedimento estruturado a partir de um nó específico do workflow no painel.
• Iniciar um procedimento adiciona latência: o agente faz uma chamada de ferramenta para entrar nele e depois avança pelo workflow gerado.

Suporte de provedores de modelo

Procedimentos estruturados forçam chamadas de ferramentas internas ao entrar em um subprocedimento e ao concluir um procedimento. As principais famílias de modelos OpenAI, Anthropic, Gemini e Grok oferecem suporte à escolha forçada de ferramenta. Outros modelos ou provedores personalizados podem não garantí-la, o que pode tornar as transições de subprocedimentos ou a conclusão de procedimentos menos confiáveis. Verifique o suporte à escolha forçada de ferramenta ao usar outro provedor de modelo.

Consulte Procedimentos para ver limites aplicáveis a todos os procedimentos, incluindo o limite de tamanho do conteúdo e como os procedimentos estruturados diferem dos de formato livre.