Ferramentas como código
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 deelevenlabs.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:
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:
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:
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.
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.
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
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:
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.
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:
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:
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:
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:
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.
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:
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.
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.
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
GETou nenhum corpo em umPOST,PUTouPATCH. - 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.