Agents

Agents nedir?

Agents, Cloudflare’in yapay zekâ ajanı geliştirme SDK’sıdır. Ve ilk netleştirilmesi gereken şey şu: ayrı faturalanan bir ürün değil, bir kütüphanedir.

Resmî ifade net:

“The Agent class is an extension of DurableObject — agents are Durable Objects. […] Agent does not extend DurableObject directly. It extends Server from the partyserver package, which extends DurableObject. Think of it as layers: DurableObject > Server > Agent.”

Sohbet katmanıyla birlikte tam hiyerarşi: DurableObject > Server > Agent > AIChatAgent.

Limit sayfası da bu mirası doğruluyor: “Many limits are inherited from those applied to Workers scripts and/or Durable Objects.”

Agents SDK’nın kendisi MIT lisanslı açık kaynaktır — github.com/cloudflare/agents. Bu, bu katalogdaki çoğu üründen farklı: kodu okuyabilir, fork’layabilir, katkı verebilirsin.

Ağustos 2026’dan beri bir de panel yüzeyi var

4 Ağustos 2026’da Cloudflare “Cloudflare Agents” adını yalnızca SDK için değil, yönetilen bir deneyim için de kullanmaya başladı:

“We’re bringing together everything you need to deploy and manage hosted agents on Cloudflare, starting with observability. […] Cloudflare Agents brings all of your deployed agent sessions into a single experience […] First stop: agent tracing”

Bu yeni bir fatura kalemi yaratmıyor. Agents dokümanlarındaki tek açık fiyat ifadesi tracing için ve o da Workers Observability faturasına gidiyor.

Karıştırılan beş isim

Son ikisi özellikle karışıyor. “Agent Lee is currently in beta and only available to accounts on a Free plan” — panelde çalışan bir yardımcıdır, üzerine uygulama geliştiremezsin. “Agent setup” ise her doküman sayfasının başlığında göründüğü için ürün sanılıyor.

Nasıl çalışır?

Yaşam döngüsü

Taşıyıcı garanti kimliktir:

“An instance of an Agent is globally unique: given the same name (or ID), you will always get the same instance of an agent.”

Durum — this.setState()

setState() sırayla üç iş yapar:

1. SQLite’a kaydeder (kalıcı)
2. Bağlı tüm istemcilere yayınlar
3. onStateChanged()’i tetikler (yayından sonra, best-effort)

Durum yalnızca JSON’a serileştirilebilir olmalı. Tanımı “Immediately consistent — Read your own writes” ve “Thread-safe — Safe for concurrent updates.”

Doğrulama ayrı bir kancadır:

“onStateChanged() is not intended for validation; it is a notification hook and should not block broadcasts. Use validateStateChange() for validation.”

validateStateChange() kalıcılaştırma ve yayından önce çalışır, senkron olmalıdır ve hata fırlatmak güncellemeyi iptal eder.

SQL depolama — this.sql

“Every individual Agent instance has its own SQL (SQLite) database that runs within the same context as the Agent itself. This means that inserting or querying data within your Agent is effectively zero-latency: the Agent does not have to round-trip across a continent or the world to access its own data.”

SDK aynı veritabanında bazı tabloları rezerve eder — demoda göreceğin tablolar bunlar:

Ayrım kuralı açık: durumu küçük tut, çünkü her değişiklikte tüm istemcilere yayınlanır. Geçmiş veri, büyük koleksiyonlar, ilişkiler ve sorgulanabilir veri SQL’e ait.

Zamanlama

Mekanizma, çoklu zamanlamanın neden mümkün olduğunu açıklıyor:

“Since Durable Objects only allow one alarm at a time, the Agent class works around this by managing multiple schedules in SQL and using a single alarm.”

Yönetim API’si: getScheduleById(), listSchedules({ id, type, timeRange }) (asenkron; senkron getSchedules() kullanımdan kaldırıldı), cancelSchedule(id).

Hibernation ve keepAlive()

“Durable Objects are evicted after a period of inactivity (typically 70–140 seconds with no incoming requests, WebSocket messages, or alarms). During long-running operations — streaming LLM responses, waiting on external APIs, running multi-step computations — the agent can be evicted mid-flight.”

AIChatAgent streaming sırasında keepAlive()’ı kendisi çağırır — orada elle eklemene gerek yok.

WebSocket protokolü

Her yeni bağlantıda ajan otomatik olarak üç JSON metin karesi gönderir:

