> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 自由形式の手順

## 概要

自由形式の手順は、1つのタスクを平易な自然言語で説明します。エージェントは指示を解釈し、状況に応じて表現や順序を調整します。自由形式の手順では、ツール（通話終了などのシステムツールを含む）の呼び出し、ナレッジベースのドキュメントの検索、他の手順への連鎖ができます。

## 自由形式の手順を使う場面

エージェントが状況に合わせて表現や順序を調整でき、自然言語で素早く作成したい場合は、自由形式の手順を使用します。構造化された手順、ワークフロー、システムプロンプトとの比較については、[手順を使う場面](/docs/ja/eleven-agents/customization/procedures#when-to-use-procedures)を参照してください。

## 手順の構成

エディターでの返金手順の例です。

![返金手順の例](/docs/_fern-img/e1264b7a4f94403453087d30ef0894e72d412ba69378e6b8cb1b675e53e887b7.webp)

手順は、トリガーとコンテンツという2つの主要部分で構成されます。どちらにも他のリソースへのインライン参照を含められます。上のスクリーンショットでは、レンチアイコン付きのタグとして表示されています。各手順には、ダッシュボードに表示される名前もあります。

### 名前

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

### トリガー

エージェントがこの手順を使用するタイミングの説明です。例：*ユーザーが注文の返金を求めた場合*。

トリガーを空にするのは、[サブ手順](#sub-procedures)を作成する場合だけです。

### コンテンツ

Markdownで記述する手順の本文です。コンテンツには、質問する、注文を検索する、ツールを呼び出す、通話を終了するなど、エージェントが行うことを記述します。順に実行する番号付きのステップにすることも、状況に応じた一般的なガイダンスにすることもできます。各ステップやガイドラインは、1文（*ユーザーに注文IDを尋ねる*）でも、何をするのかとその理由を説明する短い段落でもかまいません。

順番に行うアクションには番号付きステップを、ステップ内の要件や下位項目には箇条書きを使用します。

### インライン参照

手順では、さまざまな種類のリソースをインラインで参照できます。

* ツール（例：注文の検索、カードへの請求、通話の終了、担当者への転送）
* ナレッジベースのドキュメント
* 他の手順

ステップでエージェントがツール、ナレッジベースのドキュメント、または別の手順を使用する必要がある場合は、必ずインライン参照を使用します。参照によりリソースが手順に自動で追加され、エージェントが使用できるようになります。\_ここで計算ツールを使用する_のように通常の文章で言及することもできますが、リソースがすでにエージェントに追加されている場合に限ります。

トリガーまたはコンテンツで`/`を入力し、スラッシュメニューからリソースを選択して参照を挿入します。参照はエディター内でクリック可能なタグとして表示されます。タグをクリックすると、元のリソースを開いて設定を確認できます。

APIを通じて自由形式のコンテンツを記述する場合は、次の構文で参照を挿入します。

```text focus={1-5}
[tool id="tool_abc123"]
[kb id="kb_abc123"]
[procedure id="agtprc_abc123"]
[system_tool id="end_call"]
{{customer_id}}
```

インラインの手順参照には、同じエージェントの手順を使用する必要があります。エージェントのスコープと複製時の動作については、[制限事項](/docs/ja/eleven-agents/customization/procedures#limitations)を参照してください。

トリガー内の参照により、リソースの出力に基づいて手順を開始できます。たとえば、\_`get_user`がtier 'gold'を返した場合_です。コンテンツ内の参照は、そのステップでリソースを呼び出す、または参照するようエージェントに指示します。

![手順エディターのスラッシュメニュー](/docs/_fern-img/8625ffec0f5584619e6ccb97720fd86f2e8d3cd0061308ad87b57f176e5535e3.webp)

参照先のリソースが後で削除された場合、またはアカウントがそのリソースへのアクセス権を失った場合、タグは壊れた状態で表示されます。エディター上部の**エラー**バッジには、これらの参照が一覧表示されます。リソースが存在しない場合は_無効\_、存在するもののアカウントにアクセス権がない場合は_利用不可_と表示されます。バッジを開くと影響を受けるステップを確認でき、参照を修正または削除できます。

![無効な参照を一覧表示するエラーダイアログ](/docs/_fern-img/e9ec6b19be2992da80a726883baf53265a5d5b38621373cd7e60375c944674cd.webp)

## サブ手順

サブ手順のトリガーは空です。参照している別の手順からのみ実行できます。

サブ手順を使用すると、1つのエージェント内で[ステップを共有](#composing-procedures)でき、同時に利用可能な手順の数を減らせます。エントリー手順にはトリガーを設定し、そのコンテンツから関連するサブ手順を参照し、サブ手順のトリガーは空のままにします。

エスカレーション用のサブ手順には、会話を担当者へ引き継ぐステップを含めることができます。返金およびキャンセルの手順からこれを参照し、トリガーは空のままにします。エージェントはどちらの手順でもステップの一部としてエスカレーションできますが、それら以外ではサブ手順を利用できません。

## ドキュメントからのインポート

既存の標準作業手順書（SOP）をもとに作成を始められます。手順一覧の **+** メニューで**SOPから**を選択し、ファイルをアップロードします。

対応形式：`PDF`、`DOCX`、`TXT`、`MD`、`HTML`、`EPUB`。ファイルは20MB以下である必要があります。

インポーターはドキュメントを分析し、最大10件の個別手順を識別して、それぞれに生成された名前、トリガー、コンテンツを含む下書きを作成します。各下書きを開いて調整してください。ドキュメントにSOPが10件を超えて含まれている場合は、アップロードする前に小さなファイルに分割してください。

![SOPアップロードダイアログ](/docs/_fern-img/716601fc90dea757e23971e5aabe063e6a66fc0f75878247dc9f1fc3011f5197.webp)

## 自由形式の手順を管理する

#### ダッシュボードで作成

[ダッシュボード](https://elevenlabs.io/app/agents)でエージェントを開き、**手順**を選択します。
**+** を使用して自由形式の手順を作成します。トリガーを追加し、コンテンツエディターに
指示を記述してから、エージェントの変更を公開します。

#### APIで管理

自由形式の手順は、`content`にMarkdownを保存します。

### 前提条件

* `ELEVENLABS_API_KEY`環境変数に設定したElevenLabs APIキー。
* 対象の`agent_id`と`branch_id`。ブランチ操作については、[エージェントのバージョニング](/docs/ja/eleven-agents/operate/versioning)を参照してください。
* `elevenlabs` Pythonパッケージまたは`@elevenlabs/elevenlabs-js` JavaScriptパッケージのバージョン`2.60.0`以降。

手順の下書きは[ユーザーごと・ ブランチごと](/docs/ja/eleven-agents/operate/versioning#drafts)です。公開すると、そのブランチの新しいエージェントバージョンに手順の
変更が保存されます。他のユーザーの下書きには影響しません。

### 下書きを作成する

```python focus={1,5-15}
from elevenlabs import CreateProcedureRequestModel, ElevenLabs

elevenlabs = ElevenLabs()

procedure = elevenlabs.conversational_ai.agents.procedures.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
    request=CreateProcedureRequestModel(
        name="Refund request",
        type="free_form",
        trigger="When the user asks to refund, return, or get money back for an order",
        content="Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
    ),
)

print(procedure.procedure_id)
```

```typescript focus={5-15}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const procedure = await elevenlabs.conversationalAi.agents.procedures.create(
  "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
  {
    name: "Refund request",
    type: "free_form",
    trigger: "When the user asks to refund, return, or get money back for an order",
    content: "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
  }
);

console.log(procedure.procedureId);
```

```bash focus={1-8}
curl -X POST "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund request",
    "type": "free_form",
    "trigger": "When the user asks to refund, return, or get money back for an order",
    "content": "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"]."
  }'
```

レスポンスには新しい`procedure_id`が含まれます。下書きを更新するには、
`name`、`content`、`type`、明示的な
`trigger`を指定して`PATCH /procedures/{procedure_id}/draft`を呼び出します。

エントリー手順には空でない`trigger`を使用します。
[サブ手順](#sub-procedures)には、空の文字列を使用します。

### 変更を公開する

ブランチ上のエージェントを更新し、自由形式の手順の下書きを新しいバージョンとして公開します。
リクエストの本文フィールドは不要です。下書きの状態のまま公開されます。

```python focus={5-8}
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
)
```

```typescript focus={5-7}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
});
```

```bash focus={1-5}
curl -X PATCH \
  "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

下書きの削除と破棄の動作については[手順を管理する](/docs/ja/eleven-agents/customization/procedures#manage-procedures)を、
エンドポイントスキーマの全体については
[手順APIリファレンス](/docs/ja/api-reference/agents/procedures/)を参照してください。

## ベストプラクティス

> **Tip**
>
> エージェントは、トリガーから適切な手順を選び、コンテンツに従う必要があります。手順数が増えるほど、より高性能なモデルのほうがこれを確実に実行できます。選択肢については、[モデル](/docs/ja/eleven-agents/customization/llm)を参照してください。

手順を適切に記述するとは、必要なときに手順を実行するトリガーと、エージェントが従えるコンテンツの2つを適切に記述することです。

### 手順の反復改善

小さく始め、[エージェントテスト](/docs/ja/eleven-agents/customization/agent-testing)で各変更を確認してから次の変更に進むことをおすすめします。

1. トリガーと短いコンテンツを記述します。
2. 手順を開始すべきリクエストと、似ているが開始すべきでないリクエストに対するシミュレーションテストを作成します。
3. 手順全体を実行するシミュレーションテストを作成します。
4. テストを実行します。失敗した場合は、トリガーまたはコンテンツを修正します。
5. 変更のたびにテストを再実行します。

テストや実際の会話が失敗した場合は、手順を変更する前に過去の会話から類似した失敗を検索し、それらすべてに対応する1つの指示を記述します。原因はナレッジベースやエージェント設定にある場合もあります。[Architect](/docs/ja/eleven-agents/operate/architect)でこの検索を実行できます。失敗した会話を開き、**Architect**を選択して、類似した失敗を探して修正案を提示するよう依頼してください。Architectでは会話をテストに変換することもできます。

> **Tip**
>
> トリガーを素早く反復改善するには、**最大会話ターン数**を`1`に設定したシミュレーションテストで試してください。シミュレーションは最初のやり取りの後に停止します。最初のリクエストで適切な手順が開始されるかを確認するにはこれで十分で、各実行も短く済みます。

### トリガーの記述

#### トリガーは具体的かつ重複しないようにする

重複または曖昧なトリガーは、誤った手順の実行につながります。\_ユーザーがサブスクリプションのキャンセルを求めた場合_のほうが、\_ユーザーがアカウントについて質問した場合_より適しています。

#### ユーザーの視点で記述する

エージェントが何をすべきかではなく、ユーザーが何を求めているかを説明します。エージェントのアクションとして表現されたトリガーは信頼性が低くなります。\_ユーザーがサブスクリプションのキャンセルを求めた場合_のほうが、\_ユーザーのサブスクリプションをキャンセルする_より適しています。

#### ユーザーが実際に尋ねる表現を網羅する

狭すぎるトリガーでは、ユーザーの表現が異なる場合に実際のリクエストを見逃す可能性があります。ユーザーが言いそうな言い回しのバリエーションを含めてください。\_ユーザーが注文の返金、返品、または払い戻しを求めた場合_のほうが、\_ユーザーが返金を要求した場合_より確実に実行されます。[過去の会話を検索](/docs/ja/eleven-agents/customization/agent-analysis/smart-search)して、ユーザーがリクエストをどのように表現しているかを確認してください。

#### 関連する手順間で引き継ぐ

ユーザーは手順の途中でリクエストを変更することがあり、トリガーだけでは適切な手順が開始されない場合があります。過去の会話で頻繁に見られる切り替えについては、最初の手順のコンテンツに他の手順へのインライン参照を追加します。たとえば、\_ユーザーが交換ではなく返金を希望する場合は、次を実行する：\_と記述し、続けて返金手順へのインライン参照を追加します。ほとんどの手順で引き継ぎが必要な場合は、代わりにトリガーをより明確に区別してください。

### コンテンツの記述

#### 命令形を使う

\_顧客の最新の注文を検索するとよいでしょう_ではなく、\_顧客の最新の注文を検索する_のように、エージェントへの指示としてステップを記述します。直接的な指示は、提案よりも従いやすくなります。

#### ステップが重要な理由を説明する

理由を示すと、手順に列挙されていないエッジケースにも対応できます。\_返金処理には注文IDが必要なため_と短く説明するだけで、ステップで想定していない状況にもエージェントが対応しやすくなります。1行の説明で同じ目的を果たせる場合は、すべて大文字の「MUST」や厳格なスクリプトを避けてください。

#### 避けることではなく、行うことを記述する

必要な動作を説明します。\_注文が見つからない場合は、ユーザーに注文IDの確認を依頼する_のほうが、\_注文の詳細を捏造しない_より効果的です。大きな損失につながるミスには、[ガードレール](/docs/ja/eleven-agents/best-practices/guardrails)も追加してください。

#### 事実はナレッジベースに保存する

手順では、状況に応じてエージェントが行うべきことを説明します。価格、プランの詳細、営業時間などの具体的な情報は、[ナレッジベース](/docs/ja/eleven-agents/customization/knowledge-base)に含めます。必要とする手順からドキュメントを参照してください。たとえば、すべてのプランの価格を手順に列挙する代わりに、\_次のドキュメントに記載の価格を提示する：\_と記述し、続けて料金ドキュメントへのインライン参照を追加します。

### 手順の組み合わせ

#### 状況ごとに1つの手順を記述する

1つの状況を複数の狭い手順に分割すると、エージェントが選ぶべきトリガーが増え、誤ったものを開始しやすくなります。2つの手順が同じリクエストで開始される場合は、統合してください。コンテンツが約3,000文字を超える場合は、通常、複数の状況を扱っています。

#### 共有するステップをサブ手順に抽出する

同じステップが複数の手順に含まれる場合（顧客の本人確認、注文の検索、担当者へのエスカレーション）は、それらを[サブ手順](#sub-procedures)に抽出し、必要な各手順からスラッシュメニューで参照します。共有ステップを1か所で管理すると、使用するすべての手順で一貫性を維持できます。

#### 呼び出されたときだけ実行するアクションにはサブ手順を使用する

本人確認やエスカレーションのように、別の手順から要求された場合にのみエージェントが実行すべきアクションには、サブ手順を使用します。トリガーがないため、会話開始時にエントリー手順と競合しません。トリガーの選択肢が減るため、エージェントが適切な手順を選びやすくなります。

#### 使用する手順からツールを参照する

ツールをエージェント全体に追加するのではなく、そのツールを使用する手順から参照します。これにより、関係のない会話でツールが利用されません。自由形式の手順では、ツールはその手順が直近で開始された5件のうちの1つである間のみ使用できます。詳細は[制限事項](/docs/ja/eleven-agents/customization/procedures#limitations)を参照してください。

#### グローバルな動作にはシステムプロンプトを使用する

口調、アイデンティティ、拒否ポリシー、ガードレールは、[システムプロンプト](/docs/ja/eleven-agents/best-practices/prompting-guide)に含めます。タスク固有のステップは手順に記述してください。

#### 手順はエージェントとともにバージョン管理される

手順はエージェント設定の一部であるため、新しいエージェントバージョンを公開すると、エージェント設定とまとめてスナップショットが保存されます。以前の手順セットにロールバックするには、以前のエージェントバージョンを復元します。[エージェントのバージョニング](/docs/ja/eleven-agents/operate/versioning)を参照してください。

#### 既存のドキュメントから作成を始める

チームにすでにSOPがある場合は、インポーターで下書きに変換してから調整してください。