Menjalankan task pada autonomous AI agent (seperti arsitektur goal-conditioned) membutuhkan kontrak API yang berbeda dari CRUD konvensional. Reasoning model memerlukan latensi tinggi (puluhan detik hingga menit), berbiaya komputasi mahal melalui LLM token, dan rentan menghasilkan efek samping ganda jika klien melakukan retry otomatis saat jaringan terputus. Solusinya adalah mendesain kontrak API berbasis deklarasi goal yang ketat, validasi state sebelum eksekusi, serta mekanisme idempotensi tangguh.

1. Struktur Skema Payload Goal-Conditioned

Agent otonom bekerja optimal bila menerima state target yang diinginkan beserta batas aman eksekusi (guardrails), bukan instruksi langkah demi langkah. Payload harus mendefinisikan deskripsi goal, batasan operasional (misal: budget komputasi atau jumlah step maksimal), dan konteks environment awal.

Berikut contoh skema JSON Schema minimal untuk mendefinisikan goal task:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["goal", "guardrails"],
  "properties": {
    "goal": {
      "type": "object",
      "required": ["intent", "target_state"],
      "properties": {
        "intent": { "type": "string", "minLength": 5 },
        "target_state": { "type": "object" }
      }
    },
    "guardrails": {
      "type": "object",
      "required": ["max_steps", "timeout_seconds"],
      "properties": {
        "max_steps": { "type": "integer", "minimum": 1, "maximum": 50 },
        "timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 600 },
        "allowed_tools": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "pre_conditions": {
      "type": "object",
      "description": "State hash atau versi entitas yang harus cocok sebelum eksekusi"
    }
  }
}

2. Mekanisme Deduplikasi via Idempotency Key

Klien mengirimkan header Idempotency-Key (biasanya UUID v4). Server memverifikasi key ini sebelum memicu agent worker. Ada dua pendekatan penyimpanan state idempotensi:

  • Redis SETNX: Sangat cepat untuk locking sementara dan mengecek request dalam proses. Cocok untuk caching respons cepat dengan TTL (misalnya 24 jam).
  • PostgreSQL Unique Constraint: Menyediakan garansi ACID penuh. Menyimpan task ID, idempotency key, request fingerprint (hash SHA-256 dari payload), dan status eksekusi dalam satu transaksi database.

Jika klien mengirim key yang sama dengan payload yang berbeda, server harus mengembalikan error 409 Conflict. Jika payload identik dan task sedang berjalan, kembalikan HTTP 200 OK atau 202 Accepted beserta link tracking task yang sudah ada tanpa menduplikasi antrean.

Implementasi Middleware Idempotency Sederhana (Node.js/Express)

const crypto = require('crypto');

async function idempotencyMiddleware(req, res, next) {
  const idempotencyKey = req.header('Idempotency-Key');
  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Header Idempotency-Key diwajibkan' });
  }

  const payloadHash = crypto
    .createHash('sha256')
    .update(JSON.stringify(req.body))
    .digest('hex');

  // ponytail: menggunakan Redis murni; ganti ke tabel Postgres bila butuh riwayat audit permanen
  const existing = await redis.get(`idemp:${idempotencyKey}`);
  
  if (existing) {
    const record = JSON.parse(existing);
    if (record.hash !== payloadHash) {
      return res.status(409).json({ 
        error: 'Idempotency-Key telah dipakai dengan payload berbeda' 
      });
    }
    // Kembalikan respons yang sama tanpa trigger task baru
    return res.status(record.statusCode).json(record.response);
  }

  // Set lock dengan TTL 3600 detik
  await redis.set(`idemp:${idempotencyKey}`, JSON.stringify({
    hash: payloadHash,
    statusCode: 202,
    response: { status: 'PENDING', message: 'Task sudah dalam antrean' }
  }), 'EX', 3600, 'NX');

  next();
}

3. Pola Asinkron: Mengatasi Timeout Reasoning Agent

Tahapan reasoning pada model otonom sering kali melampaui timeout standar gateway HTTP (umumnya 30-60 detik). Karena itu, endpoint trigger wajib bersifat asinkron:

  1. HTTP 202 Accepted: Endpoint inisiasi mengembalikan status 202 dengan header Location: /v1/tasks/{task_id}.
  2. Polling Pattern: Klien memeriksa endpoint status secara berkala. Respons menyertakan status eksekusi (queued, running, succeeded, failed) dan snapshot reasoning trace.
  3. Webhook Pattern: Klien mendaftarkan webhook_url dalam payload. Worker agent akan mengirimkan payload HTTP POST ke URL tersebut begitu target_state tercapai atau batas guardrails dilanggar.

4. Validasi Pre-condition State Sebelum Aksi

Masalah umum agent AI adalah hilangnya relevansi context: saat agent mulai bertindak, data di dunia nyata sudah berubah dari saat task dibuat. Desain API perlu mendukung validasi prasyarat state sebelum eksekusi tool pertama:

  • Optimistic Locking (ETag / Version): Payload menyertakan versi entitas yang akan dimodifikasi (misal: account_version: 12). Jika entitas sudah berubah menjadi versi 13, gagalkan task segera dengan status PRECONDITION_FAILED (HTTP 412).
  • Dry-run Validation: Sebelum agent worker mengonsumsi token LLM, server mengevaluasi ketersediaan dependensi eksternal (API pihak ketiga, saldo token, izin role alat) secara deterministik.

Menerapkan validasi ketat pada API contract agent menjamin sistem backend tetap konsisten, mencegah pemborosan komputasi LLM berulang, dan mengeliminasi race condition akibat aksi agen yang tidak terkendali.