shouldSendProtocolMessages(connection, ctx) metodunu false döndürecek şekilde ezerek üçünü de bastırabilirsin — RPC, onMessage ve this.broadcast() çalışmaya devam eder.

Callable RPC

{
  "type": "rpc",
  "id": "unique-request-id",
  "method": "add",
  "args": [2, 3]
}

Streaming varyantı @callable({ streaming: true }); ilk parametre her zaman bir StreamingResponse olur, stream.send(chunk) ve stream.end() çağırırsın.

React hook’ları

useAgent → agents/react paketinde. useAgentChat → @cloudflare/ai-chat/react paketinde. Farklı paketler. useAgent şunu döndürür: { agent, name, setState, call, stub, send, close, reconnect }. Yeniden bağlanma otomatiktir.

Sohbet ajanları — AIChatAgent

@cloudflare/ai-chat paketinde, Vercel AI SDK üzerine kurulu. Otomatik mesaj kalıcılığı, devam ettirilebilir streaming, çoklu istemci senkronizasyonu, araç desteği ve satır boyutu koruması sağlar. WebSocket protokolü temel Agent protokolünden ayrıdır: CF_AGENT_USE_CHAT_REQUEST, CF_AGENT_USE_CHAT_RESPONSE, CF_AGENT_CHAT_MESSAGES, CF_AGENT_TOOL_APPROVAL, CF_AGENT_STREAM_RESUME_*.

Araç çağırma ve insan onayı

Bekleme süresine göre üç ayrı mekanizma var:

Günlerce sürebilecek bir onay bir Workflow olmalı — waitForApproval() kalıcıdır ve ajanı ayakta tutmaz.

MCP

İstemci olarak: this.addMcpServer(name, url, opts) — HTTP yükü olmadan RPC taşıması için bir Durable Object binding’i de kabul ediyor.

Sunucu olarak: API değişti.

Gözlemlenebilirlik

Agents, Node’un diagnostics_channel mekanizması üzerinden yapılandırılmış olay yayınlar ve “zero overhead when nobody is listening.” Kanallar: agents:state, agents:rpc, agents:schedule, agents:lifecycle, agents:workflow, agents:mcp, agents:email, agents:fiber. Her olay { type, agent, name, payload, timestamp } taşır.

Ne zaman kullanılır, ne zaman kullanılmaz

Kullanılır

Cloudflare’in kendi çerçevelemesi bu platformdaki en güçlü argüman: “10.000 ajan, her biri zamanın %1’inde aktif” senaryosu Durable Objects üzerinde “~100 active at any moment” demektir; sanal makinelerde “10,000 always-on instances” demektir. Çünkü boşta maliyet “Zero (hibernated)”.

Yani ajanların hayatlarının çoğunu bekleyerek geçiriyorsa, bu mimarinin karşılığı yok.

Bunun dışında: durum senkronizasyonu gereken çok istemcili sohbet arayüzleri, varlık başına (kullanıcı, sipariş, cihaz) uzun yaşayan ajanlar, ve zamanlanmış görevlerle çalışan arka plan ajanları.

Düz Workers + Durable Objects tercih edilir

SDK’nın eklediği dört şeye ihtiyacın yoksa. Yalnızca satır saklayıp HTTP cevaplayan bir DO, partyserver ve agents katmanlarından hiçbir fayda görmez.

Kararlı API sözleşmesi gerekiyorsa. SDK 0.22.0 ve minor sürümlerde kırıcı değişiklik geliyor. Durable Objects’in kendisi GA ve kararlı. Ekibin minor sürümde kırılma kaldıramıyorsa DO API’sine yaz.

İş yükün sohbet veya oturum şeklinde değilse. Sayaç, rate limiter, lider seçimi, koordinasyon — bunlar DO problemidir.

Derlemede dekoratör istemiyorsan. @callable() TC39 dekoratörleri, target: "ES2021" ve bir Vite eklentisi gerektiriyor; experimentalDecorators açıksa sessizce bozuluyor.

Workflows tercih edilir

Cloudflare’in kendi karar tablosu net:

Günler veya aylar sürebilecek bir onay kesinlikle bir Workflow olmalı. Ayrıntı için Workflows.

Barındırılan bir ajan çerçevesi tercih edilir

