構造化された手順

概要

構造化された手順は、固定された順序のステップを実行する手順です。自由形式の手順は、エージェントが解釈し、状況に合わせて調整する自然言語のガイダンスです。構造化された手順は、手順が適用されるたびにエージェントが順番に実行する、型付きステップの順序付きリストです。

発信者の本人確認、チケットのエスカレーション、支払いの受け付けなど、特定のステップを毎回同じ方法で実行する必要がある場合は、構造化された手順を使用します。平易な言葉による短いステップリストとして作成できます。

他のすべての手順と同様に、構造化された手順には適用されるタイミングを説明するトリガーがあります。会話がトリガーに一致すると、エージェントは手順のステップを順番に実行し、その後、残りの会話に戻ります。

構造化された手順を使う場面

特定のステップを毎回同じ方法で実行する必要がありながら、平易なステップとして素早く作成したい場合は、構造化された手順を使用します。構造化された手順はワークフローより記述しやすい一方、表現力は低くなります。自由形式の手順、ワークフロー、システムプロンプトとの比較については、手順を使う場面を参照してください。

構造化された手順の構成

構造化された手順は、名前、トリガー、順序付きのステップリストの3つで構成されます。

名前

ダッシュボードで手順を識別する短いラベルです。名前がLLMに送信されることはないため、エージェントの動作には影響しません。

トリガー

エージェントがこの手順を実行すべきタイミングを平易な言葉で説明します。たとえば、ユーザーが注文の返金を求めたとき です。エージェントはユーザーの意図を各手順のトリガーと比較し、一致するものを実行します。そのため、トリガーは具体的で明確に区別できるものにしてください。エージェントが参照するのはトリガーのテキストだけで、手順の名前やIDは参照しません。トリガーの仕組みはすべての手順で共通です。詳しくはトリガーの記述を参照してください。

トリガーを空欄にすると、別の手順から呼び出された場合にのみ実行されるサブ手順になります。

ステップ

手順本体は、型付きステップの順序付きリストです。複数のステップタイプを組み合わせて、タスクを記述します。

すべてのステップをどこでも使用できるわけではありません。Ifアーム内では、別のIfまたはRetry以外の任意のステップを使用できます。Toolステップの失敗ハンドラー内では、Ifまたは別のTool以外の任意のステップを使用できます。

APIステップリファレンス

構造化された手順のcontentは、steps配列を含むJSONエンコード済みドキュメントです。各ステップはtypeで識別されるオブジェクトです。トリガーはcontentの一部ではなく、手順の別のトップレベルフィールドです。APIおよびSDKのペイロードでは、手順自体にtype: "deterministic"を使用します。

Ask

Askステップは、エージェントに情報を要求させ、ユーザーが適切な応答を提供するまで待機するよう指示します。

• APIタイプ：ask
• instruction：必須の空でない文字列。

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

Tell

Tellステップは、エージェントに自分の言葉で1つのメッセージを生成するよう指示します。ユーザーの応答を待たずに続行します。

• APIタイプ：tell
• instruction：必須の空でない文字列。

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

Say

Sayステップは、指定されたテキストを記載どおりに正確に発話してから続行します。message_translationsを指定すると、エージェントがサポートする追加言語ごとに、言語コードをキーとして正確なメッセージを設定できます。

• APIタイプ：say
• message：必須の空でない文字列。
• message_translations：言語コードを{ "value": "..." }にマッピングする任意のオブジェクト。

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

If、else if、else

Ifステップには、順序付きの条件アームを1つ以上含めます。最初に一致したアームが実行されます。任意のfallback配列がElseアームです。

• APIタイプ：branch
• branches：必須の、空でない条件アームのリスト。
• fallback：任意のElseステップのリスト。
• 各アームにはconditionと、空でないstepsリストが必要です。

{
  "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."
    }
  ]
}

動作はif/else-if/elseと同じです。

1. 条件を順番に評価します。
2. 最初に一致したアームを実行します。
3. 一致する条件がない場合は、fallbackを実行します。
4. アームが終了すると、手順はメインシーケンスに戻ります。

上記の例では、モデルが自然言語で評価するテキスト条件を使用しています。条件には、動的変数に対する式も使用できます。

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

式条件は、ツールの結果によって入力されるか、会話開始時に設定される動的変数を検査します。ユーザーの直近の返信は読み取れません。ユーザーの発言内容に基づいて分岐するには、テキスト条件を使用してください。

1つのIfステップ内のすべてのアームでは、llmまたはexpressionのいずれか、同じ条件タイプを使用する必要があります。

Tool

Toolステップは特定のツールを呼び出します。

• APIタイプ：tool_call
• tool_id：必須の空でないツールID。ツールがエージェントにアタッチされている必要があります。
• tool_name：ツールと一致する必須のツール名。
• instruction：ツールの呼び出し方法を説明する任意の指示。
• schema_overrides：ツールパラメータの任意の固定値。
• on_failure：任意の失敗ハンドラー。

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

固定パラメータ値

パラメータが常に特定の値を取る必要がある場合は、schema_overridesを使用します。モデルはオーバーライドされたパラメータを参照したり選択したりしません。キーはツールスキーマ内のパラメータパスで、各値はソースを指定します。

{
  "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" }
  }
}

失敗処理

on_failureがない場合、ツール呼び出しに失敗すると会話が終了します。代わりにリカバリーステップを実行するには、on_failureを追加してください。

• fallback：ツールが失敗したときに実行する、必須の空でないステップリスト。
• branches：条件付き失敗処理用に予約されています。空のままにしてください。

{
  "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."
      }
    ]
  }
}

