> 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.

# コードツール

**コードツール** を使うと、独自のWebhookエンドポイントを立ち上げてホストしなくても、サンドボックス化されたサーバーサイド環境でエージェントにカスタムJavaScriptを実行させることができます。組み込みのコードエディターでロジックを一度記述すれば、エージェントがツールを呼び出すたびにElevenLabsが実行します。

> **Note**
>
> これはエンタープライズ限定の機能です。

## 概要

コードツールは、エージェントが呼び出したときに実行されるJavaScript関数です。関数本体全体を記述するため、タスクに応じて必要なだけの処理をツールに実行させられます。

* **カスタム計算**：ツール呼び出しパラメータだけを使用して、価格ルール、単位変換、スコアリングロジック、日付計算を適用します。ネットワークアクセスは不要です。
* **外部APIの呼び出し**：許可リストに登録されたドメインに対して `fetch` を実行します。ワークスペースのシークレットと認証接続は関数のコンテキストに注入されます。
* **複数ソースの統合**：2つまたは3つのAPIを呼び出し、結果をマージ、比較、照合してから、単一の回答として返します。
* **条件分岐**：ツール呼び出しパラメータに応じて異なるロジックを実行します。分岐ごとに別のツールは必要ありません。
* **データの整形**：未加工のアップストリームレスポンスではなく、エージェントに表示したい構造そのままで返します。

> **Info**
>
> カスタムロジックを必要としない単一の外部API呼び出しには、通常、[Webhook ツール](/docs/ja/eleven-agents/customization/tools/webhook-tools) の方が設定が簡単です。ユーザーのブラウザまたはアプリでアクションをトリガーするには、代わりに[クライアント ツール](/docs/ja/eleven-agents/customization/tools/client-tools) を使用してください。

## 仕組み

コードは、単一のデフォルト非同期関数をエクスポートするJavaScriptモジュールです。この関数は `ctx` オブジェクトを受け取り、ツールの結果を返します。

```javascript
export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;

  return { message: `Hello from ${city}!` };
};
```

返した値がツールの結果になります。結果はエージェントに返され、会話の文字起こしに表示され、[動的変数の割り当て](/docs/ja/eleven-agents/customization/tools/webhook-tools#tool-configuration) に使用できます。

### `ctx` オブジェクト

`ctx` は、呼び出し時にツールがアクセスできるすべての要素へのエントリーポイントです。エージェントが指定するパラメータは常に `ctx.args` に渡されます。シークレット、設定値、認証接続は任意で、ツールの **コンテキストオブジェクト** セクションでマッピングした場合にのみ表示されます。

| プロパティ                  | 説明                                                                                                                                                                                                                            |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx.args`             | エージェントが指定したツール呼び出しパラメータ。                                                                                                                                                                                                      |
| `ctx.config`           | このツールのコンテキストにマッピングしたプレーンテキストの文字列変数。                                                                                                                                                                                           |
| `ctx.secrets`          | リクエストヘッダーで使用するために、このツールのコンテキストにマッピングしたワークスペースシークレット。生のシークレットがコードに公開されることはありません。注入はエグレス時にヘッダー内でのみ行われます。                                                                                                                        |
| `ctx.auth_connections` | `X-With-Auth-Connection` リクエストヘッダーで使用するために、このツールのコンテキストにマッピングした、設定済みの[認証接続](/docs/ja/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods)への参照。基になる認証情報がコードに公開されることはありません。注入はエグレス時にヘッダー内でのみ行われます。 |

> **Note**
>
> エージェントがツールを呼び出す際に見えるのは `ctx.args` のみです。シークレット、設定値、認証
> 接続がエージェントに公開されることはありません。

#### パラメータの設定

パラメータは、エージェントがツールを呼び出す際に指定する値であり、`ctx.args` に渡されます。ツール設定フォームの **パラメータ** セクション、またはコードエディターの **Params** タブにある **Define Params** サブタブで定義します。各パラメータには、データ型、識別子、会話から正しい値を判断するためにエージェントが使用する説明を設定します。コードでは、以下の `ctx.args.appointment_datetime` のように、識別子でその値を読み取ります。

![コードツールのパラメータを定義する](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp)

#### コンテキストオブジェクトの設定

ツールの **コンテキストオブジェクト** セクションで、シークレット、設定値、認証接続を追加します。各エントリには型と名前を設定します。パネルには、以下の `ctx.secrets.DEMO_KEY` のように、各エントリの正確なアクセサーが表示されます。

![ワークスペースシークレットをコードツールのコンテキストオブジェクトにマッピングする](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp)

### ネットワークアクセス

サンドボックス内で実行されるコードは、ワークスペースで明示的に許可したドメインにのみアクセスできます。コードから呼び出す必要があるドメインを、**ElevenAgents Settings** の **Code Tool Network Access** に追加してください。その他のドメインへのリクエストは失敗します。

> **Warning**
>
> **Code Tool Network Access** の編集には、ワークスペース管理者権限が必要です。

### 実行制限

* **タイムアウト**：各実行は、ツールに設定された1〜30秒のレスポンスタイムアウト以内に完了する必要があります。
* **外部パッケージは使用不可**：コードツールは現在、npm依存関係なしで実行されます。

### コードのテスト

保存前に、コードエディターの **Run** を使用して、サンプルパラメータ値でコードを実行します。

* **Params** — ツールで定義した各パラメータのテスト値を設定します。
* **Output** — 返された結果、または実行に失敗した場合のエラーを確認します。
* **Logs** — `console.log`、`console.warn`、`console.error` で出力された内容に加え、ビルドと実行のタイミングを確認します。

## ガイド

このガイドでは、温度を変換し、見やすく整形された文字列を返すコードツールを作成します。

#### 新しいコードツールを作成する

エージェント設定ページの **Agent** セクションで、**Add Tool** を選択します。ツールタイプとして **Code** を選択し、名前と説明を設定します。

| フィールド | 値                   |
| ----- | ------------------- |
| 名前    | convert_temperature |
| 説明    | 摂氏と華氏の間で温度を変換する     |

#### パラメータを定義する

LLMが指定すべき内容を認識できるように、2つのパラメータを追加します。

| データ型   | 識別子       | 必須   | 説明                     |
| ------ | --------- | ---- | ---------------------- |
| number | value     | true | 変換する温度の値               |
| string | from_unit | true | 変換元の単位：`"C"` または `"F"` |

#### コードを書く

コードエディターを開き、デフォルトのソースを以下に置き換えます。

```javascript
export default async (ctx) => {
  const { value, from_unit } = ctx.args;

  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }

  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};