Yönetilen eval, prompt yönetimi veya ajan pazaryeri istiyorsan. Cloudflare sana bir çalışma zamanı ve (Ağustos 2026’dan beri) tracing veriyor; eval koşum takımı, prompt sürümleme arayüzü veya barındırılan ajan kataloğu vermiyor.

Ekibin Python öncelikliyse. SDK TypeScript. Python Workers var ve Workers RPC diller arası çalışıyor, ama Agent sınıfı, kancalar ve @callable TypeScript.

Tek seferde uzun CPU işi gerekiyorsa. Ajan başına CPU süresi 30 saniye. Duvar saati sınırsız ama gerçekten CPU-yoğun 10 dakikalık bir iş yanlış şekil.

Ajan çerçevesinin kendisi için GA/SLA taahhüdü gerekiyorsa. Yok.

LangGraph/CrewAI gibi bir yapıya çoktan yatırım yaptıysan ve sadece barındırma arıyorsan. Workers’a deploy etmek mümkün ama SDK’nın görüşleriyle çatışırsın; bir container platformu daha az efor olabilir.

Somut örnekler

Ortak wrangler.jsonc:

{
  "name": "ajan",
  "main": "src/server.ts",
  "compatibility_date": "2026-08-31",
  "compatibility_flags": ["nodejs_compat"],
  "ai": { "binding": "AI" },
  "durable_objects": {
    "bindings": [{ "name": "ChatAgent", "class_name": "ChatAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ChatAgent"] }]
}

new_sqlite_classes zorunlu — hem durum hem mesaj kalıcılığı SQLite backend’ini gerektiriyor. nodejs_compat da agents paketi tarafından isteniyor.

Durumu koruyan sohbet ajanı

import { AIChatAgent } from '@cloudflare/ai-chat';
import { routeAgentRequest } from 'agents';
import { createWorkersAI } from 'workers-ai-provider';
import { streamText, convertToModelMessages } from 'ai';

export class ChatAgent extends AIChatAgent {
  maxPersistedMessages = 200;

  async onChatMessage() {
    const workersai = createWorkersAI({ binding: this.env.AI });
    const sonuc = streamText({
      model: workersai('@cf/google/gemma-4-26b-a4b-it'),
      system: 'Sen yardımsever bir asistansın. Türkçe yanıtla.',
      messages: await convertToModelMessages(this.messages),
    });
    return sonuc.toUIMessageStreamResponse();
  }
}

export default {
  async fetch(request: Request, env: Env) {
    return (await routeAgentRequest(request, env))
      ?? new Response('Bulunamadı', { status: 404 });
  },
} satisfies ExportedHandler<Env>;

maxPersistedMessages bir maliyet ayarıdır: yazılan satır milyon başına $1.00 faturalanıyor.

Zamanlanmış ajan — üç modu bir arada

import { Agent } from 'agents';

type OzetDurum = { sonCalisma: string | null; calismaSayisi: number };

export class OzetAjani extends Agent<Env, OzetDurum> {
  initialState: OzetDurum = { sonCalisma: null, calismaSayisi: 0 };

  async onRequest(request: Request) {
    const kullaniciId = new URL(request.url).searchParams.get('kullanici');

    // Cron — idempotent, tekrar çağırmak kopya oluşturmaz
    await this.schedule('0 8 * * *', 'gunlukOzet', { kullaniciId });

    // Tek seferlik, 30 saniye sonra — İDEMPOTENT DEĞİL
    await this.schedule(30, 'hatirlatmaGonder', { mesaj: 'E-postanı kontrol et' });

    // Sabit aralık, saniye hassasiyetinde — İDEMPOTENT DEĞİL
    await this.scheduleEvery(90, 'veriEsitle', { hedef: 'ambar' });

    return Response.json(await this.listSchedules());
  }

  async gunlukOzet(p: { kullaniciId: string }) {
    this.setState({
      ...this.state,
      sonCalisma: new Date().toISOString(),
      calismaSayisi: this.state.calismaSayisi + 1,
    });
  }

  async hatirlatmaGonder(p: { mesaj: string }) { /* … */ }
  async veriEsitle(p: { hedef: string }) { /* … */ }
}

Bu örnekte onRequest her çağrıldığında cron tek kalır ama gecikmeli görev ve aralık birikir. Üretimde bu ayrımı bilmeden yazılan kod, birkaç gün sonra binlerce zamanlanmış görevle uyanır.

MCP sunucusu — güncel API

import { McpServer } from '@modelcontextprotocol/server';
import { createMcpHandler } from 'agents/mcp/server';
import { z } from 'zod';

