Sıfırdan AI agent kurmak: tool calling döngüsü

Çekirdek döngü

Aşağıdaki iskelet herhangi bir model sağlayıcısına uyarlanabilir. model.generate çağrısını kullandığın sağlayıcının SDK'sıyla değiştir; araç çağrısı biçimi sağlayıcıya göre biraz farklıdır.

type ToolCall = { id: string; name: string; args: unknown };
type Message =
  | { role: "user" | "assistant"; content: string; toolCalls?: ToolCall[] }
  | { role: "tool"; toolCallId: string; content: string };

type Tools = Record<string, (args: unknown) => Promise<string>>;

const MAX_STEPS = 8;

export async function runAgent(goal: string, tools: Tools): Promise<string> {
  const messages: Message[] = [{ role: "user", content: goal }];

  for (let step = 0; step < MAX_STEPS; step++) {
    const reply = await model.generate({ messages, tools: describe(tools) });
    messages.push(reply);

    if (!reply.toolCalls?.length) return reply.content;

    for (const call of reply.toolCalls) {
      const result = await runTool(tools, call);
      messages.push({ role: "tool", toolCallId: call.id, content: result });
    }
  }

  throw new Error("Agent did not finish within the step limit");
}

İyi araç tasarımı

• Az sayıda araç ver. Çok araç, modelin doğru olanı seçmesini zorlaştırır.
• Araç adı ve açıklaması ne yaptığını ve ne zaman kullanılacağını açıkça söylesin.
• Girdileri bir şemayla (örneğin zod) tanımla ve çalıştırmadan önce doğrula.
• Çıktıyı kısa tut. Uzun çıktı bağlamı doldurur ve maliyeti artırır; gerekirse özetle ya da kırp.
• Salt okunur araçları, veri değiştiren araçlardan ayır.

Hataları modele geri ver

Araç hata verirse döngüyü çökertme. Hata mesajını araç sonucu olarak modele döndür; model genellikle girdisini düzeltip yeniden dener. Yine de her araca bir zaman aşımı koy ve tekrar eden aynı hatayı yakalayıp döngüyü sonlandır.

Sınırlar ve güvenlik

• Adım limiti: döngü sonsuza gitmesin.
• Yetki: her araç yalnızca gerekli en az izinle çalışsın.
• Onay: e-posta göndermek, ödeme yapmak, silmek gibi geri alınamaz işlemleri insan onayına bağla.
• Dış içerik güvenilmezdir. Web sayfası ya da e-postadan gelen metin, talimat gibi davranmaya çalışabilir.

Test ve izleme

Her adımı kaydet: modelin isteği, çağrılan araç, girdisi, çıktısı ve süresi. Gerçek görevlerden küçük bir değerlendirme seti çıkar ve prompt ya da araç değiştirdikçe bu setle sonuçları karşılaştır. Agent'lar sessizce kötüleşebilir; ölçmediğin şeyi fark etmezsin.