Agent Çalıştırmaları

Agent Çalıştırmaları, bir yapay zeka Agent'ının üst düzey bir hedefi alt görevlere ayırdığı, bunları yürüttüğü, sonuçları değerlendirdiği ve gerektiğinde yeniden planladığı hedefe yönelik yürütmelerdir. Yazma/gönderme/silme işlemleri insan onayı gerektirir.

Durum: Planlandı (Faz 2, Kilometre Taşı M2.1)

Uç Noktalar

Yöntem	Yol	Açıklama	Yetkilendirme	Hız Limiti
POST	/agent-runs	Bir agent çalıştırması oluştur	JWT + Yetki	10/dk
GET	/agent-runs	Kullanıcı agent çalıştırmalarını listele	JWT	60/dk
GET	/agent-runs/:id	Çalıştırma detayını ve izleme kaydını getir	JWT	60/dk
POST	/agent-runs/:id/steps/:stepId/approve	Duraklatılmış bir işlemi onayla	JWT	30/dk
POST	/agent-runs/:id/steps/:stepId/reject	Duraklatılmış bir işlemi reddet	JWT	30/dk
DELETE	/agent-runs/:id	Bir çalıştırmayı iptal et	JWT	10/dk
GET	/agent-runs/:id/trace	Tam değişmez izleme kaydı	JWT	60/dk

Agent Çalıştırması Oluştur

İstek

Alan	Tür	Zorunlu	Açıklama
goal	string	Evet	Agent için üst düzey hedef
contextIds	string[]	Hayır	Çalıştırmaya bağlanacak bağlam kimlikleri
budget	object	Hayır	Bütçe kısıtlamaları
budget.maxCredits	number	Hayır	Harcanabilecek maksimum kredi
budget.maxMinutes	number	Hayır	Dakika cinsinden maksimum süre

Yanıt

{
  "data": {
    "id": "run-abc123",
    "goal": "Research our top 5 competitors and add comparison to Notion",
    "status": "planning",
    "plan": [],
    "budget": { "maxCredits": 100, "maxMinutes": 30, "spent": 0 },
    "createdAt": "2026-07-15T10:00:00.000Z"
  }
}

Agent Çalıştırma Durumu Yaşam Döngüsü

pending → planning → running → completed
                   ↘ awaiting_approval → running (onaylandı)
                   ↘ awaiting_approval → cancelled (reddedildi)
                   ↘ failed
         → cancelled (kullanıcı tarafından)

Onay Kapısı

Agent riskli bir işlemle (yazma, gönderme, silme) karşılaştığında duraklar ve insan onayını bekler.

Onayla

POST /agent-runs/:id/steps/:stepId/approve

Reddet

POST /agent-runs/:id/steps/:stepId/reject
{ "reason": "Don't update that Notion page yet" }

İzleme Kaydı

İzleme kaydı, agent'ın gerçekleştirdiği girdiler, çıktılar ve model kararları dahil her işlemin yalnızca ekleme yapılabilen günlüğüdür.

{
  "data": {
    "steps": [
      {
        "stepId": "step-1",
        "action": "web_search",
        "input": { "query": "competitor pricing SaaS 2026" },
        "output": { "results": [...] },
        "status": "completed",
        "startedAt": "2026-07-15T10:01:00.000Z",
        "completedAt": "2026-07-15T10:01:15.000Z"
      }
    ]
  }
}