function sunucuOlustur() {
  const server = new McpServer({ name: 'merhaba', version: '1.0.0' });

  server.registerTool(
    'merhaba',
    { description: 'Selam verir', inputSchema: { ad: z.string().optional() } },
    async ({ ad }) => ({
      content: [{ type: 'text', text: `Merhaba, ${ad ?? 'Dünya'}!` }],
    }),
  );

  return server;
}

export default {
  fetch(request, env, ctx) {
    return createMcpHandler(sunucuOlustur, {
      route: '/mcp',
      allowedHostnames: ['mcp.ornek.com'],
    })(request, env, ctx);
  },
} satisfies ExportedHandler;

Kritik ayrıntı: fabrikayı geçir, örneği değil. Resmî ifade: “Pass the factory itself. Do not create one global server instance or pass a constructed SDK v2 server directly.” Handler her istek için bir MCP sunucusu oluşturur.

Araç çağıran ajan, onay kapısıyla

export class AracAjani extends AIChatAgent {
  async onChatMessage() {
    const workersai = createWorkersAI({ binding: this.env.AI });

    return streamText({
      model: workersai('@cf/google/gemma-4-26b-a4b-it'),
      messages: await convertToModelMessages(this.messages),
      stopWhen: stepCountIs(5),
      tools: {
        // Sunucu tarafı — otomatik çalışır
        havaDurumu: tool({
          description: 'Bir şehrin hava durumunu getirir',
          inputSchema: z.object({ sehir: z.string() }),
          execute: async ({ sehir }) => havaGetir(sehir),
        }),

        // İstemci tarafı — execute yok, tarayıcı cevaplar
        saatDilimi: tool({
          description: 'Kullanıcının saat dilimini tarayıcıdan alır',
          inputSchema: z.object({}),
        }),

        // İnsan onaylı — eşiğin üstünde onay ister
        odemeYap: tool({
          description: 'Ödeme işler',
          inputSchema: z.object({
            tutar: z.coerce.number(),
            alici: z.string(),
          }),
          needsApproval: async ({ tutar }) => tutar > 100,
          execute: async ({ tutar, alici }) => tahsilEt(tutar, alici),
        }),
      },
    }).toUIMessageStreamResponse();
  }
}

React’e bağlı ajan, tipli RPC ile

// server.ts
import { Agent, routeAgentRequest, callable } from 'agents';

export type SayacDurum = { sayi: number };

export class SayacAjani extends Agent<Env, SayacDurum> {
  initialState: SayacDurum = { sayi: 0 };

  validateStateChange(sonraki: SayacDurum) {
    if (sonraki.sayi < 0) throw new Error('sayı negatif olamaz');
  }

  @callable()
  artir() {
    this.setState({ sayi: this.state.sayi + 1 });
    return this.state.sayi;
  }

  @callable()
  sifirla() { this.setState({ sayi: 0 }); }
}

// client.tsx
import { useAgent } from 'agents/react';

export default function Uygulama() {
  const [sayi, setSayi] = useState(0);

  const ajan = useAgent<SayacAjani, SayacDurum>({
    agent: 'SayacAjani',
    name: 'kullanici-123',
    onStateUpdate: (durum) => setSayi(durum.sayi),
  });

  return (
    <>
      <p>{sayi}</p>
      <button onClick={() => ajan.stub.artir()}>+</button>
      <button onClick={() => ajan.stub.sifirla()}>Sıfırla</button>
    </>
  );
}

Worker’dan ve ajandan ajana çağrı — dekoratörsüz

import { getAgentByName } from 'agents';

// Worker fetch handler'ından
const sayac = await getAgentByName(env.SayacAjani, 'ortak-sayac');
const yeni = await sayac.artir();          // düz Durable Object RPC

// Bir ajandan diğerine
class Orkestrator extends Agent {
  async devret(gorevId: string) {
    const isci = await getAgentByName(this.env.IsciAjani, gorevId);
    return await isci.calis();
  }
}

Bu çağrılarda @callable() kullanılmaz. Dekoratör yalnızca dış istemcilerden gelen WebSocket RPC içindir.

Günlerce bekleyebilen insan onayı

import { AgentWorkflow } from 'agents/workflows';

