構造化プロシージャ
構造化プロシージャ
エージェントが毎回同じ方法で実行する、型付きステップの固定シーケンス
概要
構造化プロシージャは、固定された順序のステップを実行するプロシージャです。自由形式プロシージャは、エージェントが解釈し、状況に応じて調整する自然言語のガイダンスです。構造化プロシージャは、プロシージャが適用されるたびにエージェントが順番に実行する、型付きステップの順序付きリストです。
発信者の本人確認、チケットのエスカレーション、支払いの受付など、特定のステップをすべての通話で同じ方法で行う必要がある場合は、構造化プロシージャを使用します。簡潔な平易な言葉のステップリストとして作成できます。
すべてのプロシージャと同様に、構造化プロシージャには適用するタイミングを説明するトリガーがあります。会話がトリガーに一致すると、エージェントはプロシージャのステップを順番に実行し、その後会話の残りに戻ります。
構造化プロシージャを使用する場合
特定のステップを毎回同じ方法で実行する必要がある一方で、平易なステップで素早く作成したい場合は、構造化プロシージャを使用します。自由形式プロシージャ、ワークフロー、システムプロンプトとの比較については、プロシージャを使用する場合を参照してください。
構造化プロシージャの構成
構造化プロシージャは、名前、トリガー、順序付きステップリストの3つで構成されます。
名前
ダッシュボードでプロシージャを識別するための短いラベルです。名前がLLMに送信されることはないため、エージェントの動作には影響しません。
トリガー
たとえば「ユーザーが注文の返金を求めた場合」のように、エージェントがこのプロシージャを実行すべきタイミングを平易な言葉で説明します。エージェントはユーザーの意図を各プロシージャのトリガーと比較して一致するものを実行するため、トリガーは具体的で区別しやすいものにしてください。トリガーはすべてのプロシージャで同じように機能します。トリガーの書き方を参照してください。
ステップ
プロシージャ本文は、型付きステップの順序付きリストです。複数のステップタイプがあり、それらを組み合わせてタスクを説明します。
APIステップリファレンス
構造化プロシージャのcontentは、steps配列を含むJSONエンコード済みドキュメントです。各ステップはtypeで識別されるオブジェクトです。
Ask
Askステップは、情報を求め、ユーザーが適切な回答を提供するまで待つようエージェントに指示します。
- APIタイプ：
ask instruction：必須の空でない文字列。
Tell
Tellステップは、自身の言葉で1つのメッセージを生成するようエージェントに指示します。Askとは異なり、続行する前にユーザーの応答を待ちません。
- APIタイプ：
tell instruction：必須の空でない文字列。
Say
Sayステップは、指定されたテキストを記載どおりに正確に発話します。
- APIタイプ：
say message：必須の空でない文字列。
If、else if、else
Ifステップには、1つ以上の順序付き条件分岐が含まれます。最初に一致した分岐が実行されます。任意のfallback配列はelse分岐として機能します。
- APIタイプ：
branch branches：必須の空でない条件分岐リスト。fallback：任意のelseステップリスト。- 各分岐には
conditionと空でないstepsリストが必要です。
これはif/else-if/elseのように動作します。
- 条件は順番に評価されます。
- 最初に一致した分岐が実行されます。
- 一致する条件がない場合は、
fallbackが実行されます。 - 分岐が終了すると、プロシージャはメインシーケンスに戻ります。
上記の例では自然言語の条件を使用しています。条件にはワークフロー式も使用できます。
1つのIfステップ内のすべての分岐では、同じ条件タイプ、つまりllmまたはexpressionのいずれかを使用する必要があります。
Ifステップはプロシージャの最初のステップにできます。ただし、次の制限があります。
- Ifステップはネストできません。
- 2つのIfステップを連続して配置することはできません。
- 式条件をAskステップの直後に置くことはできません。ユーザーの自由形式テキストの応答を評価するには、LLM条件を使用してください。
Tool
Toolステップは特定のツールを呼び出します。
- APIタイプ：
tool_call tool_id：必須の空でないツールID。tool_name：必須のツール名。instruction：ツールの呼び出し方法を説明する任意の指示。on_failure：任意の失敗ハンドラー。
on_failureがない場合、ツール呼び出しが失敗するとプロシージャは停止します。特定の失敗を処理したり、ツールを再試行したり、フォールバックステップに進んだりするには、on_failureを追加してください。
branches：任意の順序付き条件リスト。最初に一致した分岐が実行されます。fallback：必須の空でないステップリスト。どの分岐にも一致しない場合に実行されます。
失敗ハンドラーの分岐には、Ask、Tell、Say、Sub-procedure、System tool、Retryステップを含められます。ToolまたはIfステップは含められません。1つの失敗ハンドラー内のすべての条件分岐では、同じ条件タイプを使用する必要があります。
Retry
Retryステップは、それを含む失敗ハンドラーのToolステップを再試行します。
- APIタイプ：
retry max_retries：1～3の任意の整数。デフォルトは1です。- 値は、元のツール呼び出し後の再試行回数を数えます。
- Retryは
on_failure内でのみ有効です。 - 後続のステップには到達できないため、Retryは失敗ハンドラー分岐の最後のステップである必要があります。
- すべての試行が失敗すると、プロシージャは停止します。
Sub-procedure
Sub-procedureステップは別の構造化プロシージャを実行します。終了すると、Sub-procedureステップの次のステップに実行が戻ります。
- APIタイプ：
sub_procedure procedure_id：必須の空でないプロシージャID。- 対象は同じエージェント上に存在する必要があります。
- 対象は構造化プロシージャである必要があります。
- プロシージャが自身を呼び出すことはできません。
System tool
System toolステップは組み込みのシステムアクションを実行します。
- APIタイプ：
system_tool system_tool_name：必須のシステムツール名。- 現在サポートされているのは
end_callのみです。今後、さらにシステムツールが追加される可能性があります。 end_callは終端であるため、それを含むシーケンスまたは分岐の最後のステップである必要があります。
完全なAPI例
この例では、配送ステータスに基づいて注文キャンセルを処理します。失敗したツール呼び出しを再試行し、別の構造化プロシージャを呼び出してから、通話を終了します。
構造化プロシージャの実行方法
会話中にユーザーのリクエストがプロシージャのトリガーに一致すると、エージェントはプロシージャに入り、毎回同じ方法でステップを順番に実行します。プロシージャ内では、エージェントはそれらのステップに集中し、最後に到達すると会話で中断した場所に戻ります。
Toolステップが失敗し、on_failureが定義されていない場合、残りのステップを実行せずにプロシージャは停止します。on_failureが設定されている場合、プロシージャは最初に一致した失敗分岐または必須のフォールバックを実行します。選択されたハンドラーがツールを再試行する、通話を終了する、または別の終端パスを呼び出す場合を除き、処理済みの失敗後は次のプロシージャステップに進みます。
構造化プロシージャを管理する
ダッシュボードで作成
APIで管理
ダッシュボードでエージェントを開き、プロシージャを選択します。 **+**を使用して構造化プロシージャを作成します。トリガーを追加し、各ステップのタイプを選択して、 エージェントの変更を公開します。
ベストプラクティス
各ステップタイプは固有の動作をすでに強制するため、詳細を明示する必要はほとんどありません。各ステップの 意図を書き、残りはステップタイプに任せてください。以下のガイダンスでは、適切に設定する価値があるケースを説明します。
ステップの記述
Askステップでユーザーの回答を待つ
Askステップは、質問を行い、適切な回答を受け取るまで進みません。情報が収集されたことを確認するための 後続ステップは不要です。Askステップは、次に進む前にそれを保証します。
Toolステップはツール呼び出しだけに使う
Toolステップはツールの実行のみを行います。この間、エージェントは発話や判断を行えません。ユーザーに話しかける、 またはツールの返却内容に基づいて分岐する場合は、Toolステップの前後に別のステップとして配置してください。
表現にはTell、正確な文言にはSayを選ぶ
エージェント自身にメッセージを作成させる場合はTellステップを、文言をそのまま使用する必要がある場合は Sayステップを使います。どちらも送信するメッセージは1つだけなので、1つのメッセージを送るようステップに指示する必要はありません。
プロシージャの構成
プロシージャの構成に関する一般的なガイダンスは、構造化プロシージャにも適用されます。詳細は、自由形式プロシージャのページにあるプロシージャの構成を参照してください。
タイプを組み合わせる場合に固有のパターンとして、自由形式プロシージャから構造化プロシージャを参照できます。オープンエンドな処理は自由形式プロシージャで行い、本人確認やエスカレーションのように毎回同じ方法で実行する必要がある部分は、構造化プロシージャに委任してください。
制限事項
- Ifステップはネストできず、2つのIfステップを連続して配置することもできません。
モデルプロバイダーのサポート
構造化プロシージャでは、サブプロシージャへの移行時とプロシージャ完了時に内部ツール呼び出しが強制されます。主要なOpenAI、Anthropic、Gemini、Grokのモデルファミリーは、ツール選択の強制をサポートしています。その他のモデルやカスタムプロバイダーでは保証されない場合があり、サブプロシージャの移行やプロシージャの完了の信頼性が低下する可能性があります。別のモデルプロバイダーを使用する場合は、ツール選択の強制がサポートされていることを確認してください。
コンテンツサイズの上限や、構造化プロシージャと自由形式プロシージャの違いなど、すべてのプロシージャに適用される制限についてはプロシージャを参照してください。