Saltar a la navegación

Herramientas como código

Crea, edita y versiona herramientas de agentes con los SDK de Python y JavaScript

Descripción general

Una herramienta se almacena como una configuración con esquemas JSON anidados para sus parámetros. Escribir esa configuración a mano implica mantener los parámetros de ruta sincronizados con la URL, las listas required sincronizadas con sus propiedades y asignar a cada parámetro exactamente una fuente de valor. El creador de herramientas de los SDK de Python y JavaScript te permite describir la misma herramienta mediante llamadas a métodos encadenadas. Después genera la solicitud que tools.create() y tools.update() ya aceptan.

Úsalo para:

  • Definir herramientas de webhook, cliente y sistema en código, y revisarlas como cualquier otro cambio de código.
  • Cargar una herramienta, cambiar un parámetro y volver a enviarla sin modificar el resto de su configuración.
  • Almacenar herramientas como JSON en el control de versiones y validarlas en CI.

El creador se ejecuta íntegramente en el SDK. No llama a rutas de API nuevas y cualquier elemento que cree se puede abrir y editar en el panel de control.

Requisitos

  • Python: el paquete elevenlabs. El creador se importa desde elevenlabs.agent_tools.
  • JavaScript: el paquete @elevenlabs/elevenlabs-js. El creador se exporta desde la raíz del paquete.

Crear una herramienta de webhook

Tool.webhook(name, description) inicia una herramienta de webhook. El nombre y la descripción son lo que ve el LLM al decidir si debe llamar a la herramienta. Este ejemplo busca un pedido mediante el número que proporciona la persona que llama, envía una clave de API desde los secretos del espacio de trabajo y almacena el estado del pedido en una variable dinámica:

from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool
elevenlabs = ElevenLabs()
get_order = (
Tool.webhook("get_order", "Look up an order by the number the caller gives")
.get("https://api.example.com/orders/{order_id}")
.path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
.query_param("include", Schema.string().constant("items"))
.header("Authorization", Header.secret("sec_orders_api"))
.assign("order_status", "order.status")
.options(response_timeout_secs=10)
)
tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

Los métodos de solicitud establecen el método HTTP y la URL. Los marcadores {name} de la URL se rellenan con parámetros de ruta:

PythonJavaScriptEstablece
get(url), post(url), put(url), patch(url), delete(url)igualEl método y la URL. POST, PUT y PATCH necesitan un cuerpo; GET no puede tenerlo.
path_param(name, schema)pathParam(name, schema)Un parámetro de ruta para el marcador {name} de la URL.
query_param(name, schema)queryParam(name, schema)Un parámetro de consulta.
body(schema)body(schema)El cuerpo de la solicitud. Debe ser un esquema de objeto.
response(schema)response(schema)El esquema del cuerpo de la respuesta. Debe ser un esquema de objeto.
header(name, value)header(name, value)Una cabecera de solicitud. Consulta Cabeceras y autenticación.
auth(connection)auth(connection)La conexión de autenticación que se usará.
assign(variable, path)assign(variable, path)Almacena en una variable dinámica el valor de path en la respuesta (notación de puntos).

Establecer un parámetro o una cabecera cuyo nombre ya existe lo reemplaza y conserva su posición. remove_path_param(), remove_query_param(), remove_header() y remove_assignment() (removePathParam() y equivalentes en JavaScript) eliminan uno. Los nombres de los parámetros deben ser únicos entre la ruta, la consulta y el cuerpo.

Un cuerpo es un esquema de objeto construido propiedad a propiedad:

refund = (
Tool.webhook("issue_refund", "Refund an order the caller asked to return")
.post("https://api.example.com/refunds")
.body(
Schema.object()
.property("order_id", Schema.string().from_variable("order_id"))
.property(
"reason",
Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
)
.property("note", Schema.string().describe("Anything else the caller said").optional())
)
)

Esquemas de parámetros

Schema crea los esquemas de parámetros que usan las herramientas de webhook y cliente. Cada método devuelve un esquema nuevo y deja sin modificar aquel sobre el que se llamó, por lo que puedes definir un esquema una vez y usarlo en varias herramientas.

ConstructorCrea
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Un valor literal
Schema.object()Un objeto. Añade propiedades con property().
Schema.array(items)Una matriz cuyos elementos cumplen el esquema items

De dónde procede un valor

Cada literal necesita exactamente una fuente de valor, aparezca donde aparezca: en un parámetro, en un cuerpo, en un esquema de respuesta o dentro de un objeto o una matriz. Un objeto o una matriz también pueden tener una, que proporciona entonces el valor completo.