export class MasrafAkisi extends AgentWorkflow<MasrafAjani, MasrafParam> {
  async run(event, step) {
    const masraf = event.payload;

    const dogrulanmis = await step.do('dogrula', async () => {
      if (masraf.tutar <= 0) throw new Error('Geçersiz tutar');
      return { ...masraf, dogrulandi: Date.now() };
    });

    await this.reportProgress({
      step: 'onay', status: 'pending',
      message: `${masraf.tutar} TL için onay bekleniyor`,
    });

    // Kalıcı kapı — ajan beklerken ayakta durmaz
    const onay = await this.waitForApproval(step, { timeout: '7 days' });

    return await step.do('isle', async () =>
      ({ masrafId: crypto.randomUUID(), ...dogrulanmis }));
  }
}

Demo 1: Uçtan uca sohbet ajanı

Amaç: konuşması süreç yeniden başlatmasından sağ çıkan, sunucu aracı, tarayıcı aracı ve onay kapısı olan bir streaming sohbet ajanı. Süre: ~15 dakika.

Adım 1 — İskeleti kur

npm create cloudflare@latest sohbet-ajani     # "Hello World" Worker seç
cd sohbet-ajani
npm install agents @cloudflare/ai-chat ai workers-ai-provider zod
npm ls agents @cloudflare/ai-chat

npm ls çıktısı; agents 0.22.x ve @cloudflare/ai-chat 0.11.x sürümleri görünmeli

Adım 2 — Yapılandır ve tipleri üret

wrangler.jsonc dosyasını yukarıdaki ortak config ile değiştir, sonra:

npx wrangler types

worker-configuration.d.ts içinde AI: Ai ve ChatAgent: DurableObjectNamespace satırları

ChatAgent üyesi yoksa binding adı ile class_name eşleşmiyordur.

Adım 3 — Yerelde çalıştır

npm run dev

Terminalde yerel adres ve proje kökünde oluşan .wrangler/state dizininin listesi

.wrangler/state dizini Durable Object SQLite dosyalarının yaşadığı yerdir.

Adım 4 — WebSocket el sıkışmasını incele

Tarayıcıda DevTools → Network → WS filtresi → bağlantıyı seç → Messages.

Bağlantı adresi yönlendirme şemasını gösterir:

ws://localhost:5173/agents/sohbet-ajani/default
                            │             │
                        sınıf adı    örnek adı
                       (kebab-case)

Sohbet trafiği başlamadan önce üç protokol karesi gelir:

{"type":"cf_agent_identity", ...}      // ajan adı ve sınıfı
{"type":"cf_agent_state", ...}         // mevcut durum
{"type":"cf_agent_mcp_servers", ...}   // bağlı MCP sunucuları

DevTools Network → WS → Messages panelinde cf_agent_identity, cf_agent_state ve cf_agent_mcp_servers kareleri

Adım 5 — Üç araç yolunu da çalıştır

Sohbet arayüzünde iki araç çağrısının sonucu; hava durumu ve saat dilimi yanıtları

Onay istemi ekranı ve DevTools'ta Onayla'ya basıldığında giden CF_AGENT_TOOL_APPROVAL karesi

Adım 6 — Kalıcılığı ve akış devamlılığını kanıtla

Streaming sürerken tarayıcıyı sert yenile, sonra tekrar bağlan.

CF_AGENT_STREAM_RESUME_REQUEST karesi ve sunucunun CF_AGENT_STREAM_RESUME_ACK veya CF_AGENT_STREAM_RESUME_NONE yanıtı

Sonra npm run dev’i tamamen durdur, yeniden başlat ve sayfayı yenile — konuşma hâlâ orada, çünkü mesajlar .wrangler/state içindeki SQLite’a yazıldı.

wrangler dev kapatılıp açıldıktan sonra sayfa yenilendiğinde geçmiş mesajların hâlâ görünmesi

Adım 7 — Yayına al ve gerçek depolamayı incele

npx wrangler deploy

Panelde: Durable Objects → ChatAgent namespace → Data Studio → örnek adı default.

SELECT name FROM sqlite_master WHERE type='table';
SELECT * FROM cf_agents_state;

Data Studio sorgu sonucu; cf_agents_state, cf_agents_schedules, cf_agents_queues ve sohbet mesaj tablosu

Sohbet mesajı tablosunun adı belgelenmemiştir — varsaymak yerine sqlite_master’dan keşfet.

ChatAgent namespace'inin Metrics sekmesi; istek sayısı, süre ve bellek kullanımı

Bu demoda ölçülenler:

