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 na ordem definida 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 liga, escalar um ticket ou processar 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 sempre da mesma forma, mas você ainda quiser criar rapidamente usando etapas simples. Procedimentos estruturados são mais fáceis de escrever do que um workflow, mas são 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, então 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 uma etapa Tentar novamente. Dentro do manipulador de falha de uma etapa Ferramenta, você pode usar qualquer etapa, exceto um Se ou outra Ferramenta.

Referência de etapas da API

O content de um procedimento estruturado é um documento codificado em JSON que contém um array 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 foi escrito e depois continua. Forneça message_translations para dar ao agente uma mensagem exata para cada idioma adicional compatível com ele, 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. O array fallback opcional é 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. Após o término de uma ramificação, 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 de 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 da ferramenta obrigatório e não vazio. A ferramenta deve estar associada ao agente.
• tool_name: Nome obrigatório da ferramenta, que deve corresponder à 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 ter 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 nomeia 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, Subprocedimento, Ferramenta do sistema e Tentar novamente. Ele não pode conter etapas Ferramenta ou Se. Após a execução do manipulador, o procedimento continua com a etapa após a etapa Ferramenta.

Tentar novamente

Uma etapa Tentar novamente executa de novo 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: Número 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 inacessíveis.

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

Subprocedimento

Uma etapa Subprocedimento executa outro procedimento estruturado. Quando as etapas desse procedimento são concluídas, a execução retorna à etapa após a etapa Subprocedimento.

• Tipo da API: sub_procedure
• procedure_id: ID do 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 invocar 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, 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

A publicação do agente ou o salvamento do rascunho do agente rejeita um procedimento estruturado que viola qualquer uma destas regras. O erro indica a etapa com problema pelo respectivo caminho.

• Duas etapas Se não podem ser colocadas uma após a outra.
• 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 só pode aparecer dentro de on_failure e deve ser a última etapa nesse local.
• 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 Subprocedimento deve apontar para um procedimento estruturado existente no mesmo agente e não para ele próprio.
• tool_id deve ser uma ferramenta do agente, tool_name deve corresponder, e schema_overrides deve corresponder ao esquema da ferramenta.
• A lista steps, cada instruction e cada message devem ser não vazios.

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

Exemplo completo de API

Este exemplo processa o cancelamento de um pedido com base no status de envio. Ele fixa um parâmetro de ferramenta, se recupera de uma chamada de ferramenta com falha, invoca 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 o rascunho do agente é salvo ou o agente é publicado; quem cria os procedimentos nunca precisa compilar nada.

Quando a solicitação do usuário corresponde ao gatilho de um procedimento, a plataforma entra no procedimento e executa suas etapas em ordem. Dentro do procedimento estruturado, o agente se concentra em cada etapa isoladamente. Quando chega ao fim, a plataforma devolve o controle ao restante da conversa.

As conexões de workflow não podem apontar para nem partir de um procedimento estruturado. Use uma etapa Subprocedimento para encadear procedimentos estruturados. A plataforma gerencia a entrada por um gatilho correspondente e a conclusão, incluindo devolver o controle ao nó do workflow em que o procedimento começou.

As regras a seguir descrevem o comportamento das etapas em tempo de 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 explicá-lo. Escreva a intenção de cada etapa e deixe que o tipo de etapa faça o resto. As orientações abaixo abordam os casos que vale a pena acertar.

Para testar um procedimento estruturado, siga Iterando em um procedimento.

Escolhendo tipos de etapa

Estruturando o procedimento

Trabalhando com ferramentas

Escrevendo instruções

Compondo procedimentos

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

Um padrão é específico da combinação de tipos: um procedimento de formato livre pode fazer referência a um estruturado. Mantenha o tratamento aberto em um procedimento de formato livre e delegue as partes que precisam ser executadas sempre da mesma maneira, 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.
• As arestas do workflow não podem se conectar a um procedimento estruturado nem partir dele. Use uma etapa Sub-procedure para encadear procedimentos estruturados; a entrada e a conclusão são gerenciadas pela plataforma.
• 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 modelos

Procedimentos estruturados forçam chamadas internas de ferramentas 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 garantir isso, 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 modelos.

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