Code Execution Tool

A Code Execution Tool permite que seu Agente execute código predefinido durante uma conversa.
Ela é útil em cenários em que o Agente precisa realizar cálculos, transformar dados, validar entradas ou executar lógica de negócio personalizada que vai além das Tools padrão.

---

🔹 Como funciona

• Você configura a Tool com uma descrição que explica em linguagem simples o que o código faz.

  O Agente decide chamar essa Tool com base nessa descrição.

• Você pode definir properties (variáveis) que o Agente vai coletar do usuário antes de executar o código.

  • Cada property tem um nome, um tipo e uma descrição.
  • A descrição diz ao Agente como extrair e formatar os dados a partir da conversa.

• A Tool contém um bloco de código, onde você implementa a função main().

  • O Agente passará as properties coletadas como entradas.
  • A função deve retornar a saída processada.

• Importante: Se o Agente decidir usar a Tool mas alguma property estiver faltando, ele vai primeiro pedir esses valores ao usuário e só depois executar o código.

---

🔹 Campos de configuração

Ao criar uma Code Execution Tool:

1. Name → Um rótulo claro, por exemplo Discount Calculator
2. Description → Explicação em linguagem natural, por exemplo
   “Executa um cálculo para determinar o preço final após o desconto.”
3. Properties → Variáveis coletadas do usuário, por exemplo:
   • price (number) → “O preço original do produto em USD.”
   • discount (number) → “O percentual de desconto a ser aplicado.”
4. Code → Uma função JavaScript dentro de main() que processa a entrada e retorna o resultado.

---

🔹 Exemplo de configuração

Name: Discount Calculator
Description: “Executa um cálculo para retornar o preço final do produto após aplicar um desconto.”

Properties:

• price (number) → “O preço original em USD.”
• discount (number) → “Percentual de desconto (0–100).”

Exemplo de código:

function main({{price}}, {{discount}}) {
  const finalPrice = price - (price * (discount / 100));
  return { finalPrice };
}

🔹 Exemplo de caso de uso

Usuário: “O produto custa 200 dólares, e eu tenho 15% de desconto. Qual é o preço final?”

1. O Agente decide usar a Discount Calculator Tool.
2. Properties coletadas: price = 200, discount = 15.
3. O código executa: 200 - (200 * 0.15) = 170.
4. O Agente responde: “O preço final após o desconto é 170 USD.”

---

🔹 Boas práticas

• Mantenha a descrição simples → isso garante que o Agente saiba quando usar a Tool.
• Valide as entradas dentro do seu código (por exemplo, verifique se os números são positivos).
• Retorne saídas estruturadas em JSON, para que o Agente possa usar o resultado de forma consistente.
• Teste internamente antes de expor a Tool aos usuários.

---

✅ Resumo

A Code Execution Tool dá ao seu Agente flexibilidade para lidar com lógica personalizada.
Com descrições de properties claras e um código bem escrito, seu Agente pode coletar entradas dinamicamente, processá-las e entregar resultados precisos em tempo real.