コードツール

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

概要

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

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

仕組み

コードは、単一のデフォルト非同期関数をエクスポートする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 に渡されます。ツール設定フォームの パラメータ セクション、またはコードエディターの Params タブにある Define Params サブタブで定義します。各パラメータには、データ型、識別子、会話から正しい値を判断するためにエージェントが使用する説明を設定します。コードでは、以下の ctx.args.appointment_datetime のように、識別子でその値を読み取ります。

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

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

ネットワークアクセス

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

実行制限

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

コードのテスト

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

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

ガイド

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

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

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.

認証の例

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

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の選択

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