PythonJavaScriptEl valor
describe(text)describe(text)Lo proporciona el LLM, guiado por text.
from_variable(name)fromVariable(name)Se lee de una variable dinámica cuando se ejecuta la herramienta.
constant(value)constant(value)Siempre es value.
system_provided()systemProvided()Lo completa el sistema cuando se ejecuta la herramienta. Solo literales.
omit()omit()Se omite de la solicitud. Solo para una propiedad opcional.

En un objeto o una matriz, describe() documenta el contenedor para el LLM, y cada propiedad o elemento sigue teniendo su propia fuente.

Otros métodos de esquema

PythonJavaScriptFunción
optional()optional()Hace que una propiedad sea opcional. Las propiedades son obligatorias salvo que se marquen como opcionales.
choices(values)choices(values)Limita una cadena a un conjunto fijo de valores entre los que elige el LLM.
allowed_from(variable)allowedFrom(variable)Rechaza un valor del LLM que no esté en la lista de una variable dinámica. Necesita describe().
property(name, schema) / without(name)property(name, schema) / without(name)Añade, reemplaza o elimina una propiedad de objeto. Una propiedad reemplazada conserva su posición.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Requiere al menos una, o todas, las propiedades opcionales de un grupo.

Cabeceras y autenticación

El valor de una cabecera procede de uno de cuatro lugares. Usa un secreto o una variable de entorno para cualquier dato sensible, de modo que el valor nunca aparezca en la configuración de la herramienta:

ConstructorEl valor de la cabecera es
Header.value(text)Texto fijo.
Header.secret(id)Un secreto del almacén de secretos del espacio de trabajo.
Header.variable(name)Una variable dinámica, leída al ejecutar la herramienta.
Header.env_var(label) / Header.envVar(label)Una variable de entorno del espacio de trabajo, resuelta para el entorno actual.

AuthConnection.id(id) usa una conexión de autenticación del espacio de trabajo mediante su ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) la selecciona desde una variable de entorno, para que la misma configuración de herramienta pueda usar una conexión distinta en cada entorno.

from elevenlabs.agent_tools import AuthConnection, Header
update_profile = (
Tool.webhook("update_profile", "Update the caller's email address")
.put("https://api.example.com/profiles/{profile_id}")
.path_param("profile_id", Schema.string().from_variable("profile_id"))
.body(Schema.object().property("email", Schema.string().describe("The new email address")))
.header("X-Api-Key", Header.env_var("profiles_api_key"))
.auth(AuthConnection.env_var("profiles_oauth"))
)

Crear una herramienta de cliente

Tool.client(name, description) inicia una herramienta de cliente, que se ejecuta en tu aplicación en lugar de en un servidor. Añade sus parámetros con param(name, schema). Establece expects_response / expectsResponse cuando el agente deba esperar el resultado de tu aplicación:

show_map = (
Tool.client("show_store_map", "Show the caller a map of the nearest store")
.param("store_id", Schema.string().describe("The store to show"))
.options(expects_response=False)
)

Crear una herramienta de sistema

Las herramientas de sistema están integradas en la plataforma. Cada una tiene su propio constructor en SystemTool, que recibe la configuración de esa herramienta:

PythonJavaScript
SystemTool.end_call()SystemTool.endCall()
SystemTool.skip_turn(wait_timeout_secs=...)SystemTool.skipTurn({ waitTimeoutSecs })
SystemTool.language_detection(...)SystemTool.languageDetection(options?)
SystemTool.play_keypad_touch_tone(...)SystemTool.playKeypadTouchTone(options?)
SystemTool.voicemail_detection(voicemail_message=...)SystemTool.voicemailDetection({ voicemailMessage })
SystemTool.knowledge_base(enabled_strategies=...)SystemTool.knowledgeBase({ enabledStrategies })
SystemTool.transfer_to_number(...)SystemTool.transferToNumber(options?)
SystemTool.transfer_to_agent()SystemTool.transferToAgent()

Las dos herramientas de transferencia toman sus destinos de transfer(condition, destination, options). La condición indica al LLM cuándo transferir allí, y el destino usa el mismo Destination que los workflows como código. Una transferencia a una URI SIP necesita una transferencia SIP REFER:

from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination
transfer = (
SystemTool.transfer_to_number()
.transfer("Caller asks for billing", Destination.phone("+15551234567"))
.transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)
to_sales = SystemTool.transfer_to_agent().transfer(
"Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)

Opciones de herramientas

La configuración compartida por todos los tipos de herramientas se incluye en options(), como argumentos con nombre en Python y como objeto en JavaScript. Sus nombres coinciden con los campos de la configuración de la herramienta en la API:

Se aplica aPythonJavaScript
Todas las herramientasname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Herramientas de webhookexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Herramientas de clienteexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

El tiempo de espera de respuesta de una herramienta de webhook es de 5 a 300 segundos. El de una herramienta de cliente es de 1 a 120 segundos, o -1 para esperar el tiempo necesario, lo que requiere expects_response / expectsResponse. follow_redirects / followRedirects necesita una lista de dominios permitidos.

Vincular herramientas a un agente

Las herramientas de webhook y cliente se crean de forma independiente con tools.create() y se vinculan a agentes mediante ID, por lo que una herramienta puede compartirse entre varios agentes. Las herramientas de sistema forman parte de la configuración del agente: build_config() / buildConfig() devuelve la entrada para las herramientas integradas del agente.

from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput
order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
agent = elevenlabs.conversational_ai.agents.create(
name="Support line",
conversation_config=ConversationalConfig(
agent=AgentConfig(
prompt=PromptAgentApiModelOutput(
prompt="You are a support agent for Acme.",
tool_ids=[order_tool.id],
built_in_tools=BuiltInToolsOutput(
end_call=SystemTool.end_call().build_config(),
transfer_to_number=transfer.build_config(),
),
)
)
),
)

El campo prompt.tools del agente, que contiene configuraciones de herramientas integradas, está obsoleto. No se puede combinar con tool_ids y, cuando una solicitud lo incluye, las herramientas integradas del agente se reemplazan por las herramientas de sistema que contiene. En su lugar, crea herramientas con tools.create() y vincúlalas mediante ID.

Editar una herramienta existente

Tool.from_response() / Tool.fromResponse() carga una herramienta devuelta por tools.get(). Se conservan los campos que el creador no modela y los valores predeterminados que completa la API, por lo que al volver a enviarla solo cambia lo que hayas modificado. as_webhook(), as_client() y as_system() (asWebhook() y equivalentes en JavaScript) te proporcionan la herramienta tipada para editarla, o None / undefined si es de otro tipo.

Para cambiar una propiedad del cuerpo, lee el esquema del cuerpo, vuelve a establecer la propiedad y establece el cuerpo:

from elevenlabs.agent_tools import ObjectSchema
loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
raise ValueError("Not a webhook tool")
body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())
elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())

Almacenar herramientas en el control de versiones

to_json_string() / toJSONString() escribe la herramienta en el formato de transferencia de la API: claves en snake_case, ordenadas en todos los niveles y con sangría de 2 espacios. Tiene la misma estructura que conserva la CLI en su directorio tool_configs/, y ambos SDK escriben archivos idénticos byte a byte para la misma herramienta, de modo que las diferencias se mantienen pequeñas. Tool.from_json() / Tool.fromJSON() lo vuelve a leer.

from pathlib import Path
from elevenlabs.agent_tools import Tool
Path("tool_configs/get_order.json").write_text(get_order.to_json_string())
stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())

Una configuración habitual es la misma que para los workflows: inicializa los archivos con elevenlabs tools pull, edítalos directamente o con el creador, ejecuta Tool.from_json(file).build() / Tool.fromJSON(file).build() en CI para cada pull request y envíalos con tools.update() o elevenlabs tools push al fusionar.

Validación

Las llamadas encadenadas nunca fallan por sí solas. build(), build_config() / buildConfig(), to_json() / toJSON() y to_json_string() / toJSONString() comprueban toda la herramienta y generan o lanzan un único ToolValidationError cuya lista issues enumera cada problema, cada uno con un code, un message y la path de la parte a la que afecta, como body.reason.

from elevenlabs.agent_tools import ToolValidationError
try:
request = refund.build()
except ToolValidationError as err:
for issue in err.issues:
print(issue.code, issue.path, issue.message)

Los errores incluyen:

  • Un marcador de URL sin parámetro de ruta, o un parámetro de ruta sin marcador. Las plantillas de variables de entorno, como {{system__env_api_host}}, no son marcadores.
  • Un literal sin fuente de valor, o con más de una.
  • Un cuerpo en un GET, o la ausencia de cuerpo en un POST, PUT o PATCH.
  • El mismo nombre de parámetro en más de una de estas ubicaciones: ruta, consulta y cuerpo.
  • omit() en una propiedad obligatoria, choices() en un esquema que no es una cadena o una constante que no coincide con el tipo del esquema.
  • Una herramienta de transferencia sin destinos, un destino del tipo incorrecto o un destino de URI SIP sin transferencia SIP REFER.
  • Una opción que no se aplica al tipo de herramienta o un tiempo de espera fuera de su intervalo.

Tipos de herramientas más recientes que tu SDK

Una herramienta cargada desde la API o desde un archivo puede ser de un tipo que el creador no puede editar, como una herramienta MCP. Se carga con el tipo "other" y se conserva sin cambios al pasar por from_json() / fromJSON() y to_json_string() / toJSONString(), y build() la informa como advertencia mediante on_warning / onWarning.