失敗ハンドラーには、Ask、Tell、Say、Sub-procedure、System tool、Retryステップを含めることができます。ToolまたはIfステップは含められません。ハンドラーの実行後、手順はToolステップの次のステップから続行します。

Retry

Retryステップは、それを含む失敗ハンドラーをツール呼び出しを含めて再実行します。試行ごとにツールが再度呼び出され、再び失敗した場合はハンドラー内のすべてのステップが再び実行されます。試行回数を使い切ると、会話が終了します。

• APIタイプ：retry
• max_retries：1～3の任意の整数。デフォルトは1です。
• 値は、元のツール呼び出し後の試行回数を数えます。
• Retryはon_failure内でのみ有効です。
• 後続のステップには到達できなくなるため、Retryは失敗ハンドラーの最後のステップでなければなりません。

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

Sub-procedure

Sub-procedureステップは、別の構造化された手順を実行します。その手順のステップが完了すると、Sub-procedureステップの次のステップに実行が戻ります。

• APIタイプ：sub_procedure
• procedure_id：必須の空でない手順ID。
• 対象は同じエージェント上に存在する必要があります。
• 対象は構造化された手順である必要があります。
• 手順は自分自身を呼び出せません。

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

System tool

System toolステップは、組み込みのシステムアクションを実行します。

• APIタイプ：system_tool
• system_tool_name：必須のシステムツール名。
• 現在サポートされているのはend_callのみです。今後、さらにシステムツールが追加される可能性があります。
• end_callは終端処理のため、含まれるシーケンス、アーム、または失敗ハンドラーの最後のステップでなければなりません。

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

検証ルール

エージェントを公開するとき、またはエージェントの下書きを保存するとき、これらのルールのいずれかに違反する構造化された手順は拒否されます。エラーには、問題のあるステップがそのパスとともに示されます。

• 2つのIfステップを連続して配置することはできません。
• Ifステップをネストすることはできません。
• 式条件を持つIfステップを、Askステップの直後に配置することはできません。
• 1つのIfステップ内のすべての条件は、llmまたはexpressionのいずれか、同じタイプである必要があります。
• Retryはon_failure内でのみ使用でき、そこでは最後のステップでなければなりません。
• end_callは、それが含まれるリスト内の最後のステップでなければなりません。
• 失敗ハンドラーのfallbackには、少なくとも1つのステップを含める必要があります。
• Sub-procedureは、同じエージェント上に存在する構造化された手順を指す必要があり、自分自身を指すことはできません。
• tool_idはエージェント上のツールである必要があり、tool_nameは一致し、schema_overridesはツールのスキーマと一致する必要があります。
• stepsリスト、すべてのinstruction、すべてのmessageは空であってはなりません。

これらのルールのいずれかに該当する手順の再構成方法については、ベストプラクティスを参照してください。

完全なAPI例

この例では、配送状況に基づく注文キャンセルを処理します。ツールパラメータを固定し、ツール呼び出しの失敗から回復し、別の構造化された手順を呼び出してから、通話を終了します。

{
  "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"
    }
  ]
}

構造化された手順の実行方法

構造化された手順のステップをエージェントが実行する形式に変換することをコンパイルと呼びます。プラットフォームでは公開時にすべての構造化された手順をコンパイルするため、自分でコンパイルする必要はありません。現在、コンパイル結果は ワークフロー タブで読み取り専用ノードとして確認できます。

ユーザーのリクエストが手順のトリガーに一致すると、エージェントはその手順に入り、ステップを順番に実行します。構造化された手順内では、エージェントは各ステップを個別に処理します。最後に到達すると、会話の残りの部分に戻ります。

以下のルールは、実行時のステップの動作を説明します。

構造化された手順を管理する

ベストプラクティス

各ステップタイプにはそれぞれ固有の動作がすでに設定されているため、詳細を明示する必要はほとんどありません。各ステップの意図を書けば、あとはステップタイプが処理します。以下では、特に重要なケースのガイダンスを紹介します。

構造化された手順をテストするには、手順の反復改善で説明しているステップに従ってください。

ステップタイプの選択

手順の構成

ツールの使用

指示の書き方

手順の組み合わせ

手順を組み合わせるための一般的なガイダンスは構造化された手順にも適用されます。詳しくは、自由形式の手順のページにある手順の組み合わせを参照してください。

タイプを組み合わせる場合に特有のパターンとして、自由形式の手順から構造化された手順を参照できます。自由形式の手順ではオープンエンドな対応を行い、本人確認やエスカレーションなど、毎回同じ方法で実行する必要がある部分は構造化された手順に委任してください。

制限事項

• Ifステップはネストできず、2つのIfステップを連続して配置することもできません。
• サポートされているシステムツールはend_callのみです。
• 構造化された手順からナレッジベースドキュメントを参照することはできません。
• 手順完了時に現在のターンを終了する方法はありません。エージェントはターンを開いたままにし、話し続ける場合があります。
• ダッシュボード内の特定のワークフローノードから構造化された手順を開始することはできません。
• 手順の開始にはレイテンシーが加わります。エージェントは手順に入るためにツール呼び出しを行い、その後生成されたワークフローを進みます。

モデルプロバイダーのサポート

構造化された手順では、サブ手順への移行時と手順完了時に、内部ツール呼び出しが強制されます。主要なOpenAI、Anthropic、Gemini、Grokのモデルファミリーは、強制ツール選択をサポートしています。その他のモデルやカスタムプロバイダーでは保証されない場合があり、サブ手順の移行や手順の完了の信頼性が低下する可能性があります。別のモデルプロバイダーを使用する場合は、強制ツール選択がサポートされていることを確認してください。

コンテンツサイズの上限や構造化された手順と自由形式の手順の違いなど、すべての手順に適用される制限については、手順を参照してください。