```

保存する前に、**Run** を使っていくつかのサンプル値（例：`value: 100, from_unit: "C"`）を試し、出力を確認します。

#### オーケストレーション

ツールを使用すべきタイミングを認識できるように、エージェントのシステムプロンプトを更新します。

**`System prompt`**

```plaintext System prompt
When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.
```

#### テスト

会話を開始して、以下を試します。

> *摂氏100度は華氏で何度ですか？*

エージェントがツールを呼び出し、変換後の値を読み上げるはずです。

### 認証の例

**シークレットを使用してAPIを呼び出す**

```javascript
export default async (ctx) => {
  const { order_id } = ctx.args;

  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }

  return await response.json();
};
```

ツールの **コンテキストオブジェクト** セクションで、`EXAMPLE_API_KEY` をワークスペースシークレットにマッピングします。次に、リクエストがエグレスできるように、`api.example.com` を **Code Tool Network Access** に追加します。参照する値はプレースホルダーです。実際のシークレットはエグレス時にヘッダーへ代入され、コードから見えることはありません。

**OAuth認証接続を使用してAPIを呼び出す**

```javascript
export default async (ctx) => {
  const { customer_id } = ctx.args;

  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });

  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }

  return await response.json();
};
```

ツールの **コンテキストオブジェクト** セクションで、`EXAMPLE_CRM` を設定済みの[認証接続](/docs/ja/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods)にマッピングします。参照する値はプレースホルダーです。実際の認証情報はエグレス時にヘッダーへ代入され、コードから見えることはありません。

## ベストプラクティス

#### ツールには直感的な名前を付け、詳しく説明する

アシスタントが適切なツールを呼び出さない場合は、各ツールをいつ選択すべきかをアシスタントがより明確に理解できるよう、ツール名と説明を更新する必要があるかもしれません。ツール名や引数名を短くするために、略語や頭字語を使用しないでください。

ツールをいつ呼び出すべきかについて、詳しい説明を含めることもできます。複雑なツールでは、各引数についての説明も含めると、アシスタントがその引数を収集するためにユーザーへ何を尋ねる必要があるかを把握しやすくなります。

#### ツールパラメータには直感的な名前を付け、詳しく説明する

ツールパラメータには、明確で説明的な名前を使用してください。該当する場合は、説明内でパラメータに期待される形式を指定します（例：日付の場合はYYYY-mm-ddまたはdd/mm/yy）。

#### アシスタントのシステムプロンプトに、ツールを呼び出す方法とタイミングに関する追加情報を含めることを検討する

システムプロンプトで明確な指示を与えると、アシスタントのツール呼び出し精度を大幅に向上させることができます。たとえば、以下のような指示でアシスタントをガイドします。

```plaintext
Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.
```

複雑なシナリオにはコンテキストを提供します。例：

```plaintext
Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.
```

#### LLMの選択

> **Warning**
>
> ツールを使用する場合は、GPT 6やClaude Sonnet 5.5のような高知能モデルを選択することをおすすめします。

LLMの選択は、関数呼び出しの成功に重要な影響を与えます。一部のLLMは、会話から関連するパラメータを抽出するのが難しい場合があります。