Demo 2: Zamanlama ve kalıcılığın yeniden başlatmadan sağ çıkması

Amaç: durumun ve bekleyen zamanlanmış görevlerin SQLite’a yazıldığını ve çalışma zamanını öldürünce kaybolmadığını kanıtlamak. Süre: ~10 dakika.

Adım 1 — Kendi uyanışlarını sayan bir ajan yaz

import { Agent, routeAgentRequest } from 'agents';

type TikDurum = {
  tik: number;
  acilisSayisi: number;
  sonTik: string | null;
};

export class TikAjani extends Agent<Env, TikDurum> {
  initialState: TikDurum = { tik: 0, acilisSayisi: 0, sonTik: null };

  async onStart() {
    // Her soğuk başlangıçta artar — tahliye ve yeniden başlatma dahil
    this.setState({ ...this.state, acilisSayisi: this.state.acilisSayisi + 1 });

    this.sql`CREATE TABLE IF NOT EXISTS tik_log (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      an TEXT NOT NULL
    )`;
  }

  async onRequest(request: Request) {
    const url = new URL(request.url);

    if (url.pathname.endsWith('/basla')) {
      await this.scheduleEvery(15, 'tik', {});               // aralık
      await this.schedule(120, 'sonraCalis', { not: '2dk' }); // tek seferlik
      await this.schedule('*/5 * * * *', 'cronTik', {});      // cron
    }

    if (url.pathname.endsWith('/dur')) {
      for (const s of await this.listSchedules()) {
        await this.cancelSchedule(s.id);
      }
    }

    return Response.json({
      durum: this.state,
      zamanlamalar: await this.listSchedules(),
      log: this.sql`SELECT * FROM tik_log ORDER BY id DESC LIMIT 5`,
    });
  }

  async tik() {
    const an = new Date().toISOString();
    this.sql`INSERT INTO tik_log (an) VALUES (${an})`;
    this.setState({ ...this.state, tik: this.state.tik + 1, sonTik: an });
    console.log('tik', this.state.tik);
  }

  async sonraCalis(p: { not: string }) { console.log('tek seferlik', p.not); }
  async cronTik() { console.log('cron çalıştı'); }
}

Adım 2 — İncelenebilir bir durum dizini ile çalıştır

npx wrangler dev --persist-to ./demo-durum

Varsayılan .wrangler/state yerine açık bir yol kullanmak, “gerçekten diske mi yazıyor?” sorusunu kontrol edilebilir kılıyor.

Adım 3 — Zamanlamaları başlat ve referans ölçüm al

curl -s localhost:8787/agents/tik-ajani/demo-1/basla | jq
# ~60 saniye bekle
curl -s localhost:8787/agents/tik-ajani/demo-1 | jq

JSON çıktısı; acilisSayisi 1, tik yaklaşık 4 ve üç zamanlama satırı

Her zamanlama satırı { id, callback, payload, time } ve "interval" / "delayed" / "cron" tipini taşır. time saniye cinsinden Unix zaman damgasıdır — JavaScript Date’ine çevirirken 1000 ile çarpman gerekir.

Adım 4 — Çalışma zamanını öldür ve yeniden başlat

# Ctrl-C ile wrangler dev'i durdur, sonra:
npx wrangler dev --persist-to ./demo-durum
curl -s localhost:8787/agents/tik-ajani/demo-1 | jq

JSON çıktısı; acilisSayisi 2'ye çıkmış ama tik sayacı sıfırlanmamış, üç zamanlama da hâlâ listede

Görülmesi gerekenler:

• acilisSayisi 2’ye çıktı — onStart() yeniden çalıştı, yani gerçekten soğuk başlangıç.
• tik sıfırlanmadı, kaldığı yerden devam ediyor.
• Üç zamanlama da hâlâ listede ve terminalde tik satırları /basla çağırmadan yeniden akmaya başlıyor.
• tik_log yeniden başlatma öncesi satırları tutuyor.

Adım 5 — Diskteki SQLite’a bak

find ./demo-durum -name '*.sqlite' | head
sqlite3 <dosya> ".tables"
sqlite3 <dosya> "SELECT * FROM cf_agents_schedules;"
sqlite3 <dosya> "SELECT * FROM cf_agents_state;"

sqlite3 çıktısı; cf_agents_state, cf_agents_schedules ve kendi tik_log tablon aynı veritabanında

Adım 6 — Cron’un idempotent olduğunu doğrula

