Introdução a Agentes

Ferramentas (Tools)

Permitir que a IA consulte pedidos, estoque ou FAQ via funções que seu código executa.

Intermediário 30 min 30 pontos Leitura 0%

Nesta aula você vai

  • Definir schema de tool e implementar executor seguro
  • Usar function calling ou JSON estruturado
  • Validar argumentos antes de chamar APIs internas

Ferramentas (Tools)

Objetivos

  • Permitir que IA execute ações controladas por você
  • Nunca deixar o modelo acessar banco diretamente

Padrão: você controla execução

LLM sugere tool + args  →  SEU código valida  →  SEU código executa  →  resultado volta ao LLM

O LLM não roda SQL. Ele pede; você executa.

Definição de tools (OpenAI function calling)

const tools = [
  {
    type: 'function',
    function: {
      name: 'buscar_pedido',
      description: 'Retorna status de entrega de um pedido pelo ID numérico',
      parameters: {
        type: 'object',
        properties: {
          pedido_id: { type: 'string', description: 'Ex: 8842' },
        },
        required: ['pedido_id'],
      },
    },
  },
];

Executor seguro

async function executeTool(name, args, userId) {
  if (name === 'buscar_pedido') {
    const id = String(args.pedido_id).replace(/\D/g, '');
    if (!id) throw new Error('ID inválido');
    // Autorização: pedido pertence ao userId?
    return await orderService.getStatus(id, userId);
  }
  throw new Error(`Tool desconhecida: ${name}`);
}

Loop agente (simplificado)

async function runAgent(userMessage, history) {
  let messages = [...history, { role: 'user', content: userMessage }];

  for (let step = 0; step < 3; step++) {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages,
      tools,
      tool_choice: 'auto',
    });

    const msg = response.choices[0].message;

    if (msg.tool_calls?.length) {
      messages.push(msg);
      for (const call of msg.tool_calls) {
        const args = JSON.parse(call.function.arguments);
        const result = await executeTool(call.function.name, args, userId);
        messages.push({
          role: 'tool',
          tool_call_id: call.id,
          content: JSON.stringify(result),
        });
      }
      continue; // LLM formata resposta com dados reais
    }

    return msg.content; // resposta final
  }
  return 'Não consegui concluir a solicitação.';
}

Alternativa sem function calling: JSON manual

Peça no system prompt:

Se precisar buscar pedido, responda SOMENTE:
{"action":"buscar_pedido","pedido_id":"123"}
Caso contrário, responda texto normal ao usuário.

Seu código detecta JSON → executa → segunda chamada com resultado. Mais frágil, mais portável.

Tools comuns para negócio

Tool Função
buscar_pedido(id) Status, rastreio
listar_produtos(q) Catálogo
buscar_faq(q) Artigos de ajuda
criar_ticket(texto) Escala humano

Comece com uma.

Segurança

  • Allowlist de tools por produto
  • Timeout por execução (5s)
  • Log de toda tool call com args (sem dados sensíveis em log público)
  • Rate limit por tool (busca pedido ≠ disparar e-mail)

Resumo

  • Tool = função sua exposta ao LLM via schema
  • LLM escolhe tool; código executa e valida
  • Function calling nativo reduz parsing manual
  • Uma tool bem feita > dez tools instáveis