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 uma pessoa, 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 todas as vezes, mas você ainda quiser criar rapidamente usando etapas simples. Para saber como ele se compara a procedimentos de formato livre, workflows e ao prompt de 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, por isso os gatilhos devem ser concretos e distintos. Um gatilho funciona da mesma forma que em qualquer procedimento; consulte Como escrever gatilhos.

Etapas

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

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 pelo seu type.

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. Diferentemente de Perguntar, 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.

• Tipo da API: say
• message: String obrigatória e não vazia.

{
  "type": "say",
  "message": "Your refund has been submitted."
}

Se, else if e else

Uma etapa Se contém uma ou mais ramificações condicionais ordenadas. A primeira ramificação correspondente é executada. O array fallback opcional atua como a ramificação else.

• Tipo da API: branch
• branches: Lista obrigatória e não vazia de ramificações condicionais.
• fallback: Lista opcional de etapas else.
• 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 em linguagem natural. As condições também podem usar expressões de workflow:

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

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

Uma etapa Se pode ser a primeira etapa do procedimento. No entanto:

• Etapas Se não podem ser aninhadas.
• Duas etapas Se não podem ser colocadas consecutivamente.
• Uma condição de expressão não pode seguir diretamente uma etapa Perguntar. Use uma condição de LLM para avaliar uma resposta em texto livre do usuário.

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.
• tool_name: Nome de ferramenta obrigatório.
• instruction: Instrução opcional que descreve como chamar a ferramenta.
• on_failure: Manipulador de falhas 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."
}

Sem on_failure, uma chamada de ferramenta com falha interrompe o procedimento. Adicione on_failure para tratar falhas específicas, tentar a ferramenta novamente ou continuar com etapas alternativas.

• branches: Lista opcional de condições ordenadas. A primeira ramificação correspondente é executada.
• fallback: Lista obrigatória e não vazia de etapas. Ela é executada quando nenhuma ramificação corresponde.

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

As ramificações do manipulador de falhas podem conter etapas Perguntar, Informar, Dizer, Subprocedimento, Ferramenta do sistema e Tentar novamente. Elas não podem conter etapas Ferramenta ou Se. Todas as ramificações condicionais em um manipulador de falhas devem usar o mesmo tipo de condição.

Tentar novamente

Uma etapa Tentar novamente refaz a etapa Ferramenta cujo manipulador de falhas a contém.

• Tipo da API: retry
• max_retries: Inteiro opcional de 1 a 3. O padrão é 1.
• O valor conta as novas tentativas após a chamada original da ferramenta.
• Tentar novamente só é válido dentro de on_failure.
• Tentar novamente deve ser a etapa final em sua ramificação do manipulador de falhas, pois as etapas seguintes seriam inacessíveis.
• Se todas as tentativas falharem, o procedimento é interrompido.

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

Subprocedimento

Uma etapa Subprocedimento executa outro procedimento estruturado. Quando ele termina, a execução retorna à etapa posterior à etapa Subprocedimento.

• 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 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 de ferramenta do sistema obrigatório.
• Atualmente, apenas end_call é compatível. Mais ferramentas do sistema poderão ser adicionadas posteriormente.
• Como end_call é terminal, ele deve ser a etapa final em sua sequência ou ramificação.

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

Exemplo completo de API

Este exemplo processa um cancelamento de pedido com base no status de envio. Ele tenta novamente uma chamada de ferramenta que falhou, invoca outro procedimento estruturado e depois encerra a chamada.

{
  "trigger": "When the user asks to cancel an order and request a refund.",
  "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.",
              "on_failure": {
                "fallback": [
                  {
                    "type": "retry",
                    "max_retries": 2
                  }
                ]
              }
            }
          ]
        }
      ],
      "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."
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Como um procedimento estruturado é executado

Quando a solicitação do usuário corresponde ao gatilho de um procedimento durante uma conversa, o agente entra no procedimento e executa suas etapas em ordem, da mesma forma todas as vezes. Enquanto está no procedimento, o agente se concentra nessas etapas; ao chegar ao fim, retorna ao ponto em que parou na conversa.

Se uma etapa Ferramenta falhar e não definir on_failure, o procedimento será interrompido sem executar as etapas restantes. Quando on_failure está configurado, o procedimento executa a primeira ramificação de falha correspondente ou seu fallback obrigatório. Uma falha tratada continua para a próxima etapa do procedimento, a menos que o manipulador selecionado tente a ferramenta novamente, encerre a chamada ou invoque outro caminho terminal.

Gerenciar um procedimento estruturado

Boas práticas

Como escrever etapas

Como compor procedimentos

As orientações gerais para compor procedimentos também se aplicam aos procedimentos estruturados — consulte Como compor 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 forma, como verificação de identidade ou escalonamento, a um procedimento estruturado.

Limitações

• As etapas If não podem ser aninhadas, e duas etapas If não podem ser posicionadas uma após a outra.

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 são compatíveis com a escolha forçada de ferramenta. Outros modelos ou provedores personalizados podem não garanti-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 os 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.