curl -s localhost:8787/agents/tik-ajani/demo-1/basla
curl -s localhost:8787/agents/tik-ajani/demo-1/basla
curl -s localhost:8787/agents/tik-ajani/demo-1 | jq '.zamanlamalar | length'

jq çıktısı; cron sayısı 1'de kalmış ama aralık ve gecikmeli görevlerin çoğalmış olduğu

Cron kopyalanmaz; aralık ve gecikmeli görev kopyalanır. Bu asimetri, zamanlamadaki en yaygın hatanın kaynağıdır.

Adım 7 — Yayına al ve maliyet dersini gör

npx wrangler deploy
curl -s https://sched-demo.<altalan>.workers.dev/agents/tik-ajani/demo-1/basla
npx wrangler tail

Gerçek edge'den akan tik logları, yaklaşık 15 saniyelik aralıklarla

Durable Objects namespace Metrics sekmesi; Duration (GB-s) değerinin sürekli tırmandığı grafik

Bu demoda ölçülenler:

Fiyatlandırma

Ayrı bir Agents kalemi yok

Agents için fiyat sayfası yoktur (/agents/platform/pricing/ → 404) ve agents/llms.txt faturalama sayfası listelemez. Agent bir Durable Object olduğuna göre Workers ve Durable Objects ücretlerini ödersin — ama yukarıda belirtildiği gibi bu cümleyi Cloudflare kendisi yazmamıştır.

Agents dokümanlarındaki tek açık fiyat ifadesi tracing içindir:

“Agent traces use Workers tracing and follow Workers Observability pricing. […] Every span counts as one observability event, including spans not shown in the Agents view. Tracing is free while in beta. Beginning October 1, 2026, tracing will be included in existing Workers Observability pricing”

Ödediğin şey: Workers

“The Workers Paid plan includes Workers, Pages Functions, Workers KV, Hyperdrive, and Durable Objects usage for a minimum charge of $5 USD per month for an account. […] There are no additional charges for data transfer (egress) or throughput (bandwidth).”

Standart kullanım modeli: ayda 10 milyon istek dahil, fazlası milyon başına $0.30; “No charge or limit for duration”; ayda 30 milyon CPU-milisaniye dahil, fazlası milyon CPU-ms başına $0.02.

Ödediğin şey: Durable Objects hesaplama

İstek tanımı geniş: “Includes HTTP requests, RPC sessions, WebSocket messages, and alarm invocations.”

Ödediğin şey: Durable Objects SQLite depolama

Bir ajanın faturasını belirleyen dört dipnot

WebSocket mesajlarında 20:1 indirim var. “For compute requests billing-only, a 20:1 ratio is applied to incoming WebSocket messages… For example, 100 WebSocket incoming messages would be charged as 5 requests.” Giden mesajlar ve protokol ping’leri ücretsiz. Bu oran yalnızca faturayı etkiler, metriklere yansımaz.

Her setAlarm() bir satır yazmadır. Her this.schedule(), her cron yeniden kurulumu ve her keepAlive() kalp atışı alarm sistemine dokunur. 15 saniyelik bir aralık, ajan başına günde ~5.760 alarm yazması demektir.

Duration her zaman 128 MB üzerinden faturalanır, “even if your Durable Object uses less.” Ayrıca “Calling accept() on a WebSocket in an Object will incur duration charges for the entire time the WebSocket is connected” — SDK’nın varsayılan olarak hibernate: true kullanmasının sebebi tam olarak budur.

Hibernation maliyet modelinin tamamıdır. “Durable Objects that are idle and eligible for hibernation are not billed for duration, even before the runtime has hibernated them.” Sık aralık zamanlaması olan bir ajan hiç hibernate olmaz ve sürekli duration öder.

Limitler

~250.000 rakamının dayanağı: “up to 500 scripts per account […] but each script (project) can define multiple Agents.”

Lisanslama ve hukuki çerçeve

SDK açık kaynaktır — bu bu katalogda nadir bir durum. github.com/cloudflare/agents MIT lisanslı, yaklaşık 5.500 yıldızlı bir monorepo. Kodu okuyabilir, fork’layabilir, kendi değişikliklerinle çalıştırabilirsin. Bu, satıcı bağımlılığı değerlendirmende önemli bir fark: SDK’nın kendisi seni bağlamıyor, çalıştığı platform bağlıyor (Durable Objects).

