> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Ferramentas como código

## Visão geral

Uma [ferramenta](/docs/pt/eleven-agents/customization/tools) é 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.

> **Note**
>
> 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](/docs/pt/eleven-agents/customization/tools/webhook-tools). 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:

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

```typescript
import { ElevenLabsClient, Header, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const getOrder = Tool.webhook("get_order", "Look up an order by the number the caller gives")
  .get("https://api.example.com/orders/{order_id}")
  .pathParam("order_id", Schema.string().describe("The order number, e.g. A-1042"))
  .queryParam("include", Schema.string().constant("items"))
  .header("Authorization", Header.secret("sec_orders_api"))
  .assign("order_status", "order.status")
  .options({ responseTimeoutSecs: 10 });

const tool = await elevenlabs.conversationalAi.tools.create(getOrder.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:

| Python                                                           | JavaScript                 | Define                                                                                                                         |
| ---------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | igual                      | O 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](#headers-and-authentication).                                |
| `auth(connection)`                                               | `auth(connection)`         | A [conexão de autenticação](/docs/pt/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) 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:

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

```typescript
const 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().fromVariable("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.

| Construtor                                                                | Cria                                                       |
| ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `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.

| Python                | JavaScript           | O valor                                                                                                                                    |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `describe(text)`      | `describe(text)`     | É fornecido pelo LLM, orientado por `text`.                                                                                                |
| `from_variable(name)` | `fromVariable(name)` | É lido de uma [variável dinâmica](/docs/pt/eleven-agents/customization/personalization/dynamic-variables) 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

| Python                                            | JavaScript                                    | Faz                                                                                                      |
| ------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `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:

| Construtor                                       | O 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](/docs/pt/eleven-agents/integrate/environment-variables) 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.

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

```typescript
import { AuthConnection, Header } from "@elevenlabs/elevenlabs-js";

const updateProfile = Tool.webhook("update_profile", "Update the caller's email address")
  .put("https://api.example.com/profiles/{profile_id}")
  .pathParam("profile_id", Schema.string().fromVariable("profile_id"))
  .body(Schema.object().property("email", Schema.string().describe("The new email address")))
  .header("X-Api-Key", Header.envVar("profiles_api_key"))
  .auth(AuthConnection.envVar("profiles_oauth"));
```

## Criar uma ferramenta de cliente

`Tool.client(name, description)` inicia uma [ferramenta de cliente](/docs/pt/eleven-agents/customization/tools/client-tools), 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:

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

```typescript
const showMap = 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({ expectsResponse: false });
```

## Criar uma ferramenta de sistema

As [ferramentas de sistema](/docs/pt/eleven-agents/customization/tools/system-tools) já vêm integradas à plataforma. Cada uma tem seu próprio construtor em `SystemTool`, que recebe as configurações dessa ferramenta:

| Python                                                  | JavaScript                                            |
| ------------------------------------------------------- | ----------------------------------------------------- |
| `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](/docs/pt/eleven-agents/customization/agents-as-code/workflows#transfer-destinations). Uma transferência para um URI SIP precisa de uma transferência SIP REFER:

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

```typescript
import { Destination, SystemTool } from "@elevenlabs/elevenlabs-js";

const transfer = SystemTool.transferToNumber()
  .transfer("Caller asks for billing", Destination.phone("+15551234567"))
  .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), {
    transferType: "sip_refer",
  });

const toSales = SystemTool.transferToAgent().transfer(
  "Caller wants to buy something",
  Destination.agent("agent_sales"),
  { transferMessage: "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 a            | Python                                                                                                                                       | JavaScript                                                                                                                          |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Todas as ferramentas   | `name`, `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 webhook | `execution_mode`, `content_type`, `response_filter`, `follow_redirects`, `follow_redirects_allowed_domains`, `dynamic_variable_placeholders` | `executionMode`, `contentType`, `responseFilter`, `followRedirects`, `followRedirectsAllowedDomains`, `dynamicVariablePlaceholders` |
| Ferramentas de cliente | `execution_mode`, `expects_response`, `dynamic_variable_placeholders`                                                                        | `executionMode`, `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.

```python
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(),
                ),
            )
        )
    ),
)
```

```typescript
const orderTool = await elevenlabs.conversationalAi.tools.create(getOrder.build());

const agent = await elevenlabs.conversationalAi.agents.create({
  name: "Support line",
  conversationConfig: {
    agent: {
      prompt: {
        prompt: "You are a support agent for Acme.",
        toolIds: [orderTool.id],
        builtInTools: {
          endCall: SystemTool.endCall().buildConfig(),
          transferToNumber: transfer.buildConfig(),
        },
      },
    },
  },
});
```

> **Warning**
>
> 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:

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

```typescript
import { type ObjectSchema, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const loaded = Tool.fromResponse(
  await elevenlabs.conversationalAi.tools.get("tool_id")
).asWebhook();
if (!loaded) throw new Error("Not a webhook tool");

const body = loaded.bodySchema as ObjectSchema;
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")));
loaded.queryParam("locale", Schema.string().describe("The caller's language").optional());

await elevenlabs.conversationalAi.tools.update("tool_id", 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](/docs/pt/eleven-agents/operate/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.

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

```typescript
import { Tool } from "@elevenlabs/elevenlabs-js";
import { readFile, writeFile } from "node:fs/promises";

await writeFile("tool_configs/get_order.json", getOrder.toJSONString());

const stored = Tool.fromJSON(await readFile("tool_configs/get_order.json", "utf8"));
await elevenlabs.conversationalAi.tools.update("tool_id", stored.build());
```

Uma configuração típica é a mesma usada para [workflows](/docs/pt/eleven-agents/customization/agents-as-code/workflows#store-workflows-in-version-control): 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`.

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

```typescript
import { ToolValidationError } from "@elevenlabs/elevenlabs-js";

try {
  const request = refund.build();
} catch (err) {
  if (err instanceof ToolValidationError) {
    for (const issue of err.issues) console.error(issue.code, issue.path, issue.message);
  } else {
    throw err;
  }
}
```

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`.