コードツール | ElevenLabs Documentation

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

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

概要

コードツールは、エージェントが呼び出したときに実行されるJavaScript関数です。関数本体をすべて記述するため、タスクに必要な範囲で処理を実装できます：

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

カスタムロジックのない単一の外部API呼び出しでは、通常はWebhook ツールのほうが簡単に設定できます。ユーザーのブラウザやアプリでアクションを実行するには、代わりにクライアントツールを使用してください。

仕組み

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

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}!` };
};

返した値がツールの結果になります。これはエージェントに返され、会話トランスクリプトに表示され、動的変数の割り当てに使用できます。

`ctx`オブジェクト

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

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

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

パラメーターを設定する

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

コンテキストオブジェクトを設定する

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

ワークスペースシークレットをコードツールのコンテキストオブジェクトにマッピングする

ネットワークアクセス

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

Code tool allowed domainsリストの編集には、ワークスペース管理者権限が必要です。

実行制限

タイムアウト：各実行は、ツールに設定された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"`

コードを記述

コードエディターを開き、デフォルトのソースを次の内容に置き換えます：

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` };
};

保存前に、いくつかのサンプル値（例：value: 100, from_unit: "C"）でRunを実行し、出力を確認します。

オーケストレーション

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

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を呼び出す

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 allowed domainsへ追加します。参照する値はプレースホルダーです。実際のシークレットはエグレス時にヘッダーへ置換され、コードから見えることはありません。

OAuth認証接続を使ってAPIを呼び出す

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を設定済みの認証接続にマッピングします。参照する値はプレースホルダーです。実際の認証情報はエグレス時にヘッダーへ置換され、コードから見えることはありません。

ベストプラクティス

ツールには直感的な名前と詳しい説明を付ける

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

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

ツールパラメータには直感的な名前と詳しい説明を付ける

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

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

システムプロンプトで明確な指示を与えると、アシスタントのツール呼び出し精度を大幅に改善できます。たとえば、次のような指示でアシスタントを導きます。

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

複雑なシナリオにはコンテキストを提供してください。例：

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

LLMの選択

ツールを使用する場合は、GPT 5.2、Gemini-2.5-Flash、 Claude Sonnet 4.5などの高性能モデルを選び、Gemini-2.0-Flashは避けることをおすすめします。

LLMの選択は、関数呼び出しの成功に重要であることに注意してください。一部のLLMでは、会話から関連するパラメータを抽出するのが難しい場合があります。

概要

仕組み

ctxオブジェクト