Çalıştığı platform tescillidir. Agent bir Durable Object olduğu için Cloudflare Hizmet Şartları geçerlidir. SDK’yı başka bir yerde çalıştıramazsın — DurableObject sınıfı Cloudflare çalışma zamanına aittir.

Sürüm riski sözleşme riskidir. SDK 0.22.0 ve minor sürümlerde kırıcı değişiklik geliyor. Bir müşteriye AI ajanı hizmeti satıyorsan, hizmet seviyesi taahhüdü verirken alt katmanda 1.0 öncesi bir kütüphane olduğunu bil. Ayrıca ajan çerçevesinin kendisi için hiçbir GA veya SLA taahhüdü yoktur.

KVKK açısından üç nokta. Birincisi, ajanın durumu ve sohbet geçmişi Durable Object’in SQLite’ında kalıcı olarak saklanır — silme talebini karşılarken hem cf_agents_state hem de sohbet mesajı tablosunu temizlemen gerekir. İkincisi, Durable Object’ler kendi bölgelerinde çalışır ve Cloudflare bir konum garantisi vermez; ajan verisinin nerede saklandığı yurt dışına aktarım değerlendirmesi gerektirir. Üçüncüsü, Workers AI modeli çağırıyorsan Workers AI’ın, üçüncü taraf model çağırıyorsan AI Gateway’in hukuki çerçevesi de devreye girer.

Data Studio erişimi denetim kaydı üretir. Her sorgu iki denetim günlüğü olayı yazar ve Workers Platform Admin rolü gerektirir. Üretim verisine kimin eriştiğini izlemen gerekiyorsa bu kayıtları topla.

Sık yapılan hatalar

@callable() dekoratörünü her yerde kullanmak. Dekoratör yalnızca dış istemcilerden gelen WebSocket RPC içindir. İç çağrılarda getAgentByName() ve düz Durable Object RPC kullan — WebSocket serileştirmesini tamamen atlar.

AIChatAgent streaming’i etrafına keepAlive() eklemek. Gereksiz — “AIChatAgent automatically calls keepAlive() during streaming responses.” Fazladan kalp atışı fazladan alarm, fazladan alarm fazladan faturalanan satır demektir. keepAlive()’ı uzun özel hesaplama, yavaş dış API ve çok adımlı araç yürütmesi için sakla.

setTimeout’un hayatta kalmasını beklemek. Zamanlayıcılar, uçuştaki fetch’ler ve closure’lar tahliyede ölür. Sonradan olması gereken her şey schedule(), queue(), runFiber() veya bir Workflow’a ait.

Yeni kodda getSchedules() kullanmak. Senkron biçim kullanımdan kaldırıldı; await this.listSchedules(kriter) kullan. Ayrıca schedule.time saniye cinsindendir — new Date(schedule.time * 1000).

onRequest içinde koşulsuz scheduleEvery() çağırmak. Cron idempotent ama aralık ve gecikmeli görev değil. Her istekte bir görev daha birikir.

MCP hızlı başlangıcını takip etmek. Şablonlar hâlâ kullanımdan kaldırılmış McpAgent kullanıyor. createMcpHandler ile başla ve sunucu fabrikasını geçir, oluşturulmuş global bir örneği değil.

new_sqlite_classes migration’ını unutmak. Hem durum hem mesaj kalıcılığı SQLite backend’ini gerektiriyor; olmadan sessizce çalışmaz.

experimentalDecorators açıkken @callable() kullanmak. Sessizce bozulur — TC39 dekoratörleri gerekiyor.

Durumu büyük tutmak. setState() her değişiklikte tüm bağlı istemcilere yayınlar. Geçmiş veri ve büyük koleksiyonlar this.sql’e ait.

Üretime karşı gelişigüzel Data Studio sorgusu çalıştırmak. Her sorgu gerçek bir nesneye gerçek bir istektir ve istek, süre, okunan satır ve yazılan satır olarak faturalanır.

Doküman ana sayfasını güncel sanmak. /agents/ iki ay geride; Ağustos 2026 lansmanlarının hiçbiri orada yok.

Blog yazılarındaki durum etiketlerine güvenmek. Nisan 2026 ses (voice) yazısı “experimental” diyor, güncel doküman Beta diyor. Project Think lansman yazısı API’nin “önümüzdeki günler ve haftalarda” gelişeceğini söylüyor; dört buçuk ay sonra doküman hâlâ “Think experimental’dan mezun olmadan önce” diyor.