Ir para a navegação

Ferramentas como código

Crie, edite e versione ferramentas de agentes com os SDKs de Python e JavaScript

Visão geral

Uma ferramenta é armazenada como uma configuração com esquemas JSON aninhados para seus parâmetros. Escrever essa configuração manualmente significa manter os parâmetros de caminho alinhados com a URL, as listas required alinhadas com suas propriedades e atribuir a cada parâmetro exatamente uma fonte de valor. O criador de ferramentas nos SDKs de Python e JavaScript permite descrever a mesma ferramenta com chamadas de método encadeadas. Em seguida, ele produz a solicitação que tools.create() e tools.update() já aceitam.

Use-o para:

  • Definir ferramentas de webhook, cliente e sistema em código e revisá-las como qualquer outra alteração de código.
  • Carregar uma ferramenta, alterar um parâmetro e enviá-la de volta sem afetar o restante da configuração.
  • Armazenar ferramentas como JSON no controle de versão e validá-las na CI.

O criador é executado inteiramente no SDK. Ele não chama novos endpoints da API, e tudo que ele cria pode ser aberto e editado no painel.

Requisitos

  • Python: o pacote elevenlabs. O criador é importado de elevenlabs.agent_tools.
  • JavaScript: o pacote @elevenlabs/elevenlabs-js. O criador é exportado da raiz do pacote.

Criar uma ferramenta de webhook

Tool.webhook(name, description) inicia uma ferramenta de webhook. O nome e a descrição são o que o LLM vê ao decidir se deve chamar a ferramenta. Este exemplo busca um pedido pelo número informado por quem liga, envia uma chave de API dos segredos do workspace e armazena o status do pedido em uma variável 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())

Os métodos de solicitação definem o método HTTP e a URL. Os placeholders {name} na URL são preenchidos com parâmetros de caminho:

PythonJavaScriptDefine
get(url), post(url), put(url), patch(url), delete(url)igualO método e a URL. POST, PUT e PATCH precisam de um corpo; GET não pode ter um.
path_param(name, schema)pathParam(name, schema)Um parâmetro de caminho para o placeholder {name} na URL.
query_param(name, schema)queryParam(name, schema)Um parâmetro de consulta.
body(schema)body(schema)O corpo da solicitação. Deve ser um esquema de objeto.
response(schema)response(schema)O esquema do corpo da resposta. Deve ser um esquema de objeto.
header(name, value)header(name, value)Um cabeçalho de solicitação. Consulte Cabeçalhos e autenticação.
auth(connection)auth(connection)A conexão de autenticação a usar.
assign(variable, path)assign(variable, path)Armazena o valor em path na resposta (notação de ponto) em uma variável dinâmica.

Definir um parâmetro ou cabeçalho cujo nome já existe o substitui e mantém sua posição. remove_path_param(), remove_query_param(), remove_header() e remove_assignment() (removePathParam() e assim por diante no JavaScript) removem um item. Os nomes dos parâmetros devem ser únicos entre caminho, consulta e corpo.

Um corpo é um esquema de objeto criado propriedade por propriedade:

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 cria os esquemas de parâmetros usados por ferramentas de webhook e cliente. Cada método retorna um novo esquema e deixa inalterado aquele em que foi chamado, para que você possa definir um esquema uma vez e usá-lo em várias ferramentas.

ConstrutorCria
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Um valor literal
Schema.object()Um objeto. Adicione propriedades com property().
Schema.array(items)Uma matriz cujos elementos correspondem ao esquema items

De onde vem um valor

Todo literal precisa de exatamente uma fonte de valor, onde quer que apareça: em um parâmetro, em um corpo, em um esquema de resposta ou dentro de um objeto ou matriz. Um objeto ou matriz também pode ter uma fonte, que fornece então o valor inteiro.

PythonJavaScriptO valor
describe(text)describe(text)É fornecido pelo LLM, orientado por text.
from_variable(name)fromVariable(name)É lido de uma variável dinâmica quando a ferramenta é executada.
constant(value)constant(value)É sempre value.
system_provided()systemProvided()É preenchido pelo sistema quando a ferramenta é executada. Apenas literais.
omit()omit()É deixado de fora da solicitação. Apenas para uma propriedade opcional.

Em um objeto ou matriz, describe() documenta o contêiner para o LLM, e cada propriedade ou elemento ainda tem sua própria fonte.

Outros métodos de esquema

PythonJavaScriptFaz
optional()optional()Torna uma propriedade opcional. As propriedades são obrigatórias, exceto quando marcadas como opcionais.
choices(values)choices(values)Limita uma string a um conjunto fixo de valores, do qual o LLM escolhe.
allowed_from(variable)allowedFrom(variable)Rejeita um valor do LLM que não esteja na lista de uma variável dinâmica. Precisa de describe().
property(name, schema) / without(name)property(name, schema) / without(name)Adiciona, substitui ou remove uma propriedade de objeto. Uma propriedade substituída mantém sua posição.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Exige pelo menos uma, ou todas, de um grupo de propriedades opcionais.

Cabeçalhos e autenticação

Um valor de cabeçalho vem de um entre quatro lugares. Use um segredo ou uma variável de ambiente para qualquer informação sensível, para que o valor nunca apareça na configuração da ferramenta:

ConstrutorO valor do cabeçalho é
Header.value(text)Texto fixo.
Header.secret(id)Um segredo do armazenamento de segredos do workspace.
Header.variable(name)Uma variável dinâmica, lida quando a ferramenta é executada.
Header.env_var(label) / Header.envVar(label)Uma variável de ambiente do workspace, resolvida para o ambiente atual.

