eduardweb.
OpenAI & ClaudeAvansat#architecture#typescript#openai#agents

Function calling cu OpenAI: pattern curat pentru un agent care interoghează baza de date

De Bogdan Răducanu, 21 oct. 2026 · 26 vizualizări · 3 like-uri

Postat 21 oct. 2026
typescript
import OpenAI from "openai";
import { z } from "zod";

const client = new OpenAI();

const OrderSearchSchema = z.object({
  customerEmail: z.string().email(),
  status: z.enum(["PENDING", "SHIPPED", "DELIVERED"]).optional()
});

async function runAgent(userPrompt: string) {
  const messages: OpenAI.ChatCompletionMessageParam[] = [
    { role: "user", content: userPrompt }
  ];

  const response = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages,
    tools: [{
      type: "function",
      function: {
        name: "getOrders",
        description: "Caută comenzile unui client după email și status",
        parameters: {
          type: "object",
          properties: {
            customerEmail: { type: "string", description: "Email-ul clientului" },
            status: { type: "string", enum: ["PENDING", "SHIPPED", "DELIVERED"] }
          },
          required: ["customerEmail"]
        }
      }
    }]
  });

  const toolCall = response.choices[0].message.tool_calls?.[0];
  if (toolCall && toolCall.function.name === "getOrders") {
    const args = OrderSearchSchema.parse(JSON.parse(toolCall.function.arguments));
    
    // Query parametrizat sigur în baza ta de date
    const dbData = await db.orders.findMany({
      where: { email: args.customerEmail, status: args.status },
      take: 5
    });

    messages.push(response.choices[0].message);
    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      content: JSON.stringify(dbData)
    });

    const final = await client.chat.completions.create({ model: "gpt-4o-mini", messages });
    return final.choices[0].message.content;
  }

  return response.choices[0].message.content;
}

Dacă lași un LLM să scrie direct SQL brut pe baza promptului de la user, o să ai un incident de securitate înainte să apuci să bei prima cafea. Function calling (sau tool calling) schimbă complet problema: constrângi modelul la o schemă JSON strictă pe care o validezi tu înainte să atingi baza.

Am implementat pattern-ul ăsta recent la un dashboard intern cu vreo 14.000 de comenzi active, unde suportul tehnic trebuia să pună întrebări în limbaj natural. În loc de text-to-SQL clasic, am mers pe funcții semantice expuse ca tools.

De ce funcții semantice și nu generare de SQL?

Când îi ceri modelului să genereze SQL pe baza unei scheme de tabele, apar două probleme mari: halucinațiile pe clauzele WHERE și riscul evident de injection sau exfiltrare de date. Chiar și cu un user de DB cu permisiuni de read-only, tot nu vrei ca un prompt injection să ruleze un SELECT masiv care să-ți blocheze baza.

Abordarea sigură este să-i oferi modelului tool-uri cu intenție clară: getOrderStatus(orderId), searchCustomerByEmail(email) sau getRevenueMetrics(startDate, endDate). Modelul nu știe numele tabelelor tale, nu știe cheile străine și nu poate modifica logica query-ului.

Bucla de execuție a agentului

Pattern-ul se bazează pe o buclă în trei pași:

  1. Trimiți mesajul utilizatorului împreună cu definițiile de tools.
  2. Dacă modelul răspunde cu tool_calls, extragi argumentele JSON, le validezi (eu folosesc Zod) și rulezi query-ul tău parametrizat din backend.
  3. Trimiți rezultatul query-ului înapoi în conversație cu rolul tool, iar modelul generează răspunsul final redactat pentru user.

Modelul acționează doar ca un parser inteligent de intenții și un agregator de date, nu ca un administrator de sistem.

Capcane din producție și trade-off-uri

Trade-off-ul principal e latența. Pentru o singură întrebare simplă ai două round-trips complete către API-ul OpenAI. La noi, asta adaugă în medie între 900ms și 1.8s peste timpul normal de răspuns. Pentru un tool intern de operațiuni e perfect acceptabil; pentru un landing page public ar fi mult prea lent.

A doua problemă pe care am pățit-o des: enum-urile. Dacă ai un status în DB precum COMPLETED și nu specifici exact lista de valori permise în descrierea schemei JSON, GPT-4 o să-ți paseze success, done sau finished. Pune mereu câmpul enum explicit în schemă, altfel pierzi ore întregi debuggând query-uri care întorc zero rezultate.

Un alt detaliu critic este volumul datelor returnate de funcție. Dacă tool-ul tău întoarce 200 de rânduri de date brute, o să-ți mănânci context window-ul de pomană și crește costul per request. Limitează query-urile la maxim 5-10 rânduri sau fă agregarea direct în DB înainte să trimiți JSON-ul înapoi către model.

Pattern-ul funcționează impecabil când vrei să expui rapoarte complexe fără să scrii 20 de filtre într-un UI de React. Voi cum gestionați context window-ul când un query întoarce totuși un set mai mare de rezultate: le trunchiați agresiv sau adăugați un pas intermediar de rezumat?

Răspunsuri 0

Se încarcă răspunsurile…

Loghează-te pentru a răspunde

Doar membrii comunității pot lăsa comentarii.