コードで管理するツール
PythonおよびJavaScript SDKでエージェントツールを構築、編集、バージョン管理
概要
ツールは、パラメータ用のJSONスキーマをネストした設定として保存されます。この設定を手動で記述する場合、パスパラメータとURL、required リストとそのプロパティをそれぞれ一致させ、すべてのパラメータに値の取得元を1つだけ指定する必要があります。PythonおよびJavaScript SDKのツールビルダーを使うと、同じツールをメソッドチェーンで記述できます。その後、tools.create() と tools.update() がそのまま受け取れるリクエストが生成されます。
次の用途に使用できます。
- Webhook、クライアント、システムツールをコードで定義し、ほかのコード変更と同じようにレビューする。
- ツールを読み込み、ほかの設定を変えずにパラメータを1つ変更して反映する。
- ツールをJSONとしてバージョン管理に保存し、CIで検証する。
ビルダーはSDK内だけで動作します。新しいAPIエンドポイントは呼び出しません。また、ビルダーで作成したものはすべて ダッシュボードで開いて編集できます。
要件
- Python:
elevenlabsパッケージ。ビルダーはelevenlabs.agent_toolsからインポートします。 - JavaScript:
@elevenlabs/elevenlabs-jsパッケージ。ビルダーはパッケージルートからエクスポートされます。
Webhookツールを構築する
Tool.webhook(name, description) でWebhookツールの作成を開始します。名前と説明は、ツールを呼び出すかどうかを判断するときにLLMが参照します。この例では、発信者が伝えた番号から注文を検索し、ワークスペースのシークレットからAPIキーを送信して、注文ステータスを動的変数に保存します。
リクエストメソッドでは、HTTPメソッドとURLを設定します。URL内の {name} プレースホルダーには、パスパラメータの値が入ります。
すでに存在する名前のパラメータやヘッダーを設定すると、位置を維持したまま置き換えられます。remove_path_param()、remove_query_param()、remove_header()、remove_assignment()(JavaScriptでは removePathParam() など)を使うと削除できます。パラメータ名は、パス、クエリ、ボディ全体で一意である必要があります。
ボディは、プロパティを1つずつ追加して構築するオブジェクトスキーマです。
パラメータスキーマ
Schema は、Webhookツールとクライアントツールで使用するパラメータスキーマを構築します。各メソッドは新しいスキーマを返し、呼び出し元のスキーマは変更しません。そのため、一度定義したスキーマを複数のツールで使用できます。
値の取得元
パラメータ、ボディ、レスポンススキーマ、オブジェクトや配列の内部など、どこに現れる場合でも、各リテラルには値の取得元を1つだけ指定する必要があります。オブジェクトや配列にも取得元を指定でき、その場合は値全体が提供されます。
オブジェクトまたは配列で describe() を使うと、LLM向けにコンテナを説明できます。各プロパティまたは要素には、引き続き個別の取得元が必要です。
その他のスキーマメソッド
ヘッダーと認証
ヘッダー値の取得元は4種類あります。機密情報にはシークレットまたは環境変数を使用し、ツール設定に値が表示されないようにしてください。
AuthConnection.id(id) は、IDを指定してワークスペースの認証接続を使用します。AuthConnection.env_var(label) / AuthConnection.envVar(label) は環境変数から認証接続を選択するため、同じツール設定で環境ごとに異なる接続を使用できます。
クライアントツールを構築する
Tool.client(name, description) で、サーバーではなくアプリケーション内で実行されるクライアントツールの作成を開始します。param(name, schema) でパラメータを追加します。エージェントがアプリケーションからの結果を待つ必要がある場合は、expects_response / expectsResponse を設定します。
システムツールを構築する
システムツールはプラットフォームに組み込まれています。それぞれに SystemTool 上の専用コンストラクターがあり、各ツールの設定を受け取ります。
2つの転送ツールでは、transfer(condition, destination, options) で転送先を指定します。条件はLLMに転送のタイミングを伝え、転送先にはコードで管理するワークフローと同じ Destination を使用します。SIP URIへの転送にはSIP REFER転送が必要です。
ツールオプション
すべての種類のツールで共通する設定は options() に指定します。Pythonではキーワード引数、JavaScriptではオブジェクトを使用します。名前はAPIのツール設定フィールドと一致します。
Webhookツールのレスポンスタイムアウトは5~300秒です。クライアントツールでは1~120秒、または完了まで無期限に待機する場合は-1です。-1を指定するには expects_response / expectsResponse が必要です。follow_redirects / followRedirects には、許可するドメインのリストが必要です。
ツールをエージェントに接続する
Webhookツールとクライアントツールは tools.create() で個別に作成し、IDでエージェントに接続します。そのため、1つのツールを複数のエージェントで共有できます。システムツールはエージェント設定の一部です。build_config() / buildConfig() は、エージェントの組み込みツール用エントリを返します。
ツール設定をインラインで保持するエージェントの prompt.tools フィールドは非推奨です。tool_ids とは
併用できません。また、リクエストにこのフィールドを含めると、エージェントの組み込みツールが、そこに含まれる
システムツールに置き換えられます。代わりに tools.create() でツールを作成し、IDで接続してください。
既存のツールを編集する
Tool.from_response() / Tool.fromResponse() は、tools.get() が返したツールを読み込みます。ビルダーがモデル化していないフィールドやAPIによって補完されるデフォルト値も保持されるため、再度反映したときに変更されるのは編集した部分だけです。as_webhook()、as_client()、as_system()(JavaScriptでは asWebhook() など)を使うと、編集用の型付きツールを取得できます。別の種類の場合は None / undefined が返されます。
ボディのプロパティを変更するには、ボディスキーマを読み取り、プロパティを再設定してからボディを設定します。
ツールをバージョン管理に保存する
to_json_string() / toJSONString() は、APIの通信形式でツールを書き出します。キーはsnake_caseで、すべての階層で並べ替えられ、2スペースでインデントされます。これはCLIが tool_configs/ ディレクトリに保持する形式と同じです。また、同じツールであれば両方のSDKがバイト単位で同一のファイルを書き出すため、差分を小さく保てます。Tool.from_json() / Tool.fromJSON() で再度読み込めます。
一般的な構成はワークフローと同じです。elevenlabs tools pull でファイルを作成し、直接またはビルダーで編集します。すべてのプルリクエストに対してCIで Tool.from_json(file).build() / Tool.fromJSON(file).build() を実行し、マージ時に tools.update() または elevenlabs tools push で反映します。
検証
メソッドチェーンの呼び出し自体が失敗することはありません。build()、build_config() / buildConfig()、to_json() / toJSON()、to_json_string() / toJSONString() はツール全体をチェックし、単一の ToolValidationError を発生させます。その issues にはすべての問題が一覧表示され、各問題には code、message、および対象部分の path(body.reason など)が含まれます。
エラーには次のものがあります。
- 対応するパスパラメータがないURLプレースホルダー、または対応するプレースホルダーがないパスパラメータ。
{{system__env_api_host}}などの環境変数テンプレートはプレースホルダーではありません。 - 値の取得元がない、または複数あるリテラル。
GETにボディがある、またはPOST、PUT、PATCHにボディがない。- パス、クエリ、ボディのうち複数の場所で同じパラメータ名が使われている。
- 必須プロパティに
omit()を使用している、文字列以外のスキーマにchoices()を使用している、または定数がスキーマの型と一致しない。 - 転送先がない転送ツール、種類が正しくない転送先、またはSIP REFER転送を指定していないSIP URI転送先。
- ツールの種類に適用できないオプション、または範囲外のタイムアウト。
SDKより新しいツールタイプ
APIまたはファイルから読み込んだツールが、MCPツールなど、ビルダーで編集できないタイプである場合があります。その場合、種類は "other" として読み込まれ、from_json() / fromJSON() と to_json_string() / toJSONString() を経由しても変更されません。また、build() は on_warning / onWarning を通じて警告として報告します。