AuthConnection.id(id) usa uma conexão de autenticação do workspace pelo ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) a seleciona de uma variável de ambiente, para que a mesma configuração de ferramenta possa usar uma conexão diferente em cada ambiente.

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"))
)

Criar uma ferramenta de cliente

Tool.client(name, description) inicia uma ferramenta de cliente, que é executada no seu aplicativo em vez de em um servidor. Adicione seus parâmetros com param(name, schema). Defina expects_response / expectsResponse quando o agente precisar aguardar o resultado do seu aplicativo:

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

Criar uma ferramenta de sistema

As ferramentas de sistema já vêm integradas à plataforma. Cada uma tem seu próprio construtor em SystemTool, que recebe as configurações dessa ferramenta:

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()

As duas ferramentas de transferência recebem seus destinos de transfer(condition, destination, options). A condição indica ao LLM quando transferir para lá, e o destino usa o mesmo Destination dos workflows como código. Uma transferência para um URI SIP precisa de uma transferência 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"
)

Opções de ferramenta

As configurações compartilhadas por todos os tipos de ferramenta ficam em options(), como argumentos nomeados em Python e um objeto em JavaScript. Seus nomes correspondem aos campos da configuração da ferramenta na API:

Aplica-se aPythonJavaScript
Todas as ferramentasname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Ferramentas de webhookexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Ferramentas de clienteexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

O tempo limite de resposta de uma ferramenta de webhook é de 5 a 300 segundos. O de uma ferramenta de cliente é de 1 a 120 segundos, ou -1 para aguardar o tempo necessário, o que exige expects_response / expectsResponse. follow_redirects / followRedirects exige uma lista de domínios permitidos.

Vincular ferramentas a um agente

Ferramentas de webhook e cliente são criadas separadamente com tools.create() e vinculadas aos agentes por ID, para que uma ferramenta possa ser compartilhada por vários agentes. Ferramentas de sistema fazem parte da configuração do agente: build_config() / buildConfig() retorna a entrada das ferramentas integradas do 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(),
),
)
)
),
)

O campo prompt.tools do agente, que contém configurações de ferramentas embutidas, está obsoleto. Ele não pode ser combinado com tool_ids e, quando uma solicitação o inclui, as ferramentas integradas do agente são substituídas pelas ferramentas de sistema que ele contém. Em vez disso, crie ferramentas com tools.create() e vincule-as por ID.

Editar uma ferramenta existente

Tool.from_response() / Tool.fromResponse() carrega uma ferramenta retornada por tools.get(). Os campos que o criador não modela e os padrões preenchidos pela API são preservados, portanto, enviá-la de volta altera somente o que você mudou. as_webhook(), as_client() e as_system() (asWebhook() e assim por diante no JavaScript) fornecem a ferramenta tipada para edição, ou None / undefined se ela for de outro tipo.

Para alterar uma propriedade do corpo, leia o esquema do corpo, defina a propriedade novamente e defina o corpo:

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())

Armazenar ferramentas no controle de versão

to_json_string() / toJSONString() grava a ferramenta no formato de transmissão da API: chaves em snake_case, ordenadas em todos os níveis, com recuo de 2 espaços. É o mesmo formato que a CLI mantém no diretório tool_configs/, e ambos os SDKs gravam arquivos idênticos byte a byte para a mesma ferramenta, mantendo os diffs pequenos. Tool.from_json() / Tool.fromJSON() o lê novamente.

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())

Uma configuração típica é a mesma usada para workflows: preencha os arquivos com elevenlabs tools pull, edite-os diretamente ou com o criador, execute Tool.from_json(file).build() / Tool.fromJSON(file).build() na CI a cada pull request e envie-os com tools.update() ou elevenlabs tools push durante o merge.

Validação

Chamadas encadeadas nunca falham por si só. build(), build_config() / buildConfig(), to_json() / toJSON() e to_json_string() / toJSONString() verificam a ferramenta inteira e geram ou lançam um único ToolValidationError, cuja lista issues relaciona cada problema, com um code, uma message e o path da parte a que se refere, 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)

Os erros incluem:

  • Um placeholder de URL sem parâmetro de caminho ou um parâmetro de caminho sem placeholder. Modelos de variável de ambiente como {{system__env_api_host}} não são placeholders.
  • Um literal sem fonte de valor ou com mais de uma.
  • Um corpo em um GET ou nenhum corpo em um POST, PUT ou PATCH.
  • O mesmo nome de parâmetro em mais de um entre caminho, consulta e corpo.
  • omit() em uma propriedade obrigatória, choices() em um esquema que não é uma string ou uma constante que não corresponde ao tipo do esquema.
  • Uma ferramenta de transferência sem destinos, um destino do tipo errado ou um destino de URI SIP sem transferência SIP REFER.
  • Uma opção que não se aplica ao tipo de ferramenta ou um tempo limite fora do intervalo permitido.

Tipos de ferramenta mais novos que seu SDK

Uma ferramenta carregada da API ou de um arquivo pode ser de um tipo que o criador não consegue editar, como uma ferramenta MCP. Ela é carregada com o tipo "other" e passa sem alterações por from_json() / fromJSON() e to_json_string() / toJSONString(), enquanto build() a informa como um aviso por meio de on_warning / onWarning.